このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.0.3 を使用してください。 |
ZhiPu AI チャット
Spring AI は、ZhiPu AI のさまざまな AI 言語モデルをサポートしています。ZhiPu AI 言語モデルと対話し、ZhiPuAI モデルに基づいて多言語会話アシスタントを作成できます。
中国語を話さない方は、ZhiPuAI の国際サイト Z.ai (英語) を参照してください。
前提条件
ZhiPu AI 言語モデルにアクセスするには、ZhiPuAI を使用して API を作成する必要があります。
Create an account at ZhiPu AI 登録ページ (英語) (or Z.ai registration page (英語) ) and generate the token on the API キーページ (英語) (or Z.ai API Keys page (英語) ).
Spring AI プロジェクトは、API キーページから取得した API Key の値に設定する必要がある spring.ai.zhipuai.api-key という名前の構成プロパティを定義します。
この構成プロパティは、application.properties ファイルで設定できます。
spring.ai.zhipuai.api-key=<your-zhipuai-api-key>API キーなどの機密情報を扱う際のセキュリティを強化するために、Spring 式言語 (SpEL) を使用してカスタム環境変数を参照できます。
# In application.yml
spring:
ai:
zhipuai:
api-key: ${ZHIPUAI_API_KEY}# In your environment or .env file
export ZHIPUAI_API_KEY=<your-zhipuai-api-key>この構成をアプリケーションコード内でプログラム的に設定することもできます。
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("ZHIPUAI_API_KEY");リポジトリと BOM の追加
Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。
依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。
自動構成
Spring AI 自動構成、スターターモジュールのアーティファクト名に大きな変更がありました。詳細については、アップグレードノートを参照してください。 |
Spring AI は、ZhiPuAI チャットクライアント用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml ファイルに次の依存関係を追加します。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-zhipuai</artifactId>
</dependency> または、Gradle build.gradle ビルドファイルに保存します。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-zhipuai'
}| Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。 |
チャットのプロパティ
再試行プロパティ
プレフィックス spring.ai.retry は、ZhiPu AI チャットモデルの再試行メカニズムを構成できるプロパティプレフィックスとして使用されます。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.retry.max-attempts | 再試行の最大回数。 | 10 |
spring.ai.retry.backoff.initial-interval | 指数関数的バックオフポリシーの初期スリープ期間。 | 2 秒 |
spring.ai.retry.backoff.multiplier | バックオフ間隔の乗数。 | 5 |
spring.ai.retry.backoff.max-interval | 最大バックオフ期間。 | 3 分 |
spring.ai.retry.on-client-errors | false の場合、NonTransientAiException をスローし、 | false |
spring.ai.retry.exclude-on-http-codes | 再試行をトリガーすべきではない HTTP ステータスコードのリスト (NonTransientAiException をスローするなど)。 | 空 |
spring.ai.retry.on-http-codes | 再試行をトリガーする必要がある HTTP ステータスコードのリスト (例: TransientAiException をスローする)。 | 空 |
接続プロパティ
接頭辞 spring.ai.zhipuai は、ZhiPuAI への接続を可能にするプロパティ接頭辞として使用されます。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.zhipuai.base-url | The URL to connect to ZhiPuAI API. | |
spring.ai.zhipuai.api-key | API キー | - |
プロパティの構成
チャットの自動構成の有効化と無効化は、プレフィックス 有効にするには、spring.ai.model.chat=zhipuai (デフォルトで有効になっています) 無効にするには、spring.ai.model.chat=none (または zhipuai と一致しない値) この変更は、複数のモデルの構成を可能にするために行われます。 |
プレフィックス spring.ai.zhipuai.chat は、ZhiPuAI のチャットモデル実装を構成できるプロパティプレフィックスです。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.zhipuai.chat.enabled (削除され、無効になりました) | ZhiPuAI チャットモデルを有効にします。 | true |
spring.ai.model.chat | ZhiPuAI チャットモデルを有効にします。 | ジプアイ |
spring.ai.zhipuai.chat.base-url | Optional overrides the spring.ai.zhipuai.base-url to provide chat specific url. | |
spring.ai.zhipuai.chat.api-key | Optional overrides the spring.ai.zhipuai.api-key to provide chat specific api-key. | - |
spring.ai.zhipuai.chat.options.model | This is the ZhiPuAI Chat model to use. You can select between models such as: |
|
spring.ai.zhipuai.chat.options.maxTokens | チャット補完で生成するトークンの最大数。入力トークンと生成されたトークンの合計の長さは、モデルのコンテキストの長さによって制限されます。 | - |
spring.ai.zhipuai.chat.options.temperature | 使用するサンプリング温度 (0 から 1 の間)。0.8 のような高い値を指定すると出力はよりランダムになり、0.2 のような低い値を指定すると出力はより集中的かつ決定論的になります。通常は、この値か top_p のいずれかを変更することを推奨しますが、両方を変更することは推奨しません。 | 0.7 |
spring.ai.zhipuai.chat.options.topP | 温度によるサンプリングの代替として、核サンプリングと呼ばれる方法があります。この方法では、モデルは top_p 確率質量を持つトークンの結果を考慮します。つまり、0.1 は、上位 10% の確率質量を構成するトークンのみが考慮されることを意味します。通常は、この値または温度のいずれかを変更することを推奨しますが、両方を変更することは推奨しません。 | 1.0 |
spring.ai.zhipuai.chat.options.stop | モデルは stop で指定された文字の生成を停止します。現在は ["stop_word1"] の形式で単一のストップワードのみをサポートしています | - |
spring.ai.zhipuai.chat.options.user | エンドユーザーを表す一意の識別子。ZhiPuAI が不正使用を監視および検出できます。 | - |
spring.ai.zhipuai.chat.options.requestId | このパラメーターはクライアントによって渡され、一意性を保証する必要があります。これは、各リクエストの一意の識別子を区別するために使用されます。クライアントがパラメーターを提供しない場合は、プラットフォームがデフォルトで生成します。 | - |
spring.ai.zhipuai.chat.options.doSample | do_sample が true に設定されている場合、サンプリング戦略が有効になります。do_sample が false の場合、サンプリング戦略パラメーターの temperature と top_p は有効になりません。 | true |
spring.ai.zhipuai.chat.options.response-format.type | Control the format of the model output. Set to | - |
spring.ai.zhipuai.chat.options.thinking.type | Control whether to enable the large model’s chain of thought. Available options: | - |
spring.ai.zhipuai.chat.options.tool-names | 単一のプロンプトリクエストで関数呼び出しを有効にするツールのリスト（名前で識別されます）。これらの名前のツールは、ToolCallback レジストリに存在している必要があります。 | - |
spring.ai.zhipuai.chat.options.tool-callbacks | ChatModel に登録するツールコールバック。 | - |
spring.ai.zhipuai.chat.options.internal-tool-execution-enabled | False の場合、Spring AI はツール呼び出しを内部で処理せず、クライアントにプロキシします。その後、ツール呼び出しを処理し、適切な関数にディスパッチして、結果を返すのはクライアントの責任です。True (デフォルト) の場合、Spring AI は関数呼び出しを内部で処理します。関数呼び出しをサポートするチャットモデルにのみ適用されます。 | true |
ChatModel 実装の共通の spring.ai.zhipuai.base-url および spring.ai.zhipuai.api-key をオーバーライドできます。spring.ai.zhipuai.chat.base-url および spring.ai.zhipuai.chat.api-key プロパティが設定されている場合は、共通のプロパティよりも優先されます。これは、異なるモデルおよび異なるモデルエンドポイントに異なる ZhiPuAI アカウントを使用する場合に便利です。 |
spring.ai.zhipuai.chat.options というプレフィックスが付いたすべてのプロパティは、リクエスト固有のランタイムオプションを Prompt 呼び出しに追加することで実行時にオーバーライドできます。 |
ランタイムオプション
ZhiPuAiChatOptions.java [GitHub] (英語) は、使用するモデル、温度、周波数ペナルティなどのモデル構成を提供します。
起動時に、ZhiPuAiChatModel(api, options) コンストラクターまたは spring.ai.zhipuai.chat.options.* プロパティを使用してデフォルトのオプションを構成できます。
実行時に、新しいリクエスト固有のオプションを Prompt 呼び出しに追加することで、デフォルトのオプションをオーバーライドできます。たとえば、特定のリクエストのデフォルトのモデルと温度をオーバーライドするには、次のようにします。
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
ZhiPuAiChatOptions.builder()
.model(ZhiPuAiApi.ChatModel.GLM_4_Air.getValue())
.temperature(0.5)
.build()
));| モデル固有の ZhiPuAiChatOptions [GitHub] (英語) に加えて、ChatOptions#builder() [GitHub] (英語) で作成されたポータブル ChatOptions [GitHub] (英語) インスタンスを使用できます。 |
サンプルコントローラー
新しい Spring Boot プロジェクトを作成し、spring-ai-starter-model-zhipuai を pom (または gradle) の依存関係に追加します。
src/main/resources ディレクトリに application.properties ファイルを追加して、ZhiPuAi チャットモデルを有効にして構成します。
spring.ai.zhipuai.api-key=YOUR_API_KEY
spring.ai.zhipuai.chat.options.model=glm-4-air
spring.ai.zhipuai.chat.options.temperature=0.7api-key を ZhiPuAI 資格情報に置き換えます。 |
これにより、クラスに挿入できる ZhiPuAiChatModel 実装が作成されます。以下は、テキスト生成にチャットモデルを使用する単純な @Controller クラスの例です。
@RestController
public class ChatController {
private final ZhiPuAiChatModel chatModel;
@Autowired
public ChatController(ZhiPuAiChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", this.chatModel.call(message));
}
@GetMapping(value = "/ai/generateStream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
var prompt = new Prompt(new UserMessage(message));
return this.chatModel.stream(prompt);
}
}手動構成
ZhiPuAiChatModel [GitHub] (英語) は ChatModel と StreamingChatModel を実装し、低レベル ZhiPuAiApi クライアントを使用して ZhiPuAI サービスに接続します。
spring-ai-zhipuai 依存関係をプロジェクトの Maven pom.xml ファイルに追加します。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-zhipuai</artifactId>
</dependency> または、Gradle build.gradle ビルドファイルに保存します。
dependencies {
implementation 'org.springframework.ai:spring-ai-zhipuai'
}| Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。 |
次に、ZhiPuAiChatModel を作成し、テキスト生成に使用します。
var zhiPuAiApi = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
var chatModel = new ZhiPuAiChatModel(this.zhiPuAiApi, ZhiPuAiChatOptions.builder()
.model(ZhiPuAiApi.ChatModel.GLM_4_Air.getValue())
.temperature(0.4)
.maxTokens(200)
.build());
ChatResponse response = this.chatModel.call(
new Prompt("Generate the names of 5 famous pirates."));
// Or with streaming responses
Flux<ChatResponse> streamResponse = this.chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));ZhiPuAiChatOptions は、チャットリクエストの構成情報を提供します。ZhiPuAiChatOptions.Builder は流れるようなオプションビルダーです。
低レベル ZhiPuAiApi クライアント
ZhiPuAiApi [GitHub] (英語) が提供するのは、ZhiPu AI API (英語) 用の軽量 Java クライアントです。
API をプログラムで使用する方法の簡単なスニペットを次に示します。
ZhiPuAiApi zhiPuAiApi =
new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("Hello world", Role.USER);
// Sync request
ResponseEntity<ChatCompletion> response = this.zhiPuAiApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_4_Air.getValue(), 0.7, false));
// Streaming request
Flux<ChatCompletionChunk> streamResponse = this.zhiPuAiApi.chatCompletionStream(
new ChatCompletionRequest(List.of(this.chatCompletionMessage), ZhiPuAiApi.ChatModel.GLM_4_Air.getValue(), 0.7, true));詳細については、ZhiPuAiApi.java [GitHub] (英語) の JavaDoc を参照してください。
ZhiPuAiApi サンプル
ZhiPuAiApiIT.java [GitHub] (英語) テストでは、軽量ライブラリの使用方法の一般的な例をいくつか示します。
