Spring AI 2.0 GA 升级清单：从 1.x 迁过来的 5 个必看变化

为什么要升级

Spring AI 2.0 GA 在 2026-06-12 发布，距离 1.0 不到一年。但这次的升级不是版本号小跳，而是把 1.x 时代所有”能用但别扭”的地方做了重写。

如果不升级，1.x 还能用，但你会逐渐被以下问题卡住：

工具超过 20 个时 token 爆掉
不同 ChatModel 的 Tool Calling 行为不一致
配置项命名混乱（.options 段、toolNames() 等）
MCP 集成停留在早期规范
项目想升级 Spring Boot 4 时和 Spring AI 1.x 不兼容

反过来，升级的代价是真实的：Spring AI 2.0 硬依赖 Spring Boot 4.0/4.1 + Spring Framework 7.0 + Java 17（推荐 21），整个项目的依赖链都要跟着走。

变化 1：基线重定义，升级是”全家桶”

2.0 依赖：

Spring Boot 4.0 / 4.1
Spring Framework 7.0
Jackson 3（不是 Jackson 2）
Java 17 起步，推荐 21
MCP Java SDK 2.0

意味着什么？任何还在 Spring Boot 3.x 的项目，迁 Spring AI 2.0 = 同时迁 Spring Boot 4 + Jackson 3。这通常是 2-4 周的迁移工作量，分两步走更稳：先把项目升到 Spring Boot 4 + Jackson 3，再升 Spring AI 2.0。

变化 2：Tool Calling 循环从”内部实现”变成”Advisor 一等公民”

这是 2.0 最核心的架构变化。

1.x 时代，每个 ChatModel 内部都有自己的 Tool Calling 循环——OpenAI 的循环、Anthropic 的循环、DeepSeek 的循环，行为不完全一致。你想”在工具调用前后插个权限检查”？做不了，因为循环埋在 ChatModel 实现里。

2.0 的方案：

// ToolCallingAdvisor 自动注册到 ChatClient
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(ToolCallingAdvisor.builder().build())
    .build();

工具调用循环被提升到 Advisor 链里，所有 ChatModel 共享同一套执行框架。结果：拦截、包装、替换执行策略第一次成为可能。

需要”在每次工具调用前做权限审计”？加个 Advisor。
需要”工具调用失败时回退到默认回答”？加个 Advisor。
需要”工具调用超过 5 次强制结束”？加个 Advisor。

2.0 暴露了 4 个扩展点：doInitializeLoop / doBeforeCall / doAfterCall / doFinalizeLoop，每个都是可插拔的横切点。

变化 3：ToolSearchToolCallingAdvisor——100 个工具只发 5 个

工具多了之后，prompt 会塞满工具描述。单次调用 10-21K token 起步。

2.0 引入 ToolSearchToolCallingAdvisor，核心机制：工具不再”全部塞进 prompt”，而是注册到工具中心，模型按需检索。

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        ToolSearchToolCallingAdvisor.builder()
            .maxTools(5)
            .searchStrategy(SearchStrategy.SEMANTIC)
            .build()
    )
    .build();

实测效果：在 OpenAI、Anthropic、Gemini 上，token 消耗降低 34-64%，准确率没有可测量的下降。

为什么这件事重要？**企业级 AI 应用的核心矛盾不是”模型不够强”，而是”工具太多”**。你接了 50 个内部系统，每个系统 3-5 个 API，那就是 200+ 工具。1.x 时代要么硬扛 token 成本，要么手动分组搞多 Agent。2.0 给了一个标准答案。

配置侧一行：

1 2	spring.ai.chat.client.tool-search-advisor.enabled=true spring.ai.chat.client.tool-search-advisor.tool-index-type=vector

变化 4：MCP 2.0 + 新注解

MCP 集成是 2.0 的另一大块升级。

SDK 升级到 MCP Java SDK 2.0，符合最新规范
三个新注解：@McpTool、@McpResource、@McpPrompt，声明式写 MCP 服务端
默认传输改为 Streamable HTTP（替代之前的 STDIO），和生产环境部署对齐
内建 OAuth 2.0、API Key 鉴权、OpenTelemetry metrics

这意味着什么？**MCP 服务从”手写 HTTP 处理器”变成”加注解”**。一个 Spring Boot 项目挂几个 @McpTool 方法，就对外暴露了标准 MCP 服务，被 Claude、Cursor、Spring AI Alibaba 任何兼容客户端消费。

@McpTool(description = "Query an order summary by order id")
public OrderSummary findOrder(@McpToolParam String orderId) {
    // 业务逻辑
    return orderService.findById(orderId);
}

变化 5：Options 重构 + 全量 JSpecify

1.x 的 Options 和配置属性耦合，.options 段在配置文件里非常反直觉。2.0 重写了这块：

哪些 Option 是必填、哪些可选，API 上写清楚
默认值在 Option 级别定义，不在 model / config 散落
Option 用 Builder 创建，创建后不可变
移除了 .options 段在 application.yml 中的”奇怪路径”

更彻底的是，2.0 全量加了 JSpecify 注解——所有方法的参数和返回值都标注了 @Nullable 或 @Nonnull。Kotlin 开发者终于能在编译期检查空安全，Java 开发者靠 IDE 静态分析也能少踩 NPE 的坑。

迁移实战清单

如果你决定升级，按这个顺序：

先把 Spring Boot 升到 4.x、Jackson 升到 3。这一步独立做，验证业务逻辑 OK。
改 Spring AI 依赖到 2.0。spring-ai-starter-model-openai 等核心 starter 都还在。
跑一遍应用，看启动时哪些 Option 路径失效。.options 段全部去掉，配置 key 跟着 2.0 重命名。
改 Tool 注册方式。toolNames() 和 SpringBeanToolCallbackResolver 没了，工具必须注册为 ToolCallback bean 并显式通过 .tools() 传入。
**加 ToolCallingAdvisor**。如果你的代码以前依赖 model 内部工具循环，要显式在 ChatClient 上加这个 Advisor 才能跑通。
MCP 集成。如果你自己写过 MCP 服务端，按 2.0 新注解重写一遍，传输改成 Streamable HTTP。

意味着什么？

Spring AI 2.0 的本质变化是：**从”LLM 调用的胶水”变成”Agent 运行时框架”**。

1.x 时代，Spring AI 主要解决”Java 怎么调 LLM”。2.0 时代，它开始承担”如何治理 Tool Calling 循环、如何管理大量工具、如何被 Agent 框架集成”这些更上层的问题。

对 Java 后端来说，这是一个信号：Spring 团队不打算让 Java 在 AI Agent 时代掉队。Spring AI 2.0 + Spring AI Alibaba 的组合，已经能完整覆盖 LangChain + LangGraph 在 Python 生态里做的事。

如果你正在用 Spring AI 1.x 跑生产，别急着升，但要在 2026 年底前规划升级窗口。等到 Spring AI 生态（Alibaba、第三方 starter）的 2.0 适配都稳定了再动，是更稳的策略。