跳到主要内容

OpenAI公式SDK

备注

これは OpenAI Official SDK 統合のドキュメントで、公式 OpenAI Java SDK を使用します。

LangChain4jはチャットモデル用に3つの異なるOpenAI統合を提供しており、これはその#2です:

  • OpenAIはOpenAI REST APIのカスタムJava実装を使用し、Quarkus(Quarkus RESTクライアントを使用)およびSpring(SpringのRestClientを使用)で最もよく動作します。
  • OpenAI Official SDKは公式のOpenAI Java SDKを使用します。
  • Azure OpenAIはMicrosoftのAzure SDKを使用し、高度なAzure認証メカニズムを含むMicrosoft Javaスタックを使用している場合に最もよく動作します。

この統合のユースケース​

この統合はOpenAI Java SDK GitHubリポジトリを使用し、次から提供されるすべてのOpenAIモデルで動作します:

  • OpenAI
  • Microsoft Foundry
  • GitHub Models

DeepSeekなど、OpenAI APIをサポートするモデルでも動作します。

OpenAIドキュメント​

Maven依存関係​

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-official</artifactId>
<version>1.23.0-beta33</version>
</dependency>

モデルの設定​

备注

この設定、および次の使用方法のセクションは、非ストリーミングモード(「ブロッキング」または「同期」モードとも呼ばれます)向けです。 ストリーミングモードは2セクション後で詳しく説明します。モデルとのリアルタイムチャットが可能ですが、使用はより複雑です。

OpenAIモデルを使用するには、通常エンドポイントURL、APIキー、モデル名が必要です。これはモデルのホスト場所によって異なり、この統合は 自動構成により設定を容易にしようとします:

汎用設定​

import com.openai.models.ChatModel;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openaiofficial.OpenAiOfficialChatModel;

import static com.openai.models.ChatModel.GPT_5_MINI;

// ....

ChatModel model = OpenAiOfficialChatModel.builder()
.baseUrl(System.getenv("OPENAI_BASE_URL"))
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_5_MINI)
.build();

OpenAI設定​

OpenAIのbaseUrl(https://api.openai.com/v1)がデフォルトのため、省略できます:

ChatModel model = OpenAiOfficialChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_5_MINI)
.build();

Azure OpenAI設定​

汎用設定​

Azure OpenAIではbaseUrlの設定が必須で、URLがopenai.azure.comで終わる場合はAzure OpenAIが自動検出されます:

ChatModel model = OpenAiOfficialChatModel.builder()
.baseUrl(System.getenv("AZURE_OPENAI_ENDPOINT"))
.apiKey(System.getenv("AZURE_OPENAI_KEY"))
.modelName(GPT_5_MINI)
.build();

Azure OpenAIの使用を強制したい場合は、isAzure()メソッドも使用できます:

ChatModel model = OpenAiOfficialChatModel.builder()
.baseUrl(System.getenv("AZURE_OPENAI_ENDPOINT"))
.apiKey(System.getenv("AZURE_OPENAI_KEY"))
.isAzure(true)
.modelName(GPT_5_MINI)
.build();

パスワードレス認証​

「パスワードレス」認証を使用してAzure OpenAIに認証できます。APIキーを管理しないため、より安全です。

そのためには、まずAzure OpenAIインスタンスがマネージドIDをサポートするよう構成し、次にこのアプリケーションにアクセス権を付与します。例:

# Enable system managed identity on the Azure OpenAI instance
az cognitiveservices account identity assign \
--name <your-openai-instance-name> \
--resource-group <your-resource-group>

# Get your logged-in identity
az ad signed-in-user show \
--query id -o tsv

# Give access to the Azure OpenAI instance
az role assignment create \
--role "Cognitive Services OpenAI User" \
--assignee <your-logged-identity-from-the-previous-command> \
--scope "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>"

次に、Maven の pom.xml に azure-identity 依存関係を追加する必要があります:

<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>

APIキーが構成されていない場合、LangChain4jは自動的にAzure OpenAIのパスワードレス認証を使用します。

GitHub Models設定​

