1. 从一次技术选型的纠结说起去年年底团队接了一个企业知识库问答的项目需求很明确把公司内部散落在各个系统里的文档、工单、会议纪要整合起来做一个能对话检索的入口。技术栈是 Spring Boot 那一套团队里没人想引入 Python 服务于是很自然地盯上了 Spring AI。真正上手之后才发现Spring AI 本身提供的是相当底层的抽象——ChatClient、EmbeddingModel、VectorStore 这些接口确实把各家模型的能力统一了但当你真要把一个企业级应用搭起来会发现大量胶水代码需要自己写多轮对话的记忆怎么管理工具调用Function Calling的注册和编排怎么做RAG 的检索增强流程怎么串可观测性怎么接这些问题 Spring AI 给了零件但没给整车。后来接触到 Spring AI Alibaba第一反应是这是不是又一个套壳。花了两天时间把它的源码结构和模块划分过了一遍结论是它确实在 Spring AI 之上做了不少实事而且做的位置很讲究。这篇就先从整体概览和分层架构入手把它到底加了什么这件事讲清楚。如果你正在评估要不要在项目里引入它或者单纯想理解一个 AI 应用框架该怎么分层这篇应该能帮你省下不少翻源码的时间。需要先说明的是下面涉及的具体类名、模块名基于我实际阅读的版本不同版本之间可能有调整但分层思路是稳定的。另外我补充的一些为什么这样设计的推断是基于常见工程实践的合理演绎不代表官方设计文档的原话。2. Spring AI 已经给了什么又缺了什么在讲 Spring AI Alibaba 之前必须先把 Spring AI 的定位说清楚否则很容易把两者的职责搞混。很多人一上来就问Spring AI Alibaba 是不是替代 Spring AI 的这个问题的答案是否定的——它是构建在 Spring AI 之上的理解这一点是理解整个分层架构的前提。2.1 Spring AI 的核心抽象层Spring AI 做的事情本质上是标准化。它定义了一套模型无关的接口ChatModel / ChatClient统一对话模型的调用方式屏蔽 OpenAI、通义千问、Ollama 等不同厂商的 API 差异EmbeddingModel统一文本向量化接口VectorStore统一向量数据库的读写抽象支持多种向量库实现ToolCallback工具调用的注册机制Advisor一个拦截器链式的扩展点可以在请求前后插入逻辑这套抽象的价值在于可替换。你今天用某家云厂商的模型明天想换成本地部署的开源模型理论上只需要换依赖和配置业务代码不用动。这是 Spring 生态一贯的依赖倒置思路。但问题也恰恰出在这里。抽象层为了保持通用必然要做减法。它不会替你决定对话历史存哪里、不会替你实现复杂的检索策略、不会替你编排多个 Agent 的协作。这些决策和编排恰恰是企业应用里最耗时的部分。2.2 企业落地时真正卡住的地方我把团队当时遇到的坑列一下这些也是 Spring AI Alibaba 重点要解决的问题卡点具体表现自己实现的成本对话记忆多轮对话历史需要持久化还要控制 token 上限需要自己接 Redis/数据库处理截断策略RAG 流程文档解析、分块、向量化、检索、重排、拼 prompt每个环节都要选型串起来容易乱工具调用编排多个工具如何注册、如何让模型正确选择需要理解 Function Calling 协议细节可观测性一次对话调了哪些模型、耗时多少、token 消耗需要自己埋点对接监控系统多 Agent 协作复杂任务需要多个角色分工几乎没有现成方案全靠手写状态机你看这些都不是调不通模型的问题而是调通了模型之后怎么把它变成一个能上线的系统的问题。Spring AI 解决的是前者Spring AI Alibaba 瞄准的是后者。2.3 一个关键的判断它不是重复造轮子我一开始担心的是Spring AI Alibaba 会不会把 Spring AI 的接口又包一层导致学习成本翻倍。实际看下来它的做法是扩展而非替换——核心的 ChatClient、ChatModel 这些还是用 Spring AI 的它主要是在上层补充了应用级的组件以及在下层补充了国内模型的适配。这个判断很重要因为它决定了你的迁移成本。如果你已经用 Spring AI 写了一些代码引入 Spring AI Alibaba 之后这些代码大概率不用重写只是多了一些可以选用的高级能力。这一点比某些全盘另起炉灶的框架要友好得多。3. 分层架构拆解五个层次各管什么Spring AI Alibaba 的模块划分我倾向于用五层来理解。这个分层不是官方文档里画的那种严格框图而是我按依赖关系和职责边界梳理出来的方便记忆和定位问题。3.1 模型适配层把国内模型接进来最底层是模型适配。Spring AI 官方对 OpenAI 系的支持很完善但国内开发者常用的通义千问、百炼平台上的各类模型需要额外的适配。这一层做的事情就是提供符合 Spring AI 接口规范的 Model 实现。这里有个细节值得说适配层不只是转发 HTTP 请求这么简单。不同厂商的 API 在参数命名、流式返回格式、工具调用协议上都有差异。比如同样是流式输出有的用 SSE 的data:字段有的用自定义事件类型同样是工具调用返回的 JSON 结构也不完全一致。适配层的价值就是把这些差异消化掉对上暴露统一的接口。提示如果你只是用官方已经支持的模型这一层你几乎感知不到。但一旦要接入自建模型服务或者小众厂商这一层就是你必须打交道的地方。3.2 核心能力层Graph、Memory、RAG 三件套往上一层是框架的核心能力我认为这是 Spring AI Alibaba 最有价值的部分主要包含三块Graph图编排是这里面最重的设计。它把 AI 应用的执行流程抽象成一张有向图节点是执行单元比如一次模型调用、一次工具执行、一次条件判断边是流转关系。这个思路和 LangGraph 很像好处是复杂流程可以被显式地画出来、调试、复用。为什么需要它因为真实业务里的 AI 流程很少是一问一答更多是判断意图 → 检索 → 生成 → 校验 → 必要时重试这样的多步流程用 if-else 写会迅速失控。Memory记忆解决对话历史的存储和检索。它不只是把历史消息存起来还涉及短期记忆当前会话和长期记忆跨会话的用户偏好的区分以及 token 超限时的截断或摘要策略。RAG检索增强把文档处理的完整链路封装起来读取、分块、向量化、存储、检索、重排、拼装。这一层通常会对接具体的向量库和 Embedding 模型。3.3 编排与运行时层让流程真正跑起来有了 Graph 的定义还需要一个运行时来执行它。这一层负责节点调度、状态传递、异常处理、中断恢复。我理解它和 Graph 的关系有点像 Spring 容器和 Bean 定义的关系——定义是静态的运行时是动态的。这一层还涉及流式输出的处理。AI 应用的响应往往是流式的token 一个一个吐出来运行时需要把图执行过程中的中间结果也以流的方式推给前端这对状态管理提出了更高要求。3.4 可观测与治理层上线之后才知重要这一层在 demo 阶段完全用不上但一上生产就变成刚需。它包含调用链追踪、token 消耗统计、模型调用耗时监控、异常告警等。Spring 生态本身有 Micrometer、Actuator 这些可观测性基础设施这一层要做的是把 AI 调用的指标接进去。我踩过的一个坑是早期没做 token 统计上线一个月后发现某几个用户的调用量异常高排查时完全没有数据支撑只能临时加日志。所以这一层建议在项目早期就预留接口哪怕先只记录最基础的调用次数和耗时。3.5 应用集成层和 Spring 生态打通最上层是和 Spring Boot 生态的集成包括自动配置、Starter 依赖、配置属性绑定等。这一层决定了用起来顺不顺。好的集成应该做到加一个依赖、写几行配置核心能力就能用起来而不是让你手动 new 一堆对象。这五层的关系可以这样理解下面两层是能力中间一层是执行上面两层是落地。你评估一个 AI 框架值不值得用其实就是在看这五层里哪几层它替你做了。4. 和裸用 Spring AI 的对比多出来的到底是什么光讲分层还是有点抽象我用一个具体场景来对比做一个带知识库检索的问答机器人。分别看裸用 Spring AI 和用 Spring AI Alibaba 的差异。4.1 裸用 Spring AI 的典型代码量假设你要实现用户提问 → 检索相关文档 → 拼进 prompt → 调用模型 → 返回答案这个流程用 Spring AI 你需要自己写文档加载和分块逻辑或者引入额外的文档处理库手动调用 EmbeddingModel 把分块向量化手动写入 VectorStore查询时手动做相似度检索手动拼接检索结果和用户问题调用 ChatClient如果要支持多轮还要自己管理历史消息这里面每一步都不难但加起来是几百行代码而且每一步的选型和参数都需要你自己决策。更麻烦的是当你想调整检索策略比如加个重排时改动会散落在多处。4.2 用 Spring AI Alibaba 的差异用 Spring AI Alibaba 的 RAG 能力上面这些步骤大部分被封装成了配置和声明式的调用。你更多是在配置一个流程而不是编写一个流程。Graph 的引入让流程可视化调整策略时改的是图的结构而不是散落各处的代码。这个差异的本质是裸用 Spring AI 你是在写代码用 Spring AI Alibaba 你是在编排流程。前者灵活但重复劳动多后者有约束但开发效率高。对于大多数企业应用后者的性价比更高。4.3 什么时候反而不该用它也不是所有场景都适合。如果你的需求就是调一下模型拿个结果没有任何检索、记忆、编排的需求那引入 Spring AI Alibaba 就是杀鸡用牛刀直接用 Spring AI 的 ChatClient 就够了。框架的价值和你的流程复杂度成正比流程越复杂它替你省的事越多。我的经验判断是当你的 AI 流程超过三步或者需要多轮对话记忆或者需要接知识库就值得考虑引入。低于这个复杂度先裸用 Spring AI 跑起来等复杂度上来了再迁移也不迟。5. 上手前必须想清楚的几个问题在真正动手之前有几个问题我建议你先想清楚这些是我在实际项目中踩过或者见别人踩过的。5.1 版本兼容性是个隐形雷区Spring AI 本身还在快速迭代API 时有变动。Spring AI Alibaba 作为上层框架对 Spring AI 的版本有依赖要求。我遇到过一次因为 Spring AI 小版本升级导致上层行为变化的情况排查了大半天。建议的做法是在pom.xml或build.gradle里把 Spring AI 和 Spring AI Alibaba 的版本都显式锁定不要用动态版本号。升级时先在小范围验证别直接上生产。5.2 向量库选型要提前定RAG 能力依赖向量库。开发阶段用内存向量库很方便但生产环境必须换成持久化的方案。这个切换如果做得晚可能会发现检索行为有差异不同向量库的相似度算法、索引方式不同返回结果会有细微差别。我的建议是开发阶段就用和生产一致的向量库哪怕数据量小。这样能避免开发环境好好的上线就翻车的经典问题。5.3 别指望框架替你解决 prompt 工程框架能帮你把流程串起来但 prompt 怎么写、检索结果怎么组织、模型怎么选这些还是得你自己调。我见过有人以为换个框架问答质量就能提升结果发现该不准还是不准。框架解决的是工程问题不是效果问题这两件事要分开看。5.4 可观测性从第一天就要有前面提过这个真的重要。哪怕你只是加一个拦截器记录每次调用的模型名、耗时、token 数也比什么都没有强。等到出问题再补你会后悔的。注意以上这些注意事项是基于常见工程实践的总结具体到你的项目还需要结合团队的技术栈和运维能力来判断。6. 我对这套架构设计的几点理解最后聊点偏设计哲学的东西这些是我读完源码之后的一些体会不一定对但可能对理解框架有帮助。第一它选择了扩展 Spring AI而不是重写这条路。这个选择很聪明因为 Spring AI 的抽象层是经过社区验证的重写既费力又容易和上游脱节。扩展的代价是要跟着上游的节奏走但收益是生态兼容性好。第二Graph 的引入是这套框架的分水岭。在 Graph 之前AI 应用的编排基本靠代码堆Graph 之后编排变成了可描述、可复用的东西。这个思路和当年工作流引擎的演进很像从硬编码到流程定义是复杂系统必经的一步。第三分层清晰带来的好处是按需取用。你不需要一次性把所有能力都用上可以先用模型适配层再加 RAG再加 Graph逐步演进。这种渐进式的采用路径对团队来说学习成本是可控的。第四它明显是面向企业场景设计的。从可观测性、多 Agent 协作、记忆管理这些能力就能看出来它假设的使用场景不是做个 demo而是做个能上线的系统。这个定位决定了它的复杂度也决定了它的价值。我在实际使用中的一个体会是不要试图一次性理解所有模块。先抓住模型适配 RAG Graph这条主线把最简单的问答流程跑通然后再按需深入其他模块。框架的文档和示例代码是很好的起点但真正理解它还是得自己动手改一改、跑一跑。踩过几次坑之后你会对哪一层该负责什么有更清晰的感觉这种体感是看文档看不来的。
