Spring AI 2.0 系列（一）：Spring AI 2.0升级了什么？

Spring AI 2.0 系列（一）：Spring AI 2.0升级了什么？

本文基于 Spring AI 2.0.2。2.0 于 2026 年 6 月正式 GA，2.0.2 是当前稳定维护版本；2.1.0-RC1 虽已发布，但仍属候选版本，生产项目建议先以 2.0.2 为基准。具体 API 以官方 Release Notes 和对应版本文档为准。

官网学习入口：spring.io/projects/spring-ai#learn，可自行选择对应版本。
中文参考手册：Chat Client API :: Spring AI 参考手册

这是 Spring AI 2.0 系列的第一篇。这篇会先花点篇幅把 Spring AI 的核心概念对齐，再看 2.0 的升级；如果你已经比较熟悉 Spring AI，可以直接跳到第四节看 2.0 的定位变化；如果想更多了解Spring AI，建议按顺序读。

一、Spring AI 是什么

Spring AI 是 Spring 官方推出的 AI 应用框架，面向 Java 开发者。它的目标很直接：让写 AI 功能和写其他 Spring 组件差不多——用 Starter、自动配置、统一抽象把模型接入和周边工程问题包起来，开发者主要关注业务逻辑。

它不是某个模型的 SDK 封装，也不是一个实验性工具。从设计上看，它要解决的是 Java 应用接入大模型时的一整串工程问题：换模型要不要改业务代码、多轮上下文怎么管、模型返回的 JSON 怎么稳定映射、工具调用由谁执行、RAG 怎么接、生产环境怎么观测。这些问题不是某一个模型能解决的，而是应用框架该解决的。

二、核心概念：先认识这几个抽象

在展开特性之前，先把 Spring AI 里几个常打交道的概念对齐。后面看 2.0 的变化会顺很多，因为 2.0 主要是在调整这些抽象之间的职责边界，而不是发明一堆新品类。

概念	解决什么问题
ChatModel	底层模型调用抽象，屏蔽供应商差异
ChatClient	面向应用开发者的高层 API，日常写业务主要用它
Advisor	在请求前后插入记忆、工具调用、RAG、日志等逻辑
ToolCallback	把 Java 方法注册成模型可调用的工具
Chat Memory	多轮对话上下文管理
结构化输出	把模型输出映射成 Java 对象
RAG / VectorStore	接向量库做检索增强
可观测性	指标、日志、评估、原生镜像等生产化能力

其中 ChatModel 和 ChatClient 的关系值得单独说一句：ChatModel 是底层积木，ChatClient 是应用层门面。1.x 里两者的边界还比较模糊，2.0 则把这条线划得更清楚。

三、主要特性与能力

下面这些能力，是 Spring AI 长期提供的。2.0 没有推翻它们，而是把它们重新组织到更可组合的架构上。

可移植的模型抽象。 通过 ChatClient 和 ChatModel，可以用一致的方式调用不同供应商的模型，比如 OpenAI、Anthropic、Google、Ollama、Azure OpenAI 等。业务代码尽量不直接依赖某一家 SDK，换模型时改动范围可控。

提示与输出管理。 支持提示填充（Prompt Filling），把相关数据注入到发给模型的提示里；也支持结构化输出（Structured Outputs），把模型返回直接映射成 Java 对象，方便程序处理。

函数调用（Function Calling）。 模型可以根据对话内容，请求执行预先定义好的客户端函数或工具，从而访问实时信息或执行具体操作，比如查数据库、调 API。对应到 Spring AI 的抽象，就是 ToolCallback 和工具调用管线。

对话记忆（Chat Memory）。 模型本身是无状态的，框架负责维护和管理对话历史，让模型能理解上下文，进行连贯的多轮对话。

检索增强生成（RAG）。 内置对 RAG 模式的支持。可以把企业文档存进向量数据库（PGVector、Chroma、Milvus 等），提问时先检索相关内容，再作为上下文发给模型，减少幻觉。

可观测性与评估。 提供对 AI 操作的可观测性支持，也包含评估工具，帮助检测和防止模型产生幻觉。

面向生产的特性。 继承 Spring Boot 的生产就绪理念，支持虚拟线程、GraalVM 原生镜像，并与 Spring Boot DevTools、Docker Compose、Testcontainers 有较好集成。

四、定位与优势

对于已经在用 Spring 生态的团队，Spring AI 的主要优势可以概括为三点。

对 Spring 开发者友好。 熟悉 Spring Boot 的话，用 Spring AI 会比较自然。它提供 Starter、自动配置和配置属性，上手成本低。

避免重复造轮子。 它借鉴了其他语言 AI 应用框架的经验，但专为 Java 和 Spring idioms 设计，省去在 Java 里从头搭 AI 集成基础设施的麻烦。