GitHub Modelsでは、デフォルトのbaseUrl(https://models.inference.ai.azure.com)を使用できます:

ChatModel model = OpenAiOfficialChatModel.builder()
.baseUrl("https://models.inference.ai.azure.com")
.apiKey(System.getenv("GITHUB_TOKEN"))
.modelName(GPT_5_MINI)
.build();

または、isGitHubModels()メソッドを使用してGitHub Modelsの使用を強制でき、baseUrlが自動設定されます:

ChatModel model = OpenAiOfficialChatModel.builder()
.apiKey(System.getenv("GITHUB_TOKEN"))
.modelName(GPT_5_MINI)
.isGitHubModels(true)
.build();

GitHub Modelsは通常、GitHub ActionsまたはGitHub Codespaces使用時に自動入力されるGITHUB_TOKEN環境変数で構成されるため、自動検出されます:

ChatModel model = OpenAiOfficialChatModel.builder()
.modelName(GPT_5_MINI)
.isGitHubModels(true)
.build();

この最後の構成は使いやすく、GITHUB_TOKEN環境変数がコードやGitHubログに露出しないため、より安全です。

モデルの使用​

前のセクションでは、ChatModel インターフェースを実装する OpenAiOfficialChatModel オブジェクトを作成しました。

AI Serviceで使用するか、Javaアプリケーションで直接使用できます。

この例では、Spring Beanとしてオートワイヤリングされています:

@RestController
class ChatModelController {

ChatModel chatModel;

ChatModelController(ChatModel chatModel) {
this.chatModel = chatModel;
}

@GetMapping("/model")
public String model(@RequestParam(value = "message", defaultValue = "Hello") String message) {
return chatModel.chat(message);
}
}

構造化出力​

構造化出力機能は ツールとレスポンスフォーマットの両方でサポートされています。

構造化出力の詳細はこちらをご覧ください。

構造化出力 for Tools​

ツールの構造化出力機能を有効にするには、モデル構築時に.strictTools(true)を設定します:

OpenAiOfficialChatModel.builder()
// ...
.strictTools(true)
.build();

これにより、現在のOpenAIの制限により、すべてのツールパラメータが必須(JSONスキーマではrequired)になり、 JSON スキーマ内の各 object に additionalProperties=false が設定されます。

構造化出力 for Response Format​

AIサービス使用時にレスポンスフォーマット用の構造化出力機能を有効にするには、 モデル構築時にsupportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))と.strictJsonSchema(true)を設定します:

import static dev.langchain4j.model.chat.Capability.RESPONSE_FORMAT_JSON_SCHEMA;

// ...

OpenAiChatModel.builder()
// ...
.supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))
.strictJsonSchema(true)
.build();

この場合、AIサービスは指定されたPOJOからJSONスキーマを自動生成し、LLMに渡します。

モデルの設定 for streaming​

备注

上記の 2 つのセクションでは、非ストリーミングモード(「ブロッキング」または「同期」モードとも呼ばれます)でのモデルの設定方法を詳しく説明しました。 このセクションはストリーミングモード用であり、モデルとのリアルタイムチャットを可能にしますが、使用はより複雑です。

これは非ストリーミングモードと似ていますが、OpenAiOfficialChatModel の代わりに OpenAiOfficialStreamingChatModel クラスを使用する必要があります:

StreamingChatModel model = OpenAiOfficialStreamingChatModel.builder()
.baseUrl(System.getenv("OPENAI_BASE_URL"))
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_5_MINI)
.build();

非ストリーミング設定セクションで詳述されているように、特定のisAzure()およびisGitHubModels()メソッドを使用して、Azure OpenAIまたはGitHub Modelsの使用を強制することもできます。

プロンプトキャッシュ(Prompt Caching)​

OpenAI は、長く繰り返されるプロンプトのプレフィックスをキャッシュし、キャッシュの読み取りを入力料金のごく一部で課金します。 以下の制御は、Chat Completions API のモデルと Responses API のモデルの両方で機能します。

プロンプトキャッシュの詳細はこちらを参照してください。

promptCacheKey と promptCacheOptions​

promptCacheKey は任意の文字列で、ルーティングを誘導し、関連するリクエストがキャッシュエントリを保持するマシンに到達する可能性を高めます。リクエストを特定のマシンに固定するものではなく、キャッシュヒットを保証するものでもありません。

