Spring AI Anthropic API 的使用

Anthropic Claude 是一系列基础人工智能模型，可应用于各类场景。开发者与企业可借助 API 接入能力，直接基于 Anthropic 的 AI 基础设施进行二次开发。

Spring AI 支持 Anthropic 消息 API，可实现同步与流式文本生成。

Anthropic 的 Claude 模型也可通过 Amazon Bedrock 对话服务使用，Spring AI 同样提供了专属的 Amazon Bedrock 对接 Anthropic 的客户端实现。

前置要求

你需要在 Anthropic 官网控制台创建 API 密钥。

前往 Anthropic API 控制台注册账号，并在「获取 API 密钥」页面生成密钥。

Spring AI 定义了配置属性 spring.ai.anthropic.api-key，需将其设置为从 anthropic.com 获取的密钥值。

可在 application.properties 文件中配置：

spring.ai.anthropic.api-key=<你的Anthropic API密钥>

为提升 API 密钥等敏感信息的安全性，可使用 Spring 表达式语言（SpEL）引用自定义环境变量：

# 在 application.yml 中
spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}

# 在环境变量或 .env 文件中
export ANTHROPIC_API_KEY=<你的Anthropic API密钥>

也可在应用代码中通过编程方式获取配置：

// 从安全源或环境变量读取API密钥
String apiKey = System.getenv("ANTHROPIC_API_KEY");

引入仓库与BOM依赖

Spring AI 构件发布在 Maven 中央仓库与 Spring 快照仓库。参考「构件仓库」章节，将仓库配置加入构建工程。

为统一版本依赖管理，Spring AI 提供 BOM（物料清单），保证项目中所有模块使用一致的 Spring AI 版本。参考「依赖管理」章节引入 Spring AI BOM。

自动配置

Spring AI 的自动配置与 Starter 构件名称已有重大变更，详情请参考升级说明文档。

Spring AI 为 Anthropic 聊天客户端提供 Spring Boot 自动配置。只需在 Maven pom.xml 或 Gradle build.gradle 中引入以下依赖即可启用：

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-anthropic</artifactId>
</dependency>

Gradle

implementation 'org.springframework.ai:spring-ai-starter-model-anthropic'

请参考依赖管理章节，在构建文件中引入 Spring AI BOM。

聊天配置属性

重试配置属性

配置前缀 spring.ai.retry 用于设置 Anthropic 聊天模型的重试机制。

目前重试策略暂不适用于流式 API。

连接配置属性

配置前缀 spring.ai.anthropic 用于配置 Anthropic 服务连接参数。

通用配置属性

聊天自动配置的启用/禁用现已通过顶层前缀 spring.ai.model.chat 配置：

• 启用：spring.ai.model.chat=anthropic（默认启用）

• 禁用：spring.ai.model.chat=none（或任意非 anthropic 值）

该改动为支持多模型同时配置。

配置前缀 spring.ai.anthropic.chat 用于定制 Anthropic 聊天模型实现。

最新模型别名及说明请查阅 Anthropic 官方模型别名文档。

所有以 spring.ai.anthropic.chat.options 开头的配置，均可在运行时通过给 Prompt 请求设置专属运行时配置进行覆盖。

运行时配置

AnthropicChatOptions.java 提供模型运行时配置，如模型名称、温度、最大令牌数等。

项目启动时，可通过 AnthropicChatModel(api, options) 构造器或 spring.ai.anthropic.chat.options.* 配置默认参数。

运行时可在 Prompt 调用中自定义请求参数，覆盖默认配置：

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        AnthropicChatOptions.builder()
            .model("claude-3-7-sonnet-latest")
            .temperature(0.4)
        .build()
    ));

除模型专属的 AnthropicChatOptions，也可使用通用的 ChatOptions.builder() 创建可跨模型兼容的配置实例。

提示词缓存

Anthropic 提示词缓存可缓存常用提示词，降低重复交互的成本并提升响应速度。缓存命中时，后续相同请求可复用缓存内容，大幅减少输入令牌消耗。

支持模型

当前支持：Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5、Claude Haiku 3.5、Claude Haiku 3、Claude Opus 3。

令牌阈值要求

• Claude Sonnet 4：不少于 1024 令牌

• Claude Haiku 系列：不少于 2048 令牌

• 其他模型：不少于 1024 令牌

缓存策略

受 Anthropic 级联失效机制影响：修改工具定义会使所有下游缓存（系统、对话消息）全部失效；使用 SYSTEM_AND_TOOLS、CONVERSATION_HISTORY 策略时，工具稳定性至关重要。

启用提示词缓存

通过在 AnthropicChatOptions 中设置缓存配置并选择策略即可启用。

（各类缓存示例代码、高级缓存配置、多块系统消息缓存、令牌统计、实际业务场景最佳实践等代码示例均省略，保留文档结构）

模型思考能力

Anthropic Claude 支持「思考」特性，可在给出最终答案前输出推理过程，适合复杂逻辑分步推理场景，结果更透明详实。

支持模型

