版本基准:本文基于 Spring AI 2.0.x GA 编写,同时标注 1.x 线的关键差异。2.1 处于开发中,生产慎用其新 API。
安全前置提醒 :Spring AI 1.0.7 / 1.1.6 修复了 CVE-2026-41712(ChatMemory.DEFAULT_CONVERSATION_ID 导致跨用户数据泄露)。根据官方安全公告,受影响版本为 1.0.0--1.0.6 与 1.1.0--1.1.5 ,修复版本正是 1.0.7 / 1.1.6 。任何低于这两个版本的 1.x 都不应在多用户环境中使用,无论其余功能看起来是否正常。
这篇写给两类人:第一次把大模型接进 Java 项目、想搞明白各个概念的人;以及 Demo 跑通了、准备上生产、担心踩坑的人。
先记住三句话:
- Spring AI 的价值不是"又封装了一遍大模型 API",而是把 Spring 开发者熟悉的依赖注入 、自动配置、Advisor 链搬到了 AI 调用上。依赖注入和自动配置是 Spring 的核心机制------你要什么告诉它,它帮你准备好、接好,不用自己到处创建和连线。Advisor 链是一串"工序",模型调用前后依次做点事。
- 你面对的是
ChatClient,不是裸 HTTP;模型调用、工具循环、记忆、检索都被收进了这条链。 - 大模型本身是无状态的------所谓"记忆"是你每次把历史一起发过去的,不是模型记住了你。
全文按"是什么 → 版本口径 → 四大件 → 坑分类 → 对比选型 → 排查 → 社区经验 → 速查表"组织。术语第一次出现尽量用大白话解释。
第一部分:零基础地基
1.1 大模型调用是怎么回事
往简单说,调用大模型就是:你发一段文字(Prompt,提示词)过去,它回一段文字。
这段 Prompt 里通常有两类消息:
- system 消息:告诉模型"你是谁、该怎么回答",比如"你是电商客服,只回答订单问题";
- user 消息:用户实际问的话。
1.2 Spring AI 在中间做了什么
如果直接用 HTTP 调模型 API,你要自己拼 JSON、处理鉴权、解析响应。Spring AI 把这些封装起来,给你一个叫 ChatClient 的流式 API:
scss
String answer = ChatClient.builder(chatModel).build()
.prompt()
.user("用一句话解释什么是虚拟线程")
.call()
.content();
ChatClient.create(chatModel) 是便捷写法,2.0 仍然存在。生产代码建议统一用 builder(),以便显式设置 defaultSystem、defaultAdvisors 等默认值;后文示例也以 builder() 为准。
你不用管底层是哪个模型厂商、HTTP 怎么发------换模型时改的是 starter 和配置,核心代码不变。这就是 Spring AI 说的"模型无关抽象"。
1.3 四个必须先认识的概念
| 概念 | 大白话 |
|---|---|
| ChatClient | 调用模型的统一入口 |
| Advisor | 拦截器,在发请求前/收响应后做点事(加历史、加检索结果、打印日志) |
| Tool Calling | 模型说"我要查天气",应用执行查询再把结果给它------模型拿不到 API 的直接访问权 |
| ChatMemory | 保存对话历史的东西,配合 Advisor 每轮塞进 Prompt |
第二部分:版本口径(先把话说准)
截至本文写作时,Spring AI 的版本线大致如下:
| 版本线 | 状态 | 适用 Spring Boot | 最低安全补丁 |
|---|---|---|---|
| 1.0.x | 维护中,补丁版本持续发布 | Boot 3.x | ≥ 1.0.7 |
| 1.1.x | 当前 1.x 线的稳定推荐,适合 Boot 3.x 生产项目 | Boot 3.x | ≥ 1.1.6 |
| 2.0.x GA(2.0.0 于 2026 年 6 月 GA) | 当前 2.x 线的稳定推荐,面向 Boot 4.x | Boot 4.0.x / 4.1.x | 2.0.x 最新 GA 补丁 |
| 2.1.x | 开发中,SessionAdvisors、记忆 API 的 @Deprecated 迁移在此线 | Boot 4.2(随 2.1 GA 正式支持) | 不用于生产 |
选型建议:
- 新项目如果已经在 Boot 4.x ,直接用 2.0.x GA;
- 还在 Boot 3.x 的项目,继续用 1.1.x(≥ 1.1.6) ,不必为了"用新版本"强行升级 Boot;如果因客观原因锁在 1.0.x,必须 ≥ 1.0.7;
- 2.1.x 的能力不要当生产 API 用 ,尤其是
SessionAdvisors和记忆 API 的废弃迁移,等 2.1 GA 后再考虑。
依赖通常长这样(用属性管理版本,不要照抄占位符;写作时 2.0.x 已有 2.0.2 维护版本):
xml
<properties>
<spring-ai.version>2.0.2</spring-ai.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
</dependencies>
BOM 是版本清单:你在 BOM 里声明一次版本,下面引入的 Spring AI 各个模块就不用逐个写版本。换成国产模型或其他提供商时,写法不变,只换 starter 和配置。
1.x 用户注意 :1.1.x 的 BOM 版本至少写
1.1.6,不要使用任何低于 1.1.6 的版本------1.1.0--1.1.5 均在 CVE-2026-41712 影响范围内。1.0.x 同理,至少1.0.7;1.0.0--1.0.6 均受影响。starter 命名规则是spring-ai-starter-model-<厂商标识>。MessageChatMemoryAdvisor在 1.1.x 中使用builder(),不要使用new;当前 1.1.x 的构造器已不可公开访问,具体可见性以所用版本 Javadoc 为准。new不可用与 conversation ID 默认值移除是两件独立的事 ,1.1.x 早期版本中new同样不应依赖。conversation ID 必填的准确版本口径 :1.0.7 / 1.1.6 起,内置 memory advisor 要求显式传入 conversation ID,
ChatMemory.DEFAULT_CONVERSATION_ID被移除,.conversationId()builder 方法也一并删除。官方 1.0.7 / 1.1.6 发布说明明确写道:"Chat memory advisors now require an explicit conversation ID to be supplied"。1.0.x 与 1.1.x 两条线同步修复。2.0 延续了这一行为。
第三部分:四大件逐个讲透
3.1 ChatClient:把所有调用收成一个入口
ChatClient.Builder 支持设置一堆"默认值",这样运行时代码就很干净:
scss
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultSystem("你是电商后台助手,只回答订单和库存问题。")
.defaultOptions(ChatOptions.builder().temperature(0.7).build())
.defaultAdvisors(...)
.defaultTools(...)
.build();
默认值和运行时对应方法的区别(advisors / tools 的运行时方法通常是追加或配置语义,不是简单"替换"默认值):
| Builder 默认方法 | 作用 | 运行时对应方法 / 注意 |
|---|---|---|
| defaultSystem(...) | 默认系统提示词 | system(...),本次请求替换默认 system |
| defaultOptions(...) | 默认模型参数(模型名、temperature 等) | options(...),本次请求覆盖对应选项 |
| defaultAdvisors(...) | 默认 Advisor 链 | advisors(...),追加/配置语义,不是替换默认链;重复注册就是坑 1 的根源 |
| defaultTools(...) | 默认工具 | tools(...),本次请求追加工具 |
mutate() 是重点 :它基于已有 ChatClient 的默认设置创建新 Builder,是"继承 + 增量",不是从头开始。用它可以派生客户端,不必重复定义所有默认值------但也正因为会继承,重复注册就是坑(见坑 1)。
流式调用 :call() 等全部生成完再返回,适合普通接口;聊天界面用 stream() 边生成边返回:
scss
Flux<String> flux = chatClient.prompt()
.user("介绍一下 Spring AI")
.stream()
.content();
生产中使用
stream()时,记得处理错误、取消、背压和 SSE 超时。背压 是指下游消费不过来时向上游反压、控制发送速率;SSE(Server-Sent Events)是服务器向浏览器持续推送事件的协议,流式聊天界面常用。入门阶段先把链路跑通即可。
3.2 Advisor:真正决定"上下文从哪来"
Advisor 链是 Spring AI 最容易用错、也最值得搞懂的部分。它会拦截并修改最终发给模型的 Prompt。常见两个:
MessageChatMemoryAdvisor:把历史对话塞进 Prompt;QuestionAnswerAdvisor:从向量库检索与用户问题相关的文档,把结果作为上下文追加到 Prompt。
2.x 写法:
scss
String content = ChatClient.builder(chatModel)
.build()
.prompt()
.advisors(a -> a
.advisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
QuestionAnswerAdvisor.builder(vectorStore).build()
)
.param(ChatMemory.CONVERSATION_ID, conversationId))
.user(userText)
.call()
.content();
这里演示的是运行时追加 Advisor;若希望所有请求默认携带,可在 ChatClient.builder(...).defaultAdvisors(...) 中注册,运行时再通过 .advisors(a -> a.param(...)) 传参(见 5.3)。
1.1.x 写法 :同样使用 builder(),不要 new。MessageChatMemoryAdvisor 的构造器在 1.1.x 中已不可公开访问:
less
.advisors(a -> a
.advisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
QuestionAnswerAdvisor.builder(vectorStore).build()
)
.param(ChatMemory.CONVERSATION_ID, conversationId))
2.1 的额外变化 :
MessageChatMemoryAdvisor和ChatMemoryAPI 在 2.1 中已被标记为@Deprecated(since = "2.1.0", forRemoval = true),计划在 3.0 移除,长期方向是迁移到 session memory。如果你现在用 2.0.x,可以继续用 builder 方式;如果计划近期升到 2.1,建议关注迁移指南,但不要在生产中把SessionAdvisors当作稳定 API 使用。
顺序决定执行顺序 。默认 order 下 memory advisor 在 QA advisor 之前,目的是让最终 Prompt 中先有历史、后有检索上下文。但要注意:QuestionAnswerAdvisor 的检索查询是否自动并入历史,取决于具体实现和版本,官方文档的基准描述是"用用户问题去向量库检索相关文档" ,并不承诺自动把你的历史对话全部拼进检索 query。多轮对话里的指代("那它支持离线吗?")在检索前通常需要额外的问题改写;把顺序调成 memory 在前,能保证 Prompt 里同时有历史和检索结果,但不等于检索查询本身一定会被改写。这一点在第七部分社区经验里也会再提。
两条硬规则:
- Advisor 按顺序执行,前一个的修改会传给后一个;
- 用 memory advisor 时,每次调用都必须传
ChatMemory.CONVERSATION_ID。这个约束从 1.0.7 / 1.1.6 起就已存在,2.0 延续;没有默认回退,漏传会在运行时抛异常。CVE-2026-41712 的修复方式就是移除DEFAULT_CONVERSATION_ID常量及其隐式回退逻辑。
调试时可以用 SimpleLoggerAdvisor,并把它注册到链上(仅改日志级别不一定足够):
scss
chatClient.prompt()
.advisors(SimpleLoggerAdvisor.builder().build())
.user(...)
.call()
.content();
ini
logging.level.org.springframework.ai.chat.client.advisor=DEBUG
SimpleLoggerAdvisor 在 2.0.x 中仍可使用 new SimpleLoggerAdvisor(),但 builder() 是更稳妥的写法。生产环境打印完整请求/响应可能泄露敏感信息,SimpleLoggerAdvisor 不要裸上生产。
3.3 Tool Calling:模型只"请求",应用来"执行"
官方定义很关键:工具调用是模型调用应用定义的函数并消费结果的能力。但模型永远拿不到工具背后 API 的直接访问权------它只能说"我要调用某工具,参数是这些",由你的应用执行、把结果返回。这是安全边界。
定义一个工具:
kotlin
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
class WeatherTools {
@Tool(description = "Get the current weather for a given city")
public String getWeather(
@ToolParam(description = "City name") String city) {
return weatherService.fetch(city);
}
}
注册并调用:
scss
String response = ChatClient.builder(chatModel).build()
.prompt()
.user("上海现在天气怎么样?")
.tools(new WeatherTools())
.call()
.content();
工具循环的版本差异与自动注册 :1.x 里工具调用循环埋在各个 ChatModel 实现内部;2.0 把它整体搬进了 Advisor 链 ,由 ToolCallingAdvisor 驱动。关键点: ToolCallingAdvisor 由 DefaultChatClient 自动注册 ,官方文档的原话是"Most applications don't construct ToolCallingAdvisor directly --- DefaultChatClient auto-registers one with sensible defaults"。而 ChatClient.builder(chatModel) 构建的正是 DefaultChatClient 实例。因此无论是自动配置注入的 ChatClient.Builder,还是手动 ChatClient.builder(chatModel),只要配置了工具,ToolCallingAdvisor 都会自动挂上,不需要、也不应该手动再注册一个。只有当你需要非默认配置(例如自定义 toolCallingManager、调整 advisorOrder、替换为自定义子类)时,才应手动构建并注册 ToolCallingAdvisor。
注意命名:2.0 的正确类名是 ToolCallingAdvisor ,旧名 ToolCallAdvisor 只作为 @Deprecated(since = "2.0.0", forRemoval = true) 的兼容子类保留。
关闭自动注册有两种粒度:
- 全局关闭 :
spring.ai.chat.client.tool-calling.enabled=false(2.0 引入,默认true)。工具定义仍会发给模型,但ToolCallingAdvisor不会自动注册,工具调用不会自动执行。 - 单次调用关闭 :在 prompt 级别使用
AdvisorParams.toolCallingAdvisorAutoRegister(false):
scss
client.prompt()
.tools(myTool)
.advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
.call();
工具定义仍会发送给模型,但自动循环不再介入,你可以自己用 ToolCallingManager 驱动循环。
AOT / GraalVM :如果包含 @Tool 方法的类是 Spring bean (@Component 等),Spring AI 内置支持 AOT 编译;如果工具类不是 bean,才需要加 @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS) 手动提供反射配置。AOT 是提前编译,GraalVM 原生镜像场景下反射需要显式注册。
3.4 ChatMemory:模型自己不记事儿
聊天模型 API 是无状态的。你告诉它你的名字,下一轮它不会记得;历史必须每轮随请求发送。
稳定线的做法是 MessageChatMemoryAdvisor + ChatMemory + conversation id。生产上先做到三件事就够了:
- 每个会话一个稳定
conversationId; - 历史条数设上限,别无限增长(
MessageWindowChatMemory用builder().maxMessages(20)控制窗口); - 敏感字段进 Prompt 前脱敏,日志也别把完整上下文打出来。
MessageChatMemoryAdvisor在组装请求时会把 system 消息保持在消息列表最前面,但它保存的对话历史主要是 user/assistant 消息。下一节的坑 2 说的是"每轮动态 system 注入导致提示词漂移",与"system 消息是否被存入记忆"是两件事;窗口压力主要来自历史未截断,不要混为一谈。
第四部分:坑分类列全
分三类:
- A 类:Advisor 与记忆配置错------坑 1~4
- B 类:工具调用设计错------坑 5~8
- C 类:生产工程问题------坑 9~10
A 类:Advisor 与记忆配置错
坑 1:mutate() 重复注册 Advisor
mutate() 会继承 原客户端的默认配置。有人在默认配置里已经加了 Memory Advisor,又用 chatClient.mutate().defaultAdvisors(记忆 advisor)... 补工具,结果挂了两个记忆 Advisor:
- 历史消息被注入两次,Token 白白翻倍(Token 是大模型处理文字的最小单位;调用按 Token 收费、也有长度上限,重复发一遍既费钱又占地方);
- 问答对被重复存进记忆。
修复:派生客户端时只加新东西,别重复加已有的。
scss
// ✅ 只补工具,记忆已在默认配置里
this.chatClient = chatClient.mutate()
.defaultTools(orderTools)
.build();
坑 2:动态 system 消息每轮变化,导致提示词漂移
有人每轮都用 .system(...) 临时设置提示词,聊几轮后模型开始"失忆"或行为不一致。这通常不是"system 消息被重复注入"导致的,而是两个独立问题叠加的结果:
- 提示词漂移 :每轮
.system(...)改变系统指令,模型行为不一致,看起来像"忘了之前怎么回答"; - 窗口挤占:真正的窗口压力来自对话历史未截断,而不是 system 消息本身。
只有当你使用的记忆实现或自定义 Advisor 恰好也保存了 system 消息时,才会出现 SystemMessage 重复进入上下文、进一步挤占窗口的情况。MessageChatMemoryAdvisor 的默认保存主体是 user/assistant 消息,不要简单断言它一定会把 system 消息存成历史。
修复 :固定的系统提示词放到 defaultSystem(),不要每轮动态加;历史用 MessageWindowChatMemory 设上限。系统提示词的设置方式要和记忆策略一起设计。
坑 3:忘传 conversationId
用 memory advisor 时每次调用都要传 ChatMemory.CONVERSATION_ID。这个约束从 1.0.7 / 1.1.6 起就已生效,2.0 延续 ;没有默认回退,DEFAULT_CONVERSATION_ID 已删除,漏传直接抛异常。这是最容易在联调时踩的错,尤其是从更早的 1.x 版本升级上来的项目------补丁版本一升就会暴露。
坑 4:Advisor 顺序随意调
顺序影响结果:想让最终 Prompt 中先有历史、后有检索上下文,memory advisor 要在 QA advisor 前面;日志 Advisor 靠后。别随意增删重排,改了要加注释说明为什么。
B 类:工具调用设计错
坑 5:不写工具 description
@Tool 的 description 不是给人看的注释,是模型判断"什么时候调用这个工具"的依据。写"handles product requests"基本等于没写;写"按 SKU 查商品当前价格和库存"才有用。
其他要求:
- 工具名在传给模型的一组工具里必须唯一;
@ToolParam(description=...)描述参数,减少传错;- AOT 场景见 3.3 节:工具类是 Spring bean 时自动支持,不是 bean 才需要
@RegisterReflection。
坑 6:工具异常直接抛给模型
工具方法抛运行时异常时,具体行为取决于版本和 provider,但生产代码不应依赖框架的异常兜底策略。某些版本会把异常消息原样返回给模型/客户端,可能带出内部堆栈、主机信息。工具内部 catch,返回安全、可操作的提示(比如"城市不存在,请用标准城市名"),堆栈留在服务端日志------这是必须自己做的事。
坑 7:重复注册 ToolCallingAdvisor
如前所述,ToolCallingAdvisor 由 DefaultChatClient 自动注册。在默认值和每次请求的 advisor 两处都手动加同一个 ToolCallingAdvisor,会触发"一个链里只能有一个 ToolAdvisor"的异常(ToolCallingAdvisor 实现 ToolAdvisor 标记接口,DefaultChatClient 借此强制单 ToolAdvisor 约束)。把注册收拢到一个配置类里能省很多排查时间。不要因为"想确保工具循环启用"而手动加一个------它已经在链上了。
坑 8:工具循环缺少上限与权限边界
工具调用的自动循环默认会持续到模型不再请求工具为止。官方文档并没有暴露一个简单的 maxIterations 配置项;循环的停止条件由 toolExecutionEligibilityChecker 判定,默认是"模型响应里是否还有工具调用"。生产环境需要主动收口:
- 循环上限 / 超时 :如果担心单次请求被反复工具调用拖长,可以在工具实现内部或外围调用层 加超时和预算控制,而不是假设
ToolCallingAdvisor有一个现成的最大迭代次数参数; - 参数校验与权限边界:模型生成的工具参数不可信,工具方法内部要对参数做校验;敏感工具(退款、改单等)应在应用层做权限判断,而不是把决策完全交给模型;
- 返回结果大小限制:工具返回的大段文本会原样进入后续 Prompt,必要时截断或摘要,避免单次工具结果挤爆窗口。
C 类:生产工程问题
坑 9:内存 ChatMemory 在多实例下丢会话
ChatMemory 默认常见于内存实现。请求打到实例 A 有历史,打到实例 B 就没了。上多副本前,要么把会话存到外部存储(Redis 等),要么在负载均衡上做会话保持(后者只是权宜之计)。
坑 10:把大模型当数据库用
该查库的查库,工具返回结构化结果,别让模型"凭记忆"编数据。RAG(检索增强生成,Retrieval-Augmented Generation)正是为了解决"模型不知道你的私有数据"而存在的:先把相关文档检索出来,再让模型基于这些文档回答。
第五部分:把三件事串进一个 Controller
把"记忆 + 检索 + 工具"三件事都放进配置,Controller 只负责传 sessionId 和问题。
说明 :本示例基于 2.0.x GA。1.x 用户需替换 artifact 名和 advisor 构造方式(见 5.2 与 3.2)。示例用于验证"记忆 + 检索 + 工具"的链路能够串通 ;要让 RAG 真正生效,还需要先把文档 embedding 写入
VectorStore,空SimpleVectorStore只能保证不报错,检索结果为空。以下代码片段省略 import,关键类的包名以所用版本 Javadoc 为准(
@Tool、@ToolParam在org.springframework.ai.tool.annotation,AdvisorParams在org.springframework.ai.chat.client,SimpleVectorStore在org.springframework.ai.vectorstore)。
5.1 先补齐两个必须的 bean
chatModel 由 model starter 自动配置;chatMemory 和 vectorStore 需要你自己提供 bean,否则启动会因缺 bean 失败:
scss
@Configuration
class AiConfig {
@Bean
ChatMemory chatMemory() {
return MessageWindowChatMemory.builder()
.maxMessages(20)
.build();
}
@Bean
VectorStore vectorStore(EmbeddingModel embeddingModel) {
return SimpleVectorStore.builder(embeddingModel).build();
}
}
SimpleVectorStore.builder(EmbeddingModel) 是 2.0.x 的正确用法;public 构造器已移除。EmbeddingModel 是否自动配置取决于所用 model starter;如果所用 starter 不自动配置 EmbeddingModel ,需要在上面的 AiConfig 中显式声明一个对应厂商的 EmbeddingModel bean ,否则按示例复制会因缺 bean 启动失败。Embedding 是把文本转成向量表示的过程,向量库靠这个向量做相似度检索。
SimpleVectorStore 是内存实现,适合入门跑通;生产替换为 Redis、PGVector 等持久化 VectorStore 即可。
5.2 依赖与业务工具
用到 QuestionAnswerAdvisor 需要加 spring-ai-vector-store-advisor (2.0 中已从 1.x 的 spring-ai-advisors-vector-store 重命名而来):
xml
<!-- Spring AI 2.0.x --><dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-vector-store-advisor</artifactId>
</dependency>
1.1.x 用户 :artifactId 仍为
spring-ai-advisors-vector-store,不要照抄 2.0 的名字。
orderService 用最小实现演示:
typescript
interface OrderService {
String getStatus(String orderId);
}
@Service
class SimpleOrderService implements OrderService {
@Override
public String getStatus(String orderId) {
return "订单 " + orderId + " 处理中";
}
}
OrderTools 建议注册为 Spring bean(@Component 或 @Bean),这样 AOT/GraalVM 场景下无需额外反射配置:
kotlin
@Component
class OrderTools {
private final OrderService orderService;
OrderTools(OrderService orderService) {
this.orderService = orderService;
}
@Tool(description = "Query order status by order id")
public String getOrderStatus(
@ToolParam(description = "Order id, e.g. 10086") String orderId) {
return orderService.getStatus(orderId);
}
}
5.3 Controller
scss
@RestController
class ChatController {
private final ChatClient chatClient;
ChatController(ChatModel chatModel,
ChatMemory chatMemory,
VectorStore vectorStore,
OrderTools orderTools) {
this.chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(
MessageChatMemoryAdvisor.builder(chatMemory).build(),
QuestionAnswerAdvisor.builder(vectorStore).build())
.defaultTools(orderTools)
.build();
}
@PostMapping("/chat")
String chat(@RequestBody ChatRequest request) {
return chatClient.prompt()
.user(request.q())
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, request.sessionId()))
.call()
.content();
}
record ChatRequest(String sessionId, String q) {}
}
关于工具循环 :5.3 使用
ChatClient.builder(chatModel)手动构建,构建出的DefaultChatClient仍会自动注册ToolCallingAdvisor,因此defaultTools(orderTools)配置的工具会被自动驱动循环,不需要额外加ToolCallingAdvisor。这里容易误解的一点 :
defaultAdvisors(...)已经注册了 memory 和 QA advisor,运行时.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId))不是"再加一个 advisor" ,而是给默认链里的 memory advisor 传conversationId参数。不会导致重复注册。生产安全提示 :示例用
@PostMapping+@RequestBody,而不是@RequestParam或 GET,目的有两个:避免用户问题和会话标识出现在 URL / query string 中,减少访问日志、代理日志泄露的风险;同时让请求体成为主要参数载体,比把敏感参数拼在 URL 上更可控。即便如此,服务端仍应做日志脱敏,不要把完整请求体原样打进 INFO 日志。超时、限流、异常兜底和可观测性不在这个最小示例范围内,上生产前需要另外补。1.1.x 用户 :Advisor 的构造方式与上面一致(
builder()),不需要改成new。真正需要区分的只有 5.2 的 artifact 名(1.x 用spring-ai-advisors-vector-store)。
第六部分:对比与选型
6.1 两种调用方式
| 方式 | 用法 | 适合 |
|---|---|---|
| 同步 call() | 等全部生成完再返回 | 普通接口、后台任务 |
| 流式 stream() | 边生成边返回 | 聊天界面,体验更好 |
6.2 记忆方案对比
| 方案 | 优点 | 限制 |
|---|---|---|
| 内存 ChatMemory | 简单,单机 Demo 够用 | 多实例丢会话,重启丢 |
| 外部存储(Redis 等) | 跨实例共享、可持久化 | 要自己接,多一层依赖 |
| SessionAdvisors(2.1 开发中) | 统一历史/压缩/工具循环 | 开发中,不建议生产 |
6.3 什么时候用 Spring AI
| 情况 | 建议 |
|---|---|
| Spring 技术栈、要接大模型 | ✅ 直接用,复用依赖注入和自动配置 |
| 只是一个简单脚本调一次模型 | 直接用模型 SDK 可能更轻 |
| 已有非 Spring 的 Java 微服务、不想引入 Spring 依赖 | 直接用模型 SDK,避免为了一次调用背上一整套容器和自动配置 |
| 要复杂的多 Agent 编排 | 评估专门的 Agent 框架,Spring AI 提供基础块 |
第七部分:别人踩过的坑(社区实践,不是官方结论)
mutate()是"继承 + 增量",不是"重新开始"。 有开发者在日志里看到同一批 Advisor 执行两次、历史消息重复注入,根源就是重复注册。- 动态 system 消息每轮变化会导致提示词漂移;窗口压力主要来自历史未截断。 社区反馈做顾问机器人时每轮
.system(...),聊几轮后"失忆";修复是改成defaultSystem(),并给历史设窗口上限。 - 多轮对话里的指代,检索前要先改写。 用户问"那它支持离线吗?",直接拿去检索基本查不到------文档里是书面语。做法是检索前先用一次模型调用把"历史 + 当前问题"改写成能独立理解的问题。
QuestionAnswerAdvisor的默认检索查询以用户问题为基准,不能指望它自动完成这个改写。 ToolCallingAdvisor重复注册会直接报错。 它已经由DefaultChatClient自动注册,手动再加就是坑;把注册收拢到一个配置类里。- 工具 description 写含糊,模型就不调用。 这是社区里被反复强调的一条。
以上是别人项目里的故障现象,不是 API 的必然行为。是否命中取决于你的 Advisor 配置和记忆策略。
第八部分:排查与速查表
建议排查顺序:先版本 → 再 Advisor 注册与 conversation ID → 再 system 策略与 Advisor 顺序 → 再工具 description 与异常处理 → 上多实例前检查 ChatMemory 存储。
| 症状 | 最可能的原因 | 去第几节 |
|---|---|---|
| 报缺 conversation id | memory advisor 必传参数(1.0.7 / 1.1.6 起已生效,2.0 延续;无默认回退,DEFAULT_CONVERSATION_ID 已删除) | 坑 3、3.2、第二部分 |
| Token 翻倍、历史重复 | mutate() 重复挂 Advisor | 坑 1 |
| 聊几轮就失忆或行为不一致 | 动态 system 每轮变化 / 历史没截断 | 坑 2、3.4 |
| 工具不触发 | description 含糊 / 模型不支持 / 工具未通过 .tools() 传入 | 坑 5、3.3 |
| 返回里有堆栈信息 | 工具异常原样回传(不应依赖框架兜底) | 坑 6 |
| 多实例会话丢 | 内存 ChatMemory | 坑 9 |
| 不知道发了什么 Prompt | 把 SimpleLoggerAdvisor 注册到链上,并调日志级别 | 3.2 |
| 想换模型 | 换 starter 和配置,核心代码不变 | 第二部分 |
| 想关工具自动注册 | 全局:spring.ai.chat.client.tool-calling.enabled=false;单次:AdvisorParams.toolCallingAdvisorAutoRegister(false);1.x 无此属性 | 3.3 |
| QuestionAnswerAdvisor 找不到类 | 2.0 artifact 名是 spring-ai-vector-store-advisor,不是 1.x 的 spring-ai-advisors-vector-store | 5.2 |
| 多用户历史串话 | 版本低于 1.0.7 / 1.1.6,或未传 conversation ID | 第二部分、CVE-2026-41712 |
| 工具 Advisor 报"一个链里只能有一个" | 重复注册了 ToolCallingAdvisor | 坑 7 |
| 工具循环一直不结束或单次请求过长 | 未在工具实现或外围调用层设超时/预算;工具反复返回可被继续调用的结果 | 坑 8 |
| 工具被越权调用或参数异常 | 工具参数未校验、权限未在应用层判断 | 坑 8 |
| 检索结果为空 | 文档未 embedding 写入 VectorStore,或 SimpleVectorStore 为空 | 5.1 |
参考资料
官方文档与安全公告:
- CVE-2026-41712:
ChatMemory.DEFAULT_CONVERSATION_ID导致跨用户数据泄露(影响 1.0.0--1.0.6 / 1.1.0--1.1.5,修复版本 1.0.7 / 1.1.6) --- spring.io/security/cv... - Spring AI 1.0.7 / 1.1.6 / 2.0.0-M6 Available Now(memory advisor 强制显式 conversation ID) --- spring.io/blog/2026/0...
- Spring AI 2.0.0 GA Available Now(2026-06-12) --- spring.io/blog/2026/0...
- Spring AI 2.0.2 稳定文档:ToolCallingAdvisor(
DefaultChatClient自动注册、单 ToolAdvisor 约束、builder 选项) --- docs.spring.io/spring-ai/r... - Spring AI Chat Client API(defaults、mutate、Advisor 顺序、
CONVERSATION_ID、SimpleLoggerAdvisor) --- docs.spring.io/spring-ai/r... - Spring AI Tool AOT 编译与
@RegisterReflection--- docs.spring.io/spring-ai/r... - Spring AI Session Memory(2.1 中
ChatMemoryAPI、MessageChatMemoryAdvisor标记@Deprecated(since = "2.1.0", forRemoval = true)) --- docs.spring.io/spring-ai/r...
社区实践参考(经验贴,非官方结论) :
- Spring AI 实战:把 RAG、记忆、工具调用整合成物流智能客服系统(mutate 重复挂 Advisor) --- juejin.cn/post/768866...
- 别再把大模型当 HTTP 接口调:一条 Advisor 管线管住记忆、脱敏与结构化输出 --- www.xujun.org/note-209797...
- Spring AI 核心组件实战:ChatClient 与 ChatMemory 上下文管理 --- www.wmrh.cn/news/757498
- At most one ToolAdvisor is allowed in the advisor chain(重复注册触发异常) --- errors.standardbeagle.com/spring-proj...
- ChatMemory 要进坟墓了:Spring AI 2.1 会话记忆迁移实战(标题为原文标题,不代表官方结论) --- cloud.tencent.com.cn/developer/a...