企业级就绪。 从可观测性、可测试性到原生镜像支持，设计时就考虑了生产环境，而不是只做一个实验性工具。

五、1.0 的边界：能调模型，但工具循环还在 ChatModel 里

Spring AI 1.0 的核心贡献，是让 Java 开发者能以 Spring 惯用的方式调用大模型：统一的 ChatClient、可移植的模型抽象、结构化输出、基础 RAG。它解决的是“Java 生态能比较顺地接上 AI”这个问题。

但 1.x 有一个明显的架构特征：工具调用的执行循环写在各个 ChatModel 内部。 OpenAI、Anthropic、Ollama、MistralAI、DeepSeek、Bedrock Proxy、MiniMax 等模型实现里都有自己的工具调用循环。

这带来两个问题：一是工具循环对开发者更像黑盒，不同模型的行为可能有细微差异；二是工具调用很难像记忆、RAG、日志那样，作为 Advisor 链中的一环被组合和观测。1.x 里工具注册还依赖 toolNames() 和 SpringBeanToolCallbackResolver，按 Bean 名称在请求时隐式解析，用起来方便，但来源不够显式。

所以 1.0 的边界很清楚：它让 Java 能调模型，但工具调用、记忆、结构化输出这些能力还没有完全围绕同一条应用层管线组织起来。

六、2.0 的定位变化：ChatClient 到应用层，ChatModel 退到底层

Spring AI 2.0 于 2026 年 6 月正式 GA。如果说 1.0 解决了“Java 能调用大模型”，2.0 的核心目标，是让 Java 开发者能以工程化、可组合的方式构建生产级 Agent 应用。

最关键的信号有两个。官方把 ChatClient 定位为最常见的用户面 API，把 ChatModel 定位为更底层的 building block；与此同时，1.x 中硬编码在各个 ChatModel 里的工具调用循环被整体移除，上移到 ChatClient 的 Advisor 管线中，由 ToolCallingAdvisor 编排，或者由用户自行控制 DefaultToolCallingManager 循环。

这两件事合在一起，指向同一个结论：2.0 不再只是一个模型调用工具，而是在把 ChatClient + Advisor 做成 Agent 应用的应用层。 模型是底层积木，Advisor 管线才是应用开发者日常编排的地方。后面的工具调用外置、记忆窗口对齐、结构化输出增强、Options 重构，都可以放在这个视角下理解。

七、2.0 的具体升级

1. 基础架构与工程化：门槛提高，但基座更一致

这是 2.0 最底层的变化，为上层能力提供更稳固的基座。

• 强制 Java 21 与 Spring Boot 4 基线：Spring AI 2.0 要求 Java 21，并基于 Spring Boot 4.0/4.1 和 Spring Framework 7 构建。可以直接利用新一代 Spring 生态在可观测性、配置模型等方面的能力。
• Jackson 3 与 JSON 处理增强：JSON 序列化库从 Jackson 2 升级到 Jackson 3，包名从 com.fasterxml.jackson 迁到 tools.jackson。同时新增 JsonHelper 工具类，让自定义 JsonMapper 和处理复杂 JSON 场景更统一。
• 全面引入 JSpecify 空安全：整个代码库使用 JSpecify 注解标识参数和返回值的可空性，并配合 NullAway + ErrorProne 在编译期强制检查。这能减少 AI 应用里常见的空指针问题，也为 Kotlin 用户提供更符合语言习惯的空安全 API。
• Options 配置体系重构：默认值统一在 Options 层定义，不再分散在模型或配置属性中；Options 只能通过 Builder 创建，且不可变，保证线程安全和可预测性；移除了 application 属性键中人为添加的 .options 段，并修复了大量相关缺陷。

迁移时注意：如果项目还在 Java 17 / Boot 3.x，必须先升 JDK 和 Boot，才能引入 Spring AI 2.0。自定义 ObjectMapper、序列化器、@JsonIgnore 等 Jackson 2 相关代码要逐一验证；旧构造器创建 Options 的代码改成 Builder；空安全要在消费端配置 NullAway / ErrorProne 才真正生效，只加 JSpecify 注解不会自动强制检查。

2. 工具调用完全外置：2.0 最核心的架构变化

这是 2.0 最核心的优化，对应前面说的“函数调用”能力。它把 Agent 的构建能力从 ChatModel 的黑盒里解放出来。

