ZhiPuAI 埋め込み

Spring AI は、ZhiPuAI のテキスト埋め込みモデルをサポートしています。ZhiPuAI のテキスト埋め込みは、テキスト文字列の関連性を測定します。埋め込みは、浮動小数点数のベクトル (リスト) です。2 つのベクトル間の距離は、関連性を測定します。距離が小さいと関連性が高く、距離が大きいと関連性が低いことを示します。

前提条件

ZhiPu AI 言語モデルにアクセスするには、ZhiPuAI を使用して API を作成する必要があります。

ZhiPu AI 登録ページ (英語) でアカウントを作成し、API キーページ (英語) でトークンを生成します。Spring AI プロジェクトでは、spring.ai.zhipu.api-key という名前の構成プロパティが定義されており、これを API キーページ (英語) から取得した API Key の値に設定する必要があります。環境変数をエクスポートすることは、その構成プロパティを設定する 1 つの方法です。

export SPRING_AI_ZHIPU_AI_API_KEY=<INSERT KEY HERE>

リポジトリと BOM の追加

Spring AI アーティファクトは、Spring マイルストーンおよびスナップショットリポジトリで公開されます。これらのリポジトリをビルドシステムに追加するには、リポジトリセクションを参照してください。

依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。

自動構成

Spring AI は、Azure ZhiPuAI 埋め込みモデル用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml ファイルに次の依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-zhipuai-spring-boot-starter</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-zhipuai-spring-boot-starter'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

埋め込みプロパティ

再試行プロパティ

プレフィックス spring.ai.retry は、ZhiPuAI 埋め込みモデルの再試行メカニズムを構成できるプロパティプレフィックスとして使用されます。

プロパティ 説明 デフォルト

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 をスローし、4xx クライアントエラーコードの再試行を試行しません。

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

接続先の URL

オープンビッグモデル (英語)

spring.ai.zhipuai.api-key

API キー

-

プロパティの構成

プレフィックス spring.ai.zhipuai.embedding は、ZhiPuAI の EmbeddingModel 実装を構成するプロパティプレフィックスです。

プロパティ 説明 デフォルト

spring.ai.zhipuai.embedding.enabled

ZhiPuAI 埋め込みモデルを有効にします。

true

spring.ai.zhipuai.embedding.base-url

オプションで spring.ai.zhipuai.base-url をオーバーライドして、埋め込み固有の URL を提供します

-

spring.ai.zhipuai.embedding.api-key

オプションで spring.ai.zhipuai.api-key をオーバーライドして、埋め込み固有の API キーを提供します

-

spring.ai.zhipuai.embedding.options.model

使用するモデル

埋め込み -2

ChatModel および EmbeddingModel 実装の共通の spring.ai.zhipuai.base-url および spring.ai.zhipuai.api-key をオーバーライドできます。spring.ai.zhipuai.embedding.base-url および spring.ai.zhipuai.embedding.api-key プロパティが設定されている場合は、共通のプロパティよりも優先されます。同様に、spring.ai.zhipuai.embedding.base-url および spring.ai.zhipuai.embedding.api-key プロパティが設定されている場合は、共通のプロパティよりも優先されます。これは、異なるモデルおよび異なるモデルエンドポイントに異なる ZhiPuAI アカウントを使用する場合に便利です。
spring.ai.zhipuai.embedding.options というプレフィックスが付いたすべてのプロパティは、リクエスト固有のランタイムオプションを EmbeddingRequest 呼び出しに追加することで実行時にオーバーライドできます。

ランタイムオプション

ZhiPuAiEmbeddingOptions.java [GitHub] (英語) は、使用するモデルなどの ZhiPuAI 構成を提供します。

デフォルトのオプションは、spring.ai.zhipuai.embedding.options プロパティを使用して構成することもできます。

開始時に、ZhiPuAiEmbeddingModel コンストラクターを使用して、すべての埋め込みリクエストに使用されるデフォルトのオプションを設定します。実行時に、ZhiPuAiEmbeddingOptions インスタンスを EmbeddingRequest の一部として使用して、デフォルトのオプションをオーバーライドできます。

たとえば、特定のリクエストのデフォルトのモデル名をオーバーライドするには、次のようにします。

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        ZhiPuAiEmbeddingOptions.builder()
            .withModel("Different-Embedding-Model-Deployment-Name")
        .build()));

サンプルコントローラー

これにより、クラスに注入できる EmbeddingModel 実装が作成されます。以下は、EmbeddingModel 実装を使用する単純な @Controller クラスの例です。

spring.ai.zhipuai.api-key=YOUR_API_KEY
spring.ai.zhipuai.embedding.options.model=embedding-2
@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手動構成

Spring Boot を使用していない場合は、ZhiPuAI 埋め込みモデルを手動で構成できます。これを行うには、プロジェクトの Maven pom.xml ファイルに spring-ai-zhipuai 依存関係を追加します。

<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 をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
spring-ai-zhipuai 依存関係により、ZhiPuAiChatModel へのアクセスも提供されます。ZhiPuAiChatModel の詳細については、ZhiPuAI チャットクライアントセクションを参照してください。

次に、ZhiPuAiEmbeddingModel インスタンスを作成し、それを使用して 2 つの入力テキスト間の類似性を計算します。

var zhiPuAiApi = new ZhiPuAiApi(System.getenv("ZHIPU_AI_API_KEY"));

var embeddingModel = new ZhiPuAiEmbeddingModel(zhiPuAiApi)
    .withDefaultOptions(ZhiPuAiChatOptions.build()
        .withModel("embedding-2")
        .build());

EmbeddingResponse embeddingResponse = embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

ZhiPuAiEmbeddingOptions は、埋め込みリクエストの構成情報を提供します。オプションクラスは、オプションを簡単に作成できる builder() を提供します。