Spring AI 2.0.0 升级注意事项：Spring Boot 4、RAG Advisor、Tool Calling、MCP 怎么看

Spring AI 2.0.0 升级注意事项：Spring Boot 4、RAG Advisor、Tool Calling、MCP 怎么看

Spring AI 2.0.0 已经发布，很多 Java 项目都会遇到一个问题：

现在要不要从 Spring AI 1.1.x 升到 2.0.0？

如果你现在项目里用的是：

Spring Boot 3.5.x Spring AI 1.1.x

先别急着把 BOM 改成2.0.0。

这次升级不是只改一个版本号。

最关键的前提是：

Spring AI 1.1.x → Spring Boot 3.5.x Spring AI 2.x → Spring Boot 4.x

如果项目还没准备好升级 Spring Boot 4.x，Spring AI 2.0.0 就不适合直接往主分支上怼。

这篇只讲升级时最容易踩坑的地方。

一、先看版本基线

我本地对照了两个版本的源码依赖关系：

Spring AI 1.1.7：Spring Boot 3.5.14 Spring AI 2.0.0：Spring Boot 4.1.0

Java 版本还是 17。

所以如果你的项目还在 Spring Boot 3.5.x，不建议直接这样改：

<spring-ai.version>2.0.0</spring-ai.version>

更稳的节奏是：

先继续用 Spring AI 1.1.7 等项目升级到 Spring Boot 4.x 再评估 Spring AI 2.0.0

Demo、教程、内部样例也一样。

先保证复制能跑，再谈升级。

二、RAG Advisor 依赖名变了

RAG 这里很容易复制错。

Spring AI 1.1.7 里，VectorStore Advisor 依赖是：

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-advisors-vector-store</artifactId></dependency>

Spring AI 2.0.0 里，改成了：

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-vector-store-advisor</artifactId></dependency>

名字只差一点，但复制错就会直接拉不到依赖。

所以看 RAG 示例时，先确认项目版本：

不要只看代码块像不像。

版本不对，依赖名就不对。

三、Tool Calling 进入 Advisor 链

Tool Calling 这一块，2.0.0 的调整比较明显。

在 1.x 里，工具调用循环更分散，很多逻辑在不同ChatModel实现里处理。

到 2.0.0，工具调用更明确地进入了 Advisor 体系。

一个明显变化是：

ChatClient 会自动注册 ToolCallingAdvisor

请求里带工具时，工具调用循环由 Advisor 处理。

一些旧配置也被移除了，比如：

internalToolExecutionEnabled

如果老代码里设置过这个选项，升级时要检查。

这会影响后续怎么排查 Agent 行为。

工具调用不再只藏在某个模型实现里，而是进入ChatClient的执行链。

后面要看这些问题，都绕不开 Advisor 链：

工具选择 多轮工具调用 记忆 结构化输出 失败重试 观测日志

排查问题时，不要只盯模型实现，也要看ChatClient和 Advisor。

四、工具多了以后，不能全塞给模型

2.0.0 新增了和工具检索有关的组件：

ToolSearchToolCallingAdvisor

对应依赖也有独立名字：

spring-ai-tool-search-advisor spring-ai-starter-tool-search-advisor

它解决的问题很实际：

工具多了以后，不能每次都把所有工具描述发给模型。

一个企业 Agent 可能有几十个工具：

查订单 查库存 查物流 创建工单 审批流程 查询知识库 操作文件 调用运维平台 访问数据库

如果每次请求都把所有工具全部塞给模型，会带来几个问题：

上下文变长 token 成本上升 模型更容易选错工具 工具描述互相干扰

ToolSearchToolCallingAdvisor的思路是：

先从工具集合里检索相关工具 再把少量相关工具交给模型

这和 RAG 很像。

RAG 是从文档里检索相关资料。

Tool Search 是从工具里检索相关能力。

企业 Agent 做起来后，问题很快会从“能不能调工具”变成：

