跳到主要内容
版本:2.0.1

Bedrock Converse API

QWen 3.8 中英对照 Amazon Bedrock Converse Bedrock Converse API

Amazon Bedrock Converse API 为对话式 AI 模型提供统一接口,并具备增强的功能,包括函数/工具调用、多模态输入以及流式响应。

Bedrock Converse API 具有以下高级功能:

  • 工具/函数调用:支持在对话中进行函数定义和工具使用

  • 多模态输入:支持在对话中处理文本和图像输入

  • 流式支持:实时流式传输模型响应

  • 系统消息:支持系统级指令和上下文设置

提示

Bedrock Converse API 提供了跨多个模型提供商的统一接口,同时处理 AWS 特定的认证和基础设施问题。目前,Converse API 支持的模型 包括:Amazon Titan、Amazon Nova、AI21 Labs、Anthropic Claude、Cohere Command、Meta Llama、Mistral AI。

备注

遵循 Bedrock 的建议,Spring AI 正在过渡到使用 Amazon Bedrock 的 Converse API 来实现所有聊天对话功能。尽管现有的 InvokeModel API 支持对话应用程序,但我们强烈建议在所有 Chat 对话模型中采用 Converse API。

Converse API 不支持 embedding 操作,因此这些功能将保留在当前 API 中,现有 InvokeModel API 中的 embedding 模型功能也将得以维持。

先决条件​

有关设置 API 访问权限,请参阅 Getting started with Amazon Bedrock

  • 获取 AWS 凭证:如果您还没有 AWS 账号且尚未配置 AWS CLI,此视频教程可以帮助您完成配置:AWS CLI & SDK Setup in Less Than 4 Minutes!。您应该能够获取您的访问密钥和安全密钥。

  • 启用要使用的模型:前往 Amazon Bedrock,从左侧的 Model Access 菜单中,配置对您将要使用的模型的访问权限。

自动配置​

备注

Spring AI 的自动配置和 starter 模块的构件名称(artifact names)已发生显著变更。更多信息请参阅 升级说明。

在项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加 spring-ai-starter-model-bedrock-converse 依赖项:

<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-bedrock-converse</artifactId>
</dependency>
提示

参考 依赖管理 章节,将 Spring AI BOM 添加到您的构建文件中。

聊天属性​

前缀 spring.ai.bedrock.aws 是用于配置与 AWS Bedrock 连接的属性前缀。

属性描述默认值
spring.ai.bedrock.aws.region使用的 AWS 区域us-east-1
spring.ai.bedrock.aws.timeout整个 API 调用的最大持续时间5m
spring.ai.bedrock.aws.connection-timeout建立连接时的最大等待时间5s
spring.ai.bedrock.aws.connection-acquisition-timeout从连接池获取新连接的最大等待时间30s
spring.ai.bedrock.aws.async-read-timeout读取异步响应的最大持续时间30s
spring.ai.bedrock.aws.access-keyAWS 访问密钥-
spring.ai.bedrock.aws.secret-keyAWS 秘密密钥-
spring.ai.bedrock.aws.session-token用于临时凭据的 AWS 会话令牌-
spring.ai.bedrock.aws.profile.nameAWS 配置文件名称。-
spring.ai.bedrock.aws.profile.credentials-pathAWS 凭据文件路径。-
spring.ai.bedrock.aws.profile.configuration-pathAWS 配置文件路径。-
备注

聊天自动配置(chat auto-configurations)的启用和禁用现已通过前缀为 spring.ai.model.chat 的顶层属性进行配置。

要启用,设置 spring.ai.model.chat=bedrock-converse(默认情况下已启用)。

要禁用,设置 spring.ai.model.chat=none(或任何与 bedrock-converse 不匹配的值)。

此更改旨在允许配置多个模型。

前缀 spring.ai.bedrock.converse.chat 是用于配置 Converse API 聊天模型实现的属性前缀。

