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.xSpring AI 2.0.0 就不适合直接往主分支上怼。这篇只讲升级时最容易踩坑的地方。一、先看版本基线我本地对照了两个版本的源码依赖关系Spring AI 1.1.7Spring Boot 3.5.14 Spring AI 2.0.0Spring Boot 4.1.0Java 版本还是 17。所以如果你的项目还在 Spring Boot 3.5.x不建议直接这样改spring-ai.version2.0.0/spring-ai.version更稳的节奏是先继续用 Spring AI 1.1.7 等项目升级到 Spring Boot 4.x 再评估 Spring AI 2.0.0Demo、教程、内部样例也一样。先保证复制能跑再谈升级。二、RAG Advisor 依赖名变了RAG 这里很容易复制错。Spring AI 1.1.7 里VectorStore Advisor 依赖是dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-advisors-vector-store/artifactId/dependencySpring AI 2.0.0 里改成了dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-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 要显式传 conversationId2.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 Serverspring-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 相关实战内容。
