切换主题
TIP
本页内容由本地原稿 01-框架地图.md 同步生成。 如果你要长期修改站点内容，优先回原稿修改，再执行 npm run docs:sync。
第 1 章：先把 Spring AI Alibaba 的地图看清
这章要解决什么问题
很多人学 Spring AI Alibaba 学不进去，不是因为它难，而是因为一上来就把它看成：
- 一个模型 SDK
- 一个阿里版本的 Spring AI
- 一套工具和 RAG 的拼装包
这些理解都不完全错，但都不够准。
这章的目标只有一个：
先把地图看清，再去写代码。
1. 一句话理解 Spring AI Alibaba
如果你只记一句话，请记这句：
Spring AI Alibaba = 基于 Spring AI 的能力扩展 + 面向 Agent 应用的工程化框架。
它不只是帮你发起一次模型请求，而是继续往上解决：
- 模型怎么接
- Prompt 怎么组织
- 工具怎么挂
- 会话怎么记住
- 知识库怎么接进来
- 多步骤任务怎么编排
这也是官方概览和官方仓库 README 一直在强调的定位：
它既有底层 AI 能力，也有 Agent / Workflow / Multi-Agent 的上层能力。参考：
2. 它和 Spring AI 是什么关系
最简单的理解方式是：
| 组件 | 你可以把它想成什么 | 更擅长什么 |
|---|---|---|
| Spring AI | AI 应用基础设施层 | ChatModel、ChatClient、消息、工具、向量库等基础概念 |
| Spring AI Alibaba | 在基础设施之上的实战框架层 | ReactAgent、Graph、Context Engineering、A2A、Workflow |
你可以把它们的关系理解成：
换句话说：
Spring AI负责“怎么和模型世界对接”Spring AI Alibaba负责“怎么把这些能力组织成一个能工作的 Agent”
3. 你后面会反复遇到的 5 个主角
3.1 ChatModel
它代表“底层模型能力”。
你可以把它当成“真正去和大模型供应商说话的人”。
比如在你们公司的工程里，AiModelConfiguration.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/config/model/AiModelConfiguration.java） 就注册了多个 ChatModel Bean：
- DeepSeek
- OpenAI
- Qwen / DashScope
这一步的本质是：
先把不同模型接入 Spring 容器。
3.2 ChatClient
它更像一个“更顺手的模型调用器”。
当你的需求还是“问一句，答一句”，或者“给模型挂几个 advisor / tool callback”，ChatClient 往往已经够用了。
你们公司的 AiChatBizImpl.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/biz/impl/AiChatBizImpl.java） 就同时保留了 ChatClient 这条线。
3.3 ReactAgent
这是 Spring AI Alibaba 里非常关键的上层角色。
它不是简单的“发消息”，而是一个会做这些事的运行单元：
- 理解用户问题
- 决定要不要调工具
- 维护执行状态
- 在需要时继续推理
- 最终返回结果
从学习节奏上讲，ReactAgent 是真正进入 Spring AI Alibaba 世界的门。
3.4 RunnableConfig
很多新手第一次看到它，会把它当成“普通配置对象”。
其实它更像本次运行的上下文容器。
它常常带这些信息：
threadId- metadata
- store
- checkpoint 相关配置
后面你学记忆、长会话、Graph 的时候，它会越来越重要。
3.5 Saver
Saver 解决的是：
Agent 的状态，怎么跨一次调用保存下来。
如果没有它，Agent 每次都像“刚睡醒”。
如果有它，再配上稳定的 threadId，它就能把上下文接上。
官方示例里常见的是 MemorySaver。
你们公司的工程里则往前走了一步，使用了自定义的 AgenMysqlSaver.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/config/hooks/AgenMysqlSaver.java） 做数据库持久化。
4. 先别急着学高级特性，先把这两条主线分开
很多人被 Spring AI Alibaba 搞乱，是因为把两条线混在一起了。
4.1 第一条线：ChatClient 主线
适合：
- 普通聊天问答
- 带少量工具
- 带少量 advisor
- 偏“请求-响应型”的能力
特点：
- 结构简单
- 接近 Spring AI 原生思路
- 上手快
4.2 第二条线：ReactAgent 主线
适合：
- 更复杂的工具调用
- 多轮状态维护
- 更明显的 Agent 行为
- 后续准备升级到 Graph / Workflow
特点：
- 更像“智能体”
- 状态和执行过程更重要
- 更贴近 Spring AI Alibaba 的核心价值
你们公司的 AiChatBizImpl.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/biz/impl/AiChatBizImpl.java） 就是一个很典型的例子：
同一个聊天业务，会根据配置在 ChatClient 和 ReactAgent 之间选择不同策略。
5. 如果把整个框架压成一张图，会长这样
这张图里你可以先记住一句话：
ChatModel决定它能和哪个模型说话ChatClient/ReactAgent决定它怎么工作Tools、Memory、RAG决定它像不像一个真正能干活的 Agent
6. 对照你本地工程，框架角色都落在哪
你现在手头最重要的不是“背概念”，而是知道这些概念在项目里各自落到哪一层。
6.1 模型 Bean 在哪
AiModelConfiguration.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/config/model/AiModelConfiguration.java）
这个类最值得你观察的点有两个：
- 多个
ChatModelBean 是如何命名和注册的 ChatClientBean 又是如何基于ChatModel再包装出来的
这会帮你建立一个很重要的工程感觉：
Spring AI Alibaba 再高级，本质上也还是 Spring Bean 组装。
6.2 聊天主链路在哪
AiChatBizImpl.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/biz/impl/AiChatBizImpl.java）
你可以重点观察：
- 什么时候走
ChatClient - 什么时候走
ReactAgent - 工具和 RAG 是在哪个阶段挂进去的
6.3 Agent 组装在哪
AiAgentBuildBizImpl.java（源码路径：D:/idea_space/ai-center-server/ai-center-api-server/src/main/java/com/hy/bigdata/ai/biz/impl/AiAgentBuildBizImpl.java）
这个类很像“Agent 装配厂”：
- 读数据库配置
- 装模型
- 装工具
- 装知识库
- 最终拼成一个可运行的 Agent 参数对象
它非常适合在你学完工具、记忆、RAG 之后回头再看。
7. 这套教程接下来怎么学
我建议你不要按“文档目录”学，而是按“认知闭环”学：
- 先写出一个最小
ReactAgent - 再给它装一个工具
- 再让它记住上下文
- 再接 RAG
- 最后再去碰 Graph、Workflow、多 Agent
原因很简单：
如果连最小 Agent 都没真正写过，直接学 Graph，脑子里会全是概念，没有抓手。
8. 本章小结
你现在至少要把下面三句话记住：
Spring AI更像基础层，Spring AI Alibaba更像 Agent 上层框架。ChatClient和ReactAgent是两条不同复杂度的主线，不要混着看。- 以后你学到的工具、记忆、RAG，本质上都只是往 Agent 身上继续装能力。
9. 本章小练习
读完这章，先别急着继续。你可以先自己回答这三个问题：
- 如果只是做一个简单问答接口，我为什么不一定需要
ReactAgent？ - 如果我要做一个能调工具的智能客服，为什么
ReactAgent更有吸引力？ - 在你们公司的项目里，模型 Bean、聊天编排、工具装配分别在哪几个类里？
如果这三个问题你能答出来，说明你已经不是“看热闹”了，而是真开始进入框架了。