属性描述默认值
spring.ai.bedrock.converse.chat.enabled (已移除且不再有效)启用 Bedrock Converse 聊天模型。true
spring.ai.model.chat启用 Bedrock Converse 聊天模型。bedrock-converse
spring.ai.bedrock.converse.chat.model要使用的模型 ID。您可以使用 受支持的模型和模型功能None。请从 AWS Bedrock 控制台中选择您的 modelId。
spring.ai.bedrock.converse.chat.temperature控制输出的随机性。取值范围为 [0.0, 1.0]0.8
spring.ai.bedrock.converse.chat.top-p采样时考虑的最大累计 token 概率。AWS Bedrock 默认值
spring.ai.bedrock.converse.chat.top-k生成下一个 token 时的 token 选择数量。AWS Bedrock 默认值
spring.ai.bedrock.converse.chat.max-tokens生成响应中的最大 token 数量。500

运行时选项​

使用便携式 ChatOptions 或 BedrockChatOptions 便携式构建器来创建模型配置,例如 temperature、maxToken、topP 等。

启动时,可以通过 BedrockConverseProxyChatModel(api, options) 构造函数或 spring.ai.bedrock.converse.chat.* 属性来配置默认选项。

在运行时,你可以通过向 Prompt 调用中添加新的、特定于请求的选项来覆盖默认选项:

var options = BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.temperature(0.6)
.maxTokens(300)
.toolCallbacks(List.of(FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
.description("Get the weather in location. Return temperature in 36°F or 36°C format. Use multi-turn if needed.")
.inputType(WeatherService.Request.class)
.build()))
.build();

String response = ChatClient.create(this.chatModel)
.prompt("What is current weather in Amsterdam?")
.options(options)
.call()
.content();

提示缓存​

AWS Bedrock 的 提示缓存功能 允许你缓存常用提示,以降低重复交互的成本并提升响应速度。缓存提示后,后续相同的请求可复用已缓存的内容,从而显著减少需要处理的输入 token 数量。

备注

支持的模型

通过 AWS Bedrock 提供的 Claude 3.x、Claude 4.x 以及 Amazon Nova 模型均支持提示词缓存(Prompt caching)。

Token 要求

不同模型对缓存生效所需的最低 Token 阈值有所不同:

  • Claude Sonnet 4 及大多数模型:1024 个及以上 Token
  • 具体模型的要求可能有所不同,请参阅 AWS Bedrock 文档

缓存策略​

Spring AI 通过 BedrockCacheStrategy 枚举提供策略缓存放置功能:

  • NONE:完全禁用提示缓存(默认值)

  • SYSTEM_ONLY:仅缓存系统消息内容

  • TOOLS_ONLY:仅缓存工具定义(仅限 Claude 模型)

  • SYSTEM_AND_TOOLS:同时缓存系统消息和工具定义(仅限 Claude 模型)

  • CONVERSATION_HISTORY:在聊天记忆场景中缓存整个对话历史

这一策略性方法确保了最优的缓存断点放置位置,同时保持在 AWS Bedrock 的 4 个断点限制之内。

备注

Amazon Nova 限制

Amazon Nova 模型(Nova Micro、Lite、Pro、Premier)仅支持对 system 和 messages 内容进行缓存。它们不支持对 tools 进行缓存。

如果尝试在 Nova 模型上使用 TOOLS_ONLY 或 SYSTEM_AND_TOOLS 策略,AWS 将返回 ValidationException。对于 Amazon Nova 模型,请使用 SYSTEM_ONLY 策略。

启用提示词缓存​

通过在 BedrockChatOptions 中设置 cacheOptions 并选择一种 strategy 来启用提示缓存。

仅限系统的缓存​

最常见的用例——在多个请求之间缓存系统指令:

// Cache system message content
ChatResponse response = chatModel.call(
new Prompt(
List.of(
new SystemMessage("You are a helpful AI assistant with extensive knowledge..."),
new UserMessage("What is machine learning?")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(500)
.build()
)
);

仅工具缓存​

在保持系统提示词动态的同时,缓存大型工具定义(仅适用于 Claude 模型):

// Cache tool definitions only
ChatResponse response = chatModel.call(
new Prompt(
"What's the weather in San Francisco?",
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.TOOLS_ONLY)
.build())
.toolCallbacks(weatherToolCallbacks) // Large tool definitions
.maxTokens(500)
.build()
)
);
备注

