跳到主要内容

Amazon Bedrock

Maven 依存関係​

<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-bedrock</artifactId>
<version>1.23.0</version>
</dependency>

AWS 認証情報​

Amazon Bedrock モデルを使用するには、AWS 認証情報を設定する必要があります。 選択肢のひとつは、AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY 環境変数を設定することです。詳細はこちらを参照してください。あるいは、API キー認証のためにローカルで AWS_BEARER_TOKEN_BEDROCK 環境変数を設定することもできます。API キーの詳細については、ドキュメントを参照してください。

BedrockChatModel​

サポートされているモデルとその機能はこちらで確認できます。

モデル ID はこちらで確認できます。

設定​

ChatModel model = BedrockChatModel.builder()
.client(BedrockRuntimeClient)
.region(...)
.modelId("us.amazon.nova-lite-v1:0")
.returnThinking(...)
.sendThinking(...)
.timeout(...)
.maxRetries(...)
.logRequests(...)
.logResponses(...)
.listeners(...)
.defaultRequestParameters(BedrockChatRequestParameters.builder()
.modelName(...)
.temperature(...)
.topP(...)
.maxOutputTokens(...)
.stopSequences(...)
.toolSpecifications(...)
.toolChoice(...)
.additionalModelRequestFields(...)
.additionalModelRequestField(...)
.enableReasoning(...)
.promptCaching(...)
.requestMetadata(Map.of("team", "platform"))
.build())
.build();

例​

BedrockStreamingChatModel​

サポートされているモデルとその機能はこちらで確認できます。

モデル ID はこちらで確認できます。

設定​

StreamingChatModel model = BedrockStreamingChatModel.builder()
.client(BedrockRuntimeAsyncClient)
.region(...)
.modelId("us.amazon.nova-lite-v1:0")
.returnThinking(...)
.sendThinking(...)
.timeout(...)
.logRequests(...)
.logResponses(...)
.listeners(...)
.defaultRequestParameters(BedrockChatRequestParameters.builder()
.modelName(...)
.temperature(...)
.topP(...)
.maxOutputTokens(...)
.stopSequences(...)
.toolSpecifications(...)
.toolChoice(...)
.additionalModelRequestFields(...)
.additionalModelRequestField(...)
.enableReasoning(...)
.promptCaching(...)
.requestMetadata(Map.of("team", "platform"))
.build())
.build();

例​

Amazon Bedrock ガードレール(Guardrails)​

BedrockChatModel と BedrockStreamingChatModel は Amazon Bedrock Guardrails をサポートしています。 これらは Amazon Bedrock によって評価され、LangChain4j のガードレールとは別のものです。両方を併用することもできます。

BedrockChatRequestParameters を使ってガードレールを設定し、モデルの defaultRequestParameters として設定するとすべてのリクエストにガードレールが適用されます。あるいは ChatRequest に渡すと、単一のリクエストにのみ適用されます:

BedrockChatRequestParameters parameters = BedrockChatRequestParameters.builder()
.guardrailConfiguration(BedrockGuardrailConfiguration.builder()
.guardrailIdentifier("guardrail-id")
.guardrailVersion("1")
.build())
.build();

ChatModel model = BedrockChatModel.builder()
.modelId("us.amazon.nova-lite-v1:0")
.defaultRequestParameters(parameters)
.build();

ガードレールが介入した場合、レスポンスの finishReason() は FinishReason.CONTENT_FILTER になり、 評価の詳細は ((BedrockChatResponseMetadata) response.metadata()).guardrailAssessmentSummary() から取得できます。

選択したユーザーメッセージのみを評価する​

デフォルトでは、ガードレールはリクエスト内のすべてのユーザーメッセージと AI メッセージのテキストを評価します。 Bedrock は、ツール結果、ツール定義、ツール呼び出し、システムプロンプトを評価することはありません。

コストとレイテンシを削減するには、guardContentPlacement を設定して、ガードレールが評価するユーザーメッセージを選択します:

  • LAST_USER_MESSAGE:最後のユーザーメッセージのみ。
  • ALL_USER_MESSAGES:ユーザーメッセージのみ(すべてのユーザーメッセージ)。