工具有几十个时，模型怎么挑对那一个？

五、Memory 要显式传 conversationId

2.0.0 里，Chat Memory 也变严格了。

内置 Memory Advisor 需要显式传：

conversationId

真实系统里，会话一定要和用户、租户、业务场景绑定：

userId sessionId tenantId conversationId

如果默认会话 ID 用得太随意，不同用户的上下文就可能混在一起。

另外，PromptChatMemoryAdvisor被移除了。

建议改用：

MessageChatMemoryAdvisor

这个方向也更合理。

Memory 不应该只是往 prompt 里塞一段历史文本。

更合适的方式，是把历史对话作为消息结构交给模型。

六、MCP 重点看远程传输和生产化能力

MCP 这块，2.0.0 把不少能力收进了 Spring AI 自己的体系。

可以重点看这些变化：

MCP Java SDK 升级 MCP Server 参数校验更严格 MCP 注解能力进入 Spring AI MCP WebMVC / WebFlux transport 迁到 Spring AI SSE 标记为 deprecated，推荐 Streamable HTTP

如果只是连接本地 Filesystem MCP Server：

spring-ai-starter-mcp-client stdio ToolCallbackProvider

这条主线仍然成立。

本地工具用 stdio 没问题。

真正要注意的是远程 MCP Server。

如果要做远程服务、企业集成、多人调用，就要看这些关键词：

Streamable HTTP Stateless OAuth / API Key Micrometer / OpenTelemetry

也就是说，本地 stdio 不是废弃。

需要迁移的是旧的 SSE Server transport 场景。

七、有些 starter 被移走或调整了

2.0.0 移除或调整了一些 starter。

Upgrade notes 里明确提到过这些：

spring-ai-starter-model-azure-openai spring-ai-starter-model-openai-sdk spring-ai-starter-model-chat-memory-repository-cosmos-db

这些不再按原来的方式留在 Spring AI 主仓库里。

但下面这些还在：

spring-ai-starter-model-deepseek spring-ai-starter-model-openai spring-ai-starter-model-ollama spring-ai-starter-mcp-client spring-ai-starter-vector-store-pgvector

对Spring AI + DeepSeek示例来说，DeepSeek starter 本身不是问题。

先看更大的前提：

项目能不能一起升级到 Spring Boot 4.x。

这个前提不满足，就先别动 2.0.0。

八、到底要不要升？

如果你现在是在学习 Spring AI，或者维护一套已经跑通的 Demo：

继续用 Spring AI 1.1.7 + Spring Boot 3.5.x

原因很简单：

示例已经跑通 依赖和代码更稳定 Spring Boot 3.5.x 更贴近很多现有项目 读者复制代码时更容易成功

如果你是新项目，并且已经准备直接上 Spring Boot 4：

可以评估 Spring AI 2.0.0

但升级前至少检查这些点：

RAG Advisor 依赖名 Tool Calling 相关配置 Memory Advisor 的 conversationId MCP Server 的传输协议 被移除的模型 starter 默认 temperature 行为

已有项目迁移，建议单独拉分支验证。

不要在主分支直接改版本。

写在最后

Spring AI 2.0.0 不是单纯多几个 API。

它更像是在把 Spring AI 从：

统一模型调用框架

往：

Java Agent 开发基础设施

推进。

Tool Calling 进 Advisor 链路。

Memory 要显式传 conversationId。

MCP 更接近生产级集成方式。

工具多了以后，也开始考虑 Tool Search。

这些变化对应的是同一类工程问题：

让 Agent 更适合承载复杂任务，而不是只做一层聊天封装。

我的建议是：

学习和现有 Demo：继续用 1.1.7 新项目且准备上 Boot 4：再看 2.0.0

别为了追版本打乱项目节奏。

能跑、能排查、能回滚，比版本号更重要。

后续会继续整理 Spring AI、RAG、Tool Calling、MCP 和 Java Agent 相关实战内容。