Spring AI 入门完全手册:ChatClient、Advisor、工具调用、对话记忆

版本基准:本文基于 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 跑通了、准备上生产、担心踩坑的人。

先记住三句话:

  1. Spring AI 的价值不是"又封装了一遍大模型 API",而是把 Spring 开发者熟悉的依赖注入 、自动配置、Advisor 链搬到了 AI 调用上。依赖注入和自动配置是 Spring 的核心机制------你要什么告诉它,它帮你准备好、接好,不用自己到处创建和连线。Advisor 链是一串"工序",模型调用前后依次做点事。
  2. 你面对的是 ChatClient,不是裸 HTTP;模型调用、工具循环、记忆、检索都被收进了这条链。
  3. 大模型本身是无状态的------所谓"记忆"是你每次把历史一起发过去的,不是模型记住了你。

全文按"是什么 → 版本口径 → 四大件 → 坑分类 → 对比选型 → 排查 → 社区经验 → 速查表"组织。术语第一次出现尽量用大白话解释。

第一部分:零基础地基

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 和 ChatMemory API 在 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 里同时有历史和检索结果,但不等于检索查询本身一定会被改写。这一点在第七部分社区经验里也会再提。

两条硬规则:

  1. Advisor 按顺序执行,前一个的修改会传给后一个;
  2. 用 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。生产上先做到三件事就够了:

  1. 每个会话一个稳定 conversationId;
  2. 历史条数设上限,别无限增长(MessageWindowChatMemory 用 builder().maxMessages(20) 控制窗口);
  3. 敏感字段进 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 消息被重复注入"导致的,而是两个独立问题叠加的结果:

  1. 提示词漂移 :每轮 .system(...) 改变系统指令,模型行为不一致,看起来像"忘了之前怎么回答";
  2. 窗口挤占:真正的窗口压力来自对话历史未截断,而不是 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

参考资料

官方文档与安全公告:

社区实践参考(经验贴,非官方结论) :

相关推荐
斯维赤23 分钟前
SpringBoot接口调不通排查终极方案
java·后端·spring
泡海椒23 分钟前
jquick-pdf echart风格预算执行进度报表模板:市财政局汇报页的一条条追问与回答
后端
利威尔xu24 分钟前
Go channel 关闭 3 个 panic:向已关闭 channel 发送,服务当场崩溃
开发语言·后端·golang·并发编程·channel
Csvn1 小时前
Nginx 反向代理入门:proxy_pass 两种形态、超时链与 502/504 分辨
后端·nginx
LVZ2 小时前
AI Agent 缺的不是更强的模型,而是一个运行时
前端·javascript·后端
鶴哥只手遮天2 小时前
《VulkanSceneGraph 1.1.16 源码深度解析》第二章 内存工程:Allocator、MemoryBlock 与场景图的物理布局
后端
im_AMBER2 小时前
IO 多路复用:select、poll 和 epoll
后端·面试·架构
码农Kzx2 小时前
【开源】当桌面图标开始打台球:我用 WinForms 做了一桌“真的”台球
后端
鶴哥只手遮天2 小时前
《VulkanSceneGraph 1.1.16 源码深度解析》第五章 数据对象:从 `Data` 到 `VkBuffer`/`VkImage` 的完整链路
后端