用一个生产 API
调用多个 LLM

速览

统一调用应标准化什么

标准化真正通用的应用关注点：服务身份、租户、调用链上下文、工作负载别名、Message、超时、预算、所需能力与稳定响应封装。在供应商转换前，从版本化目录解析别名。

不要把所有功能都压进最低共同分母。供应商特定工具、推理、结构定义、媒体或缓存控制应使用类型化扩展；在调用前拒绝缺失必需能力，而不是静默降级。

单一 API 集成层

围绕工作负载构建通用契约

验证每条模型路径

• 为每个生产负载与必需能力组合建立 Golden 请求。
• 对每个合格 GPT、Claude 与 Gemini 端点运行契约测试。
• 在真实请求数据下对比输出、工具、流、错误、用量与延迟。
• 灰度路由变更，并在工作负载特定不变量回归时阻断。
• 保留供应商原生直连路径，用于诊断与已测试回滚。

在类型化供应商适配器之上使用别名

应用发送带工作负载别名与所需能力的规范请求；目录展开合格端点，策略路由器选择一个，类型化适配器映射请求。标准化响应携带供应商原生身份与证据返回。不支持的要求在执行前失败，故障切换也只使用已验证等价项。

先设计统一请求契约

先从应用需要的行为出发，而不是照搬某一家供应商的 JSON。一个实用的统一请求应包含工作负载别名、有序消息、必需能力、可选偏好、超时、最高预算、租户、调用链上下文，以及可能产生副作用时使用的幂等键。必须满足的条件与偏好要分开：例如严格遵守 JSON Schema 可以是硬要求，而较低延迟只是偏好。

响应也应有清晰边界。先返回标准化内容与工具调用，再附上最终供应商、准确模型版本、网关请求 ID、上游请求 ID、路由策略、尝试次数、用量、结束原因和任何有损转换。这样既能稳定应用代码，也不会抹掉排障所需的证据。

先按能力筛选，再优化路由

为每个允许使用的模型端点建立带版本的能力目录，记录输入模态、工具调用、并行工具、结构化输出、流式响应、上下文限制、可用区域、数据处理方式、生命周期状态，以及已验证的工作负载质量。目录应依据官方文档与实际探测持续更新，不能把营销名称当作可执行的能力承诺。

路由应分两步：先剔除不满足硬要求的候选项，再在合格集合中按质量、延迟、可用性、价格、数据驻留或租户策略排序。候选集合与排除原因都要记录，出现结果争议或账单异常时，“智能路由”才可解释。

把供应商差异收进类型化适配器

每个适配器只负责一种原生 API 的双向转换，包括消息角色、系统指令、工具、Schema、媒体、采样参数、停止原因、错误类型、限流响应头与用量。无法等价映射时必须明确拒绝。静默丢弃 Schema、工具选择、图片或安全设置，会得到 HTTP 成功却行为错误的结果。

不要把统一 API 压缩成“最低公分母”。通用核心应保持精简；确实属于供应商特性的能力，则通过带命名空间、可校验的扩展显式开放。调用方因此能清楚知道自己是在使用可迁移能力，还是主动接受了绑定边界。

把流、工具与结构化输出当作协议处理

流式响应不只是文本分片。不同供应商会以不同顺序发送内容增量、推理事件、工具参数、引用、用量与结束元数据。网关应定义自己的事件模型，测试分片组装与取消，并保留原生结束原因。一旦内容已发给调用方，自动切换模型可能造成重复文本或拼接出混合答案。

工具调用也需要完整生命周期：校验参数、授权工具、分配稳定调用 ID、记录结果，并明确由谁继续模型对话。结构化输出则要测试每条路由真正支持的 Schema 语法，并在网关边界再次校验最终结果。

统一客户端密钥，但不要混用上游密钥

应用应使用限定范围的凭证访问网关，凭证要绑定服务、租户、环境与允许的工作负载。各供应商密钥则加密保存在网关之后，分别记录负责人、环境、供应商账号、轮换计划、允许路由与紧急吊销路径。某个客户端令牌泄露时，不应暴露或解锁全部上游账号。

网关还应按租户执行配额、并发限制、模型白名单与预算上限。日志默认脱敏提示词和凭证；如果确实需要保留请求正文，应由明确的数据策略控制，而不是把它当作可观测性的附带结果。

让故障切换范围小、次数有限且可观察

短暂故障可按供应商建议进行带抖动的指数退避，但次数必须有上限。故障切换只能选择已为同一工作负载验证过的等价项。所有尝试共用原始截止时间与预算，不能每次重试都重新获得一份额度。认证失败、请求无效、策略拒绝或能力不支持时应立即停止。

部分流已经输出，或工具已经产生副作用后，不能盲目重放请求。确需恢复时，应使用幂等键、工具执行账本与明确的续跑规则。响应中保留尝试历史，运维人员才能区分“首条路由较慢”和“经过多次昂贵切换后才成功”。

衡量可接受结果，而不只比较 Token 单价

可以把用量整理成统一成本记录，但不要假设各家计费单位完全相同。原生输入、输出、缓存、推理、图片、音频及工具相关用量，应与供应商实际计费金额和币种一起保存，再关联工作负载、租户、路由、延迟、重试次数、质量评分与最终是否被接受。

真正有价值的指标是“每个可接受任务的成本”，而不是宣传页上的 Token 单价。应按别名跟踪成功率、p50/p95 延迟、Schema 合格率、工具成功率、故障切换率、预算超支与质量。告警中要包含网关请求 ID、最终路径、策略版本和上游证据。

多模型统一 API 上线检查清单

• 分别对请求、响应、别名、能力目录与路由策略做版本管理。
• 没有任何路由满足全部硬性能力与策略要求时，在执行前明确失败。
• 逐个适配器测试文本、流、工具、Schema、错误、取消与用量。
• 隔离上游密钥，并按租户与工作负载限制客户端凭证和预算。
• 别名变更先灰度，用 Golden 工作负载对比，并保留已测试的回滚路径。
• 暴露最终供应商、准确模型、转换、尝试记录、原生 ID、用量与成本。

让统一 API 失控的七个常见错误

一个模型 API 加一个能力接口

统一模型 API 为智能体提供一致推理访问；QVeris 以 Discover → Inspect → 调用提供外部 API、工具、服务与实时数据访问。把两者叠加为模型接口与能力接口，并共享工作负载身份与调用链上下文。

FAQ

官方资料与延伸阅读