AI 应用后端工程化：从原型到可交付系统 · 第 22 篇 · 第六章 · 编排与模型
抽离模型实体、供应商配置和参数模板，在统一入口下保留不同模型的能力差异与默认策略。
接入第二个模型供应商时，复制一份调用代码最快。接到第五个时，认证、消息格式、参数名、流式事件和错误处理开始遍布业务层。多模型适配的目标不是假装所有模型相同，而是统一稳定部分，同时明确暴露能力差异。
三层而不是一个 if
flowchart LR
UseCase[业务用例] --> Interface[内部模型接口]
Interface --> Manager[Provider Manager]
Manager --> OpenAI[OpenAI 适配器]
Manager --> Tongyi[通义适配器]
Manager --> Wenxin[文心适配器]
Manager --> Ollama[本地模型适配器]
Manager --> Grok[Grok 适配器]
Catalog[(模型目录/参数模板)] --> Manager
内部接口定义消息、流事件、工具调用和用量等稳定对象；Manager 根据配置选择 Provider；适配器处理 SDK 和协议差异。业务 Service 不应到处判断供应商名称。
能力矩阵比最低公分母好
某些模型支持工具调用，某些支持图像，某些有 reasoning 字段，参数范围也不同。如果接口只保留所有模型共有的最小能力，高级功能无法使用；如果调用方随意传供应商参数，抽象又失去意义。
{
"model": "provider/model-name",
"capabilities": {
"streaming": true,
"tools": true,
"vision": false,
"structured_output": true
},
"parameters": {
"temperature": {"min": 0, "max": 2, "default": 0.7},
"max_tokens": {"min": 1, "max": 8192, "default": 1024}
}
}
发布配置时根据能力矩阵校验。例如工作流使用工具节点，所选模型却不支持工具，应在发布前失败。前端参数表单也可由模板生成，避免允许非法值。
消息先归一化，再适配
内部消息可以表示 text、image、tool_call 和 tool_result。适配器将其转换为供应商格式，再把响应归一化为统一事件。未知字段可记录在原始元数据中，但不能泄漏到所有业务逻辑。
供应商之间的历史消息并不一定可直接迁移。某模型的私有 reasoning 内容可能禁止回传，工具 call ID 格式也不同。切换模型时应经过兼容转换，并在无法保真时开启新会话或明确丢弃字段。
参数默认值属于版本
把默认模型和温度写在代码里，升级后历史配置行为会变化。模型目录应保存默认参数和可选范围，应用发布快照记录实际值。供应商下线模型时，系统能列出受影响应用，而不是等调用报 404。
模型名称也不等于稳定能力。有些供应商会让同名模型滚动升级。要求严格重现时使用版本化名称，并记录响应中的真实模型版本。
Provider 发现与加载
目录可以由 YAML 描述 Provider 与模型，再由 Manager 加载实现。启动时校验目录引用的类存在、模型 ID 唯一、参数模板合法。图标等展示资产不能影响运行时加载失败语义。
本地模型与云模型生命周期不同：本地服务可能尚未启动，云服务可能凭证失效。列表接口应区分“已配置”“可连接”和“支持某能力”，不要用一个 enabled 掩盖全部状态。
失败归一化与保留细节
供应商会用不同异常表示限流、认证、内容过滤和超时。适配层转换为内部错误码，让上层统一决定重试；同时保留 Provider request ID 供排查。
不能把所有错误都转成 model unavailable。认证错误不应重试，限流可退避，内容过滤需要提示调整输入。归一化的意义是统一决策，不是抹掉原因。
回退不是无条件换模型
主模型失败后自动调用备用模型看似可靠，但工具能力、上下文窗口、数据区域和成本可能不同。只有在请求允许、消息可转换、能力满足且合规策略一致时才回退。用户可见结果应记录实际使用模型。
类比其他多供应商系统
支付、短信、对象存储都需要统一接口、能力矩阵、错误归一化和审慎回退。练习：为两个假模型定义不同能力，一个不支持工具，一个最大上下文较小。让发布校验拒绝不兼容配置，再模拟限流与认证错误，验证只有前者触发备用模型。
七次提交完成多供应商抽象
46f0577：定义模型、Provider 与参数模板实体。6322a9e：接入多个语言模型供应商。edde52d：新增 Grok 模型配置与实现。723d55b：增加模型查询服务和展示信息。7e350ec：调整模型实体并引入辅助 Agent 会话。04bffb8：补齐辅助 Agent 服务与消息管理。6125d48：更新模型节点与默认模型选择。
从实体模板到真实 Provider，再到服务、会话和工作流节点，适配层逐渐贯穿所有调用入口。越早集中差异，后续替换模型越不容易牵动整个系统。