Spring AI 2.0升级指南：1.x迁移清单与Breaking Changes全解析

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

本节目标：掌握 1.x 到 2.0 的全部关键破坏性变更。学完你能按清单逐项检查老项目，完成一次不踩坑的迁移。

44.1 版本现状

Spring AI 2.0.0 于 2026 年 6 月 12 日发布 GA。这是继 1.0 GA 之后的第一个 Major 版本，官方明确列出了一批 Breaking Changes。

当前版本线：

2.0.0：最新稳定版，本教程主线。
1.1.8 / 1.0.9：维护线，只修 bug，不再加功能。
2.0.1-SNAPSHOT / 1.1.9-SNAPSHOT：开发快照。

2.0 的硬核变化集中在五处：工具调用 API 换代、ChatClient 与 Options 收紧、Anthropic 迁移官方 SDK、OpenAI 模块重构、MCP 全面升级。下面逐项过。

44.2 升级前准备

先确认基线。2.0 要求：

Spring AI BOM：2.0.0
Spring Boot：4.0.x / 4.1.x
Java：17 及以上，建议 21

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>2.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

还有一个行为变化要知道：从 2.0.0-M7 起，OpenAI 等部分 Provider 在客户端构造时强制要求 API Key（issue #6150）。本地开发用的 Ollama 不受影响，但走云厂商的配置要检查 Key 是否齐全。

Note

2.0 还移除了 Spring AI 自带的默认温度 0.7。不显式配置的话，温度由各厂商 API 决定。想保持旧行为，就在配置里显式写 temperature=0.7。

44.3 工具调用 API 换代

2.0 最核心的变更：FunctionCallback 体系被 ToolCallback 体系取代。第 24-26 章已经讲过新 API 的用法。函数式、方法式工具和 ChatClient 注册入口的逐项对照见第 26 章 §26.2，这里只列它没覆盖的增量变化：

旧写法	新写法	说明
`@Description` + `Function` Bean	`@Tool` 注解或 `ToolCallback` Bean	声明式定义
`.function("name")` / `.toolNames("name")`	`.toolCallbacks(callback)`	按名引用被移除
`SpringBeanToolCallbackResolver`	直接声明 `ToolCallback` Bean	Bean 工具解析被移除

典型的代码迁移：

// 1.x
FunctionCallback.builder()
        .function("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build();

// 2.0
FunctionToolCallback.builder("getCurrentWeather", new MockWeatherService())
        .description("Get the weather in location")
        .inputType(MockWeatherService.Request.class)
        .build();

工具执行循环也有变化。2.0 里 ChatClient 自动注册 ToolCallingAdvisor，工具调用自动执行，不需要任何开关。internalToolExecutionEnabled、streamToolCallResponses、ToolExecutionEligibilityPredicate 全部移除。

想自定义循环条件，用新的扩展点：

ToolCallingAdvisor advisor = ToolCallingAdvisor.builder()
        .toolExecutionEligibilityChecker(response ->
                response != null && response.hasToolCalls()
                        && !"stop".equals(response.getResult().getMetadata().getFinishReason()))
        .build();

全局开关也有：spring.ai.chat.client.tool-calling.enabled=false 可以关掉自动执行。

44.4 ChatClient 与 Options 变化

ChatClient 的 Fluent API 在 2.0 成为一等公民，同时收紧了几个用法。

Options 必须传 Builder。.options() 和 .defaultOptions() 不再接收构建好的实例：

// 1.x
ChatOptions opts = AnthropicChatOptions.builder().maxTokens(100).build();
chatClient.prompt("Tell me a joke").options(opts).call().content();

// 2.0
chatClient.prompt("Tell me a joke")
        .options(AnthropicChatOptions.builder().maxTokens(100).temperature(0.7))
        .call().content();

Options 严格不可变。copy() 和 fromOptions() 移除，改集合会抛异常。要改一份副本，用 mutate()：

// 1.x
OllamaChatOptions options = originalOptions.copy();
options.setFoo("...");

// 2.0
OllamaChatOptions options = originalOptions.mutate().foo("...").build();

方法更名与属性扁平化。getDefaultOptions() 改为 getOptions()；builder 的 N() 改为 n()；配置属性的 .options 前缀移除：

# 1.x
spring.ai.openai.embedding.options.model=text-embedding-3-small

# 2.0
spring.ai.openai.embedding.model=text-embedding-3-small

tools() 不再收 Consumer。tools(t -> t.callbacks(...).context(...)) 这种写法移除，工具和上下文分开传：

chatClient.prompt()
        .tools(myCallback)
        .toolContext(Map.of("tenantId", "acme"))
        .call().content();

44.5 聊天记忆收紧

记忆相关的破坏性变更不少，逐个说。

会话 ID 必填。MessageChatMemoryAdvisor 和 VectorStoreChatMemoryAdvisor 不再有默认会话。每次调用都要通过 advisor context 传 ChatMemory.CONVERSATION_ID，缺失直接抛异常。ChatMemory.DEFAULT_CONVERSATION_ID 常量已删除，builder 上的 .conversationId() 也没了。

ChatClient chatClient = ChatClient.builder(chatModel)
        .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
        .build();

chatClient.prompt()
        .user("Hello!")
        .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "my-session"))
        .call()
        .content();

