1. 项目概述Spring AI Alibaba 到底解决什么问题先说结论Spring AI Alibaba 不是一个独立的新框架它是站在 Spring AI 这层“抽象地基”之上把阿里系的一套大模型应用基础设施给“接”了进来。如果你已经接触过 Spring AI知道它有ChatClient、ChatModel、EmbeddingModel这套统一抽象那 Spring AI Alibaba 要做的就是让你在写业务代码时不用关心底层走的是通义千问还是 DashScope 兼容接口也不用自己造轮子去处理对话历史、缓存、提示词模板这些琐碎事。我在实际项目里最直观的感受是Spring AI 本身已经帮你把“对接大模型”这件事从“HTTP 调用 JSON 解析”提升到了“面向接口编程”但真正落地产线时你会发现还有很多事它没管。比如流式输出的超时和重试策略需要自己写多轮对话的上下文管理要自己维护提示词模板的版本管理和动态参数注入基本靠拼接字符串模型切换时业务代码里散落着不同 SDK 的调用痕迹。Spring AI Alibaba 就是在这些“坑”上面做了一层补齐。它的定位不是替代 Spring AI而是让 Spring AI 在阿里云生态里更好用。你可以把它理解为Spring AI 是“标准插座”Spring AI Alibaba 是“国标转接头”它没有改变电本身但让你手里的设备能更稳定地插上去。这篇文章我先带你从整体概览和分层架构入手搞清楚它到底在 Spring AI 之上加了哪几层东西。后续我会逐步拆解每个模块的用法和源码实现这篇算是整个系列的地基。2. 设计思路为什么选择在 Spring AI 之上做扩展而不是另起炉灶2.1 三个痛点逼出来的选择我在做 AI 应用落地的过程中被三个问题反复折磨过。第一个是模型厂商锁定。今天用 A 厂的模型跑通了原型明天老板说换个成本更低的模型结果发现代码里到处是 A 厂 SDK 的痕迹改起来痛不欲生。Spring AI 的核心价值恰恰是抽象了ChatModel接口理论上换模型只改配置。但实际用下来不同模型的参数差异比如温度、top_p、stop 序列还是会渗透到业务代码里因为 Spring AI 的ChatOptions是各家模型实现各自定义的。第二个是AI 能力和业务系统的割裂。业务系统里有用户体系、权限体系、订单状态AI 能力如果要融入这些业务逻辑不能只是“调一个接口返回文本”。你需要让模型能读到你数据库里的数据、能调用你们内部的服务、能理解你们业务里的术语。Spring AI 提供了Tool Calling的基础支持但要做好还需要跟 Spring 的 Bean 体系深度整合。第三个是工程化能力缺失。开发一个 AI 接口容易上线一个 AI 接口难。你需要考虑提示词被改坏了怎么办用户多轮对话的上下文怎么存模型接口超时了是重试还是降级这些“工程问题”恰恰是 Spring AI 作为“基础抽象层”不愿意做的也是各个云厂商最擅长做的。2.2 分层架构的核心理念像搭积木一样加能力Spring AI Alibaba 的分层架构本质上是把“AI 应用开发”这件事拆成了几个关注点。从上往下看业务接入层你写业务代码的地方接触的是ChatClient、ChatModel这些高层 API不关心底层协议。模型适配层Spring AI Alibaba 通过DashScopeChatModel等实现类把阿里云的通义千问、百炼平台的各种模型包装成 Spring AI 的统一接口。同时支持通过spring.ai.model.chat这类配置快速切换。增强能力层这是它“加了什么”的重点。比如提示词模板管理、对话记忆、输出解析器、多工具调用编排。基础设施层连接阿里云的服务比如 DashScope API、阿里云日志服务、负载均衡等。这种分层设计的好处是每一层只解决一类问题你可以在不破坏其他层的情况下替换某层的实现。比如你今天用通义千问明天想换一个开源模型部署在本地只需要在模型适配层加一个实现上层的业务代码几乎不用动。注意这里说的“分层”不是代码里的包结构强制分层而是一种逻辑边界。你在实际工程中不一定非得建四个包但心里要有这根弦业务代码不要直接依赖某个模型 SDK 的类否则分层就白做了。2.3 与 Spring AI 官方扩展点的关系Spring AI 官方本身也留了一些扩展点比如Advisor顾问链用于在调用模型前后做增强、ChatClient.Builder的定制。Spring AI Alibaba 的核心策略是尽量复用这些官方扩展点而不是绕过去自己搞一套。举个例子Spring AI 的Advisor机制允许你在调用大模型之前插入“消息处理”比如把用户消息加上系统提示词、把历史对话塞进上下文。Spring AI Alibaba 里面的很多功能比如通义千问的 prompt 优化、记忆管理其实都是通过实现自定义Advisor来完成的。这样做的好处显而易见如果你已经熟悉 Spring AI 的原生写法迁移到 Spring AI Alibaba 的学习成本很低如果你不想用某个增强功能直接不在ChatClient构建时添加对应的Advisor即可完全是可选开关。这个“站在扩展点上做事”的思路比那种“自己重新定义一套 API”的做法高明很多。前者是渐进增强后者是另起炉灶。渐进增强意味着你可以逐步引入另起炉灶则意味着团队要重新学习一套东西。3. 核心模块拆解它具体加了哪几层东西3.1 模型接入层DashScope 与通义千问的封装Spring AI Alibaba 最基础的能力是把阿里云百炼平台DashScope上面的模型统一封装成 Spring AI 的ChatModel和EmbeddingModel。目前主流的模型包括通义千问系列qwen-plus、qwen-turbo、qwen-max通义千问 VL 视觉模型qwen-vl-plus通义千问开源模型的托管版本配置上非常简单在application.yml里加上spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7这段配置背后Spring AI Alibaba 自动帮你完成了几件事根据配置构建DashScopeChatModel实例初始化一个用于调用 DashScope HTTP API 的WebClient内置连接池和超时参数将ChatModel注入 Spring 容器让你可以直接在 Service 里依赖注入。用起来和 Spring AI 官方的方式几乎一致RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } PostMapping(/chat) public String chat(RequestBody String prompt) { return chatClient.prompt() .user(prompt) .call() .content(); } }不过有一点需要留意DashScope 的api-key不要硬编码在配置文件里尤其是多人协作的代码库建议通过环境变量注入。我在项目里还踩过一个坑spring.ai.dashscope.api-key和某些旧版本的spring.cloud.alibaba.ai配置前缀不兼容导致启动时一直报“未找到 api-key”。后来统一按 Spring AI Alibaba 自己的 starter 要求改成spring.ai.dashscope.api-key就正常了。3.2 提示词模板与输出解析把“调模型”变成“填表单”如果你只在业务代码里写chatClient.prompt().user(请帮我总结...)那确实不需要多少模板能力。但真实项目里的 prompt 往往很长包含系统设定、示例、动态变量。Spring AI Alibaba 在这块提供了基于 Spring 的MessageTemplate机制你可以把 prompt 写成资源文件然后动态填充变量。比如在src/main/resources/prompt-templates/下建一个summary.st文件你是 {role}请根据以下文本生成摘要要求不超过 {maxWords} 字。 文本内容 {content}然后在代码里这样用PromptTemplate promptTemplate new PromptTemplate(classpath:/prompt-templates/summary.st); Prompt prompt promptTemplate.create(Map.of( role, 资深编辑, maxWords, 200, content, articleText )); String summary chatClient.prompt(prompt).call().content();输出解析器方面Spring AI Alibaba 支持把模型输出直接映射成 POJO省去自己解析 JSON 的麻烦。你只需要定义好目标结构public record ArticleSummary(String title, String summary, ListString keywords) {}然后在调用时传入BeanOutputConverterBeanOutputConverterArticleSummary converter new BeanOutputConverter(ArticleSummary.class); String json chatClient.prompt() .user(请生成摘要) .call() .content(); ArticleSummary result converter.convert(json);这里有一个非常实用的经验实际使用中模型输出 JSON 并不总是合法 JSON。尤其是要求它输出包含中文长文本的字段时偶尔会夹带 json 标记或者末尾多一个逗号。所以我建议在 converter 转换之前加一层“小清洗”比如去掉首尾的代码块标记再交给 Jackson 解析。Spring AI Alibaba 在部分版本里内置了清洗逻辑但不要完全依赖它。3.3 记忆与上下文管理多轮对话的工程化手段单轮问答只是 demo多轮对话才是真实业务。Spring AI 原生的方式是调用时手动带上历史消息ListMessage messages List.of( new SystemMessage(你是客服助手), new UserMessage(我买了东西什么时候发货), new AssistantMessage(您的订单预计 48 小时内发货。), new UserMessage(那怎么退换货) );问题在于谁来维护这个messages列表如果是单体应用内存里放一个MapsessionId, ListMessage勉强能跑。但一旦实例多开、服务重启、或者要支持分布式部署内存方案立刻穿帮。Spring AI Alibaba 在这块提供了两个实用武器ChatMemory抽象定义消息存储的接口可以接入内存实现、Redis 实现甚至数据库实现。MessageWindowChatMemory默认实现按窗口大小保留最近的 N 条消息防止 context 无限膨胀。具体用法如下ChatMemory chatMemory MessageWindowChatMemory.builder() .maxMessages(20) .build(); ChatClient chatClient ChatClient.builder(chatModel) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory, session-id, 20)) .build();这里面的MessageChatMemoryAdvisor是关键。它会在每次请求时把当前 session 的历史消息自动加载进来放到消息列表的最前面等模型返回后再把这次的 UserMessage 和 AssistantMessage 保存回去。整个过程中你的业务代码不需要手动维护消息列表。我在实际项目中用的方案是RedisChatMemory把 session 的历史记录序列化成 JSON 存到 Rediskey 是ai:chat:memory:{sessionId}。这样做的好处是应用重启不丢上下文多副本部署也能共享同一份记忆。但要注意Redis 里的 JSON 最好带版本号字段因为消息结构升级时旧数据反序列化容易报错。3.4 工具调用Function Calling让模型能操作你的业务系统如果说前面几点只是“花架子”那工具调用就是让大模型从“聊天机器人”进化为“业务助手”的关键。Spring AI Alibaba 的 Tool Calling 能力和 Spring AI 官方基本一致但有两个增强点对 DashScope 的工具调用协议做了适配支持把 Spring 容器里的 Bean 方法直接暴露为工具不需要额外封装。最简单的使用方式是给某个 Service 的方法加上注解Component public class OrderService { Tool(description 根据订单ID查询订单状态) public String getOrderStatus(String orderId) { // 查数据库返回状态 return switch (orderServiceDao.queryStatus(orderId)) { case PENDING - 待支付; case PAID - 已支付; case SHIPPED - 已发货; default - 未知状态; }; } }然后在构建ChatClient时把这个 Bean 传进去ChatClient chatClient ChatClient.builder(chatModel) .defaultTools(new OrderService()) .build(); String reply chatClient.prompt() .user(帮我查一下订单 A123 的状态) .call() .content();模型会先识别出需要调用getOrderStatus工具生成参数{orderId: A123}然后框架帮你调用这个方法把返回结果再喂给模型最终模型生成自然语言回复。整个链路中业务侧只写了一个普通方法剩下的交给框架。这里面的一个关键提醒工具调用的“所见即所得”是有代价的。模型可能产生不存在的 orderId也可能在你没有充分授权的情况下调用不该调用的工具。所以在暴露工具之前一定要加权限校验。我习惯的做法是在Tool方法内先做参数合法性和当前用户权限的校验宁可抛出异常也不能让模型乱调。3.5 多云模型切换与路由为“换模型不换代码”留好开关项目做大了以后你不会只想用一家模型。可能主模型用 qwen-max备链路用 qwen-turbo 或者别的开源模型。Spring AI Alibaba 提供了比较灵活的路由配置最简单的方式是通过多组ChatModelBean 的定义配合Primary和Qualifier选择。Configuration public class ChatModelConfig { Bean Primary public ChatModel qwenMaxChatModel() { return new DashScopeChatModel.Builder() .model(qwen-max) .temperature(0.7) .build(); } Bean public ChatModel qwenTurboChatModel() { return new DashScopeChatModel.Builder() .model(qwen-turbo) .temperature(0.3) .build(); } }使用时通过Qualifier注入Service public class RecommendService { private final ChatModel fastModel; public RecommendService(Qualifier(qwenTurboChatModel) ChatModel fastModel) { this.fastModel fastModel; } public String recommend(String userId) { return fastModel.call( new Prompt(根据用户偏好推荐商品) ).getResult().getOutput().getText(); } }更进一步你可以自己写一个“路由ChatModel”内部根据业务类型、用户级别、成本预算等条件把请求转发到不同的底层模型。这种做法的好处是上层业务完全不知道模型切换的存在你只是在配置中心改一段路由规则而已。4. 分层架构的完整视角一张表看懂各层职责如果你埋头写代码容易陷入“哪个类放在哪个包”的细节里。我建议你从一个更高的视角来看 Spring AI Alibaba 在 Spring AI 之上加了什么。我把各层对应的核心组件和职责整理成一张表层次对应组件职责说明和原生 Spring AI 的关系业务接入层ChatClient、ChatModelAPI提供给人写业务代码的统一入口直接复用原生 API模型适配层DashScopeChatModel、DashScopeEmbeddingModel实现 DashScope 协议的模型适配实现了 Spring AI 的 SPI 接口增强能力层ChatMemory、Advisor、OutputConverter、PromptTemplate提供记忆、模板、解析、工具编排等增强大多基于原生扩展点实现连接与运维层阿里云 DashScope API、日志、监控负责与大模型服务的物理通信和可观测性相当于 Spring AI 的“transport”配置与装配层spring.ai.dashscope.*自动配置类根据配置自动创建 Bean降低使用成本相当于 Spring Boot 自动装配的角色通过这张表你可以看到Spring AI Alibaba 并没有动 Spring AI 的“骨架”而是在“血肉”层面做了大量填充。这带来的好处是你对 Spring AI 原生知识的所有积累在这里都还能用上。反过来说这也意味着你踩过 Spring AI 原生的一些坑在这里大概率还会踩。比如ChatClient的流式输出即使有 Spring AI Alibaba 封装你依然要自己处理Flux的背压和异常恢复。封装只是帮你省了“对接模型服务端”的功夫但“应用层容错”这件事框架很难替你包办。5. 实操验证从零搭建一个 Spring AI Alibaba 的最小工程光讲架构是虚的我带你把最小工程跑起来。这个过程我实测过按照下面的步骤走大概十分钟内能看到效果。5.1 初始化工程与依赖引入推荐直接用 Spring Initializr 创建工程也可以手动建 Maven 项目。这里以 Maven 为例关键依赖如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.x/version /parent dependencies !-- Spring AI Alibaba 的 starter -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version1.0.0-M3/version /dependency !-- Spring Web 用来写接口测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies注意版本号。Spring AI Alibaba 的版本迭代比较快有些早期版本对应的 Spring AI 版本较老。建议去 Maven 中央仓库看最新版本我写的1.0.0-M3只是我当时用的版本。版本选错最常见的问题就是出现NoClassDefFoundError或 Bean 装配失败因为这货对 Spring Boot 版本有强绑定。5.2 配置与启动配置文件里把 api-key 配上建议环境变量spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY:} chat: options: model: qwen-plus写一个简单的测试接口RestController RequestMapping(/ai) public class AiDemoController { private final ChatClient chatClient; public AiDemoController(ChatClient.Builder builder) { this.chatClient builder.build(); } PostMapping(/chat) public String chat(RequestBody MapString, String req) { return chatClient.prompt() .user(req.getOrDefault(message, 你好)) .call() .content(); } }启动应用后用 curl 测试curl -X POST http://localhost:8080/ai/chat \ -H Content-Type: application/json \ -d {message: 用一句话介绍你自己}如果一切正常你会收到模型返回的自我介绍。这个最小工程虽然简单但它已经跑通了“业务接入 - 模型适配 - DashScope 服务”的完整链路后面的增强能力都是在这个基础上叠加的。5.3 加一个记忆能力的升级步骤上面的 demo 是“无状态”的每次请求都不会带上下文。如果你想体验 Spring AI Alibaba 在增强层面的能力可以简单加一个 AdvisorChatMemory chatMemory MessageWindowChatMemory.builder().maxMessages(10).build(); ChatClient chatClient ChatClient.builder(chatModel) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory, default-session, 10)) .build();然后连续问两个问题第一个说“我的名字叫张三”第二个问“我叫什么名字”模型能准确回答。这个实验能够直观体现它加的“上下文管理”这一层到底有什么价值。6. 常见问题与排查技巧实录6.1 启动时报“无法加载 DashScope ApiKey”这个报错通常不是代码问题而是配置问题。排查顺序确认环境变量DASHSCOPE_API_KEY是否真的设置了echo $DASHSCOPE_API_KEY确认配置前缀是否正确应该是spring.ai.dashscope.api-key确认你用的 starter 版本里读取配置的类是否改过前缀。曾经出现过新版本把spring.cloud.alibaba.ai.dashscope.api-key也兼容的情况但如果你依赖的是标准 starter前缀就是spring.ai开头。6.2 模型返回的内容偶尔带有奇怪的换行或 markdown 标记这是大模型输出本身的不确定性导致的不是框架 bug。如果你的业务对输出格式有严格要求建议在 OutputConverter 之前加一个清洗函数。一个简单的做法String cleaned rawContent.replaceAll(json\\n?, ) .replaceAll(\\n, ) .trim();6.3 多轮对话时上下文被截断MessageWindowChatMemory是按窗口大小截断的如果你设置maxMessages10它只会保留最近 5 轮完整对话每轮包含用户消息和助手消息。当你需要更长的上下文时要么调大窗口要么换用支持持久化存储的ChatMemory实现。但注意上下文越长token 消耗越大、响应越慢需要做一个权衡。6.4 工具调用时模型传入的参数和预期不一致模型生成参数是有随机性的偶尔会出现字段名对不上、或者类型不对的情况。我的经验是在Tool注解的描述里写清楚每个参数的格式要求比如“orderId 是字符串类型格式形如 A123”。描述越明确模型传参的准确率越高。如果仍然经常出错可以在方法内做一层“防御式解析”不直接信任入参。6.5 版本兼容性矩阵我整理了一张常用的版本对应关系供参考Spring AI Alibaba 版本适配 Spring AI 版本Spring Boot 版本1.0.0-M11.0.0-M63.2.x1.0.0-M21.0.0-M63.2.x1.0.0-M31.0.0-M63.2.x更新版本请查阅官方 release 说明通常适配 3.3版本选型建议生产环境不要追最新优先选已经发布至少一两个月的稳定小版本。如果你在公司里用最好让运维或者架构组出一个“公司内部推荐版本”避免每个项目组各用各的导致维护混乱。7. 后续扩展方向与个人经验写到这里整个概览和分层的思路已经清楚了。Spring AI Alibaba 在 Spring AI 之上加的东西总结成一句话它把“对接大模型”这件事从“能用”提升到了“好用”尤其是模型适配、记忆管理、工具调用、模板解析这几个方面确实替开发者省了不少心。但我个人在实际操作中的体会是框架帮你省掉的是“重复劳动”而不是“思考”。比如它提供了ChatMemory的多种实现但你的业务是要求“按用户隔离记忆”还是“按会话隔离记忆”这是业务设计问题它提供了Tool注解但你的方法是否要暴露给模型暴露后怎么鉴权和审计这还是你自己的责任。所以在团队引入 Spring AI Alibaba 时我建议先把场景想清楚你需要的是单轮问答、多轮对话还是带工具调用的复杂 Agent你的上下文需要持久化吗存 Redis 还是数据库你允许模型调用哪些工具如何控制风险这些问题的回答决定了你会用到 Spring AI Alibaba 的哪几层能力。最后再分享一个小技巧不要只依赖框架内置的ChatClient.Builder默认装配建议你在项目里自己封装一个ChatClientFactory把默认系统提示词、默认记忆策略、默认输出解析都集中在工厂里做。这样你的业务代码会非常干净而且后续框架升级时你只需要改一个地方就能平滑切换。我目前就在项目里用这个模式维护成本和踩坑概率都明显降下来了。下一篇我会重点拆解ChatClient的完整调用链路把你从“会调接口”带到“理解调用过程的每一步”敬请关注。