模型中立——把大模型做成"可替换零件"，而不是焊死在业务里

TechLearn
620 阅读5分钟

接大模型最危险的一行代码，是写在业务里的 baseUrl

2024 年到 2026 年，团队接大模型的方式变了好几轮：先是某家闭源 API，然后国产模型陆续可用，接着又有人要求本地私有化部署。价格、合规政策、可用性，几乎每个季度都在变。

于是很多项目里出现了这样的代码：

// 三年前没人预料到，这三行会变成技术债
String url = "https://api.xxx.com/v1/chat/completions";
String key = "sk-xxxxxxxx";

它不是 bug，运行得好好的。真正的代价出现在要换模型的时候——你会发现模型供应商的信息已经渗透进了 Service、Controller、甚至前端配置里，改动面比预估大一个数量级。

一、QuickBlue 的做法：模型配置化 + 工厂化

QuickBlue（原生 AI 微服务快速开发平台）在 QuickBlue-ai 服务（8084）里，用一张表加一层工厂解决了这件事。

第一步，把模型变成数据。 AiragModel 实体（airag_model 表）记录一个模型的全部信息：

字段含义
provider供应商标识
modelName / modelType模型名称与类型（对话 / 嵌入等）
baseUrlAPI 域名，私有化或中转地址填这里
credential凭证（百度千帆为 apiKey,secretKey 格式）
modelParamsJSON 参数：temperature / maxTokens / topP 等
sysOrgCode / tenantId部门与租户归属
activateFlag是否激活

第二步，用工厂把差异收进实现层。 ChatModelFactoryManager 在 Spring 启动时扫描所有 ChatModelFactory 实现，按 provider 注册进 ConcurrentHashMap：

for (ChatModelFactory factory : factories) {
    factoryMap.put(factory.getProvider().toLowerCase(), factory);
}

目前内置 6 个工厂实现：OpenAiChatModelFactory、DashScopeChatModelFactory（通义千问）、ZhipuChatModelFactory（智谱）、QianfanChatModelFactory（百度千帆）、OllamaChatModelFactory（本地私有模型）、AnthropicChatModelFactory。

每个工厂统一产出三种能力：ChatModel（同步）、StreamingChatModel（流式）、EmbeddingModel（向量化）。业务侧只面对 ChatModelFactoryManager 一个入口，代码里没有一处 if (provider == ...)。

还有一个很实用的兜底：

factory = factoryMap.get("openai");
log.warn("未找到模型工厂: {}, 使用OpenAI兼容模式", provider);

任何自称 OpenAI 协议兼容的模型服务（各类中转、网关、本地 vLLM/Ollama 兼容端点），即使没有专属工厂，也能直接填 baseUrl 接进来。

二、切换模型，到底要动几下

答案是：一下，且不重启。

模型管理接口在 AiragModelController（/ai/model/**）：

POST   /ai/model                 # 新增模型（填 provider / baseUrl / credential / 参数）
PUT    /ai/model/activate/{id}   # 激活该模型
GET    /ai/model/default         # 读取当前默认模型
GET    /ai/model/list            # 列出已激活模型

也就是说，从"用云端大模型"切到"用本地 Ollama 私有模型"的完整操作是：在后台新增一条模型记录，baseUrl 填 http://内网地址:11434，modelName 填本地模型名，点激活。业务代码、配置文件、前端页面，一行都不用改。

三、为什么"中立"这件事值得被单独设计

因为它同时解决了三个不同角色关心的问题：

角色关心的事模型中立带来的结果
架构师不想被厂商绑定供应商是配置项，换厂商不改代码
合规/安全数据能不能出境可切到本地 Ollama 或私有化部署，数据不出内网
财务/管理者成本能不能控按场景选模型：贵的做复杂推理，便宜的做摘要分类

尤其第二条。当凭证集中存放在 airag_model.credential 字段里、而不是散落在各个 application.yml 与前端常量中，密钥随代码仓库泄露的风险面就被大幅收窄——这是很多团队在等保与代码审计环节被反复提的问题。

技术选型上，QuickBlue 基于 LangChain4j（dev.langchain4j）构建这一层，而不是自己写 HTTP 客户端拼协议。好处是协议演进由社区承担，新增供应商只是多写一个工厂类。

四、中立只是底座的一半

模型能换，只是前提；真正让 AI 产生业务价值的，是它上面那层：RAG 知识库（AiragKnowledgeService，知识 / 记忆双类型 + 向量检索）、应用编排（AiragApp，开场白、提示词、知识库关联、记忆开关、变量配置）、会话管理（AiragSession / AiragMessage，多轮对话 + SSE 流式输出）。这三层都通过同一个工厂取模型，所以换模型时它们自动跟随，不需要各自适配。

五、开源与联系

代码仓库（Apache License 2.0，可免费用于商业与学习场景）：

平台地址
🇨🇳 Giteegitee.com/ossbar/Quic…
🌍 GitHubgithub.com/58ossbar/Qu…
git clone https://gitee.com/ossbar/QuickBlue-MicroAI.git
# 或
git clone https://github.com/58ossbar/QuickBlue-MicroAI.git
  • 双数据库版本：本仓库开源 MySQL 版（各服务库隔离 + 独立账号）；官方同步提供 PostgreSQL 版（含 pgvector 向量检索），切换仅调 Nacos 配置，业务代码零侵入
  • 官网：www.creatorblue.com
  • 技术邮箱：28449472@qq.com

开源不易，如果这个项目对你有帮助，欢迎到仓库点个 Star ⭐，或转发给可能需要的同行。使用中遇到问题，欢迎提 Issue；需要定制化方案、私有化部署或商业支持，欢迎邮件联系。

六、上手

  • 在线体验：ide.budaos.com
  • （账号 admin，密码 nq963369#），可直接进入 AI 模型 / 知识库 / 应用编排页面操作
  • 本地搭建：README 快速搭建章节，向导式安装 10 分钟完成
  • 接口文档：http://localhost:8080/doc.html → QuickBlue-ai 分组

**模型是发动机，可以随时换；底座是你自己的，不能换。**把发动机的接口标准化，才谈得上什么时候换都不慌。

avatar
文章
阅读
粉丝