上个月做智能客服工作台前期图快直接用了某家模型厂商自带的SDK结果到二期产品说普通用户走便宜模型、付费用户走强模型、运营活动临时切换我一翻代码就头疼——业务层已经被厂商SDK绑死了请求对象、返回结构、错误处理全是那家特有的写法。后来我把方案改成Spring AI 通义千问多模型切换这件事变得异常简单核心逻辑就几行配置的事。这篇文章就把整套方案完整展开包括可运行的Demo、三种切换方式、以及我实际调试中踩过的版本、模型名、超时之类的坑。适合正在做Java AI应用、又不想被单一模型厂商绑死的开发者尤其对国内直连通义千问有需求的朋友。1. 为什么我最终选Spring AI 通义千问的组合1.1 AI厂商SDK各搞各的抽象层成了刚需接多个大模型最难受的地方不是模型效果而是写代码的方式完全不一样。OpenAI的SDK是一套client.chat.completions.create的写法通义千问的原生SDK走的是DashScope那套接口某些国产模型又是另一套认证和消息格式。你换一个厂商不只是改一个配置的事请求参数、返回结构、错误码、重试策略全都要重写。业务代码一旦被某个厂商SDK渗透后面每一次切换都要脱一层皮。Spring AI解决的就是这个问题。它定义了一套统一的接口ChatModel是模型层抽象ChatClient是对外使用的门面。业务代码只面向ChatClient写底层到底是通义千问、OpenAI还是本地Ollama对业务层完全透明。这个思路很像当年的JDBC——不同数据库各有各的协议但Java开发者只要写一套JDBC代码换数据库改驱动和连接串就行。大模型接入现在也等来了这么一层标准。Spring AI 2.0.1这版把ChatClient的API做得很顺手链式调用非常直观。我在切到Spring AI之后第一感受是以前几十行SDK胶水代码现在一个prompt()方法就搞定了第二感受是提示词、温度参数、流式处理全都统一了换模型基本就是改配置。如果你现在还在业务代码里到处new厂商的Client真心建议尽早抽一层不然后面切换模型的时候一定后悔。1.2 通义千问值得接的几个理由选模型厂商我主要看四点访问体验、模型能力、价格、接入成本。访问体验是说通义千问走的是阿里云百炼DashScope平台国内直连响应很稳定。之前项目里用海外模型要考虑网络延迟、额外的网关组件光是运维成本就够劝退的。模型能力上qwen系列现在的梯队拉得很清楚——qwen-turbo速度快、价格低适合高并发客服、简单分类qwen-plus是综合性价比之王大部分业务场景都能顶住qwen-max是旗舰复杂推理、长文本、代码生成这类硬任务最稳。实测同一个Prompt日常闲聊几个模型的差异不明显但涉及多步推理、代码审查、长对话记忆的时候max确实更稳。中文场景里qwen这代模型的表现属于第一梯队。而且qwen在Spring AI里有官方Starter连适配层都省了。价格上通义千问相比同档位海外模型便宜不少对创业团队和中小项目友好。接入成本上只要在百炼平台领一个API Key依赖里加一个spring-ai-starter-model-qwen剩下的就是Spring配置文件和业务代码的事。所以最终组合很自然Spring AI负责统一抽象通义千问负责模型能力中间不需要额外网关一套代码跑多个模型。2. 版本适配与依赖引入这里藏着第一个坑2.1 Spring AI 2.0.1适配哪个Spring BootSpring AI 2.0.1不是一个独立跑的框架它是Spring生态里的AI模块所以版本匹配非常重要。我自己用的组合是JDK 17 Spring Boot 3.4.5 Spring AI 2.0.1。如果你的项目还在Spring Boot 3.2.x甚至更早直接把spring-ai-bom引入启动时大概率会报Bean创建失败或者MethodNotFoundException这类错误非常误导人因为日志和你写的代码没有直接关系。建议直接用Spring Boot的BOM统一管理Spring AI版本。在pom.xml里通过dependencyManagement引入spring-ai-bom依赖项本身就不写版本号了由框架自动对齐。这样能最大程度避免我踩过的版本漂移问题——所谓版本漂移就是你在网上看到一段可用的配置复制过来发现自己的依赖版本跟人家差了一大截跑起来全是怪问题。2.2 依赖坐标和BOM的写法pom.xml核心部分如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.5/version relativePath/ /parent properties java.version17/java.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version2.0.1/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-qwen/artifactId /dependency /dependencies注意spring-ai-starter-model-qwen正是Spring AI官方对接通义千问/DashScope的Starter。你可能在社区里见过spring-ai-alibaba那是另一套东西由阿里社区维护定位偏向Spring Cloud Alibaba生态两者很容易被搞混这点我在避坑指南里专门讲。2.3 最小可运行配置依赖引入之后application.yml只需要一个API Key和一个模型名就能跑spring: application: name: spring-ai-qwen-demo ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7这里第一个坑就来了配置前缀是spring.ai.dashscope不是spring.ai.qwen。因为通义千问走的平台是阿里云百炼DashScopeSpring AI官方对接的是DashScope的OpenAI兼容接口。写错前缀不会启动报错但配置完全不生效调用时要么用默认模型要么直接403。API Key建议从环境变量读别硬编码在配置文件里。这个真的不是废话我见过太多人把真实Key写到配置文件然后误推到代码仓库被爬虫扒下来狂刷额度。Key的格式是sk-开头的一长串字符拿到的第一时间就放进环境变量。3. 三步跑通通义千问拿Key、写配置、发消息3.1 第一步在百炼平台拿API Key先打开阿里云百炼控制台开通DashScope模型服务之后在API-KEY管理页面创建一个Key。OpenAI兼容模式不用单独开默认就支持。拿到Key之后放到环境变量export DASHSCOPE_API_KEYsk-xxxx如果用的是IDEA在Run Configuration里配上环境变量即可。这个Key只在本机有效不要在代码里留任何真实Key的痕迹。3.2 第二步写好application.yml配置在上一章已经给过这里补充几个关键参数的含义model决定走哪个模型。qwen-plus是通用默认qwen-turbo轻量快速qwen-max旗舰复杂任务。temperature控制随机性取值0到2之间。对话场景0.7是常见起点代码生成建议0.2需要稳定确定性输出的场景调更低。通义千问的嵌入模型embedding也会被自动配置如果只做聊天理论上可以排除但实际影响不大不用管。3.3 第三步用ChatClient发第一条消息Controller层代码非常简洁RestController RequestMapping(/api/ai) public class AiController { private final ChatClient chatClient; public AiController(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder.build(); } GetMapping(/chat) public MapString, String chat(RequestParam(msg) String msg) { String reply chatClient.prompt(msg).call().content(); return Map.of(reply, reply); } }chatClient.prompt(msg).call().content()这行就完成了整个调用。prompt()传入用户消息call()发起同步请求content()把响应文本取出来。如果要带系统提示词写法也不复杂String reply chatClient.prompt() .system(你是一个严谨的Java技术顾问回答尽量简洁必要时给出代码示例) .user(msg) .call() .content();启动项目后浏览器直接访问http://localhost:8080/api/ai/chat?msg用一句话介绍Spring AI能正常返回中文回答说明接入成功了。这一步走通Spring AI 通义千问的最小闭环就建立了。如果要做打字机效果的流式输出用stream()方法GetMapping(value /chat/stream, produces text/event-stream;charsetUTF-8) public FluxString chatStream(RequestParam(msg) String msg) { return chatClient.prompt(msg).stream().content(); }前提是项目里引入了WebFlux依赖返回值类型必须是FluxString别在纯MVC项目里硬写这个方法否则返回类型不受支持。4. 多模型切换的三种落地姿势4.1 姿势一配置文件直接切换最简单的方式改配置文件里的model字段重启生效spring: ai: dashscope: chat: options: model: qwen-max如果你接了Nacos这类配置中心把这段配置放到配置中心里改配置可以不重启服务就热生效。这种方式最适合快速验证模型差异同一个问题分别用qwen-turbo、qwen-plus、qwen-max跑一遍看效果再定方案。缺点是路由粒度很粗所有请求都走同一个模型没法按业务场景区分。4.2 姿势二多Bean 业务路由生产环境最常见的需求是普通问答走qwen-turbo省钱复杂任务走qwen-plus深度分析走qwen-max。这时需要在Spring容器里注册多个ChatClient Bean每个对应不同模型Configuration public class MultiModelConfig { Bean(qwenTurboClient) public ChatClient qwenTurboClient(DashScopeApi dashScopeApi) { DashScopeChatOptions options DashScopeChatOptions.builder() .withModel(qwen-turbo) .build(); ChatModel model new DashScopeChatModel(dashScopeApi, options); return ChatClient.builder(model).build(); } Bean(qwenPlusClient) Primary public ChatClient qwenPlusClient(DashScopeApi dashScopeApi) { DashScopeChatOptions options DashScopeChatOptions.builder() .withModel(qwen-plus) .build(); ChatModel model new DashScopeChatModel(dashScopeApi, options); return ChatClient.builder(model).build(); } Bean(qwenMaxClient) public ChatClient qwenMaxClient(DashScopeApi dashScopeApi) { DashScopeChatOptions options DashScopeChatOptions.builder() .withModel(qwen-max) .build(); ChatModel model new DashScopeChatModel(dashScopeApi, options); return ChatClient.builder(model).build(); } }我把实现类DashScopeChatModel显式写出来是为了让每个Client对应哪个模型一眼清楚。你的Spring AI版本如果API有细微差异以本地引入jar包的源码为准有的版本方法名差个前缀整体思路不变。然后写一个路由Service按业务维度选择模型Service public class ModelRouter { private final ChatClient turboClient; private final ChatClient plusClient; private final ChatClient maxClient; public ModelRouter( Qualifier(qwenTurboClient) ChatClient turboClient, Qualifier(qwenPlusClient) ChatClient plusClient, Qualifier(qwenMaxClient) ChatClient maxClient) { this.turboClient turboClient; this.plusClient plusClient; this.maxClient maxClient; } public String chatByLevel(String userLevel, String msg) { ChatClient target switch (userLevel) { case vip - maxClient; default - plusClient; }; return target.prompt(msg).call().content(); } }这种姿势的核心价值是逻辑清晰谁走哪个模型一眼可读代码也好维护。切换模型只需要改路由规则的判断条件不改配置不动模型Bean。4.3 姿势三运行时动态切换更进阶的需求是模型选择本身是运行时参数。比如API网关让调用方自己传model参数或者根据当前请求的复杂程度自动判断是否升级模型。这时候可以维护一个模型名到ChatClient的映射Component public class ChatClientRegistry { private final MapString, ChatClient clientMap new ConcurrentHashMap(); public ChatClientRegistry(ListChatClient chatClients, Qualifier(qwenTurboClient) ChatClient turbo, Qualifier(qwenPlusClient) ChatClient plus, Qualifier(qwenMaxClient) ChatClient max) { clientMap.put(turbo, turbo); clientMap.put(plus, plus); clientMap.put(max, max); } public ChatClient get(String model) { ChatClient client clientMap.get(model); if (client null) { throw new IllegalArgumentException(未注册的模型: model); } return client; } }结合Qualifier和Bean命名把turbo、plus、max分别注册进去之后路由逻辑就可以完全动态化了。我在实际项目里加了一个简单策略请求里带model参数就走对应模型不带就走默认plus。这个方案灵活性最高适合SaaS平台、AI网关、面向C端用户的AI应用。三种方案怎么选参考这个对比| 方案 | 切换粒度 | 改动成本 | 适用场景 | | 配置文件切换 | 全局 | 最低 | 快速验证、配置中心热更新 | | 多Bean路由 | 业务维度 | 中 | 按用户等级、任务复杂度分流 | | 运行时动态 | 请求维度 | 中高 | 用户自选模型、按成本动态调度 |5. 完整可运行代码一个可切换的接入Demo5.1 工程结构一览给出一份可以直接跑的Demo工程目录结构如下spring-ai-qwen-demo/ ├── pom.xml └── src/main/ ├── java/com/example/qwen/ │ ├── QwenDemoApplication.java │ ├── config/ │ │ └── MultiModelConfig.java │ ├── router/ │ │ ├── ChatClientRegistry.java │ │ └── ModelRouter.java │ └── web/ │ └── AiController.java └── resources/ └── application.yml5.2 核心代码实现启动类就是一个普通Spring Boot应用SpringBootApplication public class QwenDemoApplication { public static void main(String[] args) { SpringApplication.run(QwenDemoApplication.class, args); } }MultiModelConfig注册三个ChatClient对应三个模型。为了简洁我这里用ChatClientRegistry做动态路由同时保留ModelRouter演示业务路由。Controller层接收model参数和消息内容交给动态路由RestController RequestMapping(/api/ai) public class AiController { private final ChatClientRegistry registry; public AiController(ChatClientRegistry registry) { this.registry registry; } GetMapping(/chat) public MapString, String chat( RequestParam(value model, defaultValue plus) String model, RequestParam(msg) String msg) { ChatClient target registry.get(model); return Map.of( model, model, reply, target.prompt(msg).call().content() ); } }路由注册那里ChatClientRegistry构造方法里我用了参数注入三个Client你也可以改成ListChatClient配合自定义标记遍历注册。前者直白后者灵活根据项目规模选择。5.3 测试与验证方法启动后用curl分别验证三种模型curl http://localhost:8080/api/ai/chat?modelturbomsg你好 curl http://localhost:8080/api/ai/chat?modelplusmsg你好 curl http://localhost:8080/api/ai/chat?modelmaxmsg你好每个请求返回的model字段会告诉你当前走的是哪个模型。要想明显看到模型差异可以问一个需要推理的问题比如问一根绳子绕地球一圈如果加长10米绳子离地面的平均高度大概是多少max模型给的推理过程会完整很多。也可以直接观察请求耗时qwen-turbo明显比qwen-max快。6. 避坑指南从配置到上线的实战教训6.1 版本搭配错误的典型症状我踩过最狠的坑是把spring-ai-bom引入到一个Spring Boot 3.2.x的旧项目里。启动直接报APPLICATION FAILED TO START Parameter 0 of method qwenChatModel in ... required a bean of type ... that could not be found.这种Bean not found的错误第一反应基本都会去查Bean定义结果搞半天才发现是版本不匹配。Spring AI 2.x对Spring Boot版本是有要求的建议直接用最新的Spring Boot 3.4.x别为了兼容老项目硬上不然你会遇到一堆莫名其妙的类加载问题。另外网上大量教程停留在Spring AI 1.0的API那时是chatModel.call(new Prompt(...))1.0.0 GA之后逐步引入ChatClient2.0的API更顺手但代码长得和旧教程不一样。搜资料时认准Spring AI 2.0字样遇到旧代码注意区分。6.2 模型名称和选型别想当然百炼控制台显示的模型名qwen-plus、qwen-max等要和配置里完全一致一个字符都不能差。我见过把qwen-max的横杠写成下划线的调用直接报模型不存在。模型选型上给个参考| 模型 | 适合场景 | 速度 | 价格档位 | | qwen-turbo | 简单问答、高并发分类、文本改写 | 最快 | 低 | | qwen-plus | 通用客服、内容生成、中等复杂度任务 | 快 | 中 | | qwen-max | 复杂推理、长文档、代码审查 | 较慢 | 高 |还有一个容易被忽略的点超长输入要留意上下文窗口限制。一次对话如果塞进很长的文档会报ContextLengthExceed需要提前对输入做截断或摘要。qwen-plus和qwen-max的上下文比turbo长但都不是无限。6.3 超时配置影响真实体感Spring AI调用DashScope默认用的是RestClient。在公司网络环境或者首次请求冷启动时特别容易因为握手慢而超时。我习惯把连接超时和读取超时调大连接5秒、读取120秒——大模型生成本来就慢读取超时设太短会误伤正常请求。配置方式可以通过自定义RestClient.Builder实现或者准备一个独立的OkHttpClient替换默认客户端。这里不展开网络细节但请记住超时时间直接决定用户体感设置不到位模型调用稍慢一点就报超时接口层面看起来就是系统不稳定。6.4 流式输出的坑流式输出我在前面给了代码但必须再提醒一次在Spring MVC项目中GetMapping返回FluxString需要引入spring-boot-starter-webflux否则返回类型不受支持。如果你的项目是Spring MVC WebFlux共存还要注意包扫描和依赖冲突的问题。AI应用的实时对话体验确实值得上流式但请先在WebFlux环境下把SSE测通再往业务里接。6.5 spring-ai-alibaba和spring-ai-starter-model-qwen别装混很多人搜spring ai alibaba停更了吗这里统一回答阿里社区维护的spring-ai-alibaba和Spring官方出的spring-ai-starter-model-qwen是两个东西。前者是结合Spring Cloud Alibaba的AI组件演进节奏看社区后者是Spring官方支持的DashScope/通义千问接入Starter跟着Spring AI主线版本持续迭代Spring AI 2.0.1还是有活跃发版的。要是为了在Spring Boot项目里接通义千问直接用spring-ai-starter-model-qwen。要是用了Spring Cloud Alibaba全家桶并且想要更整合的AI能力再去看spring-ai-alibaba。二者不是替代关系但不要装错依赖否则可能出现配置属性冲突、Bean重复注册等怪问题。实际做下来Spring AI 通义千问这套组合最大的价值不是省掉那几行SDK调用代码而是让模型变成了一个可配置、可路由的服务。以后无论你想接入一个开源模型还是换掉某个供应商业务层代码基本不用动只是新增一个Bean和一行配置的事。最后再分享一个小技巧在开发环境你完全可以用同一套接入结构同时对接通义千问和本地Ollama——比如qwen系列的开源版本一套代码线上走百炼、本地调试走免费模型开发成本直接降下来。我在把demo工程落地到自己的项目后最深的感受是技术选型时花点时间把抽象层做好后面每一次模型切换都会轻松很多。希望这份带完整代码的踩坑总结能让你直接把通义千问跑起来少走我走过的弯路。