Spring AI Amazon Bedrock Converse API 使用

Amazon 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 虽仍可用于对话应用，但官方强烈推荐所有对话模型改用 Converse API。

Converse API 不支持嵌入向量相关操作，因此向量嵌入功能仍保留在原有 InvokeModel API 中不变。

前置条件

1. 参考 Amazon Bedrock 入门文档开通 API 访问权限

2. 配置 AWS 凭证：若无 AWS 账号且未配置 AWS CLI，可参考官方教程快速完成配置，获取访问密钥与安全密钥

3. 启用模型权限：进入 Amazon Bedrock 控制台，在左侧「模型访问」菜单中，开启需要使用的模型权限

自动配置

Spring AI 自动配置与 Starter 构件名称有重大变更，升级请参考版本升级说明。

在 Maven 或 Gradle 项目中引入 spring-ai-starter-model-bedrock-converse 依赖：

Maven 依赖

<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.model.chat 控制：

• 启用：spring.ai.model.chat=bedrock-converse（默认启用）

• 禁用：spring.ai.model.chat=none 或其他非匹配值

该设计支持同时配置多个模型。

以 spring.ai.bedrock.converse.chat 为前缀配置 Converse API 聊天模型参数：

运行时参数配置

可使用通用 ChatOptions 或 BedrockChatOptions 构建器设置温度、最大令牌、topP 等模型参数。

启动时可通过 BedrockConverseProxyChatModel 构造器或配置文件设置默认参数；运行时可在 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 提示词缓存可对高频复用提示词做缓存，降低重复交互的成本并提升响应速度。缓存命中时可复用已有内容，大幅减少输入令牌消耗。

支持模型

Claude 3.x、Claude 4.x 以及 Amazon Nova 系列模型。

令牌阈值要求

• Claude Sonnet 4 及大多数模型：需不少于 1024 个令牌才可高效缓存

• 不同模型阈值有差异，以 AWS 官方文档为准

缓存策略

Spring AI 通过 BedrockCacheStrategy 枚举提供缓存策略：

• NONE：完全禁用提示词缓存（默认）

• SYSTEM_ONLY：仅缓存系统消息

• TOOLS_ONLY：仅缓存工具定义（仅 Claude 支持）

• SYSTEM_AND_TOOLS：同时缓存系统消息与工具定义（仅 Claude 支持）

• CONVERSATION_HISTORY：多轮对话场景缓存完整会话历史

策略会自动遵循 AWS Bedrock 最多 4 个缓存断点的限制。

Amazon Nova 限制

Nova 系列仅支持系统与消息内容缓存，不支持工具缓存。若对 Nova 使用 TOOLS_ONLY 或 SYSTEM_AND_TOOLS 会抛出校验异常，只能使用 SYSTEM_ONLY。

启用提示词缓存

在 BedrockChatOptions 中设置缓存策略即可开启。

仅缓存系统消息

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-3-7-sonnet-20250219-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
                .build())
            .maxTokens(500)
            .build()
    )
);

仅缓存工具定义

ChatResponse response = chatModel.call(
    new Prompt(
        "What's the weather in San Francisco?",
        BedrockChatOptions.builder()
            .model("us.anthropic.claude-3-7-sonnet-20250219-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.TOOLS_ONLY)
                .build())
            .toolCallbacks(weatherToolCallbacks)
            .maxTokens(500)
            .build()
    )
);

同时缓存系统消息和工具

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-3-7-sonnet-20250219-v1:0")
            .cacheOptions(BedrockCacheOptions.builder()
                .strategy(BedrockCacheStrategy.SYSTEM_AND_TOOLS)
                .build())
            .toolCallbacks(weatherToolCallbacks)
            .maxTokens(500)
            .build()
    )
);

会话历史缓存

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultSystem("You are a personalized career counselor...")
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory)
        .conversationId(conversationId)
        .build())
    .build();

String response = chatClient.prompt()
    .user("What career advice would you give me?")
    .options(BedrockChatOptions.builder()
        .model("us.anthropic.claude-3-7-sonnet-20250219-v1:0")
        .cacheOptions(BedrockCacheOptions.builder()
            .strategy(BedrockCacheStrategy.CONVERSATION_HISTORY)
            .build())
        .maxTokens(500)
        .build())
    .call()
    .content();

流式链式调用缓存示例

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-3-7-sonnet-20250219-v1:0")
        .cacheOptions(BedrockCacheOptions.builder()
            .strategy(BedrockCacheStrategy.SYSTEM_ONLY)
            .build())
        .build())
    .call()
    .content();

令牌用量统计

可通过原生 TokenUsage 对象或元数据 Map 获取缓存读写令牌数，用于监控与成本统计。首次创建缓存写入令牌大于0、读取为0；缓存命中时写入为0、读取大于0。

典型业务场景

• 法律文档分析：缓存合同文档内容，多次问答复用

• 批量代码评审：缓存评审规范，批量评审不同代码文件

• 知识库客服：缓存产品知识库，统一应答客户咨询

• 多租户 SaaS：缓存公共工具定义，租户独享系统提示词

最佳实践

• 按场景选择合适缓存策略

• 缓存内容满足 1024+ 令牌阈值提升收益

• 提示词需完全一致才会命中缓存

• 监控缓存读写令牌，优化成本

• 缓存固定 5 分钟 TTL，每次访问刷新计时

• 注意模型策略兼容性与缓存级联失效规则

工具调用

Bedrock Converse API 支持对话过程中的工具调用，可通过 @Tool 注解或函数式 Bean 定义工具：

public class WeatherService {
    @Tool(description = "Get the weather in location")
    public String weatherByLocation(@ToolParam(description= "City or state name") String location) {
        ...
    }
}

String response = ChatClient.create(this.chatModel)
        .prompt("What's the weather like in Boston?")
        .tools(new WeatherService())
        .call()
        .content();

也可使用函数式 Bean 作为工具：

@Bean
@Description("Get the weather in location. Return temperature in 36°F or 36°C format.")
public FunctionweatherFunction() {
    return new MockWeatherService();
}

String response = ChatClient.create(this.chatModel)
        .prompt("What's the weather like in Boston?")
        .toolNames("weatherFunction")
        .inputType(Request.class)
        .call()
        .content();

多模态能力

多模态指模型可同时处理文本、图片、视频、PDF、文档、网页等多种格式信息。Bedrock Converse API 支持多模态输入，并基于融合信息生成文本响应。

图片支持

支持 JPEG、PNG、GIF、WebP Base64 格式图片，可传入多张图片进行分析、分类、总结。

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

视频支持

Amazon Nova 支持单个视频传入，可使用 Base64 或 S3 地址；支持 MP4、WebM、FLV、MOV 等主流视频格式。

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

文档支持

支持 TXT、CSV、HTML、MD 等文本类文档，以及 PDF、DOCX、XLSX 等富媒体文档；Anthropic PDF 测试版与 Amazon 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 Boot 项目并引入 Bedrock Converse 依赖，配置 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}
spring.ai.bedrock.aws.session-token=${AWS_SESSION_TOKEN}

spring.ai.bedrock.converse.chat.options.temperature=0.8
spring.ai.bedrock.converse.chat.options.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 FluxgenerateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return this.chatClient.prompt(message).stream().content();
    }
}