该策略仅支持 Claude 模型。Amazon Nova 模型将返回 ValidationException。

系统与工具缓存​

为系统指令和工具定义建立缓存以最大化复用(仅限 Claude 模型):

// Cache system message and tool definitions
ChatResponse response = chatModel.call(
new Prompt(
List.of(
new SystemMessage("You are a weather analysis assistant..."),
new UserMessage("What's the weather like in Tokyo?")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
.build())
.toolCallbacks(weatherToolCallbacks)
.maxTokens(500)
.build()
)
);
备注

此策略使用 2 个缓存断点(一个用于工具,一个用于系统)。仅在 Claude 模型上受支持。

对话历史缓存​

为多轮对话聊天机器人和助手缓存不断增长的对话历史:

// Cache conversation history with ChatClient and memory
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultSystem("You are a personalized career counselor...")
.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
.build();

String response = chatClient.prompt()
.user("What career advice would you give me?")
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
.options(BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.CONVERSATION_HISTORY)
.build())
.maxTokens(500)
.build())
.call()
.content();

多块系统消息缓存​

使用 advisors(例如,RAG 上下文注入)时,您的系统提示可能由多个 SystemMessage 实例组成:一个静态前缀(您的基础指令)和一个动态后缀(advisor 注入的、每次请求都可能变化的上下文)。

默认情况下,当启用 SYSTEM_ONLY 或 SYSTEM_AND_TOOLS 缓存时,每个 SystemMessage 都会作为单独的 SystemContentBlock 发出,且缓存点位于最后一个块之后。如果该内容在请求之间发生任何变化,整个系统缓存都会被标记为失效——这将导致每次请求都产生 1.25 倍的缓存写入成本,而不是成本更低的缓存读取操作。

multiBlockSystemCaching 选项通过将缓存点放置在倒数第二个系统块之后(即静态前缀与动态后缀的边界处)来解决此问题,从而确保即使最后一个块自由变化,静态部分仍能保持缓存。

BedrockCacheOptions cacheOptions = BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.multiBlockSystemCaching(true)
.ttl(BedrockCacheTtl.ONE_HOUR)
.build();

BedrockChatOptions chatOptions = BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(cacheOptions)
.build();

// Static system prompt (will be cached)
SystemMessage staticPrompt = new SystemMessage("You are an expert assistant...");
// Dynamic RAG context (injected by advisor, changes each request)
SystemMessage dynamicContext = new SystemMessage("Relevant context: " + ragResults);

Prompt prompt = new Prompt(List.of(staticPrompt, dynamicContext, new UserMessage("...")), chatOptions);

这会产生一个 Bedrock system 数组,其形式为 [text(static), cachePoint, text(dynamic)],因此只有静态前缀会参与缓存键的计算。

备注

如果仅存在单个 SystemMessage,缓存点将放置在该单个块之后(与默认行为相同)。multiBlockSystemCaching 选项仅在存在两个或更多系统消息时改变缓存点的放置位置。

important

消息的顺序很重要。缓存点始终位于倒数第二个系统块之后,因此静态内容必须出现在动态内容之前。如果你将基础指令注册为第一个 SystemMessage,并让 advisors 在其后追加动态上下文,那么这一顺序要求将自然满足。

使用 ChatClient 流畅 API​

String response = ChatClient.create(chatModel)
.prompt()
.system("You are an expert document analyst...")
.user("Analyze this large document: " + document)
.options(BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.build())
.call()
.content();

使用示例​

下面是一个完整的示例,展示如何结合成本追踪使用提示词缓存:

// Create system content that will be reused multiple times
String largeSystemPrompt = "You are an expert software architect specializing in distributed systems...";
// (Ensure this is 1024+ tokens for cache effectiveness)

