首页 / Spring AI 入门教程 / 接入 Anthropic（Claude）

← 上一篇 下一篇 →
Spring AI 入门教程

接入 Anthropic（Claude）

本教程共 45 篇 · 第 12 篇 · 更新于 2026-08-16 · 约 6 分钟阅读

Spring AIAnthropicClaudeJava SDKAPI Key扩展思考多模态2.0 迁移

本节目标：把 Claude 接入 Spring AI，理解 2.0 模块迁移到官方 Java SDK 后的写法变化，并掌握扩展思考、多模态输入等 Claude 特色能力。

12.1 2.0 的重要变化：官方 Java SDK

先讲一个背景，这关系到你查资料时看到的代码能不能用。

1.x 的 spring-ai-anthropic 模块用 RestClient 手写了一套 Anthropic API 客户端，代码量很大。2.0.0-M3 起，这个模块整体重写，底层换成 Anthropic 官方的 com.anthropic:anthropic-java SDK。

官方对这个变化的定性是”薄适配层”：SDK 已覆盖的能力不再重复造轮子，Spring AI 只保留自己的抽象价值，比如 ChatModel、ChatClient、工具调用、可观测性。

好消息是 Maven 坐标、starter 名称、spring.ai.anthropic.* 配置属性、ChatClient API 全部不变。只走 ChatClient 或 ChatModel 的代码，基本不用改。

坏消息是低层 API 变了。AnthropicApi 类及其全部嵌套类型被删除，AnthropicChatModel 的公开构造方法被移除。下面几节会逐个说明。

12.2 准备工作

到 console.anthropic.com 注册账号，在 API Keys 页面生成 Key。

配置方式和其他厂商一致：

spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY}

12.3 添加依赖

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

自动配置会生成 AnthropicChatModel Bean。常用连接属性：

属性说明默认值
spring.ai.anthropic.api-keyAPI Key-
spring.ai.anthropic.base-urlAPI 地址https://api.anthropic.com
spring.ai.anthropic.timeout请求超时60s
spring.ai.anthropic.max-retries最大重试次数2
spring.ai.anthropic.chat.model模型名claude-haiku-4-5
spring.ai.anthropic.chat.max-tokens最大生成 token4096
spring.ai.anthropic.chat.temperature采样温度-

模型名按需求选：claude-opus-4-20250514 最强，claude-sonnet-4-20250514 平衡，claude-haiku-4-5 最快最便宜。完整列表以 Anthropic 官方文档为准。

Note

2.0 把 maxTokens 默认值从 500 改成了 4096。之前 1.x 用户经常遇到回复被截断，新默认值解决了这个问题。想控制成本，就显式配置 max-tokens。

12.4 基本用法

和 OpenAI 一样，注入模型直接调用：

@RestController
public class ChatController {

    private final AnthropicChatModel chatModel;

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

