同一套代码切换 OpenAI/DeepSeek/通义/OllamaSpring AI 模型抽象与选型实战系列Spring AI 深入浅出第 3 篇版本Spring AI 2.0.1 / Spring Boot 4.1.x / JDK 21标签#SpringAI #模型切换 #国产大模型 #Ollama前置阅读第 1 篇《五分钟跑通第一个应用》预计字数6500 字可复制源码 选型决策表 踩坑 FAQ本文将解决Spring AI 最大的红利是换模型不改 Java 代码。本文讲清ChatModel可移植抽象的原理给出各厂商 starter 对比、OpenAI 兼容协议接国产模型的通用套路以及云端 vs 本地 Ollama 的选型决策矩阵。你将学到为什么业务代码能零改动切换模型ChatModel抽象各厂商 starter 对比表OpenAI / DeepSeek / 通义 / 文心 / OllamaOpenAI 兼容协议接国产模型的通用三步云端 vs 本地 Ollama 的五维决策矩阵一套代码切三套配置的完整实战一、版本标注本文基于 Spring AI 2.0.1 / Boot 4.1 / JDK 21依赖沿用第 1 篇的 pomspring-ai-bom starter。二、可移植抽象ChatModel 是插座Spring AI 的核心设计业务代码只面向ChatModel接口编程不依赖任何具体厂商。不同 starter 注入不同的ChatModel实现就像换个插座上插的电器墙里的线你的代码不动。业务代码 ↓ 只依赖接口 ChatModel 接口 ChatClient ├── OpenAiChatModel OpenAI starter 注入 ├── DeepSeekChatModel DeepSeek starter 注入 ├── DashScopeChatModel 通义 starter 注入 ├── QianfanChatModel 百度文心 starter 注入 └── OllamaChatModel Ollama starter 注入于是切换模型变成了两件事都不碰业务代码换 pom 里的 starter或直接用 OpenAI 兼容协议连 starter 都不用换改application.yml里的 base-url / api-key / model这就是本文标题的底气来源。三、各厂商 starter 对比表厂商starter是否需要 Key接入方式特点OpenAIspring-ai-starter-model-openai是官方 SDK能力最强生态最全DeepSeekspring-ai-starter-model-deepseek或 OpenAI 兼容是官方 / 兼容协议性价比极高中文好通义千问spring-ai-starter-model-dashscope或 OpenAI 兼容是官方 / 兼容协议国内合规多模态全百度文心spring-ai-starter-model-qianfan是官方 SDK国内生态企业落地多Ollamaspring-ai-starter-model-ollama否本地 HTTP免费、私有化、可离线说明2.0 起部分厂商由官方维护并拆分到独立仓库发布如 Azure 由微软维护写作时以spring-ai-bom里实际坐标为准。OpenAI 兼容协议是万能钥匙——只要厂商提供 OpenAI 兼容端点就能用 OpenAI starter 直接接这也是下面重点讲的套路。四、OpenAI 兼容协议接国产模型通用三步很多国产模型DeepSeek、通义、Kimi、智谱等都提供 OpenAI 兼容接口。用这套套路不用换 starter、不用加依赖只改配置第一步保留 OpenAI starter第 1 篇 pom 不动第二步改 base-url 和 api-key 指向国产厂商第三步改 model 名为对应厂商的模型名以 DeepSeek 为例spring:ai:openai:api-key:${DEEPSEEK_API_KEY}# 换成 DeepSeek 的 Keybase-url:https://api.deepseek.com# 换成 DeepSeek 的兼容端点chat:options:model:deepseek-chat# 换成 DeepSeek 的模型名通义阿里云百炼兼容端点spring:ai:openai:api-key:${DASHSCOPE_API_KEY}base-url:https://dashscope.aliyuncs.com/compatible-mode/v1chat:options:model:qwen-plus什么时候用官方 starter什么时候用兼容协议一个简单判断只是聊天/生成兼容协议够用且切换最省事要用厂商独有特性如通义的多模态、文心的插件用官方 starter 更稳官方 starter 里没你想要的模型时兼容协议兜底五、云端 vs 本地 Ollama五维决策矩阵这是架构师最常被问的选型题。用五维打分表来做决策维度云端模型OpenAI/DeepSeek/通义本地 Ollama成本按 token 付费量大成本高免费只耗电延迟网络往返 排队可能较高本地极低取决于硬件私有化/合规数据出域有合规风险数据不出本地合规无忧能力顶级模型能力强开源模型略弱取决于模型部署复杂度零部署开箱即用需装 Ollama、拉模型、管硬件决策口诀要最强效果 快速上线→ 云端要零成本 数据隐私→ 本地 Ollama要兼顾→ 混合开发测试用 Ollama生产切云端这正是第 22 篇会讲的混合部署六、实战一套代码切三套配置代码不变只换 yml。以第 1 篇的ChatController为例Java 代码一字不改RestControllerpublicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringq){returnchatClient.prompt().user(q).call().content();}}配置 1OpenAIspring:ai:openai:api-key:${OPENAI_API_KEY}base-url:https://api.openai.comchat:options:model:gpt-4o-mini配置 2DeepSeek兼容协议starter 不变spring:ai:openai:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.comchat:options:model:deepseek-chat配置 3本地 Ollama换 starter 配置dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependencyspring:ai:ollama:base-url:http://localhost:11434chat:options:model:qwen2.5三套配置跑下来ChatController完全不用动——这就是 Spring AI 抽象的价值兑现。工程建议用 Spring Profile 管理多套配置application-openai.yml/application-deepseek.yml/application-ollama.yml启动时--spring.profiles.activedeepseek一键切换比改文件更规范。七、原理图解抽象层如何解耦实现层抽象层业务层ChatController只依赖 ChatClient/ChatModel 接口ChatClient / ChatModel 接口OpenAiChatModelDeepSeekChatModelDashScopeChatModelOllamaChatModel换厂商 换实现层的一个节点抽象层之上的业务代码纹丝不动。八、踩坑 FAQ坑 1切了模型忘改 base-url现象把 model 改成 deepseek-chat但 base-url 还是 OpenAI 的报鉴权错或 404。原因model 和 base-url 必须配套。解决换模型时一起改base-url、api-key、model 三件套。坑 2兼容协议的字段差异现象某些参数如 frequency_penalty传了国产模型报错或不生效。原因各家兼容协议实现不全不是 100% 等价。解决优先用最通用的参数temperature、max_tokens冷门参数先查厂商兼容文档。坑 3Ollama 没启动现象切到 Ollama 配置后报连接拒绝。原因本地 Ollama 服务没起或模型没拉。解决先ollama serve启动再ollama pull 模型名拉取确认base-url指向http://localhost:11434。坑 4通义/文心需要先在控制台开通现象拿到 Key 也调不通报无权限。原因通义阿里云百炼、文心千帆需要先在控制台开通对应服务、创建应用拿到正确 Key。解决去阿里云百炼 / 百度千帆控制台开通确认用的是应用 Key而非账号 Key。坑 5本地 Ollama 模型名写错现象报模型不存在。原因yml 里 model 名和ollama list里实际模型名不一致。解决ollama list查看已安装模型名yml 里写完全一致的名字区分大小写。九、小结与合集导航本篇核心一句话面向ChatModel/ChatClient接口编程让换模型从改代码变成改配置。理解了ChatModel可移植抽象掌握了各厂商 starter 对比与 OpenAI 兼容协议三步接入法拿到云端 vs 本地的五维决策矩阵完成一套代码切三套配置的实战下一篇《1.x → 2.0 升级指南》——如果你是从 Spring AI 1.x 迁移过来的存量用户这篇会给你一份照着改就行的 breaking changes 清单。十、互动钩子投票你生产环境现在用哪个模型OpenAIDeepSeek通义千问百度文心本地 Ollama其他/自建评论区聊聊你的选型理由尤其是数据合规和成本是怎么权衡的源码见置顶评论。