// First request - creates cache
ChatResponse firstResponse = chatModel.call(
new Prompt(
List.of(
new SystemMessage(largeSystemPrompt),
new UserMessage("What is microservices architecture?")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(500)
.build()
)
);

// Access cache-related token usage from metadata
Integer cacheWrite1 = (Integer) firstResponse.getMetadata()
.getMetadata()
.get("cacheWriteInputTokens");
Integer cacheRead1 = (Integer) firstResponse.getMetadata()
.getMetadata()
.get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite1);
System.out.println("Cache read tokens: " + cacheRead1);

// Second request with same system prompt - reads from cache
ChatResponse secondResponse = chatModel.call(
new Prompt(
List.of(
new SystemMessage(largeSystemPrompt), // Same prompt - cache hit
new UserMessage("What are the benefits of event sourcing?")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(500)
.build()
)
);

Integer cacheWrite2 = (Integer) secondResponse.getMetadata()
.getMetadata()
.get("cacheWriteInputTokens");
Integer cacheRead2 = (Integer) secondResponse.getMetadata()
.getMetadata()
.get("cacheReadInputTokens");

System.out.println("Cache creation tokens: " + cacheWrite2); // Should be 0
System.out.println("Cache read tokens: " + cacheRead2); // Should be > 0

令牌使用情况跟踪​

AWS Bedrock 通过响应提供缓存特定指标。您可以通过两种方法访问缓存指标:

对于可观测性处理器和指标收集,通过原生的 TokenUsage 对象访问缓存指标:

import software.amazon.awssdk.services.bedrockruntime.model.TokenUsage;

ChatResponse response = chatModel.call(/* ... */);

// Access cache metrics from native TokenUsage object
TokenUsage tokenUsage = (TokenUsage) response.getMetadata()
.getUsage()
.getNativeUsage();

if (tokenUsage != null) {
Integer cacheWrite = tokenUsage.cacheWriteInputTokens();
Integer cacheRead = tokenUsage.cacheReadInputTokens();
System.out.println("Cache write: " + cacheWrite + ", Cache read: " + cacheRead);
}

元数据映射(向后兼容)​

缓存指标也可通过元数据 Map 获取,以保持向后兼容性:

ChatResponse response = chatModel.call(/* ... */);

// Access cache metrics from metadata Map
Integer cacheWrite = (Integer) response.getMetadata()
.getMetadata()
.get("cacheWriteInputTokens");
Integer cacheRead = (Integer) response.getMetadata()
.getMetadata()
.get("cacheReadInputTokens");

缓存特定指标包括:

  • cacheWriteInputTokens:返回创建缓存条目时使用的 token 数量

  • cacheReadInputTokens:返回从现有缓存条目中读取的 token 数量

首次发送缓存提示时: - cacheWriteInputTokens 的值将大于 0 - cacheReadInputTokens 的值将为 0

当您再次发送相同的缓存提示(在 5 分钟 TTL 内): - cacheWriteInputTokens 将为 0 - cacheReadInputTokens 将大于 0

实际应用场景​

通过在不同问题之间缓存文档内容,高效分析大型法律合同或合规文档:

// Load a legal contract (PDF or text)
String legalContract = loadDocument("merger-agreement.pdf"); // ~3000 tokens

// System prompt with legal expertise
String legalSystemPrompt = "You are an expert legal analyst specializing in corporate law. " +
"Analyze the following contract and provide precise answers about terms, obligations, and risks: " +
legalContract;

// First analysis - creates cache
ChatResponse riskAnalysis = chatModel.call(
new Prompt(
List.of(
new SystemMessage(legalSystemPrompt),
new UserMessage("What are the key termination clauses and associated penalties?")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(1000)
.build()
)
);

// Subsequent questions reuse cached document - 90% cost savings
ChatResponse obligationAnalysis = chatModel.call(
new Prompt(
List.of(
new SystemMessage(legalSystemPrompt), // Same content - cache hit
new UserMessage("List all financial obligations and payment schedules.")
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(1000)
.build()
)
);

批量代码审查​

缓存审查准则,同时使用一致的审查标准处理多个代码文件:

// Define comprehensive code review guidelines
String reviewGuidelines = """
You are a senior software engineer conducting code reviews. Apply these criteria:
- Security vulnerabilities and best practices
- Performance optimizations and memory usage
- Code maintainability and readability
- Testing coverage and edge cases
- Design patterns and architecture compliance
""";

List<String> codeFiles = Arrays.asList(
"UserService.java", "PaymentController.java", "SecurityConfig.java"
);

List<String> reviews = new ArrayList<>();

for (String filename : codeFiles) {
String sourceCode = loadSourceFile(filename);

ChatResponse review = chatModel.call(
new Prompt(
List.of(
new SystemMessage(reviewGuidelines), // Cached across all reviews
new UserMessage("Review this " + filename + " code:\n\n" + sourceCode)
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(800)
.build()
)
);

reviews.add(review.getResult().getOutput().getText());
}

// Guidelines cached after first request, subsequent reviews are faster and cheaper

结合知识库的客户服务​

创建一个客户支持系统,用于缓存您的产品知识库,以提供一致且准确的响应:

// Load comprehensive product knowledge
String knowledgeBase = """
PRODUCT DOCUMENTATION:
- API endpoints and authentication methods
- Common troubleshooting procedures
- Billing and subscription details
- Integration guides and examples
- Known issues and workarounds
""" + loadProductDocs(); // ~2500 tokens

@Service
public class CustomerSupportService {

public String handleCustomerQuery(String customerQuery, String customerId) {
ChatResponse response = chatModel.call(
new Prompt(
List.of(
new SystemMessage("You are a helpful customer support agent. " +
"Use this knowledge base to provide accurate solutions: " + knowledgeBase),
new UserMessage("Customer " + customerId + " asks: " + customerQuery)
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_ONLY)
.build())
.maxTokens(600)
.build()
)
);

return response.getResult().getOutput().getText();
}
}

// Knowledge base is cached across all customer queries
// Multiple support agents can benefit from the same cached content

多租户 SaaS 应用​

在跨不同租户共享工具定义缓存的同时,针对每个租户定制系统提示:

// Shared tool definitions (cached once, used across all tenants)
List<FunctionToolCallback> sharedTools = createLargeToolRegistry(); // ~2000 tokens

// Tenant-specific configuration
@Service
public class MultiTenantAIService {

public String processRequest(String tenantId, String userQuery) {
// Load tenant-specific system prompt (changes per tenant)
String tenantPrompt = loadTenantSystemPrompt(tenantId);

ChatResponse response = chatModel.call(
new Prompt(
List.of(
new SystemMessage(tenantPrompt), // Tenant-specific, not cached
new UserMessage(userQuery)
),
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.TOOLS_ONLY)
.build())
.toolCallbacks(sharedTools) // Shared tools - cached
.maxTokens(500)
.build()
)
);

return response.getResult().getOutput().getText();
}
}

// Tools cached once, each tenant gets customized system prompt

最佳实践​

  1. 选择合适的策略:

    • 对于可复用的系统提示词和指令,使用 SYSTEM_ONLY(适用于所有模型)
    • 当拥有大型且稳定的工具但系统提示词是动态变化时,使用 TOOLS_ONLY(仅限 Claude)
    • 当系统提示词和工具都是大型且稳定的时候,使用 SYSTEM_AND_TOOLS(仅限 Claude)
    • 对于多轮对话,结合 ChatClient 记忆功能使用 CONVERSATION_HISTORY
    • 使用 NONE 显式禁用缓存
  2. 满足令牌要求:专注于缓存那些满足最低令牌要求(大多数模型为 1024 个令牌以上)的内容。

  3. 重用完全相同的内容:缓存机制在提示词内容完全匹配时效果最佳。即使发生微小变化,也需要创建新的缓存条目。

  4. 监控令牌使用情况:使用元数据指标跟踪缓存的有效性:

    Integer cacheWrite = (Integer) response.getMetadata().getMetadata().get("cacheWriteInputTokens");
    Integer cacheRead = (Integer) response.getMetadata().getMetadata().get("cacheReadInputTokens");
    if (cacheRead != null && cacheRead > 0) {
    System.out.println("Cache hit: " + cacheRead + " tokens saved");
    }
  5. 战略性缓存点放置:该实现会根据您选择的策略,自动在最优位置放置缓存断点,以确保符合 AWS Bedrock 的 4 个断点限制。

  6. 缓存有效期:AWS Bedrock 的缓存默认具有 5 分钟的 TTL(Time To Live),但也支持 1 小时的 TTL 时长。每次缓存访问都会重置计时器。您可以通过 BedrockCacheOptions 上的 BedrockCacheTtl 或通过 spring.ai.bedrock.converse.chat.cache-options.ttl 属性进行配置。

  7. 模型兼容性:注意特定模型的局限性:

    • Claude 模型:支持所有缓存策略
    • Amazon Nova 模型:仅支持 SYSTEM_ONLY 和 CONVERSATION_HISTORY(不支持工具缓存)
  8. 工具稳定性:当使用 TOOLS_ONLY、SYSTEM_AND_TOOLS 或 CONVERSATION_HISTORY 策略时,请确保工具保持稳定。更改工具定义会导致级联失效,从而使所有下游缓存断点失效。

缓存失效与级联行为​

AWS Bedrock 采用具有级联失效(cascade invalidation)机制的层级缓存模型:

缓存层级:Tools → System → Messages

每一层的变更都会使该层及其后续所有层失效:

变更内容工具缓存系统缓存消息缓存
工具❌ 无效❌ 无效❌ 无效
系统✅ 有效❌ 无效❌ 无效
消息✅ 有效✅ 有效❌ 无效

使用 SYSTEM_AND_TOOLS 策略的示例:

// Request 1: Cache both tools and system
ChatResponse r1 = chatModel.call(
new Prompt(
List.of(new SystemMessage("System prompt"), new UserMessage("Question")),
BedrockChatOptions.builder()
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
.build())
.toolCallbacks(tools)
.build()
)
);
// Result: Both caches created

