跳到主要内容
版本:2.0.1

将 Anthropic 模块迁移至官方 Java SDK

QWen 3.8 中英对照 Migrating the Anthropic Module to the Official 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.AnthropicCacheOptionsorg.springframework.ai.anthropic.AnthropicCacheOptions
org.springframework.ai.anthropic.api.AnthropicCacheStrategyorg.springframework.ai.anthropic.AnthropicCacheStrategy
org.springframework.ai.anthropic.api.AnthropicCacheTtlorg.springframework.ai.anthropic.AnthropicCacheTtl
org.springframework.ai.anthropic.api.utils.CacheBreakpointTrackerorg.springframework.ai.anthropic.CacheBreakpointTracker
org.springframework.ai.anthropic.api.utils.CacheEligibilityResolverorg.springframework.ai.anthropic.CacheEligibilityResolver
org.springframework.ai.anthropic.api.CitationDocumentorg.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.*)
ChatCompletionRequestMessageCreateParams
ChatCompletionResponseMessage
AnthropicMessageMessageParam
ContentBlockContentBlock(密封联合类型:TextBlock、ToolUseBlock、ThinkingBlock、RedactedThinkingBlock、ServerToolUseBlock、WebSearchToolResultBlock、ContainerUploadBlock、…​)
ToolTool
ToolChoiceAuto / ToolChoiceAny / ToolChoiceTool / ToolChoiceNoneToolChoice(具有 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.AnthropicCacheTypecom.anthropic.models.messages.CacheControlEphemeral。旧的枚举仅携带字面量 ephemeral 值,这也是 API 唯一支持的缓存控制类型。
org.springframework.ai.anthropic.api.StreamHelpercom.anthropic.core.http.AsyncStreamResponse<RawMessageStreamEvent>。StreamHelper 是旧版 WebClient 流式路径中用于合并 SSE 的内部辅助类;SDK 现在原生提供流式事件,Spring AI 在内部将其桥接为 Reactor Flux。调用 ChatModel.stream(Prompt) 的代码不受影响。
org.springframework.ai.anthropic.metadata.AnthropicRateLimitcom.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,请首先检查此处。

  • 如果升级后成本上升,请检查你是否曾依赖旧的 500 token 的 maxTokens 默认值来限制响应长度。

  • 缓存断点超过四个。 将多块系统缓存与工具及引用文档叠加使用可能会超出 Anthropic 的 4 个断点限制。CacheBreakpointTracker 会跳过多余的断点并记录一次 WARN 日志。缓存命中率会下降,但不会报错。

  • 过时的 org.springframework.ai.anthropic.api.AnthropicCache* 导入项是升级后大多数编译错误的根源。通过项目范围内的查找并替换即可修复。