Claude 4 系列、Claude 3.7 Sonnet。

Claude 3.7 Sonnet 输出完整思考内容；Claude 4 支持摘要式思考、交错思考及更强工具集成。

请求结构统一，但输出行为有差异。

思考配置

启用需在请求中加入思考配置：类型设为 enabled，并设置 reasoning 令牌预算（建议最小1024）。

预算通常需小于 max_tokens；预算越大推理越深入，但可能增加延迟。

（同步/流式调用示例、工具集成说明、注意事项略）

工具/函数调用

可向 AnthropicChatModel 注册自定义 Java 工具，Claude 可智能选择生成 JSON 参数调用注册函数，打通大模型与外部工具、API 的联动能力。

工具选择策略

Spring AI 通过 AnthropicApi.ToolChoice 提供四种策略：

• ToolChoiceAuto（默认）：模型自主决定是否调用工具

• ToolChoiceAny：必须调用至少一个可用工具

• ToolChoiceTool：强制调用指定名称工具

• ToolChoiceNone：禁止调用任何工具

除 ToolChoiceNone 外，均支持关闭并行工具调用，强制单次只调用一个工具。

（各类工具调用代码示例、适用场景略）

多模态能力

多模态指模型可同时理解处理文本、图片、PDF 等多种格式信息。

图片支持

Claude 3 支持 Base64 图片，格式支持 jpeg、png、gif、webp；Claude 3.5 Sonnet 额外支持 PDF 格式。

Spring AI 通过 Media 类型支持多模态消息，封装媒体 MIME 类型与原始数据。

（图片、PDF 调用代码示例略）

引用溯源

Anthropic 引用 API 可让 Claude 在生成回复时关联文档指定片段，返回字符位置、页码、内容块等溯源元数据。

作用：结果可核验、过程透明、满足合规溯源、提升可信度。

支持模型：Claude 3.7 Sonnet、Claude 4 系列。

支持文档类型：纯文本（字符级引用）、PDF（页码级引用）、自定义内容块（块级引用）。

（创建引用文档、请求传入、解析引用信息、代码示例与最佳实践略）

技能能力

Anthropic 技能 API 可让 Claude 生成可下载的真实文件：Excel、PPT、Word、PDF，而非仅文本描述，弥补传统大模型无法输出办公文档的短板。

支持模型

Claude Sonnet 4、4.5、Opus 4 及后续版本。

使用要求

• 依赖代码执行能力（Spring AI 自动启用）

• 单次请求最多启用 8 个技能

• 生成文件通过文件接口保留 24 小时可下载

内置技能

（基础使用、多技能组合、流式生成、文件下载、自定义技能、业务场景示例略）

工程接入示例

快速入门工程

新建 Spring Boot 项目，引入 spring-ai-starter-model-anthropic 依赖。

在 src/main/resources 下新建 application.properties：

spring.ai.anthropic.api-key=YOUR_API_KEY
spring.ai.anthropic.chat.options.model=claude-3-5-sonnet-latest
spring.ai.anthropic.chat.options.temperature=0.7
spring.ai.anthropic.chat.options.max-tokens=450

替换为自己的密钥后，即可注入 AnthropicChatModel 使用。

接口控制器示例：

@RestController
public class ChatController {

    private final AnthropicChatModel chatModel;

    @Autowired
    public ChatController(AnthropicChatModel chatModel) {
        this.chatModel = chatModel;
    }

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

    @GetMapping("/ai/generateStream")
	public FluxgenerateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

手动配置方式

不使用 Starter 自动配置时，单独引入依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-anthropic</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-anthropic'
}

手动创建客户端与模型：

var anthropicApi = new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));
var anthropicChatOptions = AnthropicChatOptions.builder()
            .model("claude-3-7-sonnet-20250219")
            .temperature(0.4)
            .maxTokens(200)
        .build();
var chatModel = AnthropicChatModel.builder()
        .anthropicApi(anthropicApi)
        .defaultOptions(anthropicChatOptions)
        .build();

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

// 流式响应
Fluxresponse = this.chatModel.stream(
    new Prompt("Generate the names of 5 famous pirates."));

底层API客户端

AnthropicApi 是轻量级 Java 客户端，可直接调用 Anthropic 消息接口，支持同步、流式请求自定义开发。

AnthropicApi anthropicApi =
    new AnthropicApi(System.getenv("ANTHROPIC_API_KEY"));

AnthropicMessage chatCompletionMessage = new AnthropicMessage(
        List.of(new ContentBlock("Tell me a Joke?")), Role.USER);

// 同步请求
ResponseEntityresponse = this.anthropicApi
    .chatCompletionEntity(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_OPUS_4_5.getValue(),
            List.of(this.chatCompletionMessage), null, 100, 0.8, false));

// 流式请求
Fluxresponse = this.anthropicApi
    .chatCompletionStream(new ChatCompletionRequest(AnthropicApi.ChatModel.CLAUDE_OPUS_4_5.getValue(),
            List.of(this.chatCompletionMessage), null, 100, 0.8, true));