PromptChatMemoryAdvisor 删除。它的功能是把记忆当文本塞进系统提示词，现在统一用 MessageChatMemoryAdvisor，历史记录以消息形式进提示。

JDBC 记忆表加列。JdbcChatMemoryRepository 新增 sequence_id 列决定消息顺序。旧表必须加列才能用，官方提供了 ALTER TABLE 脚本，按 conversation_id 和 timestamp 回填序号。

44.6 Anthropic 迁移官方 SDK

2.0 里 spring-ai-anthropic 底层换成了官方 com.anthropic:anthropic-java SDK，替换了自研的 RestClient 实现。第 12 章讲过接入方式，这里只说迁移。

好消息：走 ChatClient 或 ChatModel 的代码基本不用改。Maven 坐标、spring.ai.anthropic.* 配置、ChatClient API 全部保留。

要改的：

旧写法	新写法	说明
`new AnthropicApi(apiKey)`	`AnthropicChatModel.builder()`	AnthropicApi 类删除
`new AnthropicChatModel(api, options)`	`AnthropicChatModel.builder().apiKey(...).defaultOptions(...)`	公开构造器移除
`AnthropicApi.ChatCompletionRequest`	`com.anthropic.models.messages.MessageCreateParams`	直接用 SDK 类型
`org.springframework.ai.anthropic.api.AnthropicCacheOptions`	`org.springframework.ai.anthropic.AnthropicCacheOptions`	缓存类移到根包
`CitationDocument`	`AnthropicCitationDocument`	改名
`RetryTemplate` 构造参数	SDK 的 `maxRetries`	重试机制换了

// 1.x
AnthropicApi anthropicApi = new AnthropicApi(apiKey);
AnthropicChatModel chatModel = new AnthropicChatModel(anthropicApi, options);

// 2.0
AnthropicChatModel chatModel = AnthropicChatModel.builder()
        .apiKey(apiKey)
        .defaultOptions(options)
        .build();

三个行为变化要留意。

maxTokens 默认值从 500 变成 4096。以前靠 500 限制成本的，输出会变长、费用变高，记得显式设置。

Prompt 级 Options 不再合并模型默认值。直接调 ChatModel.call(Prompt) 时，prompt 里带了 Options 就按它原样用，缺的字段不会从模型默认值补齐。走 ChatClient 不受影响，它自己会合并。

缓存类型与枚举值不变。AnthropicCacheStrategy（NONE、TOOLS_ONLY、SYSTEM_ONLY、SYSTEM_AND_TOOLS、CONVERSATION_HISTORY）和 AnthropicCacheTtl（FIVE_MINUTES、ONE_HOUR）原样保留，只是换了包。

新版本还白送几个能力：内置网页搜索工具、服务等级选择、推理地域（us/eu）、原生结构化输出。需要的话看官方 Anthropic Chat 参考文档。

Tip

迁移后最容易翻车的不是编译错误，而是静默行为变化：输出变长（maxTokens 4096）、直接调 ChatModel 时参数不合并。升级后先跑一轮对比测试。

44.7 OpenAI 与模型模块变化

OpenAI 模块底层换成官方 openai-java SDK。spring.ai.openai.* 配置、builder、选项全部保留，extraBody 自动映射到 SDK 的 additionalBodyProperties，官方说预期没有重大破坏。

两个模块被移除：

spring-ai-azure-openai：改用 spring-ai-openai，类名去掉 Azure 前缀。
spring-ai-openai-sdk：并入 spring-ai-openai，类名去掉 Sdk 后缀。
spring-ai-oci-genai：迁到 oracle/spring-cloud-oracle 仓库。
spring-ai-hanadb-store：删除。

Minimax 专属支持也删了。官方建议改用 Anthropic 支持，把 base URL 配成 https://api.minimax.io/anthropic，模型用 MiniMax 的型号。

44.8 MCP 相关变化

