OpenAI 埋め込み

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

前提条件

OpenAI 埋め込みモデルにアクセスするには、OpenAI を使用して API を作成する必要があります。

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

export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>

リポジトリと BOM の追加

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

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

自動構成

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

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

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

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

埋め込みプロパティ

再試行プロパティ

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

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

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.openai は、OpenAI への接続を可能にするプロパティ接頭辞として使用されます。

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

spring.ai.openai.base-url

接続先の URL

https://api.openai.com

spring.ai.openai.api-key

API キー

-

spring.ai.openai.organization-id

オプションで、API リクエストに使用する組織を指定できます。

-

spring.ai.openai.project-id

必要に応じて、API リクエストに使用するプロジェクトを指定できます。

-

複数の組織に属しているユーザー(または従来のユーザー API キーを使用してプロジェクトにアクセスしているユーザー)の場合は、オプションで、API リクエストに使用する組織とプロジェクトを指定できます。これらの API リクエストからの使用量は、指定された組織とプロジェクトの使用量としてカウントされます。

プロパティの構成

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

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

spring.ai.openai.embedding.enabled

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

true

spring.ai.openai.embedding.base-url

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

-

spring.ai.openai.chat.embeddings-path

ベース URL に追加するパス

/v1/embeddings

spring.ai.openai.embedding.api-key

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

-

spring.ai.openai.embedding.organization-id

オプションで、API リクエストに使用する組織を指定できます。

-

spring.ai.openai.embedding.project-id

必要に応じて、API リクエストに使用するプロジェクトを指定できます。

-

spring.ai.openai.embedding.metadata-mode

ドキュメントコンテンツ抽出モード。

EMBED

spring.ai.openai.embedding.options.model

使用するモデル

text-embedding-ada-002 (その他のオプション: テキスト埋め込み -3- 大、テキスト埋め込み -3- 小)

spring.ai.openai.embedding.options.encodingFormat

埋め込みを返す形式。float または Base64 のいずれかにすることができます。

-

spring.ai.openai.embedding.options.user

エンドユーザーを表す一意の識別子。OpenAI が不正使用を監視および検出できます。

-

spring.ai.openai.embedding.options.dimensions

結果として得られる出力埋め込みの次元数。text-embedding-3 以降のモデルでのみサポートされます。

-

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

ランタイムオプション

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

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

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

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

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

サンプルコントローラー

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

spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.embedding.options.model=text-embedding-ada-002
@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 を使用していない場合は、OpenAI 埋め込みモデルを手動で構成できます。これを行うには、プロジェクトの Maven pom.xml ファイルに spring-ai-openai 依存関係を追加します。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
</dependency>

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
spring-ai-openai 依存関係により、OpenAiChatModel へのアクセスも提供されます。OpenAiChatModel の詳細については、OpenAI チャットクライアントセクションを参照してください。

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

var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));

var embeddingModel = new OpenAiEmbeddingModel(
        openAiApi,
        MetadataMode.EMBED,
        OpenAiEmbeddingOptions.builder()
                .withModel("text-embedding-ada-002")
                .withUser("user-6")
                .build(),
        RetryUtils.DEFAULT_RETRY_TEMPLATE);

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

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