// Request 2: Change only system prompt (tools same)
ChatResponse r2 = chatModel.call(
new Prompt(
List.of(new SystemMessage("DIFFERENT system prompt"), new UserMessage("Question")),
BedrockChatOptions.builder()
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
.build())
.toolCallbacks(tools) // SAME tools
.build()
)
);
// Result: Tools cache HIT (reused), system cache MISS (recreated)

// Request 3: Change tools (system same as Request 2)
ChatResponse r3 = chatModel.call(
new Prompt(
List.of(new SystemMessage("DIFFERENT system prompt"), new UserMessage("Question")),
BedrockChatOptions.builder()
.cacheOptions(BedrockCacheOptions.builder()
.strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
.build())
.toolCallbacks(newTools) // DIFFERENT tools
.build()
)
);
// Result: BOTH caches MISS (tools change invalidates everything downstream)

实现细节​

Spring AI 中的提示缓存实现遵循以下关键设计原则:

  1. 策略性缓存点放置:缓存断点会根据所选策略自动放置在最优位置,确保符合 AWS Bedrock 的 4 个断点限制。

  2. 提供商可移植性:缓存配置通过 BedrockChatOptions 而非单个消息进行,从而在切换不同 AI 提供商时保持兼容性。

  3. 线程安全性:缓存断点跟踪采用线程安全机制实现,以正确处理并发请求。

  4. UNION 类型模式:AWS SDK 使用 UNION 类型,其中缓存点作为独立的块添加,而非作为属性。这与直接 API 方法不同,但确保了类型安全和 API 合规性。

  5. 增量缓存:CONVERSATION_HISTORY 策略将缓存断点放置在最后一条用户消息上,实现增量缓存,使每一轮对话都基于之前缓存的前缀进行构建。

