このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.1.2 を使用してください。 |
OpenAI SDK 埋め込み (正式)
Spring AI は、OpenAI Java SDK を通じて OpenAI のテキスト埋め込みモデルをサポートし、Microsoft Foundry や GitHub モデルなどの OpenAI のサービスとの堅牢かつ公式にメンテナンスされた統合を提供します。
| この実装は OpenAI の公式 OpenAI Java SDK [GitHub] (英語) を使用しています。Spring の代替 AI 実装については、OpenAI 埋め込みを参照してください。 |
OpenAI のテキスト埋め込みは、テキスト文字列の関連性を測定します。埋め込みは浮動小数点数のベクトル（リスト）です。2 つのベクトル間の距離は、それらの関連性を測定します。距離が小さいほど関連性が高く、距離が大きいほど関連性が低いことを示します。
OpenAI SDK モジュールは、指定されたベース URL に基づいてサービスプロバイダー (OpenAI、Microsoft Foundry、または GitHub モデル) を自動的に検出します。
認証
認証はベース URL と API キーを使用して行われます。実装では、Spring Boot プロパティまたは環境変数を通じて柔軟な設定オプションが提供されます。
OpenAI の使用
OpenAI を直接使用している場合は、OpenAI サインアップページ (英語) でアカウントを作成し、API キーページ (英語) で API キーを生成します。
ベース URL はデフォルトで api.openai.com/v1 (英語) に設定されるため、設定する必要はありません。
spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1または環境変数を使用します:
export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1Microsoft Foundry の使用
Microsoft Foundry URL を使用すると、Microsoft Foundry が自動的に検出されます。以下のプロパティを使用して設定できます。
spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>または環境変数を使用します:
export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>パスワードレス認証（Azure に推奨）:
Microsoft Foundry は、API キーを提供せずにパスワードレス認証をサポートしており、Azure で実行する場合の安全性が高まります。
パスワードレス認証を有効にするには、com.azure:azure-identity 依存関係を追加します。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>次に、API キーなしで設定します。
spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environmentGitHub モデルの使用
GitHub モデルのベース URL を使用すると、GitHub モデルが自動的に検出されます。models:read スコープで GitHub パーソナルアクセストークン（PAT）を作成する必要があります。
spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXXまたは環境変数を使用します:
export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX| API キーなどの機密情報を扱う際のセキュリティを強化するために、プロパティで Spring 式言語 (SpEL) を使用できます。 |
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}リポジトリと BOM の追加
Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。
依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。
自動構成
Spring AI は、OpenAI SDK 埋め込みモデル用の Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml または Gradle build.gradle ビルドファイルに以下の依存関係を追加してください。
Maven
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}| Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。 |
プロパティの構成
接続プロパティ
プレフィックス spring.ai.openai-sdk は、OpenAI SDK クライアントを構成できるプロパティプレフィックスとして使用されます。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.openai-sdk.base-url | 接続先の URL。設定されていない場合は、 | |
spring.ai.openai-sdk.api-key | API キー。設定されていない場合は、 | - |
spring.ai.openai-sdk.organization-id | 必要に応じて、API リクエストに使用する組織を指定します。 | - |
spring.ai.openai-sdk.timeout | リクエストのタイムアウト期間。 | - |
spring.ai.openai-sdk.max-retries | 失敗したリクエストの最大再試行回数。 | - |
spring.ai.openai-sdk.proxy | OpenAI クライアント (Java | - |
spring.ai.openai-sdk.custom-headers | リクエストに含めるカスタム HTTP ヘッダー。ヘッダー名とヘッダー値のマップ。 | - |
マイクロソフトファウンドリープロパティ
OpenAI SDK 実装は、自動構成による Microsoft Foundry のネイティブサポートを提供します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.openai-sdk.microsoft-foundry | Microsoft Foundry モードを有効にします。ベース URL に | false |
spring.ai.openai-sdk.microsoft-deployment-name | Microsoft Foundry デプロイ名。指定されていない場合はモデル名が使用されます。エイリアス | - |
spring.ai.openai-sdk.microsoft-foundry-service-version | Microsoft Foundry API サービスバージョン。 | - |
spring.ai.openai-sdk.credential | パスワードレス認証用の資格情報オブジェクト ( | - |
Microsoft Foundry はパスワードレス認証をサポートしています。com.azure:azure-identity 依存関係を追加すると、API キーが提供されていない場合、実装は自動的に環境から Azure の資格情報を使用しようとします。 |
GitHub モデルのプロパティ
GitHub モデルのネイティブサポートが利用可能です:
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.openai-sdk.github-models | GitHub モデルモードを有効にします。ベース URL に | false |
GitHub モデルには、models:read スコープの個人アクセストークンが必要です。OPENAI_API_KEY 環境変数または spring.ai.openai-sdk.api-key プロパティで設定してください。 |
埋め込みモデルのプロパティ
プレフィックス spring.ai.openai-sdk.embedding は、埋め込みモデルの実装を構成するためのプロパティプレフィックスです。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.openai-sdk.embedding.metadata-mode | ドキュメントコンテンツ抽出モード。 | EMBED |
spring.ai.openai-sdk.embedding.options.model | The model to use. You can select between models such as: |
|
spring.ai.openai-sdk.embedding.options.user | エンドユーザーを表す一意の識別子。OpenAI が不正使用を監視および検出できます。 | - |
spring.ai.openai-sdk.embedding.options.dimensions | 結果として得られる出力埋め込みの次元数。 | - |
spring.ai.openai-sdk.embedding.options で始まるすべてのプロパティは、リクエスト固有のランタイムオプションを EmbeddingRequest 呼び出しに追加することによって実行時にオーバーライドできます。 |
ランタイムオプション
OpenAiSdkEmbeddingOptions.java [GitHub] (英語) は、使用するモデル、寸法、ユーザー ID などの OpenAI 構成を提供します。
デフォルトのオプションは、spring.ai.openai-sdk.embedding.options プロパティを使用して構成することもできます。
開始時に、OpenAiSdkEmbeddingModel コンストラクターを使用して、すべての埋め込みリクエストに使用されるデフォルトのオプションを設定します。実行時に、OpenAiSdkEmbeddingOptions インスタンスを EmbeddingRequest の一部として使用して、デフォルトのオプションをオーバーライドできます。
たとえば、特定のリクエストのデフォルトのモデル名をオーバーライドするには、次のようにします。
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-3-large")
.dimensions(1024)
.build()));| モデル固有の OpenAiSdkEmbeddingOptions [GitHub] (英語) に加えて、ビルダーで作成されたポータブル EmbeddingOptions [GitHub] (英語) インスタンスを使用することもできます。 |
サンプルコントローラー
新しい Spring Boot プロジェクトを作成し、spring-ai-openai-sdk を pom (または gradle) の依存関係に追加します。
src/main/resources ディレクトリに application.properties ファイルを追加して、OpenAI SDK 埋め込みモデルを構成します。
spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.embedding.options.model=text-embedding-ada-002api-key を OpenAI の資格情報に置き換えます。 |
これにより、クラスに注入できる OpenAiSdkEmbeddingModel 実装が作成されます。埋め込みモデルを使用するシンプルな @RestController クラスの例を以下に示します。
@RestController
public class EmbeddingController {
private final EmbeddingModel embeddingModel;
@Autowired
public EmbeddingController(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
@GetMapping("/ai/embedding")
public Map<String, Object> embed(
@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
return Map.of("embedding", embeddingResponse);
}
}手動構成
OpenAiSdkEmbeddingModel [GitHub] (英語) は EmbeddingModel を実装し、公式の OpenAI Java SDK を使用して OpenAI サービスに接続します。
Spring Boot の自動構成を使用していない場合は、OpenAI SDK 埋め込みモデルを手動で設定できます。そのためには、プロジェクトの Maven pom.xml ファイルに spring-ai-openai-sdk の依存関係を追加します。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-sdk</artifactId>
</dependency> または、Gradle build.gradle ビルドファイルに次の内容を追加します。
dependencies {
implementation 'org.springframework.ai:spring-ai-openai-sdk'
}| Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。 |
spring-ai-openai-sdk 依存関係は、OpenAiSdkChatModel および OpenAiSdkImageModel へのアクセスも提供します。OpenAiSdkChatModel の詳細については、OpenAI SDK チャットセクションを参照してください。 |
次に、OpenAiSdkEmbeddingModel インスタンスを作成し、それを使用して 2 つの入力テキスト間の類似性を計算します。
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.model("text-embedding-ada-002")
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
EmbeddingResponse embeddingResponse = embeddingModel
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));OpenAiSdkEmbeddingOptions は、埋め込みリクエストの構成情報を提供します。オプションクラスは、オプションを簡単に作成できる builder() を提供します。
Microsoft Foundry 構成
Microsoft Foundry の場合:
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://your-resource.openai.azure.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.deploymentName("text-embedding-ada-002")
.azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
.azure(true) // Enables Microsoft Foundry mode
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);Microsoft Foundry はパスワードレス認証をサポートしています。プロジェクトに com.azure:azure-identity 依存関係を追加してください。API キーを指定しない場合、実装は自動的に環境の Azure 認証情報を使用しようとします。 |
GitHub モデル構成
GitHub モデルの場合:
var embeddingOptions = OpenAiSdkEmbeddingOptions.builder()
.baseUrl("https://models.inference.ai.azure.com")
.apiKey(System.getenv("GITHUB_TOKEN"))
.model("text-embedding-3-large")
.githubModels(true)
.build();
var embeddingModel = new OpenAiSdkEmbeddingModel(embeddingOptions);
