Spring AI 2.0 出来之后我把自己写过的东西重投了一遍发现最大的问题不是少讲了哪个 API而是很多 1.x 时代的博客和示例在 2.0 上照着抄就跑不通ChatClient.Builder的默认方法换了、工具注册的字符串 bean 名失效了、ToolCallAdvisor变成ToolCallingAdvisor了。更别扭的是资料的组织方式。官方 reference 按 API 排——ChatClient、Advisor、ETL、VectorStore各一章查东西很好用但你实际遇到的问题从来不是按 API 来的一次提问为什么模型调了三轮工具、向量库为什么被打了两次、检索都命中了为什么金额还是答错、月底账单涨在哪个功能上。这中间缺的是一层上线视角评测怎么落地、Token 成本怎么归因、工具能读文件能跑命令之后边界在哪。这些内容官方文档基本不讲Demo 又不会暴露只能一次次踩完再整理。所以有了这个专题15 篇从最小可用的 ChatClient 一路写到 Agent 的五种编排模式中间把 Tools、MCP、RAG 全链路、评测、可观测各自拆开。这一篇不讲代码只回答四个问题——为什么出这个专题、十五篇分别在解决什么、按你的目标该怎么读、以及这套专题没解决什么。下面就开始我们这篇的主题 [AI工程] Spring AI 专题开篇15 篇讲完 2.0 的提示词、RAG、MCP 与 Agent怎么读、读到哪算够1. 为什么要出这个专题三个具体的缺口不是想系统讲讲 Spring AI。1.1 版本断层1.x 的写法在 2.0 上是静默失效这类问题最消耗人因为它通常不报错。专题里反复出现的几处现象1.x / 网上示例2.0 的实际姿势专题落点工具不生效defaultTools(beanName)字符串 bean 名defaultTools(Object...)传对象第十一篇 6.2API 被移除中defaultToolCallbacks(...)已forRemoval统一走defaultTools(...)第十五篇类名换代ToolCallAdvisor已废弃继承自ToolCallingAdvisororder 也不同层第十四篇仪表盘空白ChatClient.builder(chatModel)手工造静态工厂写死ObservationRegistry.NOOP一个 span 都不上报第十三篇 2.2ChatClient.Builder有clone()、Advisor的默认 order 有数值、EvaluationRequest判卷只看某个字段——这些细节文档里要么分散要么没写但对能不能跑通是决定性的。所以专题里凡是涉及 API 形状的结论我都按本地 Maven 仓库里的 sources jar 逐行核对过不确定的会单独列出来让读者自己验。1.2 官方文档按 API 排读者按问题找同一个检索不准在文档里要跨 ETL 分块、Retriever、Advisor、VectorStore 四章拼起来才看得全。专题做的是按问题重组第十篇把 RAG 拆成一条能对着 debug 的链路Reader → Transformer → Embedding → Store → Retriever → 重排第十二篇把检索都对了为什么还答错落成一份评测集第十三篇把它当时到底检索到了什么落成 trace 与日志开关。1.3 缺的是工程化那一层不是又一个 Hello World第七篇之前基本是能力接入第七篇之后刻意把重心挪到工程工具怎么管第八篇的七个痛点、能力怎么复用与鉴权第九篇 MCP、质量怎么量化第十二篇、成本和延迟怎么看见第十三篇、编排怎么选第十四篇、Agent 需要什么工具箱第十五篇。Q1这个专题和官方 reference、和那些20 天学会 Spring AI的课是什么关系和 reference 是互补它是字典这里是按问题串起来的读法绝大多数结论会指回具体章节。和课程的区别在于立场这里的目标不是教会你用框架而是告诉你这个写法为什么会在生产上出事所以每篇都有迁移对照、自检清单和什么时候不该用它。2. 十五篇分别在解决什么四组每组解决一类问题。2.1 基础层16先把一个能跑的客户端立起来篇讲什么解决哪个问题第一篇Spring AI 2.0 全景Prompt、RAG、MCP 到 Agent 应用2.0 到底升级了什么哪些能力值得迁移第二篇快速接入 DeepSeek、阿里百炼 与 Ollama三家模型通道的依赖、配置与差异怎么抹平第三篇多模型、流式输出与工具调用一个应用里怎么同时挂多个模型流式怎么接工具怎么第一轮跑通第四篇提示词的使用与设置技巧system / user / template 怎么分层参数怎么注入怎么避免 prompt 变成一坨第五篇Advisor 对话拦截的使用与自定义请求前后能改什么、自定义 Advisor 怎么写、order 为什么重要第六篇对话记忆数据库与 Redis 两种实现会话历史存哪、窗口多大、怎么按conversationId隔离一句话理解这六篇只负责一件事——让一次提问变成一条你完全看得见、控得住的调用链。2.2 能力层79让模型能吐结构、能办事、能被复用篇讲什么解决哪个问题第七篇结构化输出与初代 Tools 实现怎么稳定拿到 POJO / JSONschema 校验失败谁来重试第八篇Tools / function-call 使用 原理 七大痛点description怎么写模型才会正确选工具权限、幂等、超时、循环调用怎么治第九篇MCP 实现、原理、源码读与鉴权能力跨进程 / 跨团队复用时协议怎么接、token 怎么管、坑在哪这一组的核心判断写在第八篇的结论里把决策交给模型的那一刻起你的description、参数校验和权限设计才真正决定这个功能能不能上生产。而第九篇把它再推一层——Tool解决模型能不能用我的方法MCP 解决我的能力能不能被别人复用。2.3 检索层1012RAG 从链路到质量到验证篇讲什么解决哪个问题第十篇RAG 全链路ETL、Modular RAG 到重排序分块策略、metadata 设计、检索器与重排怎么配TopK 调了有什么用第十一篇基于航空智能客服的 RAG 实战记忆、按用户隔离检索、工具接入三件事放进同一个请求怎么不打架Advisor 顺序的真实数值第十二篇RAG 评测与幻觉防线检索都命中了为什么金额还能答错两个内置评估器怎么用、批量评测集怎么建第十篇的结论是这套方法里最值钱的一句RAG 的难点不在 Advisor 怎么配而在你放进去的片段质量和你能不能稳定把它捞出来。第十一篇补上工程边界——难的是让记忆、检索、工具在同一请求里各只干自己该干的那一次第十二篇则回答我怎么知道这次改动真的变好了。2.4 工程层1315看得见、编得动、有工具箱篇讲什么解决哪个问题第十三篇给 AI 应用装上仪表盘可观测性五个观测点的真名与 tag、一次提问的完整 trace、Token 成本怎么按用户和功能归因第十四篇Agent 五种模式在 2.0 里怎么写Chain / Parallelization / Routing / Orchestrator-Workers / Evaluator-Optimizer 各给一段能跑的 Java以及哪些需求根本不该用 Agent第十五篇Spring AI Agent UtilsClaude Code 的工具箱在 Java 里被重写了一遍文件、Shell、grep、技能、跨会话记忆、子智能体这些能干活的 Agent部件怎么接2.5 知识脉络图基础层 1-6 ChatClient -- Prompt -- Advisor 链 -- ChatMemoryJDBC / Redis │ 能力层 7-9 结构化输出 -- Tool / function-call -- MCP能力对外复用 │ 检索层 10-12 RAG 全链路ETL / Retriever / 重排-- 客服实战记忆检索工具-- 评测与幻觉防线 │ 工程层 13-15 可观测trace token 成本-- Agent 五种模式 -- Agent Utils工具箱与技能在线用户提问 -- [6]会话记忆 -- [5]Advisor 链 -- [10][11]检索 -- [3]模型调用 -- [8][9]工具 / MCP 全程由 [13] 记 trace 与 token要不要把这条链编排成多 Agent看 [14] 离线[12]评测集回归改动前后各跑一次通过率-- 结论回写 [10] 的分块与检索配置3. 三条阅读路线按你要解决的问题挑不必从头读到尾。你是谁 / 要做什么建议顺序可以跳过后端同学第一次接 AI 能力1 → 3 → 5 → 6 → 7 → 81012 可后置要做 RAG / 智能问答落地5 → 10 → 11 → 12 → 139、15 后置要做 Agent / 内部 AI 平台8 → 9 → 14 → 15 → 131012 按需笔者后端 架构自己的复查顺序其实更功利什么时候回来看回来看哪篇改动前后想知道质量到底有没有变第十二篇评测集与通过率账单涨了要定位贡献方第十三篇 6.2 / 6.3Token 成本与归因一次提问模型调用数 1 查不出来为什么第十三篇 3.3带工具的 trace 嵌套 第十一Advisor 顺序评审别人这算不算 Agent第十四篇第 7 节模式落点与别用场景要给内部 Agent 配工具箱第十五篇第 7 节安全边界Q哪几篇可以当上线前检查表直接拿去用第十一客服实战和第十三可观测两篇末尾各带一份上线前自检清单是最接近直接抄进 checklist的部分第十二评测给的不是清单而是一条能重复跑的评测流水线加一张按症状定位的表。三者合起来覆盖的其实就四件事链路看得见trace 日志开关、质量能量化评测集 通过率、边界守得住按用户过滤 工具层校验 身份不从模型参数取、成本可归因token 指标 单价换算。4. 统一的版本与环境约定所有篇目按这套基线写跨篇对照时以此为准。项基线Spring AI2.0.1部分 API 对照2.0.0-M4Spring Boot3.x / 4.x4.0.1 涉及 Micrometer 模块拆分Java17虚拟线程相关写法需要 21会单独标注模型通道DeepSeek / 阿里百炼 / Ollama / Anthropic / OpenAI / Gemini按篇不同Spring AI AlibabaDashScope starter1.1.2.0其依赖的 Spring AI 是1.1.2不是 2.0spring-ai-agent-utils0.12.0incubatingApache 2.0事实来源本地~/.m2的 sources jar 逐行核对 官方文档 仓库docs/*.md倒数第二行是这个专题最容易被误读的地方如果你走阿里百炼 / DashScope 通道2.0 才有的类名要自己换回去ToolCallingAdvisor→ToolCallAdvisor、defaultTools(Object...)的可用性等。第十四篇 7.2 专门列了这张兼容表。Q为什么每篇末尾都有一段版本与待核实说明因为确实有核不到和没实跑的部分我不想把它们写成已确认的事实。这段会明确列出三件事哪些结论有源码或文档支撑含出处、哪些只核对到概念层面、哪些代码没有在你的模型通道上实跑过。模型版本号和价格一类会变的东西一律标成写这篇时或直接不写。全部示例代码与可运行工程在仓库 OxYGC/spring-ai按篇组织跑之前先看 README 里的版本要求别直接对着最新 main 抄。5. 贯穿十五篇的五个结论如果只想记住几条记这几条。#结论出处1手工ChatClient.builder(chatModel)会让可观测性归零生产一律注入ChatClient.Builder第十三篇 2.22Advisor 的 order 决定一件事在一次请求里做几次RAG 在工具循环内侧就会被反复触发memory 在外侧所以看不到工具中间消息第十一篇 73评测判卷只看EvaluationRequest的dataList检索到的文档不显式搬进去FactCheckingEvaluator就是在凭常识判卷第十二篇 3、44工具能不能被正确选用取决于description与参数 schema 的质量不是模型够不够聪明第八篇5身份、权限、金额这类判定任何一处从模型生成的参数里取都是漏洞第十一篇 5.4 / 6简单理解Spring AI 2.0 把积木给全了但没有替你决定谁该在链上、各跑几轮、出错算谁的。这十五篇讲的就是这三件没有替你决定的事。6. 还没解决什么这份清单比前十五篇更有用因为它决定了你该在哪些地方自己多想一步。未解决现状专题里的处理工具中间消息不入 memory官方文档写明的限制不是配置问题第十一篇给了两条对策让关键字段进最终回答 / 自建业务态但都不是通用解评测集怎么来框架只提供评估器判卷标准是业务的第十二篇给流水线和 CSV 样例没有替你标好答案Advisor order 是契约吗不是。数值是读 sources jar 得到的实现事实每处引用都标了升级后重新核对成本框架只给 token 数不给钱且只给 Counter 不给时长直方图第十三篇 6.2 给换算结构和查询单价要你按自己的通道填多租户与权限模型Spring AI 不涉及只在第十一篇示范了检索层过滤 工具层校验 会话 id 命名三层纵深没做体系化灰度、回滚、A/B完全没写这是发布流程问题不属于框架专题范围向量库横向选型只做了 Simple / Milvus 的替换示范第十篇 2.4 只讲换库要改哪几处没有做选型横评DashScope 侧工具调用兼容性未按每条通道实跑相关篇目的待核实说明里都点明了Agent Utils 的 API 稳定性0.x 孵化期类和字段都可能改名第十五篇按 0.12.0 的文档写并给了改名映射Q接下来会补什么按我自己的优先级有三个方向现在还没法写专题级的端到端工程把 115 装进同一个仓库一条链路从灌库跑到看板、评测集建设的完整方法论标注成本和一致性怎么管以及多 Agent 与 A2A 在真实跨团队协作下的治理。如果你在读的过程中卡在某一层欢迎带着具体报错和版本来问这类问题反过来会变成新一篇的选题。最后总结只想知道 2.0 变了什么读第一篇如果你的通道不是官方直连再配着第十四篇 7.2 那张版本兼容表看五分钟能定位到自己会不会踩。手上有一个 RAG 需求要落地直接从第十篇进第十一篇当参照实现第十二、十三篇当上线前的质量与观测检查。要判断这个需求该不该做成 Agent第十四篇第 7 节那张决策图能替你先过滤掉一大半。要给 Java 侧 Agent 配文件、Shell、记忆、技能这些部件第十五篇以及仓库里的九个 Demo。对后端 / 架构同学这套专题真正的用处不是学会 Spring AI而是它把每个能力出问题的位置标了出来——哪些是配置能解决的、哪些是实现限制、哪些必须由你的业务层兜住。还有一件事值得单说这个专题按 2.0.1 写而目前 DashScope 通道还在 Spring AI 1.1.2 上。如果你的技术栈由阿里云侧决定请先读第十四篇 7.2 再动手否则会撞到一批文档里有、你引的包里没有的类名。一句话结论这十五篇想解决的是同一件事——把 Spring AI 2.0 从能跑通的 Demo推到能上生产、出问题能定位、成本能算清的服务。参考资料 致谢[1] [AI工程] Spring AI 第一篇2.0 到底升级了什么从 Prompt、RAG、MCP 到 Agent 应用实战[2] [AI工程] Spring AI 第二篇2.0 快速接入 DeepSeek、阿里百炼与 Ollama[3] [AI工程] Spring AI 第三篇2.0 实战多模型、流式输出与工具调用怎么写[4] [AI工程] Spring AI 第四篇提示词使用与设置技巧2.0[5] [AI工程] Spring AI 第五篇Advisor 对话拦截的使用和自定义 2.0[6] [AI工程] Spring AI 第六篇对话记忆——数据库和 Redis 不同的实现[7] [AI工程] Spring AI 第七篇结构化输出与初代 Tools 实现[8] [AI工程] Spring AI 第八篇Tools / function-call 使用 原理 7 大痛点[9] [AI工程] Spring AI 第九篇MCP 实现、原理、源码读与鉴权[10] [AI工程] Spring AI 第十篇RAG 全链路讲解——从 ETL、Modular RAG 到重排序[11] [AI工程] Spring AI 第十一篇基于航空智能客服的 RAG 实战[12] [AI工程] Spring AI 第十二篇RAG 评测与幻觉防线[13] [AI工程] Spring AI 第十三篇给 AI 应用装上仪表盘[14] [AI工程] Spring AI 第十四篇Agent 五种模式在 2.0 里怎么写[15] [AI工程] Spring AI 第十五篇Spring AI Agent UtilsClaude Code 的那套工具箱被人在 Java 里重写了一遍[16] 专题示例代码 - GitHub 仓库 OxYGC/spring-ai[17] Spring AI Reference - 官方文档[18] Spring AI Alibaba - 官网