成本考虑​

AWS Bedrock 提示词缓存的定价(近似值,因模型而异):

  • 缓存写入:比基础输入令牌(base input tokens)贵 ~25%
  • 缓存读取:便宜 ~90%(仅为基础输入令牌价格的 10%)
  • 盈亏平衡点:只需 1 次缓存读取,即可节省成本

示例成本计算:

// System prompt: 2000 tokens
// User question: 50 tokens

// Without caching (5 requests):
// Cost: 5 × (2000 + 50) = 10,250 tokens at base rate

// With caching (5 requests):
// Request 1: 2000 tokens × 1.25 (cache write) + 50 = 2,550 tokens
// Requests 2-5: 4 × (2000 × 0.10 (cache read) + 50) = 4 × 250 = 1,000 tokens
// Total: 2,550 + 1,000 = 3,550 tokens equivalent

// Savings: (10,250 - 3,550) / 10,250 = 65% cost reduction

工具调用​

BedrockProxyChatModel 支持工具调用。模型可以请求执行工具,但不会自行运行工具——Spring AI 负责处理执行。

在大多数应用中,请结合自动注册的 ToolCallingAdvisor 使用 ChatClient — 参见 工具调用。如需低级别控制并自行驱动循环(例如,将工具调用与提示词缓存结合使用时),参见 ChatModel 工具调用。

