Spring AI Alibaba 依赖配置实战：版本兼容、BOM 管理、MCP 接入与冲突排查

前几天有个同事拿着一个刚 clone 下来的 Spring AI Alibaba 示例项目来找我说跑不起来。我看了一眼报错NoClassDefFoundError: org/springframework/ai/chat/model/ChatModel第一反应不是帮他查代码而是直接打开 pom.xml。果然Spring AI Alibaba 的 starter 版本和 Spring Boot 版本对不上Maven 里还躺着两个版本的 Spring AI 核心包。这种问题我遇到不是一次两次了这里的核心原因是这个项目链路上的版本、依赖、配置三个维度太容易互相打架。这篇就把我实际配置 Spring AI Alibaba 依赖时踩过的坑、验证过的组合以及为什么某些依赖必须那样写、某些配置必须放在那个位置一次性讲清楚。内容适合两类人一类是想从零接入通义千问的 Spring Boot 开发者另一类是项目已经跑起来但经常被依赖冲突折磨的排错选手。1. 先搞清楚 spring-ai-alibaba 在整个依赖链里的位置1.1 它和 Spring AI 是什么关系Spring AI 是 Spring 生态里做 AI 应用开发的统一框架它做的事情很像当年 Spring 对 JDBC 的封装把不同模型厂商的 API 差异遮住给你一套统一的ChatModel、EmbeddingModel、ImageModel抽象再往上还有一个对开发者更友好的ChatClient。你今天用通义千问明天想换 OpenAI理论上业务代码不用大改换依赖、改配置就行。Spring AI Alibaba 就是这套抽象在阿里云 DashScope百炼上的具体实现。它不是一个独立的 AI 框架而是 Spring AI 的一个厂商适配层。所以你的依赖配置里一定同时存在两类坐标org.springframework.ai开头的核心库和com.alibaba.cloud.ai开头的阿里实现库。很多依赖冲突本质就是这两类库在传递依赖时版本没对齐。套用一句我们做后端经常说的类比Spring AI 是接口Spring AI Alibaba 是实现。你写代码依赖的是接口但运行时必须有实现。如果你的 pom 里只有 starter 而没有正确的版本控制Maven 就会按照自己的仲裁规则随便挑一个传递版本最后编译不报错、运行时炸锅这种情况非常考验依赖配置的基本功。1.2 别和 Spring Cloud Alibaba 混为一谈这里必须先做一个区分因为热词里经常有人和 Spring Cloud Alibaba 搞混。Spring Cloud Alibaba 解决的是微服务治理问题比如 Nacos 做注册配置中心、Sentinel 做流量治理Spring AI Alibaba 解决的是 AI 能力接入问题比如让通义千问进入你的应用。两者一个是服务之间怎么通信的底座一个是应用怎么获得模型能力的上层入口。我曾见过有人把spring-cloud-starter-alibaba-nacos-config的配置写进 AI 项目里然后用 Nacos 的配置中心去管理spring.ai.dashscope.api-key不能说完全没道理但这是两个维度的东西。如果你只是做一个本地 AI Demo简单一个application.yml就够了Nacos 等你真有微服务化需求再上。依赖配置的第一步是先把你要解决什么问题想清楚否则很容易堆一堆用不上的依赖反而引入冲突风险。2. 版本选型Spring Boot、Spring AI、Spring AI Alibaba 的兼容组合2.1 一版本错、步步错依赖配置最怕的不是不会写 XML而是不知道当前 Spring Boot 应该配哪一版 Spring AI Alibaba。这里我先给一张我实际验证过、能直接照抄的兼容表组件推荐版本关键说明JDK17 及以上Spring Boot 3.x 的硬性门槛别用 8Spring Boot3.4.x 或 3.5.xSpring AI 1.0.0 基于 Boot 3.4 的自动配置 APISpring AI1.0.0 GASpring AI Alibaba 1.0.0.2 以它为基线Spring AI Alibaba1.0.0.2 或 1.0.0.3从 Maven Central 直接拉取为什么 Spring Boot 3.2 不行因为 Spring AI 1.0.0 里大量使用了 Spring Boot 3.4 才引入的自动配置绑定机制和新版配置属性解析你把 Boot 降到 3.2会出现NoSuchMethodError或者某些属性死活绑定不上。这种报错非常骗人表面看是代码错实际是底层版本不兼容。还有一点要提醒网上很多教程给的是 Spring AI 的 Milestone 或 Snapshot 版本比如1.0.0-M6。这些版本 API 变动非常频繁Spring AI Alibaba 的稳定版并不是对着最新快照适配的。我见过最典型的例子就是有人抄了一个用 M6 写的旧教程然后强行配上 Spring AI Alibaba 1.0.0.2一启动就报ChatClient.Builder不存在。原因很简单M6 版本的ChatClientAPI 和 GA 版本差异巨大。所以选型时认准 GA 稳定版别贪新。2.2 用 BOM 统一锁版本而不是每个依赖手写版本号依赖冲突最有效的预防手段是引入 BOMBill of Materials。Spring AI 官方提供了自己的 BOMSpring AI Alibaba 也有对应的 BOM。我的做法是两层都引入让 Maven 在一个受控的版本空间里做仲裁dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-bom/artifactId version1.0.0.2/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement这样做的好处是之后加任何 Spring AI 生态的 starter比如spring-ai-starter-mcp-client都不用再手写版本号BOM 会自动管理。手写版本号是依赖冲突的温床——你今天给 A 写了一个版本明天传递依赖给你带进来另一个版本Maven 仲裁选出最近定义的那个往往不是你想要的。全部交给 BOM 管至少版本来源是唯一的。这里有个非常实用的验证技巧加完 BOM 后在项目根目录执行mvn dependency:tree -Dincludesorg.springframework.ai看一眼整个依赖树里 Spring AI 相关组件是不是只有一个版本。如果有多个版本说明你的某个第三方依赖绕过 BOM 直接指定了版本这时候不要急后面第 5 章专门讲怎么处理。3. 最小可运行工程的依赖写法一个 starter 跑通 Qwen 对话3.1 先不搞花活把最小闭环跑起来我给人排查依赖问题时的习惯是先把所有业务代码删掉只保留一个最小的 Spring Boot Web 工程跑通一次模型调用再逐步加东西。这样可以精准锁定问题到底出在依赖配置还是业务代码。下面的内容就是我这个最小闭环的完整配置。首先是pom.xml的核心部分parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version1.0.0.2/version /dependency /dependencies注意spring-ai-alibaba-starter是一个聚合型 starter它会自动把 DashScope 相关的 ChatModel、EmbeddingModel、ImageModel 自动配置类都带进来。如果你只需要对话能力其实可以更精简地用spring-ai-alibaba-starter-dashscope但绝大多数项目后面都会用到不止一种能力直接用聚合 starter 更省心。3.2 配置文件api-key 用环境变量注入server: port: 8080 spring: application: name: spring-ai-alibaba-demo ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.8api-key 千万别硬编码在 yml 里。这个 key 本质上是你的钱袋子一旦提交到 Git泄露风险极大。我见过不止一个人把 key 写死在配置里推到 GitHub 公开仓库然后一天之内被刷掉几千块账单。正确做法是本地设置环境变量启动命令里带上比如export DASHSCOPE_API_KEYsk-xxxx mvn spring-boot:run3.3 一个 Controller 快速验证依赖和配置就位后写一个极简接口验证SpringBootApplication public class AiApplication { public static void main(String[] args) { SpringApplication.run(AiApplication.class, args); } } RestController RequestMapping(/api/ai) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/chat) public String chat(RequestParam(defaultValue 用一句话介绍你自己) String msg) { return chatClient.prompt(msg).call().content(); } }这里注入ChatClient.Builder是 Spring AI 1.0.0 的标准姿势它在 Spring AI Alibaba 的自动配置里已经注册好了。启动后访问curl http://localhost:8080/api/ai/chat?msg你好能返回一段通义千问的文字说明依赖配置这一关已经过了。到这里你已经拥有了一个能跑通的 AI 应用骨架后面的所有功能都是在这个骨架上做加法。3.4 国内环境的一个现实问题Maven 镜像如果你在国内拉取依赖特别慢或者某些依赖反复下载失败优先检查~/.m2/settings.xml里的镜像配置。用阿里云 Maven 镜像可以明显提升速度配置如下mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror需要注意spring-ai-alibaba-starter的 1.0.0.x 系列已经在 Maven Central 上镜像同步基本没有延迟问题。如果哪天报 404 找不到某个依赖先确认镜像是否同步完整再考虑换回中央仓库试试。这个排查顺序能省不少时间。4. 进阶依赖组合MCP 服务接入与多模型能力扩展4.1 怎么接入别人提供的 MCP 服务MCPModel Context Protocol是现在 AI 应用开发绕不开的话题简单理解它就是给模型装外挂工具的标准化协议。别人写了一个天气查询服务、数据库查询服务只要它实现了 MCP 协议你的应用就能通过标准方式调用不需要关心对方的内部实现。Spring AI Alibaba 对 MCP 的支持非常友好因为 Spring AI 官方已经提供了 MCP Client 的自动配置阿里实现只是在模型这一层做适配。换句话说你既能用通义千问又能把别人提供的 MCP 工具塞给这个模型用。接入步骤分三步。第一步加依赖。在 BOM 管好版本的前提下直接加dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependency第二步配置 MCP 连接。如果对方提供的是一个基于 SSEServer-Sent Events的远程 MCP Server配置长这样spring: ai: mcp: client: connections: weather-server: type: sse url: http://localhost:18000/sse如果对方提供的是本地进程比如一个用 npx 启动的 Node.js MCP Server就用 stdio 类型spring: ai: mcp: client: connections: local-tool: type: stdio command: npx args: [-y, some/mcp-server]第三步你的业务代码不用显式去调工具。只要你用了chatClient.prompt(北京今天天气如何).call().content()Spring AI 会自动把已配置的 MCP 工具注入到这次对话的工具列表里模型判断需要天气数据时会自动发起工具调用整个链路对上层是透明的。这里有个关键点想让工具调用生效你选的模型必须支持 function calling。qwen-plus、qwen-max 这些主流模型都支持但如果用某些轻量模型可能不会触发工具调用表现就是模型假装知道天气而不去查。遇到这种情况先别怀疑 MCP 配置换个更强的模型试试。4.2 不只是对话图像、向量、语音怎么加Spring AI Alibaba 的依赖设计是分模块的虽然聚合 starter 把所有自动配置都带进来了但你实际用哪些能力配置上是分开的能力配置前缀常用模型示例对话spring.ai.dashscope.chat.optionsqwen-plus、qwen-max向量化spring.ai.dashscope.embedding.optionstext-embedding-v4图像生成spring.ai.dashscope.image.optionswanx2.1-t2i-turbo语音理解spring.ai.dashscope.audio.optionsqwen-audio-turbo这些能力的依赖都已经包含在聚合 starter 里不需要额外加坐标。真正需要你额外加依赖的场景是你想把向量化能力接到向量数据库或者想在应用里用 RAG。比如接入 Redis 向量存储就需要再加一个spring-ai-starter-vector-store-redis。这就要回到第 2 章说的只有 BOM 管好了这些扩展依赖才能做到加了就能跑。4.3 依赖组合速查表我把日常项目里出现频率最高的依赖组合整理成一张表你可以直接对照着加项目需求需要加的依赖说明基础对话spring-ai-alibaba-starter聚合 starter覆盖常见能力接入远程 MCPspring-ai-starter-mcp-client支持 SSE / HTTP 类型提供 MCP 给别人spring-ai-starter-mcp-server把自己应用的能力暴露成 MCP流式对话无需额外依赖用stream()接口注意 WebFlux 支持SQL 查询转自然语言无需额外依赖用 qwen-plus 自定义工具函数接入 Redis 向量存储spring-ai-starter-vector-store-redis需要先有 Redis 环境5. 依赖冲突排查实录从报错链路到根因修复5.1 场景一NoClassDefFoundError 与 NoSuchMethodError这类报错是 Spring AI 项目里最常见的。现象是启动时或运行时突然抛java.lang.NoClassDefFoundError: org/springframework/ai/chat/model/ChatModel或者java.lang.NoSuchMethodError: org.springframework.ai.chat.model.ChatModel第一眼可能觉得是代码写错了但我可以负责任地说90% 的情况是 classpath 里有多个版本的 Spring AI 核心包。排查链路我建议这样走第一步锁定位域。在项目根目录执行mvn dependency:tree -Dincludesorg.springframework.ai看输出的依赖树里是否出现多个spring-ai-core、spring-ai-dashscope版本。第二步找到元凶。依赖树里每一行都会显示从哪个依赖引入比如某个非 AI 相关的 starter 传递引入了旧版 Spring AI。第三步修复。在dependencyManagement里把 Spring AI BOM 加上让所有版本回归统一如果某些依赖强行指定了版本就在引入它的 dependency 里加exclusion。这里我要特别提醒不要为了压制冲突去手动 override 一个你并不了解的新版本。版本统一的前提是选一个经过验证的基线比如 Spring AI Alibaba 1.0.0.2 对应的 Spring AI 1.0.0而不是直接把所有 Spring AI 包强行改成最新快照。5.2 场景二SLF4J 多个绑定的经典警告启动日志里出现SLF4J: Class path contains multiple SLF4J bindings.这个报错本身不致命但后期排查日志问题时非常痛苦——日志可能随机输出到某个不知道的 appender或者某些日志莫名消失。原因通常是某个阿里云 SDK 自带了一个log4j-slf4j-impl而 Spring Boot 自带logback-classic两个都是 SLF4J 的绑定器互相打架。修复方式是在那个 SDK 的依赖上排除冲突绑定dependency groupIdcom.xxx/groupId artifactIdsome-sdk/artifactId exclusions exclusion groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-slf4j-impl/artifactId /exclusion /exclusions /dependency判断标准很简单保留一个日志绑定器。Spring Boot 项目默认是 Logback那就把其他绑定器全部排掉。这个坑在接各种云厂商 SDK 时极其常见不止是阿里云也不止是 Spring AI。5.3 场景三DashScope 流式调用时的 Netty/Reactor 版本冲突如果你用流式接口比如chatClient.prompt(msg).stream().content()在 Spring MVC 工程里返回FluxString有可能遇到 Netty 的NoSuchMethodError或 SSE 连接异常。底层的本质是Spring AI Alibaba 的流式调用走的是 Reactive 的 WebClient而项目里某个依赖自带的旧版 Netty 把 classpath 污染了。解决思路和前面一样但这里有个更隐蔽的点如果你不是标准 Spring Boot 项目或者你的 Boot 版本本身就偏老Netty 版本不受 Boot BOM 管辖这时候必须在dependencyManagement里手动管一下 Netty 版本让它和 Boot 的预期一致。如果你用的是标准 Boot 3.4.x绝大多数情况下 Boot BOM 已经管好了出现这个报错反而要警惕是不是有人手动指定了 Netty 版本。另外一个小经验把spring-boot-starter-webflux加上能让流式接口的返回处理更顺畅。就算你主体是 Web MVC 项目加一个 WebFlux 依赖也不会有冲突因为 Boot 会同时支持两种编程模型。5.4 利用启动日志的自动配置报告快速定位排查依赖问题时不要只看堆栈的第一行要学会看 Spring Boot 的自动配置报告。在application.yml里临时加debug: true启动后日志里会出现Positive matches和Negative matches。如果 DashScope 相关的自动配置类出现在Negative matches里说明某个条件没有满足最常见的就是没配api-key或者类路径缺少某个依赖。这个技巧能帮你把排查范围从整个项目缩小到某一个自动配置条件效率提升非常明显。6. 依赖之外的配置细节api-key、模型参数与可观测性6.1 配置命名空间为什么看似一样的配置不生效Spring AI 1.0.0 把配置归属到了统一的命名空间规则是spring.ai.厂商.能力.options。比如 DashScope 对话模型是spring.ai.dashscope.chat.options.model图像模型是spring.ai.dashscope.image.options.model。我经常看到有人从老教程复制配置写的是spring.ai.dashscope.model-name或者spring.ai.dashscope.chat.model这种老式写法在这个版本下根本不会绑定到自动配置上表现出来的现象就是你改了模型名调用的还是默认模型。如果你发现项目里改了配置没有任何效果第一件事去翻官方文档里对应版本的Configuration Properties列表而不是凭记忆写前缀。版本升级时配置命名空间极容易变这是 Spring AI 系列项目的老传统。6.2 模型参数temperature、top-p 和 enable-search依赖配好了模型参数决定的是回答质量。以对话为例yaml 里可以这样配spring: ai: dashscope: chat: options: model: qwen-plus temperature: 0.85 top-p: 0.9 enable-search: trueenable-search要特别说一下这是通义千问系列的一个特色选项。开启后模型可以在必要时联网搜索回答时效性问题时效果会好很多。但它也意味着单次调用可能消耗更多 token成本会上升。如果只是做知识问答和内容生成不必开。在实际项目里我更建议把这些参数放在每次请求的动态 options 里而不是写死在 yml。因为不同业务场景需要不同的 temperature比如客服机器人希望回答稳定temperature 调低创意写作希望更有想象力temperature 调高。依赖配置负责能把模型跑起来动态参数负责跑得更合业务口味两者是不同层面的东西。6.3 可观测性ObservationHandler 和链路追踪Spring AI Alibaba 的 starter 已经引入了spring-ai-observability相关依赖也就是说只要你打开 Micrometer 的 tracing 配置每次模型调用的耗时、token 消耗、工具调用链路都会被记录。配置很简单management: tracing: sampling: probability: 1.0 endpoints: web: exposure: include: health,metrics,prometheus如果你想自定义监控逻辑可以实现一个ObservationHandler并注册成 BeanBean public ObservationHandlerObservation.Context aiObservationHandler() { return new ObservationHandlerObservation.Context() { Override public void onStart(Observation.Context context) { // 记录调用开始 } Override public void onStop(Observation.Context context) { // 记录耗时、模型名、token 用量 } Override public boolean supportsContext(Observation.Context context) { return true; } }; }这个机制的好处是监控代码和业务代码完全解耦你不需要在每个调用模型的地方手动埋点。对于要上生产的项目依赖配置过关只是第一步可观测性配置建议尽早做不然等模型调用量上来之后出问题你根本不知道是模型本身慢、网络慢还是你的业务逻辑慢。6.4 关于 Spring AI 2.0 的一点提醒热词里有人在搜 Spring AI 2.0。以我目前的实践看Spring AI 2.0 还在迭代调整中坐标前缀、配置命名空间大概率会继续变动直接用在生产项目风险偏高。如果你是新建项目我的建议是以 Spring AI 1.0.0 GA Spring AI Alibaba 1.0.0.2 这套稳定组合为基线。等 2.0 正式发版之后再对照官方迁移指南升级千万不要在生产项目里追这个进度。回到开头那个同事的问题。那天我帮他把 pom 里的 Spring AI 版本统一到 BOM 管理删掉一个多余的旧版传递依赖重新mvn spring-boot:run不到两分钟服务就起来了。他当时感叹了一句原来问题不在代码在依赖。这句话我特别认同。Spring AI Alibaba 这类项目的依赖配置本质上是在管理一个由抽象接口、厂商实现、协议客户端、日志绑定器、网络库共同组成的复杂生态。你没法让所有依赖都乖乖听话但用好 BOM、看清依赖树、理解自动配置条件就能让它们在同一个版本空间里相安无事。这也是我每次新建 AI 项目时最先花时间做的事。