BedrockGuardrailConfiguration guardrailConfiguration = BedrockGuardrailConfiguration.builder()
.guardrailIdentifier("guardrail-id")
.guardrailVersion("1")
.guardContentPlacement(BedrockGuardContentPlacement.LAST_USER_MESSAGE)
.build();

選択されたユーザーメッセージは Bedrock の guardContent ブロックとして送信され、 ガードレールは入力としてそれらのみを評価します。その他のユーザーメッセージと AI メッセージは評価されません。 モデルのレスポンスは引き続き評価されます。 ガードレールが使用するポリシーによっては、Bedrock が guardContent ブロック外の一部のコンテンツを評価する場合があります。

注意

選択されたメッセージ以外のコンテンツはチェックされません。 たとえば、LAST_USER_MESSAGE とチャットメモリを併用すると、ガードレールがブロックしたユーザーメッセージが 後続のターンでは評価されないままモデルに送信されます。 コスト削減ではなくセキュリティ制御としてガードレールを使用する場合は、デフォルト(guardContentPlacement を設定しない)を推奨します。

guardContent として送信できるのは、テキストと PNG/JPEG 画像のみです。 選択されたメッセージに他のコンテンツ(たとえば PDF や GIF 画像)が含まれている場合、 そのリクエストでは guardContentPlacement は無視され、ガードレールはデフォルトどおりすべてのユーザーメッセージと AI メッセージを評価し、 警告がログに記録されます。リクエストにユーザーメッセージが含まれない場合も、同じデフォルトが適用されます。

BedrockBatchChatModel​

BedrockBatchChatModel は、Bedrock のバッチ推論 API 上でコアの BatchChatModel インターフェースを実装しています。 この API は、サポートされているモデルについて、オンデマンド推論より低価格で多数のチャットリクエストを非同期に処理します。LangChain4j でのバッチ処理の仕組みについては、 バッチ処理を参照してください。

リクエストは JSONL ファイルとして S3 に書き込まれ、モデル呼び出しジョブが送信され、結果は S3 の出力場所から読み取られます。 ジョブと同じリージョンにある S3 バケットと、Bedrock が入力の読み取りと出力の書き込みのために引き受ける サービスロールが必要です。 入力ファイルと出力ファイルは後から削除されないため、ユーザーが削除するまでバケット内に残ります。

备注

Bedrock のバッチ推論は、ツール呼び出し、構造化出力、プロンプトキャッシュをサポートしていないため、ツール、JSON レスポンス形式、またはキャッシュポイントを指定したリクエストは UnsupportedFeatureException で拒否されます。 サービスティア、または BedrockBatchChatModel に設定されたものとは別のモデルを指定したリクエストも同様に拒否されます。 バッチ推論をサポートしているのは一部のモデルのみです。サポートされているモデルを参照してください。 また Bedrock は、サービスクォータとして 1 ジョブあたりのレコード数の最小値と最大値を設けており、これを外れるジョブは拒否されます。

依存関係​

BedrockBatchChatModel は AWS SDK の Amazon Bedrock クライアントと Amazon S3 クライアントを使用します。langchain4j-bedrock はこれらをオプションの依存関係として宣言しています。 使用するには、プロジェクトに追加してください:

<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>bedrock</artifactId>
</dependency>
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>s3</artifactId>
</dependency>

設定​

BedrockBatchChatModel model = BedrockBatchChatModel.builder()
.region(...)
.modelId("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.roleArn("arn:aws:iam::123456789012:role/my-bedrock-batch-role")
.outputS3Uri("s3://my-bucket/batch-output")
.inputS3Uri(...) // optional, defaults to outputS3Uri
.defaultRequestParameters(...)
.jobTimeout(Duration.ofHours(24)) // between 24 and 168 hours
.returnThinking(...)
.sendThinking(...)
.timeout(...)
.customHeaders(...)
.maxRetries(...)
.logRequests(...)
.logResponses(...)
.build();

S3Client と BedrockClient がビルダーに渡されない限り、モデルが独自にクライアントを作成し、close() は モデル自身が作成したクライアントをクローズします。

使い方​

// Submit a batch of chat requests, at least as many as the minimum number of records per job
List<ChatRequest> requests = ...;
BatchResponse<ChatResponse> submitted = model.submit(new BatchRequest<>(requests));

String batchId = submitted.batchId();

// Poll until the job reaches a terminal state (SUCCEEDED, FAILED, CANCELLED, EXPIRED).
BatchResponse<ChatResponse> batch = model.retrieve(batchId);
while (!batch.state().isTerminal()) {
Thread.sleep(Duration.ofMinutes(1).toMillis());
batch = model.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());
}
}

