Spring AI 框架核心内容从 ChatClient 到 Tool / Memory / RAG适用版本Spring AI2.0.x配合 Spring Boot 4.x关键词ChatClient · ChatModel · Advisor · Tool Calling · ChatMemory · Embedding · VectorStore · RAG · MCP前言对 Java 团队来说接入大模型常见两条路自己用WebClient/ OkHttp 调各家 Chat Completions API引入Spring AI用统一抽象对接模型、工具、记忆与向量库。前者上手快但一旦要做多轮会话、Tool Calling、流式输出、可观测、换模型、RAG胶水代码会迅速膨胀。Spring AI 的价值不在「多包一层 HTTP」而在把 AI 应用常见能力收成可组合的 Spring Bean 与 Advisor 链——和你写 Web、Security、Data 时的心智模型一致。一句话概括框架定位用 Spring 的方式编排 LLM模型可替换能力可插拔业务事实走 Tool语义检索走 VectorStore。下面按「它解决什么 → 核心抽象 → 关键能力 → 典型装配 → 落地注意」展开。一、Spring AI 解决什么问题痛点没有框架时Spring AI 怎么解换模型 / 换厂商改请求体、鉴权、流式协议ChatModel/ OpenAI 兼容 starter改配置即可Tool Calling 多轮循环自己写 while模型要调工具 → 执行 → 回灌 → 再调2.0 用ToolCallingAdvisor纳入 Advisor 链多轮对话记忆自己拼 messages、截断、落库ChatMemoryMessageChatMemoryAdvisorRAG自管 Embedding、切分、检索、拼 PromptDocumentEmbeddingModelVectorStore 可选 QA Advisor与业务集成散落的 HTTP 与 JSONTool直接调 Service和普通 Spring Bean 一样它不是业务中台也不替代你的 SQL / 规则引擎它是LLM 编排层。业务正确性仍应由 Tool、鉴权与权威数据源保证。二、分层心智图先记住这五层┌────────────────────────────────────────────────────────────┐ │ 应用层Controller / Service会话 ID、鉴权、限流、卡片组装 │ └────────────────────────────┬───────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────────┐ │ 编排层ChatClientfluent API │ │ System Prompt · Tools · Advisors · Options │ └────────────────────────────┬───────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────────┐ │ Advisor 链Memory / ToolCalling / RAG / 自定义横切逻辑 │ └────────────────────────────┬───────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────────┐ │ 模型层ChatModel / EmbeddingModelOpenAI 兼容等 │ └────────────────────────────┬───────────────────────────────┘ ▼ ┌────────────────────────────────────────────────────────────┐ │ 基础设施ChatMemoryRepository · VectorStore · MCP Server │ └────────────────────────────────────────────────────────────┘日常写业务90% 时间待在 ChatClient Tool Advisor只有做索引重建、换向量库时才深入Document/VectorStore。三、核心抽象一览3.1 ChatModel和「某一家模型」对话的最低层ChatModel负责把Prompt消息列表 选项发给模型返回ChatResponse。一般不必手写调用由自动配置提供实现如 OpenAI 兼容协议下的 DeepSeek、通义等。你更常接触的是上层ChatClient但要理解Chat与Embedding是两条线对话用ChatModel向量化用EmbeddingModel同一 starter 可配不同base-url/api-key/model例如 Chat 走 DeepSeekEmbedding 走 DashScope。3.2 ChatClient推荐的日常入口ChatClient是 Spring AI 的「门面」链式拼 Prompt、挂 Tools、挂 Advisors然后.call()或.stream()。最小闭环StringreplychatClient.prompt().user(有没有 Redis 相关的书).call().content();生产里通常在配置类里建好「带默认行为」的 BeanBeanChatClientaiChatClient(ChatClient.Builderbuilder,ChatMemorychatMemory,/* tools... */){returnbuilder.defaultSystem(SYSTEM_PROMPT).defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()).defaultTools(bookSearchTool,faqTool/* ... */).build();}业务 Service 里只关心「本轮用户说了什么」和「会话 ID」StringreplyaiChatClient.prompt().user(message).advisors(a-a.param(ChatMemory.CONVERSATION_ID,conversationId)).call().content();要点API作用defaultSystem/.system(...)系统角色与硬规则何时必须调 Tool、禁止编造等defaultTools/.tools(...)注册可被模型调用的业务能力defaultAdvisors/.advisors(...)挂记忆、RAG、审计、限流等横切逻辑.call()/.stream()同步拿完整回复 / 流式推 token.entity(SomeDto.class)结构化输出让模型填 JSON → 映射为 Java 对象3.3 Prompt / Message对话的数据结构一轮对话本质是消息列表SystemMessage角色与约束UserMessage用户输入AssistantMessage模型回复可能含 tool_callsToolResponseMessage或等价结构工具执行结果回灌ChatMemory存的就是这些消息Advisor 在真正调模型前会把历史拼进当前 Prompt。3.4 AdvisorAI 版的「过滤器链」Advisor 拦截ChatClient请求/响应可在调用模型前后注入历史消息Memory执行 Tool 循环2.0 的ToolCallingAdvisor检索向量库并增强 PromptRAG打点、审计、重试、护栏。心智模型对齐 Spring MVC 的 Filter / Interceptor有序链 可组合 可自定义。Spring AI 2.0 的关键变化Tool Calling 循环被提升为 Advisor 链上的一等公民ToolCallingAdvisor默认自动注册。好处是记忆、观测、自定义逻辑可以明确放在「Tool 循环内侧或外侧」而不是藏在某个模型实现的私有 while 里。常见内置 / 常用 AdvisorAdvisor做什么MessageChatMemoryAdvisor按conversationId读写多轮消息ToolCallingAdvisor模型要调工具时自动执行并回灌直到无需再调QuestionAnswerAdvisor等检索 VectorStore把相关文档塞进 Prompt经典 RAG自定义CallAdvisor日志、租户隔离、敏感词、业务卡片收集等3.5 Tool把「事实」交给业务代码Tool CallingFunction Calling是企业场景的主路径用户自然语言 → 模型理解意图并选择 Tool 参数 → Spring AI 反射/调度执行 Tool 方法 → 结构化结果回灌模型 → 模型组织口语化回复定义方式注解最常见ComponentpublicclassBookSearchTool{Tool(namesearchBooks,description按书名、作者或关键词检索上架图书返回架位与库存。查书时必须先调用。)publicMapString,ObjectsearchBooks(ToolParam(description书名或关键词)Stringkeyword,ToolParam(requiredfalse,description最多返回几本)Integerlimit){// 内部调已有 BookCatalogService / SQL返回 JSON 友好结构returnMap.of(found,true,books,List.of(/* ... */));}}设计原则比 API 本身更重要description 写给人看也写给模型看说清「何时必须调用」返回权威 JSONfound、业务字段禁止模型在无 Tool 结果时编造事实敏感身份不要进ToolParamuserId应从 JWT /SecurityContext/ ThreadLocal 注入防止伪造Tool 应是薄适配层复用现有 Service不要在 Tool 里堆业务。2.0 还提供工具规模变大时的渐进披露如ToolSearchToolCallingAdvisor先不把上百个 Tool schema 全塞进 Prompt按需检索再暴露——工具很多时再考虑。3.6 ChatMemory多轮对话的「短期记忆」抽象分层ChatMemory窗口策略如 MessageWindowChatMemory ↓ ChatMemoryRepository持久化内存 / JDBC / Redis 等典型装配BeanChatMemoryaiChatMemory(ChatMemoryRepositoryrepository){returnMessageWindowChatMemory.builder().chatMemoryRepository(repository).maxMessages(12)// 例如保留最近 6 轮 userassistant.build();}请求时传入会话键.advisors(a-a.param(ChatMemory.CONVERSATION_ID,conversationId))注意conversationId 设计要含租户/用户维度如user:{id}:{sessionId}避免串会话窗口过长费 token过短丢指代「那本呢」「第二本呢」官方 Redis Repository 可能依赖 Redis Stack若只有普通 Redis可自实现ChatMemoryRepository仍挂同一套 Advisor 链路。3.7 EmbeddingModel Document VectorStoreRAG 三件套语义检索链路业务对象 → Document(text metadata id) → EmbeddingModel 向量化 → VectorStore.add / similaritySearch → 命中文档回查业务库补库存、架位等实时字段概念职责Document一段可检索文本 metadata类型、业务主键等EmbeddingModeltext → float[]维度必须与库表 schema 一致VectorStore增删查实现有 Milvus、PGVector、Redis 等similaritySearch只负责召回候选架位、库存、上下架状态仍应ID 回查 MySQL否则向量滞后会答错。两种常见用法Advisor 式 RAGQuestionAnswerAdvisor自动检索并拼进 Prompt——适合「文档问答」Tool 内 RAGTool 里调VectorStore再回查业务库——适合「推荐 / FAQ 语义召回」且更易控制幻觉与卡片结构。企业客服场景往往更偏向2事实仍走 Tool向量只做召回。3.8 结构化输出与 OptionsStructured Output.entity(OrderSummary.class)等让回复直接映射 DTO适合抽取、分类、表单填充ChatOptionstemperature、model、maxTokens等可在配置spring.ai.openai.chat.options.*或调用时覆盖。客服话术类温度宜偏低如0.2~0.4减少胡编创意写作再拉高。3.9 MCPModel Context Protocol扩展向Spring AI 对 MCP 有集成能力把外部 MCP Server 暴露的工具接到同一套 Tool Calling 体系。对多数业务系统先把内部Tool做稳跨系统工具互通或 IDE/Agent 生态对接时再上 MCP。四、一次请求在框架内怎么走同步 Chat1. Service校验入参、生成/复用 sessionId → conversationId 2. ChatClient.prompt().user(...).advisors(conversationId).call() 3. Advisor 链示意实际 order 可配 ├─ MessageChatMemoryAdvisor读出历史 messages写入当前 Prompt ├─ 可选RAG Advisor检索文档增强 Prompt └─ ToolCallingAdvisor调用 ChatModel ├─ 若响应含 tool_calls → 执行 Tool → 结果入消息 → 再次调用模型循环 └─ 若无 tool_calls → 得到最终 assistant 文本 4. Memory Advisor把本轮 user/assistant及必要 tool 轨迹策略写回 Repository 5. Service取 .content()组装业务响应如前端卡片这就是为什么「只配了一个 ChatClient Bean」就能同时具备记忆与多 Tool 编排——循环和拼装被框架收走了。五、工程装配BOM、Starter、配置5.1 依赖BOM 管版本propertiesspring-ai.version2.0.0/spring-ai.version/propertiesdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion${spring-ai.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- 对话 EmbeddingOpenAI 兼容协议 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency!-- 可选向量库 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-vector-store-milvus/artifactId/dependency/dependencies按需替换spring-ai-starter-model-ollama、其他 VectorStore starter 等。5.2 配置要点OpenAI 兼容spring:ai:model:chat:openaiembedding:openaiopenai:chat:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.comoptions:model:deepseek-chattemperature:0.3embedding:api-key:${DASHSCOPE_API_KEY}base-url:https://dashscope.aliyuncs.com/compatible-modeoptions:model:text-embedding-v3dimensions:1024vectorstore:milvus:client:host:localhostport:19530collection-name:bookstore_bookembedding-dimension:1024# 必须与 Embedding 输出维一致metric-type:COSINE实践建议Chat 与 Embedding 可拆厂商协议兼容即可维度三方一致模型输出维、配置dimensions、向量集合 schemaRAG / 向量库用开关本地没起 Milvus 时不要强连条件装配 / exclude 自动配置。六、和业务系统的「正确接缝」Spring AI 管编排业务系统管事实。推荐边界┌──────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ 前端 Chat │────▶│ Chat API │────▶│ ChatClient │ │ sessionId │ │ JWT / 限流 │ │ Prompt Tools │ └──────────────┘ └─────────────────┘ └────────┬─────────┘ │ ┌───────────────────────────────┼───────────────────────────────┐ ▼ ▼ ▼ Tool 查书/FAQ Tool 借阅/画像 VectorStore → Catalog/FAQ Service → 订单 Service读登录态 → 仅语义召回 │ │ │ └───────────────────────────────┴──────────▶ MySQL 权威数据 ◀────┘四条原则和是否用 Spring AI 无关但用框架时更容易守住事实归 Tool话术归模型身份归鉴权上下文不归模型参数向量只做召回实时字段回查业务库System Prompt 写清强制调 Tool 的规则否则模型爱「直接答」。七、能力对照你该先学哪一块优先级能力什么时候需要P0ChatClient System Prompt任何对话入口P0Tool Tool Calling查库、下单、规则——一切要准的事实P0ChatMemory conversationId多轮指代、客服会话P1Embedding VectorStore语义推荐、文档/FAQ 模糊匹配P1流式.stream()前端打字机体验P2结构化输出.entity抽取、分类、Agent 中间态P2自定义 Advisor统一审计、租户、护栏P3MCP / 大规模 Tool Search跨系统工具、Tool 数量爆炸学习路径建议先跑通「Prompt 一个 Tool Memory」再加第二个 Tool最后才上 RAG。很多失败项目是一上来堆向量库却没把 Tool 与鉴权做对。八、Spring AI 2.0 相对 1.x 你要知道的变化结合官方演进落地时抓住三点即可Tool 循环进 Advisor 链可观测、可插拔、可替换默认ToolCallingAdvisorChatClient 仍是主 API业务代码继续 fluent 风格升级成本主要在依赖与少量 Advisor/Tool 包名生态模块化部分厂商向量库 / Memory 实现可能由厂商维护选 starter 时看清坐标与自动配置条件。若你从 1.x 迁过来优先回归「多 Tool 连续调用」和「Memory Tool 同时开启」两条路径这两处最容易受循环位置变化影响。九、常见踩坑现象常见原因对策模型不调 Tool直接编造Prompt 未强制Tool description 含糊未defaultTools系统提示写死「必须先调」检查 Bean 是否注册调了 Tool 但仍幻觉模型忽略返回或返回结构不利于引用返回found/message明确字段温度调低多轮遗忘未传同一CONVERSATION_ID窗口过小Repository 未生效前端回传 sessionId核对 Redis Key/TTL串会话 / 越权conversationId 未带 userIduserId 暴露为 Tool 参数ID 隔离身份只从安全上下文取Embedding 维度错误模型维 ≠ 配置维 ≠ collection 维三处对齐重建索引引入 VectorStore 后启动失败自动配置强连未启动的 Milvusrag.enabled 条件装配 / excludeToken 飙升历史过长Tool 返回太大System Prompt 过臃肿窗口截断Tool 只返回必要字段十、最小可行代码骨架串起来配置spring-ai-starter-model-openai api-key/base-url/model ↓ AiChatConfig ChatMemory MessageWindowChatMemory(repository) ChatClient builder .defaultSystem(...) .defaultAdvisors(MessageChatMemoryAdvisor) .defaultTools(YourTool) .build() ↓ AiChatService conversationId userOrAnon sessionId chatClient.prompt().user(msg).advisors(CONVERSATION_ID).call().content() ↓ YourTool Tool 方法 → 调现有 Service → 返回 Map/JSON把这张骨架跑通就等于掌握了 Spring AI最核心的 80%。RAG、流式、MCP、多 Agent 都是在这张骨架上加 Advisor、加 Tool、加基础设施。十一、总结一张核心概念卡片ChatClient → 你写业务时的主入口fluent ChatModel → 真正调 LLM 的端口多由 starter 提供 Advisor 链 → Memory / Tool 循环 / RAG / 自定义横切 Tool → 业务事实与副作用的唯一可靠出口 ChatMemory → 多轮上下文窗口 Repository EmbeddingVectorStore → 语义召回可选且要回查业务库 BOM Starter → 版本对齐与自动配置。