使用工具调用进行推理​

当启用扩展思考且模型决定调用工具时,该响应中的签名推理块会被自动保留,并在后续请求中与工具结果一同重放。Amazon Bedrock 要求在重放时必须包含这些推理块——若省略它们,将导致 API 错误。

无需特殊配置。Spring AI 可以透明地处理重放操作,无论您使用的是自动管理的工具循环(即配置了 ToolCallingAdvisor 的 ChatClient),还是通过 ToolCallingManager 手动驱动循环。

结构化输出​

AWS Bedrock 通过 JSON Schema 支持原生的结构化输出,确保模型生成的响应严格符合您指定的结构。该功能适用于 支持的模型,包括 Anthropic Claude 和 Amazon Nova。

使用 ChatClient 与原生结构化输出​

使用结构化输出的最简单方式是借助 ChatClient 高级 API 和 ENABLE_NATIVE_STRUCTURED_OUTPUT 顾问(advisor):

record ActorsFilms(String actor, List<String> movies) {}

ActorsFilms actorsFilms = ChatClient.create(chatModel).prompt()
.options(ToolCallingChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.build())
.advisors(AdvisorParams.ENABLE_NATIVE_STRUCTURED_OUTPUT)
.user("Generate the filmography for a random actor.")
.call()
.entity(ActorsFilms.class);

该方法会自动地:

  • 从您的 Java 类生成 JSON schema
  • 通过 AWS Bedrock OutputConfig API 在 BedrockChatOptions 上设置 outputSchema
  • 将 JSON 响应解析为您指定的类型

直接使用 outputSchema​

如需更多控制,可以直接在 BedrockChatOptions 上设置 JSON schema:

String jsonSchema = """
{
"type": "object",
"properties": {
"actor": { "type": "string" },
"movies": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["actor", "movies"],
"additionalProperties": false
}
""";

ChatResponse response = chatModel.call(
new Prompt("Generate the filmography for a random actor.",
BedrockChatOptions.builder()
.model("us.anthropic.claude-haiku-4-5-20251001-v1:0")
.outputSchema(jsonSchema)
.build()));

String content = response.getResult().getOutput().getText();
备注

AWS Bedrock 的结构化输出在构建 OutputConfig 时,内部使用固定的模式名称 response_schema。该 JSON 模式会直接传递给 AWS SDK 的 JsonSchemaDefinition。

有关更多信息,请参阅 结构化输出 文档。

多模态​

多模态是指模型能够同时理解和处理来自多种信息源的能力,这些信息源包括文本、图像、视频、PDF、DOC、HTML、MD 以及更多数据格式。

Bedrock Converse API 支持多模态输入,包括文本和图像输入,并且可以基于组合输入生成文本响应。

您需要一个支持多模态输入的模型,例如 Anthropic Claude 或 Amazon Nova 模型。

图像​

对于支持视觉多模态的模型(例如 Amazon Nova、Anthropic Claude、Llama 3.2),Bedrock Converse API 允许在请求负载中包含多张图片。这些模型可以分析传入的图片并回答问题、对图片进行分类,以及根据提供的指令对图片进行摘要。

目前,Bedrock Converse 支持 base64 编码的 image/jpeg、image/png、image/gif 和 image/webp MIME 类型图像。

