← 课程目录 🚀 从零到一
📐 学习维度 阶段6 · 第23章 Spring AI / LangChain4j 🚀 从零到一 📚 课程目录 🏠 首页 🛤️ 学习路径

23.1 Spring AI 1.0:架构与ChatClient

审校 2026-09-25 · 素材来源:L22-Spring-AI-1.0架构精讲、深度文11-SpringAI与LangChain4j实战、spring-ai-demo
📑 本篇章节导航 (共7节,点击直达)
四层架构ChatModel 与 ChatClient:低阶与高阶Advisor Chain:AI 版的过滤器链记忆与配置速览踩坑清单面试怎么问一句话总结

22 章手搓了调用大模型的全部细节:重试、格式、流式、记忆。真到项目里逐个手搓,工程量不小且各家 API 不统一——OpenAI 一个接口形态、国产模型各家一套。Spring AI(Spring 官方的 AI 应用框架,对模型、向量库、工具调用做统一抽象)的定位一句话讲透:Spring Data 统一了数据库访问,Spring AI 统一 AI 模型访问——切换模型只改配置,业务代码零修改。

四层架构


应用层   ChatClient(高级API) + Advisors(拦截器链)
模型层   ChatModel / EmbeddingModel (各厂商实现)
存储层   VectorStore (Milvus/Redis/PG...)
工具层   Function Calling / MCP Client

四层各管一段:模型层屏蔽厂商差异(GLM、DeepSeek、OpenAI 同一个接口);应用层提供带拦截器的流式调用门面;存储层统一向量读写(23.2);工具层统一能力接入(23.4)。这套「抽象 + 可替换实现」正是 Spring 一贯的手艺(14.1 自动装配的 AI 版),也决定了它最大的工程价值:供应商解耦——今天用国产模型合规、明天预算紧换性价比,改 yaml 的 base-url 与 model 两行,Controller 一行不动(22.5 的多模型路由在这里自然落地)。生态配套跟着抽象走:每个模型一个 starter(openai 的、ollama 的、各家国产的)、每个向量库一个 starter,按需引入即插即用——与 Spring Boot「starter 即功能」的肌肉记忆完全一致,Spring 开发者上手 AI 应用的学习成本被压到「学 ChatClient 一个 API」的程度。

ChatModel 与 ChatClient:低阶与高阶

ChatModel(模型层的直接接口:传消息、返响应)是裸调用;ChatClient(应用层门面:链式 API 封装提示词、Advisor、工具、记忆)才是日常主力。类比 JDBC 与 MyBatis 的关系(15 章的老朋友):能直连,但没必要。ChatClient 的链式调用把 22 章的手艺全收编:


ChatClient client = ChatClient.builder(chatModel)
    .defaultSystem("你是订单客服助手,用中文回答")   // 系统提示词
    .defaultAdvisors(new SimpleLoggerAdvisor())      // 默认拦截器
    .build();

String answer = client.prompt()
    .user("订单{{orderId}}为什么还没发货")           // 用户输入
    .advisors(a -> a.param("orderId", "10086"))
    .tools(new OrderTools())                        // 22.3的工具注册
    .call().content();                              // 同步调用取文本

.stream() 换成流式(22.4 的 SSE 直接衔接),.entity(Person.class) 直接做结构化输出绑定(22.3 的三道闸框架内建)。系统提示词放 builder 的 default 处统一定义,22.2 的四要素提示词工程在代码里就是这个位置。ChatClient 的使用纪律两条:builder 建一次、Spring 单例注入复用(每次请求 new 一个 builder 是无谓开销);ChatClient 是薄门面、无状态——多轮记忆靠 Advisor 挂记忆实现(23.2),别误以为「同一个 ChatClient 实例会自己记住上下文」,这是从「会话」语义带过来的头号误解。

顺带三个高频追问。.entity() 绑定失败会抛异常,生产上要配一次「带错误信息的格式修正重试」(22.3 的第三道闸框架没有替你按下去);.stream() 返回响应式流,接 SSE 链路时注意异步线程上的上下文传递(13.4 的 ThreadLocal 陷阱在响应式里同样存在);同一个 ChatModel 可以建多个 ChatClient——订单助手、售后助手各配各的 defaultSystem 与 Advisor,比一个全局实例到处塞 param 清晰得多。「一个业务域一个 client」是团队协作里更可维护的切法。

Advisor Chain:AI 版的过滤器链

Advisor(Spring AI 的请求/响应拦截器,类似 Servlet Filter 或 AOP 环绕)是理解 Spring AI 架构的关键件。执行链是标准洋葱模型:请求依次过 Advisor 的 before → 模型调用 → 响应逆向过 after。内置几件先把名字记住:SimpleLoggerAdvisor 记日志、QuestionAnswerAdvisor(RAG 拦截器:自动检索知识库把相关片段拼进提示词)——它让「三行代码接入 RAG」成立、SafeGuardAdvisor 内容安全兜底。QuestionAnswerAdvisor 与 23.2 的关系一句话说清:Advisor 是「什么时候检索、怎么拼」的流程件,VectorStore 是「去哪检索」的数据件——前者依赖后者注入,组合起来才是完整 RAG 链路。自定义才是生产主战场:


Advisor sensitiveMask = (req, chain) -> {
    var masked = mask(req.request());        // 入参脱敏(18章红线)
    return chain.nextCall(with(masked));     // 放行下一环
};

语义缓存(相似问题命中缓存直接回)、审计日志、按租户注入系统提示词、调用前预算检查(22.5 的成本闸门)——全是 Advisor 的菜。识别套路:凡是要在「调用前后」统一做事的需求,答案都是挂 Advisor,这与 13.3 「横切逻辑找 AOP」是同一条思维路径。顺序是 Advisor 的第二课:洋葱模型里外层包内层,「脱敏 Advisor」必须在「日志 Advisor」外面——顺序反了,日志里记的就是未脱敏的原文(20.4 的脱敏红线在 AI 链路的翻版);Spring AI 用 Order 排序,与 Servlet Filter 的 order 同一个概念。写自定义 Advisor 时的顺序感也重要:改请求的放前面(脱敏、注入),看请求的放后面(日志),响应侧则反过来——想清楚「谁该看到什么状态的数据」,顺序自然就对了。

记忆与配置速览

ChatClient 加 MessageChatMemoryAdvisor 一行即获得多轮记忆,记忆载体与裁剪策略下一节(23.2)专门拆。配置面速记:spring.ai.openai.base-url(兼容端点可指向国产模型)、api-key 从环境变量注入(22.5 红线)、chat.options.temperature 全局默认(22.1 的旋钮)。依赖坐标按需引入 spring-ai-starter-model-openai 或对应厂商 starter,向量库再单独加——Spring AI 的 BOM 管版本,别自己拼版本号(14 章依赖治理的惯性在这里延续)。测试与观测两件收尾配置:测试用 MockChatModel(伪造固定回复的模型实现)让单测不烧真钱——AI 代码也要能离线跑 CI;观测用 Spring AI 的 observability 集成,Micrometer 一次埋点把调用耗时、token 用量送进监控(16.6 的面板直接接管 AI 调用链)——「能测、能看」配齐,AI 功能才算工程完整态。

踩坑清单

面试怎么问

一句话总结

Spring AI 用「四层抽象 + ChatClient 门面 + Advisor 拦截链」把 22 章的手艺装进框架:模型可换、RAG 三行、横切有链——对 Spring 技术栈的团队,它是 AI 落地最短路径,代价是理解它的抽象分层,而这份理解在本章后面四节里逐一兑现。