gpt-5.6 以降は、ブレークポイントでキャッシュされたプレフィックスを完全一致で照合し、より短いマークされていないプレフィックスにはフォールバックしません。promptCacheOptions は、ブレークポイントの発生元を制御します:

  • implicit - OpenAI が、最新の対象メッセージの末尾にブレークポイントを置きます。
  • explicit - 設定したブレークポイントのみが使用されます。ブレークポイントがない場合、何もキャッシュされません。

Responses API のモデルでは、どちらもモデルビルダーで利用できます:

OpenAiOfficialResponsesChatModel model = OpenAiOfficialResponsesChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5.6")
.promptCacheKey("satisfaction_judge_v1")
.promptCacheOptions(OpenAiOfficialPromptCacheOptions.builder()
.mode(OpenAiOfficialPromptCacheOptions.MODE_EXPLICIT)
.ttl(OpenAiOfficialPromptCacheOptions.TTL_30M)
.build())
.build();

Chat Completions API のモデルでは、OpenAiOfficialChatRequestParameters を通じて、モデルのデフォルトとして、またはリクエストごとに設定します:

OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5.6")
.defaultRequestParameters(OpenAiOfficialChatRequestParameters.builder()
.promptCacheKey("satisfaction_judge_v1")
.promptCacheOptions(OpenAiOfficialPromptCacheOptions.explicit())
.build())
.build();

OpenAiOfficialPromptCacheOptions.implicit() と OpenAiOfficialPromptCacheOptions.explicit() は、モードのみを設定するオプションの省略形です。

promptCacheOptions.ttl は promptCacheRetention(gpt-5.6 より古いモデルに適用)より優先されます。 OpenAI は、両方を含むリクエストを拒否します。

promptCacheBreakpoint​

SystemMessage、UserMessage、ToolExecutionResultMessage はそれぞれ、プロンプトキャッシュのブレークポイントとしてマークできます。プロンプトキャッシュはプレフィックスベースであるため、ブレークポイントはマークされたメッセージの最後のコンテンツブロックに適用され、そのメッセージまでのすべてがキャッシュされるプレフィックスになります。

OpenAiOfficialPromptCacheBreakpoint.mark() は、元のメッセージには手を加えず、マークされたコピーを返します:

SystemMessage systemMessage = OpenAiOfficialPromptCacheBreakpoint.mark(SystemMessage.from(SHARED_INSTRUCTIONS));

UserMessage userMessage = OpenAiOfficialPromptCacheBreakpoint.mark(UserMessage.from(LONG_DOCUMENT));

ToolExecutionResultMessage toolResult = OpenAiOfficialPromptCacheBreakpoint.mark(someToolExecutionResultMessage);

マークは実際にはメッセージの属性にすぎないため、手動で行うこともできます。たとえば、すでにメッセージを構築している場合などです:

SystemMessage systemMessage = SystemMessage.builder()
.text(SHARED_INSTRUCTIONS)
.attributes(Map.of(OpenAiOfficialPromptCacheBreakpoint.ATTRIBUTE_KEY,
OpenAiOfficialPromptCacheBreakpoint.MODE_EXPLICIT))
.build();

メッセージをマークすると、LangChain4j はそのメッセージの内容をコンテンツブロックのリストとして送信します。プレーンな文字列形式ではブレークポイントを持てないためです。

AiMessage はブレークポイントを持てません。アシスタントの出力ブロックは、OpenAI がブレークポイントを受け付けるブロックタイプに含まれないためです。AiMessage をマークしたり、explicit 以外のモードを使用したりすると、HTTP 400 を発生させる代わりに、即座に失敗します。

各リクエストは最大 4 回のキャッシュ書き込みをサポートし、そのうち 1 回は implicit モードで消費されます。

キャッシュのトークン数の読み取り​

OpenAiOfficialTokenUsage.InputTokensDetails は、プロンプトキャッシュから読み取られた入力トークン数と書き込まれた入力トークン数を報告します:

OpenAiOfficialTokenUsage tokenUsage = (OpenAiOfficialTokenUsage) chatResponse.tokenUsage();

tokenUsage.inputTokensDetails().cachedTokens(); // tokens read from the cache
tokenUsage.inputTokensDetails().cacheWriteTokens(); // tokens written to the cache

モデルプロバイダーが報告しなかった場合、cacheWriteTokens() は null を返します。これは、報告されたゼロとは区別されます。

OpenAI Responses API​

备注