    @GetMapping("/ai/generate")
    public Map<String, String> generate(@RequestParam(defaultValue = "讲个笑话") String message) {
        return Map.of("generation", chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(defaultValue = "讲个笑话") String message) {
        return chatModel.stream(new Prompt(new UserMessage(message)));
    }
}

运行时覆盖参数用 AnthropicChatOptions：

ChatResponse response = chatModel.call(new Prompt(
        "给我 5 个海盗的名字",
        AnthropicChatOptions.builder()
                .model("claude-sonnet-4-20250514")
                .temperature(0.4)
                .maxTokens(1024)
                .build()));
Note

直接调 ChatModel 时，Prompt 里的 options 必须是完整的，2.0 不再把缺省字段合并进模型默认值。只改一个参数就用 chatModel.getOptions().mutate()。走 ChatClient 没有这个问题，它内部会先合并再传给模型。

12.5 手动构建模型

不依赖自动配置时，用 builder 手动构建。注意 2.0 里公开构造方法已经删了，只有 builder：

var chatModel = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .defaultOptions(AnthropicChatOptions.builder()
                .model("claude-sonnet-4-20250514")
                .maxTokens(1024)
                .temperature(0.7)
                .build())
        .build();

ChatResponse response = chatModel.call(new Prompt("你好"));

builder 还接受 baseUrl、timeout、maxRetries、proxy、customHeaders 等参数。

重试机制也变了。1.x 用 Spring Retry 的 RetryTemplate，2.0 由 SDK 自己处理，配置项是 spring.ai.anthropic.max-retries，默认 2。以前专门给 Anthropic 配的 RetryTemplate Bean 可以删掉。

12.6 扩展思考（Extended Thinking）

Claude 的思考模式是特色功能。开启后，模型会先展示推理过程，再给出最终答案。适合数学、逻辑分析这类需要逐步推理的任务。

配置有两个硬性要求：budgetTokens 必须大于等于 1024 且小于 maxTokens；temperature 必须设成 1.0。

var options = AnthropicChatOptions.builder()
        .model("claude-sonnet-4-20250514")
        .temperature(1.0)
        .maxTokens(16000)
        .thinkingEnabled(10000L)   // 思考预算：>=1024 且 < maxTokens
        .build();

ChatResponse response = chatModel.call(new Prompt("是否存在无限多个 n mod 4 == 3 的质数？", options));

返回的响应里会混着两类 Generation：带 signature 元数据的是思考块，纯文本的是最终答案。遍历时区分处理：

for (Generation generation : response.getResults()) {
    AssistantMessage message = generation.getOutput();
    if (message.getMetadata().containsKey("signature")) {
        System.out.println("思考过程：" + message.getText());
    } else if (message.getText() != null && !message.getText().isBlank()) {
        System.out.println("最终答案：" + message.getText());
    }
}

流式模式下，思考内容通过 thinking 元数据标记，按增量推送。想省 token 可以用 thinkingEnabled(budget, display) 指定展示方式：SUMMARIZED 返回压缩摘要，OMITTED 完全隐藏思考内容，只留签名保证多轮对话连续。

Note

思考模式受模型版本限制。Claude 4 全系和 Claude 3.7 Sonnet 支持。开启思考时 temperature 必须是 1.0，这是 Anthropic API 的硬性约束。

12.7 多模态：图片和 PDF

Claude 支持图片和 PDF 输入。图片格式限 PNG、JPEG、GIF、WebP：

var imageResource = new ClassPathResource("/test-image.png");

var userMessage = UserMessage.builder()
        .text("这张图里有什么？")
        .media(List.of(new Media(MimeTypeUtils.IMAGE_PNG, imageResource)))
        .build();

ChatResponse response = chatModel.call(new Prompt(List.of(userMessage)));

PDF 输入是 Claude 的差异化能力，适合合同、论文这类文档理解场景：

var pdfResource = new ClassPathResource("/document.pdf");

var userMessage = UserMessage.builder()
        .text("总结这份文档")
        .media(List.of(new Media(new MimeType("application", "pdf"), pdfResource)))
        .build();

一条消息里可以放多个图片或文档，Claude 会一起理解。

12.8 工具调用

Claude 的工具调用走 Spring AI 统一的 ToolCallback 机制。ChatClient 会自动注册 ToolCallingAdvisor，闭环处理工具调用循环：

ToolCallback weatherCallback = FunctionToolCallback.builder("getCurrentWeather", new WeatherService())
        .description("获取指定位置的天气")
        .inputType(WeatherService.Request.class)
        .build();

String response = ChatClient.create(chatModel)
        .prompt()
        .user("巴黎、东京、纽约的天气怎么样？")
        .tools(weatherCallback)
        .call()
        .content();

Anthropic 专属的 toolChoice 选项可以控制模型用不用工具。ToolChoiceTool 强制指定某个工具，ToolChoiceNone 禁止工具。完整机制见第 24 章。

12.9 提示词缓存

Claude 的提示词缓存能显著降低重复上下文的开销。多轮对话或固定系统提示词时，前面一大段内容每次都重新计费，缓存后按折扣价读取。

Spring AI 把它封装成策略配置，通过 AnthropicCacheOptions 开启：

var options = AnthropicChatOptions.builder()
        .model("claude-sonnet-4-20250514")
        .maxTokens(1024)
        .cacheOptions(AnthropicCacheOptions.builder()
                .strategy(AnthropicCacheStrategy.SYSTEM_ONLY)
                .build())
        .build();

策略有五种：NONE 不缓存（默认）、SYSTEM_ONLY 只缓存系统消息、TOOLS_ONLY 只缓存工具定义、SYSTEM_AND_TOOLS 两者都缓存、CONVERSATION_HISTORY 连对话历史一起缓存。

Anthropic 单请求最多 4 个缓存断点，超出的会被自动跳过并打 WARN 日志。缓存命中情况可以从响应的 usage 里读：cacheReadInputTokens 非零说明命中了缓存。

12.10 从 1.x 迁移的检查清单

如果你是老用户，对照这份清单检查代码：

  1. 删掉对 org.springframework.ai.anthropic.api 包的 import，整个包已移除。
  2. 构造方法换成 AnthropicChatModel.builder()。
  3. 确认没有依赖旧的 500 token 默认值，现在默认 4096。
  4. CitationDocument 改名为 AnthropicCitationDocument。
  5. 缓存相关类从 api 子包挪到了 org.springframework.ai.anthropic 根包。
  6. 删掉专为 Anthropic 配的 RetryTemplate，重试交给 SDK 的 maxRetries。
  7. 直接调 ChatModel 时，Prompt options 不再和模型默认值合并。

迁移后还能白拿一批新能力：结构化输出、内置联网搜索、服务等级选择（service tier）、按区域处理请求（inference-geo）、每请求自定义 HTTP 头。

12.11 常见问题排查

Anthropic 的报错和其他厂商不太一样，几个高频问题列在这里。

401 认证失败，检查 api-key。Anthropic 是预付费模式，控制台余额不足时请求也会被拒绝，充值后再试。

400 请求参数不合法，多半是思考模式没配对：budgetTokens 必须大于等于 1024 且小于 maxTokens，temperature 必须设成 1.0，规则见 12.6。

429 限流，检查请求频率。SDK 自带重试，默认 2 次，想更激进可以调大 spring.ai.anthropic.max-retries。

提示词缓存不生效，先看策略和断点：单请求最多 4 个缓存断点，超出会被跳过并打 WARN。命中情况看响应的 usage，cacheReadInputTokens 非零说明缓存生效。

回复被截断，检查 maxTokens。2.0 默认 4096，长文档总结这类任务显式调大即可。流式模式下思考内容和最终答案分开推送，按 signature 元数据区分，别混在一起处理。

12.12 小结

Anthropic 的接入和其他厂商共用一套模式：starter 依赖加配置属性。它的特殊性在 2.0 的内部重构：底层换官方 SDK，构造方式统一走 builder，重试归 SDK 管。理解这些差异，迁移和排错都心里有数。下一章接入国产厂商 DeepSeek。

上一篇
接入 OpenAI
下一篇
接入 DeepSeek