このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 2.0.1 を使用してください!

OpenAI 埋め込み

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

バージョン 2.0.0-M5 以降、Spring AI はすべての OpenAI モデルで内部的に公式の openai-java SDK を使用します。移行はスムーズに行われる予定で、既存の OpenAI API プロパティおよびビルダーのユーザーにとって互換性を損なう変更はありません。問題が発生した場合は、Spring AI GitHub の課題 (英語) までご報告ください。

前提条件

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

OpenAI サインアップページ (英語) でアカウントを作成し、API キーページ (英語) でトークンを生成します。

Spring AI プロジェクトでは、openai.com から取得した API Key の値に設定する必要がある spring.ai.openai.api-key という名前の構成プロパティが定義されています。

この構成プロパティは、application.properties ファイルで設定できます。

spring.ai.openai.api-key=<your-openai-api-key>

API キーなどの機密情報を扱う際のセキュリティを強化するために、Spring 式言語 (SpEL) を使用して環境変数を参照できます。

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>

この構成をアプリケーションコード内でプログラム的に設定することもできます。

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");

リポジトリと BOM の追加

Spring AI の成果物は、Maven Central リポジトリと Spring Snapshot リポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリのセクションを参照してください。

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

自動構成

Spring AI の自動構成およびスターターモジュールのアーティファクト名に大幅な変更がありました。詳細については、アップグレードノートを参照してください。

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

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

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

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

埋め込みプロパティ

再試行プロパティ

プレフィックス 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 リクエストに使用するプロジェクトを指定できます。

-

spring.ai.openai.timeout

OpenAI クライアントのリクエストがタイムアウトしました。

60 秒

spring.ai.openai.max-retries

OpenAI クライアントの最大再試行回数。

3

spring.ai.openai.proxy

OpenAI クライアントのプロキシ設定。

-

spring.ai.openai.custom-headers

OpenAI クライアントのリクエストに追加するカスタム HTTP ヘッダー。

空

spring.ai.openai.connection-pool-metrics-enabled

基盤となる OkHttp クライアントの接続プールメトリクスを有効にするかどうか。

false

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

プロパティの構成

埋め込み自動構成の有効化と無効化は、プレフィックス spring.ai.model.embedding を持つ最上位プロパティを介して構成されるようになりました。

有効にするには、spring.ai.model.embedding=openai (デフォルトで有効になっています)

無効にするには、spring.ai.model.embedding=none (または openai と一致しない値)

この変更は、複数のモデルの構成を可能にするために行われます。

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

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

spring.ai.model.embedding

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

開く

spring.ai.openai.embedding.base-url

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

-

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.model

使用するモデル

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

spring.ai.openai.embedding.encoding-format

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

-

spring.ai.openai.embedding.user

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

-

spring.ai.openai.embedding.dimensions

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

-

spring.ai.openai.embedding.extra-body

OpenAI 互換プロバイダーに送信する追加のボディプロパティ。

-

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.chat.base-url および spring.ai.openai.chat.api-key プロパティが設定されている場合は、共通のプロパティよりも優先されます。これは、異なるモデルおよび異なるモデルエンドポイントに異なる OpenAI アカウントを使用する場合に便利です。
spring.ai.openai.embedding というプレフィックスが付いたすべてのプロパティは、リクエスト固有のランタイムオプションを 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()
            .model("Different-Embedding-Model-Deployment-Name")
        .build()));

サンプルコントローラー

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

spring.ai.openai.api-key=YOUR_API_KEY
spring.ai.openai.embedding.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 の部品表をビルドファイルに追加してください。
spring-ai-openai 依存関係により、OpenAiChatModel へのアクセスも提供されます。OpenAiChatModel の詳細については、OpenAI チャットクライアントセクションを参照してください。

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

var embeddingModel = new OpenAiEmbeddingModel(
        MetadataMode.EMBED,
        OpenAiEmbeddingOptions.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .model("text-embedding-ada-002")
                .user("user-6")
                .build());

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

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

HTTP クライアントのカスタマイズ

Spring AI は内部で公式の openai-java SDK を使用し、SpringAiOpenAiHttpClient.Builder によって構築されたカスタムの OkHttp クライアントを使用して HTTP トランスポートを構成します。1 つ以上の OpenAiHttpClientBuilderCustomizer Bean を公開することで、基盤となる OkHttpClient が作成される前にそのビルダーをインターセプトできます。各カスタマイザーは、すべての OpenAI モデル (チャット、埋め込み、イメージ、音声、モデレーション) で使用される同じビルダーを受け取るため、カスタマイズが一律に適用されます。

@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
    void customize(SpringAiOpenAiHttpClient.Builder builder);
}

典型的な使用例としては、以下のようなものがあります。

  • OkHttp および Interceptor インスタンスの登録(認証、伝播ヘッダー、カスタムログ記録)

  • ディスパッチャー ExecutorService を交換します(たとえば、非同期 I/O を仮想スレッド経由でルーティングするため)。

  • プロキシ、SSL、ホスト名の検証、ビルダーによって公開される接続プールのサイズ設定。

複数のカスタマイザーが存在する場合、Spring AI のデフォルト設定の後に @Order / Ordered の順序で適用されるため、ユーザーコードが優先されます。

OpenAi*Model.Builder を介してモデルを手動で接続する場合にも、同じフックが使用できます。

var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder().model("gpt-4o").build())
    .httpClientBuilderCustomizer(myCustomizer)
    .build();