この機能は実験的であり、将来のリリースで変更される可能性があります。

OpenAIのResponses API(/v1/responses)は、Chat Completions APIの代替です。

OpenAiOfficialResponsesChatModelの作成​

ChatModel model = OpenAiOfficialResponsesChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5.4")
.build();

OpenAiOfficialResponsesStreamingChatModelの作成​

StreamingChatModel model = OpenAiOfficialResponsesStreamingChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName(GPT_5_MINI)
.build();

OpenAiOfficialResponsesChatRequestParametersを使用してデフォルトのリクエストパラメータを構成することもできます:

StreamingChatModel model = OpenAiOfficialResponsesStreamingChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.defaultRequestParameters(OpenAiOfficialResponsesChatRequestParameters.builder()
.modelName("gpt-4o-mini")
.previousResponseId("resp_abc123")
.reasoningEffort("medium")
.store(true)
.build())
.build();

OpenAiOfficialResponsesChatRequestParameters​

OpenAiOfficialResponsesChatRequestParametersはDefaultChatRequestParametersを拡張し、Responses API固有のフィールドを追加します: previousResponseId、maxToolCalls、parallelToolCalls、topLogprobs、truncation、include、 serviceTier、safetyIdentifier、promptCacheKey、promptCacheRetention、promptCacheOptions、 reasoningEffort、reasoningSummary、textVerbosity、streamIncludeObfuscation、store、strictTools、 strictJsonSchema。

これらのパラメータは、モデル作成時に(ビルダー上のdefaultRequestParameters経由で)デフォルトとして構成するか、 ChatRequest経由でリクエストごとに渡すことができます(リクエストごとのパラメータがデフォルトを上書きします):

ChatRequest chatRequest = ChatRequest.builder()
.messages(UserMessage.from("Hello"))
.parameters(OpenAiOfficialResponsesChatRequestParameters.builder()
.modelName("gpt-4o-mini")
.previousResponseId("resp_abc123")
.store(true)
.build())
.build();

思考 / 推論​

OpenAIの推論モデル(例:gpt-5.4、gpt-5-mini)は、 推論サマリー をサポートします。

推論サマリーを有効にするには、ビルダーで reasoningSummary を Reasoning.Summary.AUTO に設定します (または OpenAiOfficialResponsesChatRequestParameters 経由で)。 reasoningEffortでモデルが推論にかける労力も制御できます。

ChatModel model = OpenAiOfficialResponsesChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5-mini")
.reasoningEffort(ReasoningEffort.LOW)
.reasoningSummary(Reasoning.Summary.AUTO)
.build();

ChatResponse response = model.chat("What is the capital of Germany?");
response.aiMessage().text(); // "The capital of Germany is Berlin."
response.aiMessage().thinking(); // reasoning summary text

OpenAiOfficialResponsesStreamingChatModel に reasoningSummary が設定されている場合、推論サマリーのトークンがストリーミングされるのに合わせて StreamingChatResponseHandler.onPartialThinking()コールバックが呼び出されます:

StreamingChatModel model = OpenAiOfficialResponsesStreamingChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5-mini")
.reasoningEffort(ReasoningEffort.LOW)
.reasoningSummary(Reasoning.Summary.AUTO)
.build();

AiMessage.thinking()内の推論サマリーは情報提供用であり、後続リクエストで送り返す必要はありません ——OpenAIはターン間でそれを破棄します。モデルの推論状態をターン間で実際に保持するには (例:ツール呼び出しの間)、以下で説明する暗号化推論を使用してください。

暗号化推論(コンテキスト内で推論を保持)​

storeがfalse(デフォルト)の場合、または組織がゼロデータ保持の場合、 モデルの推論コンテキストはターン間で失われます。 暗号化された推論コンテンツ を include パラメータでリクエストします:

ChatModel model = OpenAiOfficialResponsesChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-5-mini")
.reasoningEffort(ReasoningEffort.MEDIUM)
.include(List.of("reasoning.encrypted_content"))
.build();

includeに"reasoning.encrypted_content"が含まれる場合、レスポンスの推論アイテムは 不透明な暗号化blobを含みます。これは自動的に AiMessage.attributes()のキー"encrypted_reasoning"の下に格納されます。

