最新の安定バージョンについては、Spring AI 2.0.1 を使用してください! |
OpenAI SDK チャット (正式)
Spring AI は、OpenAI Java SDK を通じて OpenAI の言語モデルをサポートし、Microsoft Foundry や GitHub モデルを含む OpenAI のサービスとの堅牢で公式に保守された統合を提供します。
| この実装では、OpenAI の公式 OpenAI Java SDK [GitHub] (英語) を使用しています。代替の Spring AI 実装については、OpenAI チャットを参照してください。 |
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 Snapshot リポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリのセクションを参照してください。
依存関係の管理を容易にするため、Spring AI には部品表(BOM)が用意されており、プロジェクト全体で一貫したバージョンの Spring AI が使用されるようになっています。Spring AI の部品表をビルドシステムに追加するには、依存関係管理のセクションを参照してください。
自動構成
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 の部品表をビルドファイルに追加してください。 |
プロパティの構成
接続プロパティ
プレフィックス 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 ヘッダー。ヘッダー名とヘッダー値のマップ。 | - |
Microsoft Foundry (Azure OpenAI) のプロパティ
OpenAI SDK 実装は、自動構成による Microsoft Foundry (Azure OpenAI) のネイティブサポートを提供します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
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.chat は、チャットモデルの実装を構成するためのプロパティプレフィックスです。
| プロパティ | 説明 | デフォルト |
|---|---|---|
spring.ai.openai-sdk.chat.options.model | 使用する OpenAI チャットモデルの名前。 |
|
spring.ai.openai-sdk.chat.options.temperature | 生成される補完の明らかな創造性を制御するために使用するサンプリング温度。値が高いほど出力はよりランダムになり、値が低いほど結果はより集中的かつ決定論的になります。これら 2 つの設定の相互作用を予測することは難しいため、同じ補完リクエストに対して | 1.0 |
spring.ai.openai-sdk.chat.options.frequency-penalty | -2.0 から 2.0 までの数値。正の値を指定すると、これまでのテキスト内の既存の頻度に基づいて新しいトークンにペナルティが課され、モデルが同じ行をそのまま繰り返す可能性が低くなります。 | 0.0 |
spring.ai.openai-sdk.chat.options.logit-bias | 指定したトークンが補完に表示される可能性を変更します。 | - |
spring.ai.openai-sdk.chat.options.logprobs | 出力トークンのログ確率を返すかどうか。 | false |
spring.ai.openai-sdk.chat.options.top-logprobs | 各トークン位置で返される可能性が最も高いトークンの数を指定する 0 から 5 までの整数。 | - |
spring.ai.openai-sdk.chat.options.max-tokens | 生成するトークンの最大数。非推論モデルに使用する(例: gpt-4o、gpt-3.5-turbo)。推論モデルでは使用できません(例: o1、o3、o4-mini シリーズ)。maxCompletionTokens とは相互排他的。 | - |
spring.ai.openai-sdk.chat.options.max-completion-tokens | 表示可能な出力トークンと推論トークンを含む、完了に対して生成できるトークンの数の上限。推論モデルに必要 (例: o1、o3、o4-mini シリーズ)。非推論モデルでは使用できません。maxTokens とは相互排他的。 | - |
spring.ai.openai-sdk.chat.options.n | 入力メッセージごとに生成するチャット補完選択肢の数。 | 1 |
spring.ai.openai-sdk.chat.options.output-modalities | 出力形式の一覧。「テキスト」と「オーディオ」を含めることができます。 | - |
spring.ai.openai-sdk.chat.options.output-audio | オーディオ出力のパラメーター。 | - |
spring.ai.openai-sdk.chat.options.presence-penalty | -2.0 から 2.0 までの数値。正の値は、新しいトークンがこれまでのテキストに出現したかどうかに基づいてペナルティを課します。 | 0.0 |
spring.ai.openai-sdk.chat.options.response-format.type | レスポンスフォーマットの種類: | TEXT |
spring.ai.openai-sdk.chat.options.response-format.json-schema | 型が | - |
spring.ai.openai-sdk.chat.options.seed | 指定すると、システムは再現可能な結果を得るために決定論的にサンプリングを行うよう最善を尽くします。 | - |
spring.ai.openai-sdk.chat.options.stop | API がさらなるトークンの生成を停止する最大 4 つのシーケンス。 | - |
spring.ai.openai-sdk.chat.options.top-p | 温度によるサンプリングの代替として、核サンプリングと呼ばれる方法があります。 | - |
spring.ai.openai-sdk.chat.options.user | エンドユーザーを表す一意の識別子。OpenAI が不正使用を監視および検出できます。 | - |
spring.ai.openai-sdk.chat.options.parallel-tool-calls | ツールの使用中に並列関数呼び出しを有効にするかどうか。 | true |
spring.ai.openai-sdk.chat.options.reasoning-effort | 推論モデル | - |
spring.ai.openai-sdk.chat.options.verbosity | モデルのレスポンスの詳細度を制御します。 | - |
spring.ai.openai-sdk.chat.options.store | このチャット補完リクエストの出力を、OpenAI のモデル蒸留または評価製品で使用するために保存するかどうか。 | false |
spring.ai.openai-sdk.chat.options.metadata | ダッシュボードで補完をフィルタリングするために使用される、開発者定義のタグと値。 | - |
spring.ai.openai-sdk.chat.options.service-tier | 使用するレイテンシ層を指定します: | - |
spring.ai.openai-sdk.chat.options.stream-options.include-usage | ストリーミングレスポンスに使用状況統計を含めるかどうか。 | false |
spring.ai.openai-sdk.chat.options.stream-options.include-obfuscation | ストリーミングレスポンスに難読化を含めるかどうか。 | false |
spring.ai.openai-sdk.chat.options.tool-choice | モデルによって呼び出される関数(ある場合)を制御します。 | - |
spring.ai.openai-sdk.chat.options.internal-tool-execution-enabled | false の場合、Spring AI はツール呼び出しをクライアントにプロキシし、クライアントが手動で処理できるようにします。true(デフォルト)の場合、Spring AI は関数呼び出しを内部的に処理します。 | true |
|
spring.ai.openai-sdk.chat.options で始まるすべてのプロパティは、リクエスト固有のランタイムオプションを Prompt 呼び出しに追加することによって実行時にオーバーライドできます。 |
トークン制限パラメーター: モデル固有の使用箇所
OpenAI は、トークン生成制限を制御するための相互に排他的な 2 つのパラメーターを提供します。
| パラメーター | ユースケース | 対応モデル |
|---|---|---|
| 非推論モデル | gpt-4o、gpt-4o-mini、gpt-4-turbo、gpt-3.5-turbo |
| 推論モデル | o1、o1-mini、o1-preview、o3、o4-mini シリーズ |
| これらのパラメーターは相互に排他的です。両方を設定すると、OpenAI から API エラーが発生します。 |
使用例
非推論モデル(gpt-4o、gpt-3.5-turbo)の場合:
ChatResponse response = chatModel.call(
new Prompt(
"Explain quantum computing in simple terms.",
OpenAiSdkChatOptions.builder()
.model("gpt-4o")
.maxTokens(150) // Use maxTokens for non-reasoning models
.build()
));推論モデル(o1、o3 シリーズ)の場合:
ChatResponse response = chatModel.call(
new Prompt(
"Solve this complex math problem step by step: ...",
OpenAiSdkChatOptions.builder()
.model("o1-preview")
.maxCompletionTokens(1000) // Use maxCompletionTokens for reasoning models
.build()
));ランタイムオプション
OpenAiSdkChatOptions.java [GitHub] (英語) クラスは、使用するモデル、温度、周波数ペナルティなどのモデル構成を提供します。
起動時に、OpenAiSdkChatModel(options) コンストラクターまたは spring.ai.openai-sdk.chat.options.* プロパティを使用してデフォルトのオプションを構成できます。
実行時に、Prompt 呼び出しに新しいリクエスト固有のオプションを追加することで、デフォルトのオプションをオーバーライドできます。例: 特定のリクエストのデフォルトのモデルと温度をオーバーライドするには、次のようにします。
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OpenAiSdkChatOptions.builder()
.model("gpt-4o")
.temperature(0.4)
.build()
));| モデル固有の OpenAiSdkChatOptions [GitHub] (英語) に加えて、ChatOptions#builder() [GitHub] (英語) で作成されたポータブル ChatOptions [GitHub] (英語) インスタンスを使用することもできます。 |
ツール呼び出し
OpenAiSdkChatModel にカスタム Java 関数またはメソッドを登録すると、OpenAI モデルは登録された関数 / ツールのいずれか、あるいは複数を呼び出すための引数を含む JSON オブジェクトをインテリジェントに出力します。これは、LLM の機能を外部ツールや API に接続するための強力な手法です。ツール呼び出しの詳細については、こちらを参照してください。
使用例:
var chatOptions = OpenAiSdkChatOptions.builder()
.toolCallbacks(List.of(
FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
.description("Get the weather in location")
.inputType(WeatherService.Request.class)
.build()))
.build();
ChatResponse response = chatModel.call(
new Prompt("What's the weather like in San Francisco?", chatOptions));マルチモーダル
マルチモーダル性とは、テキスト、イメージ、音声、その他のデータ形式を含むさまざまなソースからの情報を同時に理解して処理するモデルの機能を指します。
Vision
ビジョンマルチモーダルサポートを提供する OpenAI モデルには、gpt-4、gpt-4o、gpt-4o-mini が含まれます。詳細については、Vision (英語) ガイドを参照してください。
Spring AI のメッセージ [GitHub] (英語) インターフェースは、メディア [GitHub] (英語) 型を導入することで、マルチモーダル AI モデルを容易にします。
以下は、ユーザーテキストとイメージの融合を示すコード例です。
var imageResource = new ClassPathResource("/multimodal.test.png");
var userMessage = new UserMessage(
"Explain what do you see on this picture?",
List.of(new Media(MimeTypeUtils.IMAGE_PNG, imageResource)));
ChatResponse response = chatModel.call(
new Prompt(userMessage,
OpenAiSdkChatOptions.builder()
.model("gpt-4o")
.build()));またはイメージ URL を使用する:
var userMessage = new UserMessage(
"Explain what do you see on this picture?",
List.of(Media.builder()
.mimeType(MimeTypeUtils.IMAGE_PNG)
.data(URI.create("https://docs.spring.io/spring-ai/reference/_images/multimodal.test.png"))
.build()));
ChatResponse response = chatModel.call(new Prompt(userMessage));| 複数のイメージを渡すこともできます。 |
音声
オーディオ入力をサポートする OpenAI モデルには、gpt-4o-audio-preview が含まれます。詳細については、音声 (英語) ガイドを参照してください。
Spring AI supports base64-encoded audio files with the message. Currently, OpenAI supports the following media types: audio/mp3 and audio/wav.
音声入力の例:
var audioResource = new ClassPathResource("speech1.mp3");
var userMessage = new UserMessage(
"What is this recording about?",
List.of(new Media(MimeTypeUtils.parseMimeType("audio/mp3"), audioResource)));
ChatResponse response = chatModel.call(
new Prompt(userMessage,
OpenAiSdkChatOptions.builder()
.model("gpt-4o-audio-preview")
.build()));オーディオ出力
gpt-4o-audio-preview モデルは音声レスポンスを生成できます。
オーディオ出力を生成する例:
var userMessage = new UserMessage("Tell me a joke about Spring Framework");
ChatResponse response = chatModel.call(
new Prompt(userMessage,
OpenAiSdkChatOptions.builder()
.model("gpt-4o-audio-preview")
.outputModalities(List.of("text", "audio"))
.outputAudio(new AudioParameters(Voice.ALLOY, AudioResponseFormat.WAV))
.build()));
String text = response.getResult().getOutput().getText(); // audio transcript
byte[] waveAudio = response.getResult().getOutput().getMedia().get(0).getDataAsByteArray(); // audio data構造化された出力
OpenAI は、提供された JSON Schema に厳密に準拠したレスポンスをモデルが生成することを保証するカスタム構造化された出力 (英語) API を提供します。
構成
OpenAiSdkChatOptions ビルダーを使用して、レスポンス形式をプログラムで設定できます。
String jsonSchema = """
{
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"explanation": { "type": "string" },
"output": { "type": "string" }
},
"required": ["explanation", "output"],
"additionalProperties": false
}
},
"final_answer": { "type": "string" }
},
"required": ["steps", "final_answer"],
"additionalProperties": false
}
""";
Prompt prompt = new Prompt(
"how can I solve 8x + 7 = -23",
OpenAiSdkChatOptions.builder()
.model("gpt-4o-mini")
.responseFormat(ResponseFormat.builder()
.type(ResponseFormat.Type.JSON_SCHEMA)
.jsonSchema(jsonSchema)
.build())
.build());
ChatResponse response = chatModel.call(prompt);BeanOutputConverter との統合
既存の BeanOutputConverter ユーティリティを活用できます。
record MathReasoning(
@JsonProperty(required = true, value = "steps") Steps steps,
@JsonProperty(required = true, value = "final_answer") String finalAnswer) {
record Steps(
@JsonProperty(required = true, value = "items") Items[] items) {
record Items(
@JsonProperty(required = true, value = "explanation") String explanation,
@JsonProperty(required = true, value = "output") String output) {
}
}
}
var outputConverter = new BeanOutputConverter<>(MathReasoning.class);
String jsonSchema = outputConverter.getJsonSchema();
Prompt prompt = new Prompt(
"how can I solve 8x + 7 = -23",
OpenAiSdkChatOptions.builder()
.model("gpt-4o-mini")
.responseFormat(ResponseFormat.builder()
.type(ResponseFormat.Type.JSON_SCHEMA)
.jsonSchema(jsonSchema)
.build())
.build());
ChatResponse response = chatModel.call(prompt);
MathReasoning mathReasoning = outputConverter.convert(
response.getResult().getOutput().getText());サンプルコントローラー
新しい 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.chat.options.model=gpt-5-mini
spring.ai.openai-sdk.chat.options.temperature=0.7api-key を OpenAI の資格情報に置き換えます。 |
これにより、クラスに挿入できる OpenAiSdkChatModel 実装が作成されます。以下は、テキスト生成にチャットモデルを使用する単純な @RestController クラスの例です。
@RestController
public class ChatController {
private final OpenAiSdkChatModel chatModel;
@Autowired
public ChatController(OpenAiSdkChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map<String,String> generate(
@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(
@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
Prompt prompt = new Prompt(new UserMessage(message));
return chatModel.stream(prompt);
}
}手動構成
OpenAiSdkChatModel [GitHub] (英語) は ChatModel を実装し、公式の OpenAI Java SDK を使用して OpenAI サービスに接続します。
spring-ai-openai-sdk 依存関係をプロジェクトの Maven pom.xml ファイルに追加します。
<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 の部品表をビルドファイルに追加してください。 |
次に、OpenAiSdkChatModel を作成し、テキスト生成に使用します。
var chatOptions = OpenAiSdkChatOptions.builder()
.model("gpt-4o")
.temperature(0.7)
.apiKey(System.getenv("OPENAI_API_KEY"))
.build();
var chatModel = OpenAiSdkChatModel.builder()
.options(chatOptions)
.build();
ChatResponse response = chatModel.call(
new Prompt("Generate the names of 5 famous pirates."));
// Or with streaming responses
Flux<ChatResponse> response = chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));Microsoft Foundry 構成
Microsoft Foundry の場合:
var chatOptions = OpenAiSdkChatOptions.builder()
.baseUrl("https://your-resource.openai.azure.com")
.apiKey(System.getenv("OPENAI_API_KEY"))
.deploymentName("gpt-4")
.azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
.azure(true) // Enables Microsoft Foundry mode
.build();
var chatModel = OpenAiSdkChatModel.builder()
.options(chatOptions)
.build();Microsoft Foundry はパスワードレス認証をサポートしています。プロジェクトに com.azure:azure-identity 依存関係を追加してください。API キーを指定しない場合、実装は自動的に環境の Azure 認証情報を使用しようとします。 |
Key Differences from Spring AI OpenAI
この実装は、Spring AI OpenAI 実装とはいくつかの点で異なります。
| アスペクト | 公式 OpenAI SDK | 既存の OpenAI |
|---|---|---|
HTTP クライアント | OkHttp (公式 SDK 経由) | Spring RestClient/WebClient |
API アップデート | SDK アップデートによる自動 | 手動メンテナンス |
Azure サポート | パスワードレス認証を備えたネイティブ | 手動 URL 構築 |
GitHub モデル | ネイティブサポート | 未サポート |
オーディオ / モデレーション | まだサポートされていません | 完全にサポートされています |
再試行ロジック | SDK 管理 (指数バックオフ) | Spring Retry (カスタマイズ可能) |
依存関係 | 公式 OpenAI SDK |
OpenAI SDK を使用する場合:
新しいプロジェクトを始める
主に Microsoft Foundry または GitHub モデルを使用する
OpenAI からの自動 API アップデートを希望
音声文字変換やモデレーション機能は必要ありません
公式 SDK サポートを希望する
When to use Spring AI OpenAI:
既存のプロジェクトでそれを使用しています
音声文字起こし機能またはモデレーション機能が必要です
きめ細かな HTTP 制御が必要です
ネイティブの Spring リアクティブサポートが必要ですか?
カスタム再試行戦略が必要です
可観測性
The OpenAI SDK implementation supports Spring AI’s observability features through Micrometer. All chat model operations are instrumented for monitoring and tracing.
制限
OpenAI SDK の実装では、以下の機能はまだサポートされていません。
音声生成 (TTS)
音声文字起こし
モデレーション API
ファイル API 操作
これらの機能は Spring AI OpenAI の実装で利用可能です。