結果は送信されたリクエストの順序で返されます。Bedrock が部分的に完了したと報告したジョブの状態は SUCCEEDED になるため、各結果を確認してください。 model.cancel(batchId) はジョブを停止し、すでに処理されたレコードの結果は引き続き返されます(課金も発生します)。 model.list(...) は、そのリージョン内のすべてのバッチ推論ジョブを一覧表示します。 LangChain4j 経由で送信されていないジョブも含まれます。

追加のモデルリクエストフィールド(Additional Model Request Fields)​

BedrockChatRequestParameters の additionalModelRequestFields フィールドは Map<String, Object> です。 こちらで説明されているように、 共通の InferenceConfiguration ではカバーされない特定モデル向けの推論パラメータを追加できます。

リクエストメタデータ(Request Metadata)​

BedrockChatRequestParameters の requestMetadata を使用すると、Converse および ConverseStream リクエストにキーと値のペアを追加できます。 このメタデータは、Amazon Bedrock のモデル呼び出しログのフィルタリングに利用できます。モデルのデフォルトリクエストパラメータの一部として設定することも、 個別のリクエストに指定することもできます。

BedrockChatRequestParameters parameters = BedrockChatRequestParameters.builder()
.requestMetadata(Map.of("team", "platform"))
.build();

リクエストメタデータに、個人を特定できる情報、認証情報、その他の機密データを含めないでください。 詳細については、リクエストごとのメタデータタグ付けを参照してください。

Thinking / Reasoning​

Claude の思考プロセスを有効にするには、BedrockChatRequestParameters で enableReasoning を呼び出し、モデルの構築時に defaultRequestParameters 経由で設定します:

BedrockChatRequestParameters parameters = BedrockChatRequestParameters.builder()
.enableReasoning(1024) // token budget
.build();

ChatModel model = BedrockChatModel.builder()
.modelId("us.anthropic.claude-sonnet-4-20250514-v1:0")
.defaultRequestParameters(parameters)
.returnThinking(true)
.sendThinking(true)
.build();

次のパラメータも思考の挙動を制御します:

  • returnThinking:利用可能な場合に AiMessage.thinking() 内に思考内容を返すかどうか、 また、BedrockStreamingChatModel 使用時に StreamingChatResponseHandler.onPartialThinking() と TokenStream.onPartialThinking() コールバックを呼び出すかどうかも制御します。 デフォルトでは無効です。有効にすると、思考シグネチャも AiMessage.attributes() 内に保存・返却されます。
  • sendThinking:後続リクエストで AiMessage に保存された思考内容とシグネチャを LLM に送信するかどうかを制御します。 デフォルトでは有効です。

Prompt Caching​

AWS Bedrock は、類似したプロンプトで API を繰り返し呼び出す際のパフォーマンス向上とコスト削減のためにプロンプトキャッシュをサポートしています。この機能により、キャッシュされたコンテンツのレイテンシを最大 85%、コストを最大 90% 削減できます。

仕組み​

プロンプトキャッシュでは、会話内の特定のポイントをキャッシュ対象としてマークできます。同じキャッシュ済みコンテンツで後続の API 呼び出しを行うと、Bedrock はキャッシュされた部分を再利用でき、処理時間とコストを大幅に削減します。キャッシュの TTL(有効期間)は 5 分で、キャッシュヒットのたびにリセットされます。

サポートされているモデル​

