将 Anthropic 模块迁移至官方 Java SDK
在 2.0.0-M3 中,spring-ai-anthropic 基于官方 com.anthropic:anthropic-java SDK 进行了重写,替换了之前手写的 RestClient / WebClient 实现。之前的 AnthropicApi 类是一个包含 2,300 行代码和 47 个嵌套 DTO 记录的文件。
新模块是 SDK 之上的一个轻量级适配器,而非并行的 API。Spring AI 的价值在于其自身的抽象——ChatModel、ChatClient、advisors、可观测性、自动配置——以及跨提供商的功能。当 SDK 已覆盖某项关注点(如缓存控制建模、流式处理、速率限制处理)时,先前模块中的封装层被移除而非保留,因此应用程序直接使用 SDK 的类型。这有助于保持接口简洁,并避免随着 Anthropic 发布新的 SDK 版本而产生偏差。
Maven 坐标、spring-ai-starter-model-anthropic Boot starter 以及 spring.ai.anthropic.* 配置属性均保持不变。ChatClient API 也保持不变。ChatModel.call(Prompt) 和 ChatModel.stream(Prompt) 保持其签名不变。AnthropicChatOptions 保留所有现有字段,并新增了用于 skills、web search、service tier、inference geo 和 structured output 的字段。
变更内容
| 领域 | 变更 |
|---|---|
AnthropicChatModel 构造 | 移除了公共构造函数。请使用 AnthropicChatModel.builder()。 |
org.springframework.ai.anthropic.api.AnthropicApi 及其嵌套 DTO | 已移除。如需直接访问 API,请使用 SDK 的 com.anthropic.client.AnthropicClient。 |
AnthropicCacheOptions、AnthropicCacheStrategy、AnthropicCacheTtl、CacheBreakpointTracker、CacheEligibilityResolver | 已从 org.springframework.ai.anthropic.api(及 api.utils)移至根包 org.springframework.ai.anthropic。枚举值保持不变。 |
CitationDocument | 重命名为 AnthropicCitationDocument。 |
AnthropicCacheType、StreamHelper、metadata.AnthropicRateLimit | 已移除,无直接替代方案。 |
默认 maxTokens | 从 500 更改为 4096。 |
传递依赖 com.squareup.okhttp3:okhttp | 新增,由 com.anthropic:anthropic-java 引入。 |
如果仅使用 ChatClient 或 ChatModel
如果你的代码如下所示,则无需进行迁移:
@Autowired ChatClient.Builder builder;
String response = builder.build()
.prompt("Tell me a joke")
.call()
.content();
自动配置会生成一个 AnthropicChatModel Bean,并将其连接到基于新 SDK 的实现。调用方代码不受影响。
需要留意的一个行为变化是新的默认 maxTokens 值(参见 默认 maxTokens 现在为 4096)。
以编程方式构造 AnthropicChatModel
将直接使用构造函数替换为使用 Builder:
// Before
AnthropicApi anthropicApi = new AnthropicApi(apiKey);
AnthropicChatModel chatModel = new AnthropicChatModel(anthropicApi,
AnthropicChatOptions.builder().model("claude-haiku-4-5").maxTokens(2048).build(),
retryTemplate,
toolCallingManager);
// After
AnthropicChatModel chatModel = AnthropicChatModel.builder()
.apiKey(apiKey)
.defaultOptions(AnthropicChatOptions.builder()
.model("claude-haiku-4-5")
.maxTokens(2048)
.build())
.toolCallingManager(toolCallingManager)
.build();
构建器还接受 baseUrl、timeout、maxRetries、proxy、customHeaders、observationRegistry 和 observationConvention。不存在 retryTemplate 构建器方法;重试现由 SDK 处理(参见 Retry uses SDK maxRetries, not RetryTemplate)。
如果您导入了缓存或引文类型
缓存和引用辅助类已从 api(以及 api.utils)子包移至根包 org.springframework.ai.anthropic。请按照以下方式更新导入:
| 旧导入 | 新导入 |
|---|---|
org.springframework.ai.anthropic.api.AnthropicCacheOptions | org.springframework.ai.anthropic.AnthropicCacheOptions |
org.springframework.ai.anthropic.api.AnthropicCacheStrategy | org.springframework.ai.anthropic.AnthropicCacheStrategy |
org.springframework.ai.anthropic.api.AnthropicCacheTtl | org.springframework.ai.anthropic.AnthropicCacheTtl |
org.springframework.ai.anthropic.api.utils.CacheBreakpointTracker | org.springframework.ai.anthropic.CacheBreakpointTracker |
org.springframework.ai.anthropic.api.utils.CacheEligibilityResolver | org.springframework.ai.anthropic.CacheEligibilityResolver |
org.springframework.ai.anthropic.api.CitationDocument | org.springframework.ai.anthropic.AnthropicCitationDocument |
AnthropicCacheStrategy 的枚举值(NONE、TOOLS_ONLY、SYSTEM_ONLY、SYSTEM_AND_TOOLS、CONVERSATION_HISTORY)和 AnthropicCacheTtl 的枚举值(FIVE_MINUTES、ONE_HOUR)保持不变。在重命名后的 AnthropicCitationDocument 上,plainText(…)、pdf(…) 和 customContent(…) 工厂方法依然存在。
如果您直接使用 AnthropicApi
AnthropicApi、其嵌套的 DTO 记录以及 AnthropicCacheType 已被移除。在尝试使用 SDK 客户端之前,请考虑 AnthropicChatModel 是否涵盖了你的使用场景。通常情况下它已经足够,并且可以保持框架集成。
AnthropicChatModel 在 AnthropicClient 的基础上增加了以下功能:
-
提供商无关的请求和响应类型(
Prompt、ChatResponse、Generation、Usage),因此应用程序代码不依赖于com.anthropic.*。 -
工具调用与
ToolCallback和ToolCallingManager循环集成,包括自动的多轮执行。 -
流式处理采用 Reactor
Flux<ChatResponse>,而非 SDK 的基于回调的AsyncStreamResponse。 -
提示词缓存(Prompt caching),具有策略建模、TTL 控制以及 4 个断点强制检查(
AnthropicCacheOptions)。 -
Citation及其四种位置变体,通过ChatResponseMetadata暴露。 -
技能、内置 Web 搜索、服务层级、推理地理位置以及结构化输出,均作为
AnthropicChatOptions字段提供,并可以从spring.ai.anthropic.chat.*进行绑定。 -
Spring Boot 自动配置和 Micrometer 观测性支持。
-
位于模型之上的
ChatClient管道(建议器、消息模板、RAG、会话记忆、结构化输出转换器)。 -
提供商可移植性:相同的
ChatClient代码可以在 OpenAI、Bedrock、Google GenAI 和其他提供商上运行。
对于典型的聊天使用场景,请切换到 AnthropicChatModel.builder()(参见 如果您通过编程方式构造 AnthropicChatModel):
// Before
AnthropicApi api = new AnthropicApi(apiKey);
AnthropicApi.ChatCompletionRequest req = new AnthropicApi.ChatCompletionRequest(
AnthropicApi.ChatModel.CLAUDE_HAIKU_4_5.getValue(),
List.of(new AnthropicApi.AnthropicMessage(List.of(new AnthropicApi.ContentBlock("hello")), AnthropicApi.Role.USER)),
null, 1024, null, 0.7, null, null, null, null, false);
ResponseEntity<AnthropicApi.ChatCompletionResponse> resp = api.chatCompletionEntity(req);
// After
AnthropicChatModel chatModel = AnthropicChatModel.builder()
.apiKey(apiKey)
.defaultOptions(AnthropicChatOptions.builder()
.model("claude-haiku-4-5")
.maxTokens(1024)
.temperature(0.7)
.build())
.build();
ChatResponse response = chatModel.call(new Prompt("hello"));
如果你确实需要 AnthropicChatModel 未暴露的 Anthropic API 功能(例如 beta 端点、files API、自定义 skills CRUD),可以降级使用 SDK 客户端。此时你已脱离框架环境——没有可观测性,没有提供商中立性,也没有 ChatClient 管道:
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
AnthropicClient client = AnthropicOkHttpClient.builder().apiKey(apiKey).build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_HAIKU_4_5)
.maxTokens(1024)
.temperature(0.7)
.addUserMessage("hello")
.build();
com.anthropic.models.messages.Message message = client.messages().create(params);
手工实现的记录类型在 SDK 的 com.anthropic.models.messages.* 下有直接的对应类型:
已移除的类型(旧 AnthropicApi.*) | SDK 替代项(com.anthropic.models.messages.*) |
|---|---|
ChatCompletionRequest | MessageCreateParams |
ChatCompletionResponse | Message |
AnthropicMessage | MessageParam |
ContentBlock | ContentBlock(密封联合类型:TextBlock、ToolUseBlock、ThinkingBlock、RedactedThinkingBlock、ServerToolUseBlock、WebSearchToolResultBlock、ContainerUploadBlock、…) |
Tool | Tool |
ToolChoiceAuto / ToolChoiceAny / ToolChoiceTool / ToolChoiceNone | ToolChoice(具有 ToolChoiceAuto、ToolChoiceAny、ToolChoiceTool、ToolChoiceNone 变体的密封联合类型) |
Source(图像 / PDF 媒体) | Base64ImageSource、UrlImageSource、Base64PdfSource、UrlPdfSource |
MessageStartEvent、ContentBlockStartEvent、ContentBlockDeltaEvent、MessageDeltaEvent、… | RawMessageStreamEvent(密封联合类型) |
ToolUseBlock.input() 返回的是 SDK 的 JsonValue,而非 JSON 字符串。对 JsonValue 调用 .toString() 会产生 Java map 语法({key=value}),它看起来像 JSON 但并非 JSON。请使用 JsonValue.Visitor<T> 遍历,或通过 Jackson 进行序列化,以获取真正的 JSON 字符串。
已被 SDK 等效项取代
这些类型已被移除,因为 SDK 已暴露相同的概念。请直接使用 SDK 类型。
| 已移除 | 替换为 |
|---|---|
org.springframework.ai.anthropic.api.AnthropicCacheType | com.anthropic.models.messages.CacheControlEphemeral。旧的枚举仅携带字面量 ephemeral 值,这也是 API 唯一支持的缓存控制类型。 |
org.springframework.ai.anthropic.api.StreamHelper | com.anthropic.core.http.AsyncStreamResponse<RawMessageStreamEvent>。StreamHelper 是旧版 WebClient 流式路径中用于合并 SSE 的内部辅助类;SDK 现在原生提供流式事件,Spring AI 在内部将其桥接为 Reactor Flux。调用 ChatModel.stream(Prompt) 的代码不受影响。 |
org.springframework.ai.anthropic.metadata.AnthropicRateLimit | com.anthropic.errors.RateLimitException(在重试次数耗尽后由 SDK 抛出),以及 SDK 响应对象上的请求头。请将读取 ChatResponseMetadata 中速率限制元数据的代码替换为异常处理。 |
行为变更
提示词级别选项不再与模型默认值合并
上一个模块通过 ModelOptionsUtils.copyToTarget(…) 和 ModelOptionsUtils.merge(…) 将提示级别的 AnthropicChatOptions 合并到模型级别的默认值中,因此 model、temperature 以及其他未设置的字段会从模型的默认值中填充:
// Before: only maxTokens set; model + temperature inherited from defaults.
Prompt prompt = new Prompt(
"Tell me a joke",
AnthropicChatOptions.builder().maxTokens(2048).build());
chatModel.call(prompt);
新模块不会执行合并操作。提示词级别(prompt-level)的选项实例将按原样使用;如果提示词没有选项,则使用模型的默认值。
// After: prompt-level options must be "full", or null.
Prompt prompt = new Prompt(
"Tell me a joke",
chatModel.getOptions().mutate().maxTokens(2048).build());
chatModel.call(prompt);
这是 Upgrading to 2.0.0-M5 — ChatOptions Handling 中更广泛变更的前向移植,为 Anthropic 提前应用。ChatClient 在到达模型之前会自行执行合并,因此使用 ChatClient 的调用者不受影响。
默认 maxTokens 现为 4096
AnthropicChatOptions 将 maxTokens 的默认值从 500 更改为 4096。之前的默认值经常导致响应被截断,新值与其他 Spring AI 聊天模块保持一致。
如果你依赖 500 来限制成本,请显式设置:
spring.ai.anthropic.chat.max-tokens=500
重试机制使用 SDK 的 maxRetries,而非 RetryTemplate
前一个模块在其构造函数中使用了 Spring Retry 的 RetryTemplate。现在重试由 SDK 处理,并通过 maxRetries 配置(默认值为 2):
spring.ai.anthropic.max-retries=5
特定用于 Anthropic 模块的 RetryTemplate Bean 可以移除。如需更精细的控制,可通过自定义 AnthropicSetup 来配置 SDK 客户端。
流式思考事件
以下两处变更会影响订阅原始 Flux<ChatResponse> 流的任何人(而不是让 ChatClient 或 MessageAggregator 对其进行处理)。
上一个模块将 thinking 块的文本和签名打包到单个 Generation 中。SDK 将它们作为独立事件发送,新模块也按此方式转发:带有 properties.signature 的 Generation 会在 thinking 文本增量之后、任何后续文本增量之前到达。MessageAggregator 和 ChatClient 的内置聚合会透明地吸收额外的数据块。
思考文本增量(Thinking-text deltas)现在也会包含 properties.thinking = Boolean.TRUE。之前的模块将其作为普通内容输出,导致调用方在流式传输过程中无法可靠地区分思考文本和响应文本。
完整的流元数据键集合:
| 块 (Block) | Generation 携带的内容 |
|---|---|
| 思考文本增量 (Thinking text delta) | content = <thinking text>, properties.thinking = true (M3 新增) |
| 思考签名增量 (Thinking signature delta) | 空的 content, properties.signature = <signature> |
| 脱敏思考块 (Redacted thinking block) | 空的 content, properties.data = <data> |
| 同步思考块 (Sync thinking block) (非流式) | content = <thinking text>, properties.signature = <signature> (单个 Generation) |
提示缓存变更
如果你配置了 AnthropicCacheOptions,需要了解的三个行为:
-
4 个断点上限由 Spring AI 强制实施,而非 API 层面。 Anthropic 允许每个请求最多使用 4 个缓存断点。之前的模块会直接传递标记并让 API 拒绝超出部分。
CacheBreakpointTracker现在会进行计数,并静默跳过超过 4 个后的添加操作,同时记录一次性的WARN日志。最可能触发该上限的情况是SYSTEM_AND_TOOLS与多块系统提示词缓存以及引用文档的组合使用。之前因 API 错误而失败的请求,现在可以通过减少缓存成功执行,因此在升级后请检查您的缓存命中率。 -
AnthropicCacheStrategy.NONE表示“未设置”,而非“禁用”。 在 Prompt 级别设置NONE将回退到模型的默认行为。如果模型默认开启缓存,且您希望将其关闭,请构建第二个AnthropicChatModel,并将其默认值设置为AnthropicCacheOptions.disabled()。 -
工具缓存的 TTL 取自
MessageType.SYSTEM。resolveToolCacheControl会查找messageTypeTtl(MessageType.SYSTEM),这与策略无关。设置messageTypeTtl(MessageType.USER, ONE_HOUR)对工具缓存无效。
引用文档一致性在客户端进行验证
Anthropic API 要求在同一请求中,所有带有引用配置的 DocumentBlockParam 必须共享相同的 citations.enabled 值。AnthropicChatOptions.validateCitationConsistency() 现在会强制执行此规则,并在发送请求之前抛出 IllegalArgumentException。此前,该模块会允许 API 返回 HTTP 400 错误。混合使用启用和禁用引用文档的测试或调用点现在会在构建时失败,而不是在网络调用时失败。
新增的 OkHttp 传递依赖
com.anthropic:anthropic-java 会引入 com.squareup.okhttp3:okhttp。大多数应用不会受到影响;如果您有严格的依赖收敛规则或已固定的 OkHttp 版本,则可能需要添加一个 <dependencyManagement> 配置项。
新特性
迁移还启用了若干 Anthropic 功能。完整参考信息请参阅 Anthropic Chat。
-
原生技能(
AnthropicSkill、AnthropicSkillContainer)。 -
内置网络搜索工具(
AnthropicWebSearchTool)。 -
服务层级选择(
AnthropicServiceTier)。 -
用于数据驻留的推理地理位置(
us、eu)。 -
通过
JsonOutputFormat和Effort实现的原生结构化输出(需要claude-sonnet-4-6或更高版本)。 -
扩展思维显示模式(摘要 / 省略)。
-
Citation类型及其四种位置变体(CHAR_LOCATION、PAGE_LOCATION、CONTENT_BLOCK_LOCATION、WEB_SEARCH_RESULT_LOCATION)。 -
AnthropicChatOptions#httpHeaders上的逐请求 HTTP 头,与AbstractAnthropicOptions上的客户端级别customHeaders不同。customHeaders在客户端上设置一次,适用于所有请求;httpHeaders针对每个Prompt设置,并在构建请求时合并。适用于请求跟踪、Beta API 切换和路由。
无声失败的问题
编译错误比较简单,它们不会抛出异常,而是会产生不同的输出。
-
部分 Prompt 级别选项。
new Prompt(text, AnthropicChatOptions.builder().maxTokens(2048).build())不再继承模型默认的model、temperature等参数(参见 Prompt 级别选项不再与模型默认值合并)。不会出现编译错误或异常;请求将以不同的值运行。如果升级后输出发生偏移且你直接调用了ChatModel,请首先检查此处。 -
如果升级后成本上升,请检查你是否曾依赖旧的
500token 的maxTokens默认值来限制响应长度。 -
缓存断点超过四个。 将多块系统缓存与工具及引用文档叠加使用可能会超出 Anthropic 的 4 个断点限制。
CacheBreakpointTracker会跳过多余的断点并记录一次WARN日志。缓存命中率会下降,但不会报错。 -
过时的
org.springframework.ai.anthropic.api.AnthropicCache*导入项是升级后大多数编译错误的根源。通过项目范围内的查找并替换即可修复。