BytesRouter

主题

LangChain4j 文档版本 1.22.0 源快照 c79dc33e 更新于 2026-10-14

Amazon Bedrock

Maven 依赖

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

AWS 凭据

要使用 Amazon Bedrock 模型，你需要配置 AWS 凭据。 一种方式是设置 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 环境变量。更多信息可在这里找到。或者，在本地设置 AWS_BEARER_TOKEN_BEDROCK 环境变量以进行 API 密钥认证。关于更多 API 密钥细节，参见文档。

BedrockChatModel

NOTE

当前实现不支持 Guardrails。

受支持的模型及其特性可在这里找到。

模型 id 可在这里找到。

配置

java
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

NOTE

当前实现不支持 Guardrails。

受支持的模型及其特性可在这里找到。

模型 id 可在这里找到。

配置

java
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();

示例

BedrockBatchChatModel

BedrockBatchChatModel 在 Bedrock 的批量推理 API之上实现了核心的 BatchChatModel 接口，它以低于受支持模型按需推理的价格异步处理大量聊天请求。关于 LangChain4j 中批处理的工作方式，参见批处理。

请求会被写成一个 JSONL 文件存到 S3，随后提交一个模型调用任务，结果再从 S3 输出位置读回。它需要一个与任务同区域的 S3 桶，以及一个 Bedrock 会承担（assume）的服务角色，用于读取输入并写出输出。输入与输出文件事后不会被删除，因此它们会留在桶中直到你移除。

NOTE

Bedrock 批量推理不支持工具调用、结构化输出或提示词缓存，因此指定了工具、JSON 响应格式或缓存点的请求会以 UnsupportedFeatureException 被拒绝；指定了服务层级、或指定了非 BedrockBatchChatModel 上所配置模型的请求同样会被拒绝。只有一小部分模型支持批量推理，参见受支持的模型。Bedrock 还会作为服务配额强制每个任务的最小与最大记录数，并拒绝超出配额的任务。

依赖

BedrockBatchChatModel 使用 AWS SDK 的 Amazon Bedrock 与 Amazon S3 客户端，langchain4j-bedrock 将它们声明为可选依赖。要使用它，请把它们添加到你的项目：

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

配置

java
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();

除非向 builder 传入了 S3Client 与 BedrockClient，否则模型会创建它自己的，而 close() 会关闭它创建的那些。

用法

java
// 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 提交的任务。

额外的模型请求字段

BedrockChatRequestParameters 中的 additionalModelRequestFields 字段是一个 Map<String, Object>。正如这里所解释的，它允许你为某个具体模型添加未被通用 InferenceConfiguration 覆盖的推理参数。

请求元数据

使用 BedrockChatRequestParameters 上的 requestMetadata 为 Converse 与 ConverseStream 请求添加键值对。这些元数据可用于过滤 Amazon Bedrock 的模型调用日志。它可以作为模型默认请求参数的一部分配置，或针对单个请求提供。

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

请勿在请求元数据中包含个人身份信息、凭据或其他敏感数据。更多信息参见逐次请求元数据标记。

思考 / 推理

要启用 Claude 的思考过程，请在 BedrockChatRequestParameters 上调用 enableReasoning，并在构建模型时通过 defaultRequestParameters 设置它：

java
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。 默认启用。

提示词缓存

AWS Bedrock 支持提示词缓存，在以相似提示词反复调用 API 时提升性能并降低成本。该特性可将延迟最多降低 85%、缓存内容的成本最多降低 90%。

工作原理

提示词缓存让你能标记对话中要被缓存的特定位置。当你用相同的缓存内容发起后续 API 调用时，Bedrock 可复用被缓存的部分，从而显著减少处理时间与成本。缓存有 5 分钟的 TTL（生存时间），每次缓存命中都会重置。

受支持的模型

提示词缓存支持以下模型：

  • 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() 方法：

java
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 枚举为在对话中何处放置缓存点提供了三种选项：

  • AFTER_SYSTEM：将缓存点放在系统消息之后。当你有一个想在多个对话间复用的固定系统提示词时，这很理想。
  • AFTER_USER_MESSAGE：将缓存点放在用户消息之后。当你有一个保持不变的标准用户提示词或上下文时有用。
  • AFTER_TOOLS：将缓存点放在工具定义之后。当你有一组想缓存的固定工具时很有利。

示例

结合系统消息缓存的基本用法

java
// 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 特性（如推理）组合使用：

java
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. 成本优化：缓存对被反复使用的较长系统提示词或工具定义尤为有利。

更多资源

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可