1. Spring AI 多模型集成到底难在哪一套代码切换 OpenAI/DeepSeek/通义千问/智谱的配置管理痛点Spring AI 是 Spring 官方推出的 AI 应用开发框架它把不同厂商的大模型抽象成统一接口让 Java 开发者可以用ChatModel.call(Prompt)这样的标准写法调用任意模型。但真正落到项目里你会发现能调通一个模型和一套代码随时切换四家模型之间隔着一道配置管理的鸿沟。我见过太多 Spring Boot 项目是这么写的application.yml里写死一个spring.ai.openai.api-key代码里new OpenAiChatModel(...)直接实例化。业务方今天说要用 DeepSeek 省钱明天说通义千问的中文效果好后天又要求智谱做私有化——每次换模型都是一次改代码、改配置、重新打包发版的完整流程。更麻烦的是多环境开发用 OpenAI、测试用 DeepSeek、生产用通义三套配置散落在不同 profile 里稍不留神就把生产 Key 提交到了 Git。核心痛点可以归纳成四条。第一SDK 差异被硬编码OpenAI 用OpenAiApiDeepSeek 虽然兼容 OpenAI 协议但 Base URL 不同通义千问走 DashScope 的dashscope.api-key智谱又是另一套zhipuai.api-key每家的 Starter 配置项名字都不一样。第二Key 和参数写死在配置文件想给不同租户分配不同的 Key或者运营想临时调一下 temperature都得重启服务。第三换模型要发版模型标识gpt-4o、deepseek-chat、qwen-max、glm-4散落在代码各处改一个要全局搜索替换。第四Base URL 管理混乱直连各家官方地址时网络策略、额度管理、密钥轮换都是分散的没有一个统一的出口。这篇文章要解决的问题很具体如何用 Spring AI 写一套代码通过统一的 Base URL 和 Key 接入 OpenAI、DeepSeek、通义千问、智谱做到零改动切换模型。我会给出可复制的application.yml多模型配置片段、统一注入方式以及通过 TaoToken 统一 Key/API 通道完成一次请求验证的完整步骤。适合正在做企业级 AI 集成、被多模型配置折磨的 Java 开发者。先说结论Spring AI 本身已经提供了很好的抽象层缺的是配置归一化这一环。把 Base URL 和 Key 收敛到一个统一入口再配合 Spring AI 的多模型 Bean 注册机制就能实现改一行配置换一家模型。下面从环境准备讲起。2. TaoToken 统一 Key 接入前置准备Base URL 与 API Key 的获取方式在动手改application.yml之前先把统一入口这件事说清楚。Spring AI 默认的 OpenAI Starter 允许你自定义base-url这意味着只要有一家服务商同时兼容 OpenAI 的/v1/chat/completions协议就能用同一套OpenAiApi代码去调用不同厂商的模型。TaoToken 提供的正是这样一个统一通道一个 Base URL、一把 Key背后可以路由到 OpenAI、DeepSeek、通义千问、智谱等多个模型。你需要准备的东西只有两样API Key和Base URL。访问 https://taotoken.net/api 可以查看接口说明Key 的获取在控制台完成。登录后进入 API Keys 页面创建一个新 Key复制保存——它只会完整显示一次。Base URL 统一使用https://taotoken.net/api注意末尾不要带/v1Spring AI 的 OpenAI Starter 会自动拼接/v1/chat/completions路径。这里有个容易踩的坑很多人习惯把 Base URL 写成https://taotoken.net/api/v1结果请求变成了/api/v1/v1/chat/completions直接 404。记住 Spring AI 的OpenAiApi内部已经处理了版本路径你只需要给到域名加/api这一层。关于模型标识统一通道下你仍然使用各家原生的模型名。比如 OpenAI 用gpt-4o-miniDeepSeek 用deepseek-chat通义千问用qwen-max智谱用glm-4-plus。这些模型名通过请求体里的model字段传递Spring AI 的OpenAiChatOptions支持动态设置所以同一套代码可以传不同的模型名。环境准备清单JDK 17 或以上Spring AI 要求、Spring Boot 3.2、Maven 或 Gradle、一个可用的 TaoToken API Key。如果你还没装 Spring Boot 项目可以用 Spring Initializr 生成一个依赖勾选 Spring Web 和 Spring AI 的 OpenAI Starter。Maven 坐标是org.springframework.ai:spring-ai-openai-spring-boot-starter版本建议用 1.0.0 或以上。注意Spring AI 的版本迭代较快1.0.0-M 系列和正式版在配置项命名上有差异。本文以 1.0.0 正式版的spring.ai.openai.*配置前缀为准。如果你用的是里程碑版本配置项可能是spring.ai.openai.chat.options.model这种更细的层级对照官方文档调整即可。拿到 Key 之后先别急着写代码。用 curl 验证一下通道是否通畅这一步能帮你排除掉 90% 的环境问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好请回复OK}], max_tokens: 20 }如果返回的 JSON 里有choices[0].message.content说明 Key 和 Base URL 都没问题。这一步跑通后再进 Spring AI能省掉大量排查时间。接下来进入配置环节。3. 可复制的 application.yml 多模型配置统一 Base URL 与 Key 注入这一节是全文的核心直接给你可以复制粘贴的配置。Spring AI 的 OpenAI Starter 支持通过spring.ai.openai前缀配置 Base URL、API Key 和默认模型参数。我们要做的是把这三样东西从写死一家改成可切换。先看基础配置结构。在application.yml里这样写spring: ai: openai: # 统一 Base URL指向 TaoToken 通道 base-url: https://taotoken.net/api # 统一 API Key从环境变量注入避免硬编码 api-key: ${TAOTOKEN_API_KEY} chat: options: # 默认模型可被代码动态覆盖 model: deepseek-chat temperature: 0.7 max-tokens: 2048这里的关键点是base-url和api-key都指向统一通道而model只是一个默认值。真正的多模型切换发生在代码层——通过OpenAiChatOptions动态设置模型名。这样application.yml里不需要为每家模型写一段配置避免了配置膨胀。但如果你希望不同环境用不同模型可以用 Spring 的 profile 机制。比如application-dev.yml里默认用gpt-4o-miniapplication-prod.yml里默认用qwen-max# application-dev.yml spring: ai: openai: chat: options: model: gpt-4o-mini temperature: 0.9 # application-prod.yml spring: ai: openai: chat: options: model: qwen-max temperature: 0.3API Key 强烈建议用环境变量注入不要写进配置文件。在 IDEA 里可以配置 Run Configuration 的 Environment variables在服务器上用export TAOTOKEN_API_KEYsk-xxx或者 Docker 的-e参数。这样 Key 不会进 Git 仓库轮换时也不用改代码。如果你用的是application.properties格式等价写法是spring.ai.openai.base-urlhttps://taotoken.net/api spring.ai.openai.api-key${TAOTOKEN_API_KEY} spring.ai.openai.chat.options.modeldeepseek-chat spring.ai.openai.chat.options.temperature0.7现在讲多模型 Bean 的注册方式。Spring AI 的自动配置会创建一个默认的OpenAiChatModelBean但如果你想要多个模型实例并存比如一个用于对话、一个用于代码生成可以手动声明Configuration public class MultiModelConfig { Bean(chatModel) public OpenAiChatModel chatModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .defaultOptions(OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.7) .build()) .build(); } Bean(codeModel) public OpenAiChatModel codeModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .defaultOptions(OpenAiChatOptions.builder() .model(gpt-4o) .temperature(0.2) .build()) .build(); } }注意这里两个 Bean 共用同一个OpenAiApi实例也就是共用同一个 Base URL 和 Key区别只在defaultOptions里的模型名和参数。这就是一套代码多模型的精髓连接层统一模型层分离。如果你需要更灵活的运行时切换可以不注册多个 Bean而是在调用时动态构造OpenAiChatOptionspublic String chat(String modelName, String userInput) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(modelName) // 运行时传入deepseek-chat / qwen-max / glm-4-plus .temperature(0.7) .build(); Prompt prompt new Prompt(userInput, options); return chatModel.call(prompt).getResult().getOutput().getText(); }这样modelName可以来自数据库配置、请求参数或者配置中心真正做到改配置换模型代码零改动。下一节我们验证这套配置能不能跑通。4. 验证请求与成功结果一次调用跑通四家模型的完整步骤配置写好了现在写一个 Controller 来验证。目标是同一个接口传入不同的模型名分别调用 OpenAI、DeepSeek、通义千问、智谱都能返回正常结果。先写一个简单的 ServiceService public class MultiModelService { private final OpenAiChatModel chatModel; public MultiModelService(OpenAiChatModel chatModel) { this.chatModel chatModel; } public String ask(String modelName, String question) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(modelName) .temperature(0.7) .maxTokens(500) .build(); Prompt prompt new Prompt(question, options); ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getText(); } }再写 ControllerRestController RequestMapping(/api/ai) public class AiController { private final MultiModelService multiModelService; public AiController(MultiModelService multiModelService) { this.multiModelService multiModelService; } GetMapping(/chat) public MapString, String chat(RequestParam String model, RequestParam String q) { String answer multiModelService.ask(model, q); MapString, String result new HashMap(); result.put(model, model); result.put(answer, answer); return result; } }启动项目然后依次用 curl 测试四家模型。先测 DeepSeekcurl http://localhost:8080/api/ai/chat?modeldeepseek-chatq用一句话介绍Spring%20AI预期返回类似{ model: deepseek-chat, answer: Spring AI 是 Spring 官方推出的 AI 应用开发框架用于在 Spring Boot 应用中统一调用各家大模型。 }再测通义千问只改model参数curl http://localhost:8080/api/ai/chat?modelqwen-maxq用一句话介绍Spring%20AI然后测智谱curl http://localhost:8080/api/ai/chat?modelglm-4-plusq用一句话介绍Spring%20AI最后测 OpenAIcurl http://localhost:8080/api/ai/chat?modelgpt-4o-miniq用一句话介绍Spring%20AI四次请求代码一行没改只换了 URL 里的model参数。这就是统一 Base URL 统一 Key 带来的效果。如果某一家返回 404 或者模型不存在通常是模型名写错了——比如智谱的模型名是glm-4-plus而不是glm4通义是qwen-max而不是qwen_max。对照各家官方文档的模型列表核对即可。流式输出也是同理。Spring AI 的stream()方法返回FluxChatResponse配合 SSE 推给前端GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String model, RequestParam String q) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(model) .temperature(0.7) .build(); Prompt prompt new Prompt(q, options); return chatModel.stream(prompt) .map(chunk - chunk.getResult().getOutput().getText()) .filter(Objects::nonNull); }用浏览器或者 curl 访问这个接口能看到逐字返回的效果。无论背后是 DeepSeek 还是通义流式写法完全一致。到这里核心功能已经验证完毕。接下来处理实际开发中会遇到的报错。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 报错对照多模型集成最容易在鉴权和网络层翻车。下面按真实报错逐个拆解。401 Unauthorized / invalid_api_key。这是最常见的错误原因通常是 Key 没注入成功或者格式不对。先检查环境变量是否生效在代码里打印System.getenv(TAOTOKEN_API_KEY)看是否为 null。如果用的是 IDEA确认 Run Configuration 里配了环境变量如果用的是 Docker确认-e TAOTOKEN_API_KEYxxx传进去了。另一个常见原因是 Key 前面多了Bearer前缀——Spring AI 会自动加你只需要传裸 Key。还有一种情况是 Key 被禁用或额度耗尽去控制台确认状态。local proxy failed / connection refused。这个报错说明请求根本没发出去通常是 Base URL 写错了或者本地网络策略拦截。检查spring.ai.openai.base-url是否写成了https://taotoken.net/api不要带/v1不要带末尾斜杠。如果你在公司内网确认出口策略允许访问该域名。这个报错和 Key 无关纯粹是网络层问题。Error reading choices / Cannot deserialize value of typejava.util.List。这个报错说明请求发出去了但返回的 JSON 结构不符合 Spring AI 的预期。常见原因是 Base URL 多了一层或少了/v1导致请求打到了错误的端点返回了 HTML 错误页而不是 JSON。另一个原因是模型名不存在服务端返回了错误结构。先用第 2 节的 curl 命令验证通道确认返回的是标准 OpenAI 格式的 JSON。OAuth / token expired。如果你用的是 Azure OpenAI 或者某些需要 OAuth 的平台会看到这类报错。统一通道下用 API Key 鉴权不会遇到 OAuth 问题。如果确实需要 OAuth检查 token 是否过期、scope 是否正确。Spring AI 的OpenAiApi默认用 Bearer Token不涉及 OAuth 流程。模型返回空内容 / content 为 null。检查max-tokens是否设得太小有些模型在 token 耗尽时会返回空。另外确认temperature没有设成极端值。如果用的是推理模型如deepseek-reasoner内容可能在reasoning_content字段而不是content需要单独处理。连接超时 / read timeout。大模型响应慢是常态尤其是长文本生成。Spring AI 默认的超时可能不够可以在配置里调整spring: ai: openai: chat: options: model: deepseek-chat # 超时配置 base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY}如果 Starter 不直接暴露超时配置可以通过自定义RestClient.Builder或WebClient.Builder来设置。另一个办法是在OpenAiApi构建时传入自定义的RestClient。排查顺序建议先 curl 验证通道 → 再检查环境变量 → 再看 Base URL 格式 → 最后看模型名。90% 的问题在前两步就能定位。如果还是不通把完整报错和请求的 URL 贴出来对照上面几类逐一排除。6. 从统一 Key 到长期编码Spring AI 多模型集成的落地建议跑通验证之后聊聊怎么把这套方案用到真实项目里。统一 Key 接入的价值不只是少配几个 Key而是把模型切换从工程问题变成了配置问题。第一把模型名外置到配置中心或数据库。上面例子里model是请求参数生产环境更常见的做法是存在数据库的ai_model表里运营在后台改一行数据就能切换模型。Spring AI 的OpenAiChatOptions支持运行时构造所以从数据库读模型名完全可行。这样业务方说换成 DeepSeek你只需要改一条记录不用发版。第二按场景分配模型。对话用qwen-max中文好代码生成用gpt-4o逻辑强成本敏感的批量任务用deepseek-chat便宜私有化场景用本地 Ollama。这些都可以通过不同的OpenAiChatOptions实现共用同一个OpenAiApi连接。第三做好降级和重试。统一通道下如果某个模型不可用可以在代码里捕获异常后切换到备用模型。Spring AI 本身不提供自动降级需要自己封装一层。建议给每个场景配一个主模型和一个备用模型主模型失败时自动切备用。第四Key 轮换和额度监控。统一 Key 的好处是只需要在一个地方轮换但也要注意单点风险。建议定期在控制台查看用量设置额度告警。如果团队规模大可以按项目分配不同的 Key便于计费隔离。如果你正在做长期的 AI 编码或 Agent 项目可以考虑 Coding Plan 这类方案把模型调用和编码工作流结合起来。对于需要频繁验证模型效果的场景模型对话页面可以快速对比不同模型的输出。接入文档里有更详细的参数说明和示例代码。最后说一个实际经验多模型集成最容易出问题的地方不是代码而是模型名的维护。各家模型迭代快gpt-4o可能下架qwen-max可能升级到新版本。建议在数据库里维护一份模型清单定期核对官方文档避免线上突然报模型不存在。这套统一连接 动态模型的架构本质上和支付渠道、短信通道的多厂商接入是同一个思路——连接层收敛业务层灵活。
Spring AI 多模型集成实战：OpenAI/DeepSeek/通义千问/智谱一套代码全搞定，TaoToken 统一 Key 接入
1. Spring AI 多模型集成到底难在哪一套代码切换 OpenAI/DeepSeek/通义千问/智谱的配置管理痛点Spring AI 是 Spring 官方推出的 AI 应用开发框架它把不同厂商的大模型抽象成统一接口让 Java 开发者可以用ChatModel.call(Prompt)这样的标准写法调用任意模型。但真正落到项目里你会发现能调通一个模型和一套代码随时切换四家模型之间隔着一道配置管理的鸿沟。我见过太多 Spring Boot 项目是这么写的application.yml里写死一个spring.ai.openai.api-key代码里new OpenAiChatModel(...)直接实例化。业务方今天说要用 DeepSeek 省钱明天说通义千问的中文效果好后天又要求智谱做私有化——每次换模型都是一次改代码、改配置、重新打包发版的完整流程。更麻烦的是多环境开发用 OpenAI、测试用 DeepSeek、生产用通义三套配置散落在不同 profile 里稍不留神就把生产 Key 提交到了 Git。核心痛点可以归纳成四条。第一SDK 差异被硬编码OpenAI 用OpenAiApiDeepSeek 虽然兼容 OpenAI 协议但 Base URL 不同通义千问走 DashScope 的dashscope.api-key智谱又是另一套zhipuai.api-key每家的 Starter 配置项名字都不一样。第二Key 和参数写死在配置文件想给不同租户分配不同的 Key或者运营想临时调一下 temperature都得重启服务。第三换模型要发版模型标识gpt-4o、deepseek-chat、qwen-max、glm-4散落在代码各处改一个要全局搜索替换。第四Base URL 管理混乱直连各家官方地址时网络策略、额度管理、密钥轮换都是分散的没有一个统一的出口。这篇文章要解决的问题很具体如何用 Spring AI 写一套代码通过统一的 Base URL 和 Key 接入 OpenAI、DeepSeek、通义千问、智谱做到零改动切换模型。我会给出可复制的application.yml多模型配置片段、统一注入方式以及通过 TaoToken 统一 Key/API 通道完成一次请求验证的完整步骤。适合正在做企业级 AI 集成、被多模型配置折磨的 Java 开发者。先说结论Spring AI 本身已经提供了很好的抽象层缺的是配置归一化这一环。把 Base URL 和 Key 收敛到一个统一入口再配合 Spring AI 的多模型 Bean 注册机制就能实现改一行配置换一家模型。下面从环境准备讲起。2. TaoToken 统一 Key 接入前置准备Base URL 与 API Key 的获取方式在动手改application.yml之前先把统一入口这件事说清楚。Spring AI 默认的 OpenAI Starter 允许你自定义base-url这意味着只要有一家服务商同时兼容 OpenAI 的/v1/chat/completions协议就能用同一套OpenAiApi代码去调用不同厂商的模型。TaoToken 提供的正是这样一个统一通道一个 Base URL、一把 Key背后可以路由到 OpenAI、DeepSeek、通义千问、智谱等多个模型。你需要准备的东西只有两样API Key和Base URL。访问 https://taotoken.net/api 可以查看接口说明Key 的获取在控制台完成。登录后进入 API Keys 页面创建一个新 Key复制保存——它只会完整显示一次。Base URL 统一使用https://taotoken.net/api注意末尾不要带/v1Spring AI 的 OpenAI Starter 会自动拼接/v1/chat/completions路径。这里有个容易踩的坑很多人习惯把 Base URL 写成https://taotoken.net/api/v1结果请求变成了/api/v1/v1/chat/completions直接 404。记住 Spring AI 的OpenAiApi内部已经处理了版本路径你只需要给到域名加/api这一层。关于模型标识统一通道下你仍然使用各家原生的模型名。比如 OpenAI 用gpt-4o-miniDeepSeek 用deepseek-chat通义千问用qwen-max智谱用glm-4-plus。这些模型名通过请求体里的model字段传递Spring AI 的OpenAiChatOptions支持动态设置所以同一套代码可以传不同的模型名。环境准备清单JDK 17 或以上Spring AI 要求、Spring Boot 3.2、Maven 或 Gradle、一个可用的 TaoToken API Key。如果你还没装 Spring Boot 项目可以用 Spring Initializr 生成一个依赖勾选 Spring Web 和 Spring AI 的 OpenAI Starter。Maven 坐标是org.springframework.ai:spring-ai-openai-spring-boot-starter版本建议用 1.0.0 或以上。注意Spring AI 的版本迭代较快1.0.0-M 系列和正式版在配置项命名上有差异。本文以 1.0.0 正式版的spring.ai.openai.*配置前缀为准。如果你用的是里程碑版本配置项可能是spring.ai.openai.chat.options.model这种更细的层级对照官方文档调整即可。拿到 Key 之后先别急着写代码。用 curl 验证一下通道是否通畅这一步能帮你排除掉 90% 的环境问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好请回复OK}], max_tokens: 20 }如果返回的 JSON 里有choices[0].message.content说明 Key 和 Base URL 都没问题。这一步跑通后再进 Spring AI能省掉大量排查时间。接下来进入配置环节。3. 可复制的 application.yml 多模型配置统一 Base URL 与 Key 注入这一节是全文的核心直接给你可以复制粘贴的配置。Spring AI 的 OpenAI Starter 支持通过spring.ai.openai前缀配置 Base URL、API Key 和默认模型参数。我们要做的是把这三样东西从写死一家改成可切换。先看基础配置结构。在application.yml里这样写spring: ai: openai: # 统一 Base URL指向 TaoToken 通道 base-url: https://taotoken.net/api # 统一 API Key从环境变量注入避免硬编码 api-key: ${TAOTOKEN_API_KEY} chat: options: # 默认模型可被代码动态覆盖 model: deepseek-chat temperature: 0.7 max-tokens: 2048这里的关键点是base-url和api-key都指向统一通道而model只是一个默认值。真正的多模型切换发生在代码层——通过OpenAiChatOptions动态设置模型名。这样application.yml里不需要为每家模型写一段配置避免了配置膨胀。但如果你希望不同环境用不同模型可以用 Spring 的 profile 机制。比如application-dev.yml里默认用gpt-4o-miniapplication-prod.yml里默认用qwen-max# application-dev.yml spring: ai: openai: chat: options: model: gpt-4o-mini temperature: 0.9 # application-prod.yml spring: ai: openai: chat: options: model: qwen-max temperature: 0.3API Key 强烈建议用环境变量注入不要写进配置文件。在 IDEA 里可以配置 Run Configuration 的 Environment variables在服务器上用export TAOTOKEN_API_KEYsk-xxx或者 Docker 的-e参数。这样 Key 不会进 Git 仓库轮换时也不用改代码。如果你用的是application.properties格式等价写法是spring.ai.openai.base-urlhttps://taotoken.net/api spring.ai.openai.api-key${TAOTOKEN_API_KEY} spring.ai.openai.chat.options.modeldeepseek-chat spring.ai.openai.chat.options.temperature0.7现在讲多模型 Bean 的注册方式。Spring AI 的自动配置会创建一个默认的OpenAiChatModelBean但如果你想要多个模型实例并存比如一个用于对话、一个用于代码生成可以手动声明Configuration public class MultiModelConfig { Bean(chatModel) public OpenAiChatModel chatModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .defaultOptions(OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.7) .build()) .build(); } Bean(codeModel) public OpenAiChatModel codeModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .defaultOptions(OpenAiChatOptions.builder() .model(gpt-4o) .temperature(0.2) .build()) .build(); } }注意这里两个 Bean 共用同一个OpenAiApi实例也就是共用同一个 Base URL 和 Key区别只在defaultOptions里的模型名和参数。这就是一套代码多模型的精髓连接层统一模型层分离。如果你需要更灵活的运行时切换可以不注册多个 Bean而是在调用时动态构造OpenAiChatOptionspublic String chat(String modelName, String userInput) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(modelName) // 运行时传入deepseek-chat / qwen-max / glm-4-plus .temperature(0.7) .build(); Prompt prompt new Prompt(userInput, options); return chatModel.call(prompt).getResult().getOutput().getText(); }这样modelName可以来自数据库配置、请求参数或者配置中心真正做到改配置换模型代码零改动。下一节我们验证这套配置能不能跑通。4. 验证请求与成功结果一次调用跑通四家模型的完整步骤配置写好了现在写一个 Controller 来验证。目标是同一个接口传入不同的模型名分别调用 OpenAI、DeepSeek、通义千问、智谱都能返回正常结果。先写一个简单的 ServiceService public class MultiModelService { private final OpenAiChatModel chatModel; public MultiModelService(OpenAiChatModel chatModel) { this.chatModel chatModel; } public String ask(String modelName, String question) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(modelName) .temperature(0.7) .maxTokens(500) .build(); Prompt prompt new Prompt(question, options); ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getText(); } }再写 ControllerRestController RequestMapping(/api/ai) public class AiController { private final MultiModelService multiModelService; public AiController(MultiModelService multiModelService) { this.multiModelService multiModelService; } GetMapping(/chat) public MapString, String chat(RequestParam String model, RequestParam String q) { String answer multiModelService.ask(model, q); MapString, String result new HashMap(); result.put(model, model); result.put(answer, answer); return result; } }启动项目然后依次用 curl 测试四家模型。先测 DeepSeekcurl http://localhost:8080/api/ai/chat?modeldeepseek-chatq用一句话介绍Spring%20AI预期返回类似{ model: deepseek-chat, answer: Spring AI 是 Spring 官方推出的 AI 应用开发框架用于在 Spring Boot 应用中统一调用各家大模型。 }再测通义千问只改model参数curl http://localhost:8080/api/ai/chat?modelqwen-maxq用一句话介绍Spring%20AI然后测智谱curl http://localhost:8080/api/ai/chat?modelglm-4-plusq用一句话介绍Spring%20AI最后测 OpenAIcurl http://localhost:8080/api/ai/chat?modelgpt-4o-miniq用一句话介绍Spring%20AI四次请求代码一行没改只换了 URL 里的model参数。这就是统一 Base URL 统一 Key 带来的效果。如果某一家返回 404 或者模型不存在通常是模型名写错了——比如智谱的模型名是glm-4-plus而不是glm4通义是qwen-max而不是qwen_max。对照各家官方文档的模型列表核对即可。流式输出也是同理。Spring AI 的stream()方法返回FluxChatResponse配合 SSE 推给前端GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(RequestParam String model, RequestParam String q) { OpenAiChatOptions options OpenAiChatOptions.builder() .model(model) .temperature(0.7) .build(); Prompt prompt new Prompt(q, options); return chatModel.stream(prompt) .map(chunk - chunk.getResult().getOutput().getText()) .filter(Objects::nonNull); }用浏览器或者 curl 访问这个接口能看到逐字返回的效果。无论背后是 DeepSeek 还是通义流式写法完全一致。到这里核心功能已经验证完毕。接下来处理实际开发中会遇到的报错。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 报错对照多模型集成最容易在鉴权和网络层翻车。下面按真实报错逐个拆解。401 Unauthorized / invalid_api_key。这是最常见的错误原因通常是 Key 没注入成功或者格式不对。先检查环境变量是否生效在代码里打印System.getenv(TAOTOKEN_API_KEY)看是否为 null。如果用的是 IDEA确认 Run Configuration 里配了环境变量如果用的是 Docker确认-e TAOTOKEN_API_KEYxxx传进去了。另一个常见原因是 Key 前面多了Bearer前缀——Spring AI 会自动加你只需要传裸 Key。还有一种情况是 Key 被禁用或额度耗尽去控制台确认状态。local proxy failed / connection refused。这个报错说明请求根本没发出去通常是 Base URL 写错了或者本地网络策略拦截。检查spring.ai.openai.base-url是否写成了https://taotoken.net/api不要带/v1不要带末尾斜杠。如果你在公司内网确认出口策略允许访问该域名。这个报错和 Key 无关纯粹是网络层问题。Error reading choices / Cannot deserialize value of typejava.util.List。这个报错说明请求发出去了但返回的 JSON 结构不符合 Spring AI 的预期。常见原因是 Base URL 多了一层或少了/v1导致请求打到了错误的端点返回了 HTML 错误页而不是 JSON。另一个原因是模型名不存在服务端返回了错误结构。先用第 2 节的 curl 命令验证通道确认返回的是标准 OpenAI 格式的 JSON。OAuth / token expired。如果你用的是 Azure OpenAI 或者某些需要 OAuth 的平台会看到这类报错。统一通道下用 API Key 鉴权不会遇到 OAuth 问题。如果确实需要 OAuth检查 token 是否过期、scope 是否正确。Spring AI 的OpenAiApi默认用 Bearer Token不涉及 OAuth 流程。模型返回空内容 / content 为 null。检查max-tokens是否设得太小有些模型在 token 耗尽时会返回空。另外确认temperature没有设成极端值。如果用的是推理模型如deepseek-reasoner内容可能在reasoning_content字段而不是content需要单独处理。连接超时 / read timeout。大模型响应慢是常态尤其是长文本生成。Spring AI 默认的超时可能不够可以在配置里调整spring: ai: openai: chat: options: model: deepseek-chat # 超时配置 base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY}如果 Starter 不直接暴露超时配置可以通过自定义RestClient.Builder或WebClient.Builder来设置。另一个办法是在OpenAiApi构建时传入自定义的RestClient。排查顺序建议先 curl 验证通道 → 再检查环境变量 → 再看 Base URL 格式 → 最后看模型名。90% 的问题在前两步就能定位。如果还是不通把完整报错和请求的 URL 贴出来对照上面几类逐一排除。6. 从统一 Key 到长期编码Spring AI 多模型集成的落地建议跑通验证之后聊聊怎么把这套方案用到真实项目里。统一 Key 接入的价值不只是少配几个 Key而是把模型切换从工程问题变成了配置问题。第一把模型名外置到配置中心或数据库。上面例子里model是请求参数生产环境更常见的做法是存在数据库的ai_model表里运营在后台改一行数据就能切换模型。Spring AI 的OpenAiChatOptions支持运行时构造所以从数据库读模型名完全可行。这样业务方说换成 DeepSeek你只需要改一条记录不用发版。第二按场景分配模型。对话用qwen-max中文好代码生成用gpt-4o逻辑强成本敏感的批量任务用deepseek-chat便宜私有化场景用本地 Ollama。这些都可以通过不同的OpenAiChatOptions实现共用同一个OpenAiApi连接。第三做好降级和重试。统一通道下如果某个模型不可用可以在代码里捕获异常后切换到备用模型。Spring AI 本身不提供自动降级需要自己封装一层。建议给每个场景配一个主模型和一个备用模型主模型失败时自动切备用。第四Key 轮换和额度监控。统一 Key 的好处是只需要在一个地方轮换但也要注意单点风险。建议定期在控制台查看用量设置额度告警。如果团队规模大可以按项目分配不同的 Key便于计费隔离。如果你正在做长期的 AI 编码或 Agent 项目可以考虑 Coding Plan 这类方案把模型调用和编码工作流结合起来。对于需要频繁验证模型效果的场景模型对话页面可以快速对比不同模型的输出。接入文档里有更详细的参数说明和示例代码。最后说一个实际经验多模型集成最容易出问题的地方不是代码而是模型名的维护。各家模型迭代快gpt-4o可能下架qwen-max可能升级到新版本。建议在数据库里维护一份模型清单定期核对官方文档避免线上突然报模型不存在。这套统一连接 动态模型的架构本质上和支付渠道、短信通道的多厂商接入是同一个思路——连接层收敛业务层灵活。