プロンプトキャッシュは次のモデルでサポートされています:

  • Claude Opus 4.5
  • Claude Opus 4.1
  • Claude Opus 4
  • Claude Sonnet 4.5
  • Claude Haiku 4.5
  • Claude Sonnet 4
  • Claude 3.7 Sonnet
  • Claude 3.5 Sonnet
  • Claude 3.5 Haiku
  • Amazon Nova モデル

設定​

プロンプトキャッシュを有効にするには、BedrockChatRequestParameters の promptCaching() メソッドを使用します:

import dev.langchain4j.model.bedrock.BedrockChatRequestParameters;
import dev.langchain4j.model.bedrock.BedrockCachePointPlacement;

BedrockChatRequestParameters params = BedrockChatRequestParameters.builder()
.promptCaching(BedrockCachePointPlacement.AFTER_SYSTEM)
.temperature(0.7)
.maxOutputTokens(500)
.build();

ChatModel model = BedrockChatModel.builder()
.modelId("us.amazon.nova-micro-v1:0")
.region(Region.US_EAST_1)
.defaultRequestParameters(params)
.build();

キャッシュポイントの配置オプション​

BedrockCachePointPlacement 列挙型は、会話内のどこにキャッシュポイントを配置するかについて 3 つのオプションを提供します:

  • AFTER_SYSTEM:システムメッセージの後にキャッシュポイントを配置します。複数の会話で再利用したい一貫したシステムプロンプトがある場合に適しています。
  • AFTER_USER_MESSAGE:ユーザーメッセージの後にキャッシュポイントを配置します。同じままの標準ユーザープロンプトやコンテキストがある場合に有用です。
  • AFTER_TOOLS:ツール定義の後にキャッシュポイントを配置します。キャッシュしたい一貫したツール定義セットがある場合に有益です。

例​

システムメッセージキャッシュの基本的な使い方​

// Configure prompt caching to cache after system message
BedrockChatRequestParameters params = BedrockChatRequestParameters.builder()
.promptCaching(BedrockCachePointPlacement.AFTER_SYSTEM)
.build();

ChatModel model = BedrockChatModel.builder()
.modelId("us.anthropic.claude-sonnet-4-6")
.defaultRequestParameters(params)
.build();

// First request - establishes the cache
ChatRequest request1 = ChatRequest.builder()
.messages(Arrays.asList(
SystemMessage.from("You are a helpful coding assistant with expertise in Java."),
UserMessage.from("What is dependency injection?")
))
.build();

ChatResponse response1 = model.chat(request1);

// Second request - benefits from cached system message
ChatRequest request2 = ChatRequest.builder()
.messages(Arrays.asList(
SystemMessage.from("You are a helpful coding assistant with expertise in Java."),
UserMessage.from("What is the singleton pattern?")
))
.build();

ChatResponse response2 = model.chat(request2); // Faster response due to caching

他の機能との組み合わせ​

プロンプトキャッシュは、推論などの他の Bedrock 機能と組み合わせることができます:

BedrockChatRequestParameters params = BedrockChatRequestParameters.builder()
.promptCaching(BedrockCachePointPlacement.AFTER_SYSTEM)
.enableReasoning(1000) // Enable reasoning with 1000 token budget
.temperature(0.3)
.maxOutputTokens(2000)
.build();

ChatModel model = BedrockChatModel.builder()
.modelId("us.anthropic.claude-sonnet-4-6")
.defaultRequestParameters(params)
.build();

ベストプラクティス​

  1. 安定したコンテンツをキャッシュする:システムプロンプト、ツール定義、共通コンテキストなど、頻繁に変化しないコンテンツにキャッシュを使用します。
  2. 適切な配置を選ぶ:
    • システムプロンプトが会話間で一貫している場合は AFTER_SYSTEM を使用
    • 安定したツール定義セットがある場合は AFTER_TOOLS を使用
    • 繰り返されるユーザーコンテキストがあるシナリオでは AFTER_USER_MESSAGE を使用
  3. キャッシュヒットを監視する:5 分の TTL はキャッシュヒットのたびにリセットされるため、同じキャッシュ済みコンテンツへの頻繁なリクエストでキャッシュを維持できます。
  4. コスト最適化:繰り返し使用される長いシステムプロンプトやツール定義では、キャッシュが特に有益です。

追加リソース​