版本Spring AI 2.0.1·Spring Boot 4.x·JDK 17推荐 21 本章先建立全貌。环境搭建、API 细节与排障放在后续专章。把大模型接入 Java 业务常见工作包括对接各家 HTTP、组装多角色消息、解析响应与 token、执行工具调用、维护多轮记忆、检索私有知识、处理流式输出、得到结构化结果并补齐观测。这些都可以自研 SDK 封装但每个服务重复做一遍成本很高。Spring AI 的定位是用 Spring 体系里熟悉的抽象和 Boot 自动配置把上述能力收成可替换模块。业务代码尽量面向接口编写底层切换 OpenAI、Ollama 或兼容 endpoint 时主路径改动应尽量小。1.1 三层结构理解 Spring AI可以先抓住上图这三层后续章节都是在此基础上展开。应用层是业务开发最常接触的一层。多数场景从ChatClient起步API 更顺手记忆、RAG、日志、安全可通过 Advisors 接入业务方法也能以Tool/ToolCallback的形式交给模型调用。Controller 或领域服务通常停在这一层即可。抽象层是真正的解耦边界。ChatModel、EmbeddingModel、VectorStore以及消息与 Prompt都定义在这里。更换供应商时业务应尽量只依赖这些抽象类型而不是某一家的私有客户端。在图节点中做薄调用或在多模型之间路由时也常会直接使用ChatModel。提供商层是各家模型与向量库的具体实现通过spring-ai-starter-*自动配置进入容器。业务代码应尽量停留在抽象层之上。此外还有两条贯穿能力System / User / Assistant / Tool 组成的消息流以及基于 Micrometer Observation 的调用次数、耗时与 token 观测。后面各章基本是在这张图上深入某一部分而不是引入另一套概念体系。1.2 一次对话请求的路径聊天主链可以概括为业务代码 → ChatClient可选 Advisors / Tools / 模板 → PromptMessage 列表 ChatOptions → ChatModel.call 或 stream → 具体 Provider → ChatResponse文本 / 结构化结果 / toolCalls / Usage阅读这条链路时有三点值得提前澄清ChatClient不是另一套协议。它减少的是组装成本底层流通的仍是 Message、Prompt、ChatResponse。工具循环既可以发生在 ChatClient / Advisor 侧也可以由外层自行实现。这与是否引入状态图是不同层面的问题。Embedding、VectorStore、MCP不一定经过聊天主链的每一步但模块引入与自动配置的方式是一致的。默认建议普通对话优先使用ChatClient需要更薄的调用、手工控制工具循环或做多模型切换时再下沉到ChatModel。具体用法在后续章节分别说明。1.3 能力覆盖范围不必先记忆模块清单按要解决的问题来看会更清楚。上图是能力块总览这里只补几句阅读提示对话、流式、消息与选项是后面几乎所有能力的基础。Advisors、窗口 / 长期记忆、Tool、结构化输出、RAG、知识图谱是业务里最常叠加的能力块。MCP 扩展的是工具目录不替代流程编排。观测、安全、多模态与评估对应「能 Demo」之后的工程化。依赖统一走 BOM starter避免手写零散版本号。本章目标是建立「有哪些能力块、各自大致负责什么」的印象。配置方式与常见问题留到对应专章。1.4 依赖引入方式能力划分可以很细但应用侧日常入口并不复杂用spring-ai-bom固定版本引入模型 starter先打通聊天记忆仓库、向量库、MCP、Advisor 等按需追加实践上建议版本只在 BOM 中固定一处业务只引入当前场景需要的 starter。具体坐标在后续依赖章节给出。1.5 能力边界Spring AI 适合解决的是多家模型的统一接入以及工具、记忆、RAG、知识图谱接入模式、结构化输出、流式、MCP、观测等周边能力并与 Spring Boot 的使用方式对齐。它不负责、或不适合单独承担的主要是另一类问题复杂状态机、人工审批、中断后恢复 → 更适合LangGraph4jBPM、模型训练与微调平台完整 GraphRAG 产品层 / 超大规模混合检索中台通常需在VectorStore与图库之上自建 因此本系列的分工是模型与周边能力使用 Spring AI当流程本身成为业务资产时再引入图编排。二者是底座与编排的关系而不是互相替代。本分册先把 Spring AI 这一侧讲清楚。1.6 版本约定本分册示例统一基于Spring AI 2.0.1spring-ai-bom:2.0.1Spring Boot 4.xJava17推荐 21下一章先完成最小可运行工程再依次展开消息、ChatClient、Provider、记忆与工具等内容。