• 工具调用逻辑完全外置与统一：1.x 中工具调用的执行循环硬编码在各个 ChatModel 内部，开发者无法干预。2.0 移除了所有 ChatModel 中的内置循环，把工具执行的责任上移，统一由 ChatClient 通过 ToolCallingAdvisor 编排。工具调用逻辑在不同模型间变得一致，并且可组合、可观测、可扩展。
• 工具调用循环升级为递归 Advisor：工具调用的循环能力不再隐藏，而是作为一种递归 Advisor 存在于 Advisor 链中。可以像配置记忆、脱敏 Advisor 一样，在统一的“洋葱模型”管线里装配和管理工具调用、结构化输出校验重问等需要多轮交互的逻辑。
• 更灵活、安全的工具注册：移除了通过 Bean 名称隐式解析工具的 toolNames() API 和 SpringBeanToolCallbackResolver。工具必须显式注册为 ToolCallback Bean，并通过 .tools() 方法直接传入，来源和范围更明确。.tools() 现在可以直接接受 ToolCallback、ToolCallbackProvider 及其集合或数组。
• 新增工具搜索 Advisor（按需发现）：新增 ToolSearchToolCallingAdvisor，支持 LLM 按需发现和调用工具，而不是每次请求加载全部工具定义。它内置三种 ToolIndex：向量存储、Lucene、正则。这对拥有大量工具的企业级 Agent 场景很有用，可以控制 prompt 膨胀。

另外，ToolCallAdvisor 重命名为 ToolCallingAdvisor，旧名保留为废弃子类，给编译警告而不是直接编译错误，迁移时留意一下。

迁移时注意：把 toolNames() 或按 Bean 名称注册的工具改成显式 ToolCallback Bean，并在 .tools() 中传入；依赖旧 ToolCallAdvisor 的代码切到 ToolCallingAdvisor；工具数量多时，评估 ToolSearchToolCallingAdvisor，不要一次性加载全部定义；检查自定义 ChatModel 子类是否依赖了被移除的内部工具循环。

3. Chat Memory 与结构化输出：不改变大 API，但影响生产质量

这些优化对应前面说的“对话记忆”和“结构化输出”能力，提升多轮对话的可靠性及数据处理的健壮性。

• 记忆窗口的轮次边界对齐：MessageWindowChatMemory 在消息窗口溢出时，会向前推进到最近的 USER 消息进行淘汰，而不是把一轮对话从中间切断，保证上下文的逻辑完整性。
• 修复工具调用场景下的记忆重复问题：在工具调用的后续提示中，避免重复前置已经存储的记忆消息，同时仍将最新的工具响应保留在记忆中。
• JdbcChatMemoryRepository 增强：现在可以通过编程方式访问 spring_ai_chat_memory 表中的 timestamp 字段，Dialect 接口改用默认方法，自定义方言更简单。
• 结构化输出 API 增强：ChatClient.entity() 新增 EntityParamSpec，支持在单次调用中更精细地控制结构化输出的参数。

2.0.2 还有一个记忆基础设施的修复值得单独提：Neo4j ChatMemoryRepository 的索引被纠正。此前创建的索引引用了错误的节点属性，导致每次会话查找退化为全标签扫描；2.0.2 启动时会创建正确的新索引，旧索引需要手动清理。如果你用 Neo4j 做记忆存储，升级后建议执行文档里的 DROP INDEX 语句。

迁移时注意：自定义 ChatMemory 或依赖旧窗口淘汰行为的，验证轮次边界变化是否符合业务预期；使用 JdbcChatMemoryRepository 自定义 Dialect 的，检查是否需要适配新的默认方法；结构化输出如果有复杂参数控制需求，可以试试 EntityParamSpec；使用 Neo4jChatMemoryRepository 的项目，升级 2.0.2 后手动移除过期索引。

4. 生态与集成：一边收敛，一边扩展

• 模型提供商收敛：核心项目支持的模型提供商列表被精简和聚焦。OpenAI 从 3 个变体（Azure、HTTP、SDK）收敛为 1 个 SDK；Anthropic 从 2 个变体（HTTP、SDK）收敛为 1 个 SDK。spring-ai-azure-openai 模块被移除，Azure OpenAI 功能通过标准 spring-ai-openai 模块提供，依赖需要从 spring-ai-azure-openai 替换为 spring-ai-openai。Vertex AI 的非 embedding 模块、ZhipuAI、OCI GenAI 也被移出主仓库或独立维护。
• 向量存储与语义缓存扩展：新增 Amazon S3、Infinispan、Amazon Bedrock Knowledge Base 等向量存储后端；引入基于 Redis 的语义缓存 Advisor，可以缓存语义相似的查询，减少重复模型调用。
• 厂商集成模块独立：像 Azure Cosmos DB 这类厂商特定集成模块，从核心仓库独立出去，由厂商自行维护和发布，拥有独立发布节奏。

2.0.2 在可观测性上还补了一块：OpenAI 文本转语音、转写模型，ElevenLabs TTS 模型以及 Stability AI 图像模型，在存在 ObservationRegistry 时会报告 observation，产生新的指标序列和 span。内容日志处理器默认关闭，需要显式开启。