MCP Java SDK 升级到 2.0.0，Spring AI 侧跟着一批变更。第 27-31 章的内容以 2.0 为准。

旧写法	新写法	说明
`org.springaicommunity.mcp.annotation.*`	`org.springframework.ai.mcp.annotation.*`	注解类并入 Spring AI
`io.modelcontextprotocol.sdk:mcp-spring-webflux`	`org.springframework.ai:mcp-spring-webflux`	transport 模块换 groupId
`McpAsyncClientCustomizer` / `McpSyncClientCustomizer`	`McpClientCustomizer<B>`	自定义器合并
Jackson `TypeReference<T>`	Spring `ParameterizedTypeReference<T>`	elicit() 签名变化
`CreateMessageResult.builder()`	`CreateMessageResult.builder(Role, content, model)`	必填字段前移
`Builder.customizeRequest()`	`Builder.httpRequestCustomizer()`	HTTP 定制方法更名

MCP 注解的迁移可以用官方 OpenRewrite recipe 自动化：

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpAnnotations \
  -Dmaven.compiler.failOnError=false

只用 Spring AI starter 的项目，transport 模块的 groupId 由 BOM 管理，改依赖坐标即可，Java 代码不用动。

44.9 其他变化速览

剩下的变化列成速查表，遇到再细看官方升级笔记：

变更	说明
`ToolSearchToolCallingAdvisor` 换模块	移到 `spring-ai-tool-search-advisor`，新包名 `org.springframework.ai.chat.client.advisor.toolsearch`，见第 43 章
`spring-ai-advisors-vector-store` 改名	变为 `spring-ai-vector-store-advisor`
Conversation history 移出 ToolContext	工具拿不到对话历史，由 ToolCallingAdvisor 管理
`internalCall` / `internalStream` 变 private	改用 `call()` / `stream()`
可观测性 span 改名	`tool_call` 变为 `execute_tool`，新增 `spring.ai.tool.type` 等属性
JsonParser 弃用	统一用新的 `JsonHelper`，ModelOptionsUtils 的 JSON 方法移除
默认温度移除	原来框架统一 0.7，现在由厂商决定
MongoDB 记忆排序修复	之前倒序返回，2.0 修正为按发送顺序
Usage 新增缓存指标	`getCacheReadInputTokens()` / `getCacheWriteInputTokens()`
Azure Cosmos DB 移出主仓库	由 Azure 团队作为外部模块维护
Cloud Bindings 模块删除	不再提供 spring-cloud-bindings 集成

44.10 迁移步骤清单

按顺序执行，可以少踩坑：

升级 BOM 到 2.0.0，Spring Boot 升到 4.0.x/4.1.x，Java 17+。
全项目替换工具 API：FunctionCallback → ToolCallback，functions() → tools()。
删掉 internalToolExecutionEnabled、streamToolCallResponses 相关调用。
Options 相关：.options(builder)、mutate()、getOptions()、n()、属性去 .options 前缀。
聊天记忆：补 CONVERSATION_ID，PromptChatMemoryAdvisor 换 MessageChatMemoryAdvisor，JDBC 表加 sequence_id。
用 Anthropic 的检查缓存类 import 和 maxTokens 配置。
MCP 项目跑 OpenRewrite recipe，改 groupId，合并 Customizer。
检查配置里的 temperature，需要旧行为就显式写 0.7。
跑测试，重点对比输出长度和工具调用行为。
有疑问翻官方 Upgrade Notes，里面有每项变更的完整迁移示例。

Note

1.1.x 与 1.0.x 的维护线还在，但只修 bug。新功能都在 2.0 线，早晚要迁。

44.11 小结

2.0 的破坏性变更看着多，主线就几条：工具 API 换 ToolCallback、Options 收紧不可变、记忆必须显式传会话 ID、Anthropic 和 OpenAI 都迁到官方 SDK、MCP 全面升级。

迁移清单的核心是编译错误不可怕，可怕的是静默变化：maxTokens 4096、默认温度消失、Prompt 级 Options 不合并。逐项对照，先编译后对比，迁移就稳了。

到这里，Spring AI 的核心知识就讲完了。下一章是附录，汇总延伸阅读与生态资源。

从 1.x 升级到 2.0

44.1 版本现状

44.2 升级前准备

44.3 工具调用 API 换代

44.4 ChatClient 与 Options 变化

44.5 聊天记忆收紧

44.6 Anthropic 迁移官方 SDK

44.7 OpenAI 与模型模块变化

44.8 MCP 相关变化

44.9 其他变化速览

44.10 迁移步骤清单

44.11 小结