後続リクエストでそのAiMessageを返すと(例:ツール呼び出し後)、 暗号化推論が自動的にリクエストに含まれ、 モデルが推論コンテキストを再開できるようになります:

// Turn 1: model calls a tool
ChatResponse response1 = model.chat(ChatRequest.builder()
.messages(userMessage)
.parameters(ChatRequestParameters.builder()
.toolSpecifications(weatherTool)
.build())
.build());

AiMessage aiMessage1 = response1.aiMessage();
// aiMessage1.attribute("encrypted_reasoning", String.class) is not null

// Turn 2: send tool result back — encrypted reasoning is sent automatically
ChatResponse response2 = model.chat(ChatRequest.builder()
.messages(
userMessage,
aiMessage1, // contains encrypted reasoning in attributes
ToolExecutionResultMessage.from(aiMessage1.toolExecutionRequests().get(0), "sunny"))
.parameters(ChatRequestParameters.builder()
.toolSpecifications(weatherTool)
.build())
.build());

これはOpenAiOfficialResponsesStreamingChatModelでも同様に動作します。

OpenAiOfficialResponsesChatResponseMetadata​

Responses APIのレスポンスメタデータは、標準のChatResponseMetadataを超える追加フィールドを提供します:

OpenAiOfficialResponsesChatResponseMetadata metadata =
(OpenAiOfficialResponsesChatResponseMetadata) chatResponse.metadata();

metadata.id(); // Response ID (can be used as previousResponseId)
metadata.modelName(); // Model name used for the request
metadata.finishReason(); // Finish reason (STOP, LENGTH, TOOL_EXECUTION, CONTENT_FILTER, OTHER)
metadata.tokenUsage(); // Returns OpenAiOfficialTokenUsage with detailed token counts
metadata.createdAt(); // Timestamp when the response was created
metadata.completedAt(); // Timestamp when the response was completed
metadata.serviceTier(); // Service tier used for the request

バッチ処理(Batch Processing)​

OpenAiOfficialBatchChatModel は、コアの BatchChatModel インターフェースを実装し、OpenAI Batch API を通じて多数のチャットリクエストを非同期に処理します。料金は標準のトークン単価の 50% です。

リクエストは JSONL ファイルに書き込まれ、batch 目的で Files API 経由でアップロードされ、/v1/chat/completions エンドポイントに対して実行されます。バッチ内のすべてのリクエストは、同じモデルに解決される必要があります。結果は送信順序を保つため、i 番目の結果は、成功か失敗かにかかわらず、i 番目のリクエストに対応します。

OpenAiOfficialBatchChatModel batchModel = OpenAiOfficialBatchChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();

BatchResponse<ChatResponse> submitted = batchModel.submit(new BatchRequest<>(List.of(
ChatRequest.builder().messages(UserMessage.from("What is the capital of France?")).build(),
ChatRequest.builder().messages(UserMessage.from("What is the capital of Germany?")).build())));

String batchId = submitted.batchId();

// Poll until the batch reaches a terminal state (SUCCEEDED, FAILED, CANCELLED, EXPIRED).
BatchResponse<ChatResponse> batch = batchModel.retrieve(batchId);
while (!batch.state().isTerminal()) {
Thread.sleep(Duration.ofSeconds(30).toMillis());
batch = batchModel.retrieve(batchId);
}

for (BatchItemResult<ChatResponse> result : batch.results()) {
if (result.isSuccess()) {
System.out.println(result.response().aiMessage().text());
} else {
System.out.println("Failed: " + result.error().message());
}
}

実行中のバッチはキャンセルでき、既存のバッチはページネーション付きで一覧表示できます:

batchModel.cancel(batchId);

BatchPage<ChatResponse> page = batchModel.list(new BatchPagination(20, null));

Azure OpenAI もサポートされており、その場合、モデルはバッチのデプロイ名で識別されます。Files API と Batch API を実装している OpenAI 互換エンドポイントも同様にサポートされます。

バッチ固有のオプションは、ビルダーで設定できます:

OpenAiOfficialBatchChatModel batchModel = OpenAiOfficialBatchChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.completionWindow("24h") // defaults to 24h
.batchMetadata(Map.of("owner", "nightly-job")) // attached to the batch itself
.inputFileExpiresAfter(Duration.ofDays(14))
.outputExpiresAfter(Duration.ofDays(7))
.build();