Spring AI 的 Message 接口通过引入 Media 类型支持多模态 AI 模型。它包含消息中媒体附件的数据和信息,并使用 Spring 的 org.springframework.util.MimeType 以及一个用于原始媒体数据的 java.lang.Object。

以下是一个简单的代码示例,演示了将用户文本与图片进行组合。

String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text("Explain what do you see on this picture?")
.media(Media.Format.IMAGE_PNG, new ClassPathResource("/test.png")))
.call()
.content();

logger.info(response);

其输入为 test.png 图像:

多模态测试图像

同时附带文本消息“Explain what do you see on this picture?”,并生成如下形式的响应:

The image shows a close-up view of a wire fruit basket containing several pieces of fruit.
...

视频​

Amazon Nova 模型 允许在 payload 中包含单个视频,该视频可以以 base64 格式提供,也可以通过 Amazon S3 URI 提供。

目前,Bedrock Nova 支持 video/x-matroska、video/quicktime、video/mp4、video/webm、video/x-flv、video/mpeg、video/x-ms-wmv 和 video/3gpp 等 mime 类型的视频。

Spring AI 的 Message 接口通过引入 Media 类型来支持多模态 AI 模型。它包含消息中媒体附件的数据及信息,使用 Spring 的 org.springframework.util.MimeType 和用于原始媒体数据的 java.lang.Object。

以下是一个简单的代码示例,展示了如何将用户文本与视频结合。

String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text("Explain what do you see in this video?")
.media(Media.Format.VIDEO_MP4, new ClassPathResource("/test.video.mp4")))
.call()
.content();

logger.info(response);

其输入为 test.video.mp4 图像:

多模态测试视频

并附带文本消息“解释一下你在视频中看到了什么?”,并生成类似如下的响应:

The video shows a group of baby chickens, also known as chicks, huddled together on a surface
...

文档​

对于某些模型,Bedrock 允许通过 Converse API 的文档支持功能在负载中包含文档,这些文档可以以字节形式提供。文档支持有两种不同的变体,如下所述:

  • 文本文档类型(txt、csv、html、md 等),重点在于文本理解。这类用例包括基于文档中的文本元素进行问答。

  • 媒体文档类型(pdf、docx、xlsx),重点在于基于视觉的理解来回答问题。这类用例包括基于图表、图形等内容进行问答。

目前,Anthropic 的 PDF 支持(Beta) 和 Amazon Bedrock Nova 模型支持文档多模态。

下面是一个简单的代码示例,展示了用户文本与媒体文档的组合。

String response = ChatClient.create(chatModel)
.prompt()
.user(u -> u.text(
"You are a very professional document summarization specialist. Please summarize the given document.")
.media(Media.Format.DOC_PDF, new ClassPathResource("/spring-ai-reference-overview.pdf")))
.call()
.content();

logger.info(response);

它接受 spring-ai-reference-overview.pdf 文档作为输入:

多模态测试 PNG

并附带文本消息“你是一个非常专业的文档摘要专家。请对给定的文档进行摘要。”,并生成类似如下的响应:

**Introduction:**
- Spring AI is designed to simplify the development of applications with artificial intelligence (AI) capabilities, aiming to avoid unnecessary complexity.
...

示例控制器​

创建一个新的 Spring Boot 项目,并在依赖项中添加 spring-ai-starter-model-bedrock-converse。

在 src/main/resources 下添加一个 application.properties 文件:

spring.ai.bedrock.aws.region=eu-central-1
spring.ai.bedrock.aws.timeout=10m
spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID}
spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY}
# session token is only required for temporary credentials
spring.ai.bedrock.aws.session-token=${AWS_SESSION_TOKEN}

spring.ai.bedrock.converse.chat.temperature=0.8
spring.ai.bedrock.converse.chat.top-k=15

下面是一个使用聊天模型的控制器示例:

@RestController
public class ChatController {

private final ChatClient chatClient;

@Autowired
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}

@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", this.chatClient.prompt(message).call().content());
}

@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return this.chatClient.prompt(message).stream().content();
}
}