迁移时注意：使用 spring-ai-azure-openai 的项目替换为 spring-ai-openai，并按 Azure 部署方式调整配置；用了 Vertex AI 非 embedding 能力、ZhipuAI 或 OCI GenAI 的，检查是否已迁移到独立模块或替代提供商；高频重复查询场景可以评估 Redis 语义缓存 Advisor；依赖可观测性数据的，升级 2.0.2 后验证 TTS、转写、图像调用的指标和 span 是否符合预期。

八、1.x 到 2.0 变化对比

维度	1.x	2.0（含 2.0.2）	实际影响
定位	模型调用工具	Agent 编排框架	架构设计从“调模型”转向“编排 Advisor”
工具循环	ChatModel 内置	ChatClient + ToolCallingAdvisor 外置	可组合、可观测；自定义工具需显式注册
工具注册	toolNames() 隐式解析	ToolCallback Bean + .tools() 显式传入	来源更明确，但需要迁移代码
配置	Options 构造器，默认值分散	Options Builder，默认值统一，不可变	写法需迁移，线程安全提升
JSON	Jackson 2	Jackson 3（tools.jackson）	自定义序列化器需排查
空安全	注解不强制	JSpecify + NullAway 编译期强制	消费端需配置工具链
模型提供商	多变体	收敛为 SDK 单实现；Azure 合并到 openai 模块	依赖坐标需调整
基线	Java 17 / Boot 3.x	Java 21 / Boot 4.x	必须先升 JDK 和 Boot
稳定版本	1.x GA	2.0.2（2.1 尚为 RC）	生产项目以 2.0.2 为基准

九、一个最小示例：看工具如何进入 Advisor 管线

下面这段伪代码重点不在 API 细节，而在工具是怎么进入 Advisor 管线的。

// 1) 工具显式注册为 ToolCallback Bean，不再依赖 toolNames 隐式解析
@Bean
ToolCallback orderStatusTool() {
    return FunctionToolCallback.builder("orderStatus", ...)
        .description("查询订单状态")
        .build();
}

// 2) ChatClient 构建时装配 Advisor 管线
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        MessageChatMemoryAdvisor.builder(chatMemory).build()
        // ToolCallingAdvisor 也可以在这里显式装配
    )
    .build();

// 3) 请求时直接传入 ToolCallback
String answer = chatClient.prompt()
    .user("帮我查一下订单 A123 的状态")
    .tools(orderStatusTool)
    .call()
    .content();

1.x 里，工具循环发生在 ChatModel 内部；2.0 里，它是 Advisor 链中的一环。也就是说，你可以像插入记忆、脱敏、重试 Advisor 一样，对工具调用进行组合和观测。

十、升级检查清单

动手前逐项过一遍：

• JDK 是否 21+？
• Spring Boot 是否 4.x？
• Jackson 依赖和自定义序列化器是否按 Jackson 3 排查过？
• 是否还在用旧构造器创建 Options？改成 Builder。
• 工具是否还依赖 toolNames() 或 Bean 名称隐式解析？改成显式 ToolCallback。
• 是否用了 ToolCallAdvisor？考虑迁移到 ToolCallingAdvisor。
• 是否用了 spring-ai-azure-openai？替换为 spring-ai-openai。
• 自定义 ChatMemory 或 Dialect 是否需要适配轮次边界和默认方法？
• 是否使用 Neo4jChatMemoryRepository？升级 2.0.2 后清理过期索引。
• 消费端是否配置了 NullAway / ErrorProne，以享受编译期空安全校验？
• 是否有大量工具场景，值得评估 ToolSearchToolCallingAdvisor？
• 如果依赖可观测性，验证 TTS、转写、图像调用的 observation 是否按预期工作。

十一、国内生态补充：Spring AI Alibaba

国内生态里，阿里巴巴基于 Spring AI 开源了 Spring AI Alibaba。它在 Spring AI 的模型接入和 Advisor 链之上，增加了对阿里云模型、工具及云原生基础设施的深度适配，并提供了 Spring AI Alibaba Graph 作为 Agent 编排的底层运行时，以及包含 SequentialAgent、ParallelAgent、SupervisorAgent 等在内的 Agent Framework。对于需要复杂工作流和多智能体协作的国内团队，这是一个值得在 Spring AI 主线之外单独关注的方向，后续会另开一篇展开。

参考资料

• Spring AI 2.1.0-RC1 and 2.0.2 Available Now：https://spring.io/blog/2026/10/23/spring-ai-2-1-0-RC1-available-now
• Spring AI Upgrade Notes：https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/upgrade-notes.html
• Spring AI 项目主页：https://spring.io/projects/spring-ai
• Spring AI 参考文档：https://docs.spring.io/spring-ai/reference/
• 中文参考手册：https://docs.springframework.org.cn/spring-ai/reference/api/chatclient.html