企业接入 GPT、Claude、Gemini 等 AI 模型时，最初往往从几个 API Key 和一段调用代码开始。当业务进入生产环境，问题会迅速从“能不能调用”变成“谁可以调用、调用了什么、成本归谁、失败如何切换、数据是否合规、模型升级会不会影响业务”。
统一 API 的价值不是把不同接口改成同一个地址，而是给多模型应用增加一层稳定、可治理、可观测的云服务基础设施。
业务代码不应直接承担厂商切换、限流重试、密钥轮换、成本分摊和审计。把这些能力放到统一网关，才能让模型创新和企业治理同时推进。
一、先判断是否需要统一 API
以下情况满足两项以上，就值得建设统一接入层：
- 同时使用两个以上模型或云平台
- 多个产品、团队或客户共享模型资源
- 需要按场景选择质量、速度和成本不同的模型
- 需要故障切换、限流、重试或区域路由
- 希望统一管理密钥、权限、预算、日志和审计
- 需要保留厂商替换能力，减少业务代码改造
- 包含文本、图片、语音或视频等多模态任务
如果只有一个低频内部工具，直接使用官方 SDK 可能更简单。不要为了架构图好看而增加不必要的中间层。
二、统一 API 的参考架构
一条完整链路可以拆成七层：
| 层级 | 核心能力 |
|---|---|
| 业务应用 | 客服、内容、搜索、分析、Agent、内部工具 |
| 统一身份 | 用户、应用、租户、项目和服务账号身份 |
| API 网关 | 鉴权、配额、限流、请求校验和路由 |
| 模型适配 | 协议转换、参数映射、流式输出和错误归一化 |
| 策略编排 | 模型选择、降级、重试、缓存和内容策略 |
| 可观测与治理 | 日志、追踪、用量、成本、质量和审计 |
| 模型与云资源 | 官方模型 API、云模型平台、自部署模型和数据服务 |
业务系统只面向稳定的内部接口。模型名称、版本、区域、供应商密钥和失败策略由服务端配置管理，避免散落在每个应用中。
三、模型组合应该围绕任务，而不是追逐排名
先列出真实任务，再为任务设定质量、时延、上下文、模态、安全和成本要求。
| 任务 | 主要指标 | 建议策略 |
|---|---|---|
| 客服问答 | 正确率、引用、响应时延、拒答率 | 主模型 + 知识检索 + 低风险降级模型 |
| 内容生产 | 品牌一致性、可编辑性、成本 | 轻量模型初稿 + 强模型审核或重写 |
| 数据提取 | 结构正确率、稳定性、吞吐 | 结构化输出 + 固定版本 + 自动验证 |
| 代码与分析 | 任务完成率、工具调用、上下文 | 能力优先，设置时长和预算护栏 |
| 图片/语音/视频 | 模态质量、生成时长、版权与安全 | 独立队列、异步任务和资产审计 |
模型路由应由评测数据驱动。不要仅根据公开榜单切换生产模型，也不要把价格最低直接等同于单位业务成本最低。
四、协议兼容不能停留在字段改名
即使统一成类似 OpenAI 或 Anthropic 的请求格式，不同模型仍可能在以下方面存在差异：
- 系统指令、工具调用和结构化输出能力
- 上下文长度、图片和文件输入方式
- 流式事件、结束原因与错误码
- Token 计算、缓存、推理参数和输出限制
- 安全策略、数据处理、区域与版本生命周期
适配层应明确“共同子集”和“厂商扩展”。共同能力使用统一字段，特殊能力通过命名空间或能力声明暴露，避免为了形式统一而丢失关键功能。
建议为每个模型维护能力清单、参数映射、错误映射、测试用例和升级记录。模型版本变化必须先通过回归评测，再进入生产别名。
五、路由、降级与重试如何设计
路由维度
可以按业务、租户、地区、数据级别、任务类型、质量档位、预算、时延和模型健康状态路由。核心交易链路与批量离线任务不应共用同一套策略。
降级顺序
降级不一定是换模型。合理顺序可能是：缩短非必要上下文、关闭非核心增强、切换同系列轻量模型、切换备选供应商、转为异步处理，最后才返回可解释错误。
重试边界
只对明确的临时错误重试，使用指数退避和随机抖动，并设置最大次数、总超时和熔断。输入错误、权限错误和内容策略拒绝不应无条件重试。
对会产生外部动作的 Agent 或工具调用，应使用幂等键、状态机和去重，避免模型请求重试导致重复下单、重复发信或重复写入。
Google Cloud 的生成式 AI 错误处理建议对临时错误使用退避并避免流量尖峰；其文档也区分按需共享容量和预配吞吐等供给方式。具体规则应以所用平台当前文档为准。
六、密钥、权限和租户隔离
密钥管理
- 密钥只保存在服务端密钥管理系统，不写入网页、App 或代码仓库
- 按环境、应用、团队或客户分开，不共用“万能 Key”
- 定期轮换，对泄露和异常调用提供快速吊销路径
- 记录密钥负责人、用途、权限、创建和到期时间
OpenAI 官方 API 文档明确建议把 API Key 作为秘密保存在服务端环境变量或密钥管理服务中，不应暴露在浏览器或客户端代码里。
权限模型
建议使用“主体—项目—模型—动作—配额”五个维度。例如某个服务账号只能调用文本模型、单次输出不超过限制、每日预算不超过阈值，且不能读取其他租户日志。
多租户隔离
请求、缓存、文件、向量数据、日志和费用必须带租户边界。排查问题时也不能让运营人员默认看到完整的敏感输入输出。
七、日志与数据治理：先分类，再决定记录什么
不要默认把所有 Prompt 和结果完整写入日志。建议把数据分成公开、内部、敏感和严格受限等级，然后定义允许的模型、区域、存储、脱敏、保留期限和查看权限。
日志可以拆成两类：
- 运行元数据：请求 ID、模型、版本、时延、Token、状态、重试、租户和成本
- 内容数据：输入、输出、文件、检索片段与工具参数
运行元数据通常用于监控；内容数据可能涉及隐私、商业秘密和监管要求，应最小化、脱敏、加密，并提供删除流程。使用任何模型服务前，都应核对官方数据使用、保留和区域政策。OpenAI 和 Google Cloud 都提供数据控制或保留说明，实际设置取决于产品、功能和合同条件。
八、成本治理要落到“单位业务结果”
仅统计 Token 费用不足以指导业务。统一平台应至少支持：
- 按租户、产品、环境、团队、任务和模型分摊费用
- 预算阈值、异常增长和单位成本告警
- 输入、输出、缓存、工具调用、图片/音视频等分类统计
- 失败和重试成本、长上下文浪费、空闲 GPU 或预留容量
- 每次会话、每个合格线索、每个完成任务的单位成本
常见优化顺序
- 删除重复上下文和不必要输出
- 对稳定前缀、知识和结果做合适缓存
- 让轻量模型承担分类、提取和初步处理
- 只把复杂或高价值任务升级到强模型
- 批量任务使用异步队列并平滑流量
- 用质量评测确认降本没有伤害业务结果
成本策略不能独立于质量。一次更便宜但需要人工返工三次的调用，实际可能更贵。
九、可观测性应该包含五类面板
| 面板 | 核心指标 |
|---|---|
| 可用性 | 请求量、成功率、错误码、限流、熔断和供应商健康 |
| 性能 | 首字节、完整时延、队列、流式中断、P95/P99 |
| 用量与成本 | 输入输出 Token、模态用量、缓存、预算和单位业务成本 |
| 质量 | 任务成功、结构正确、事实、引用、人工接管和投诉 |
| 安全与审计 | 权限拒绝、异常密钥、敏感数据、策略命中和管理员操作 |
每个请求应有内部追踪 ID，并记录上游业务请求与下游模型请求的关联。官方 API 返回的请求 ID 也应保留，便于与平台支持一起排查。
十、生产上线前必须有评测和变更管理
建立一组来自真实业务的评测集，覆盖正常、边界、敏感、长上下文、工具错误和供应商故障场景。每次修改模型、版本、系统指令、检索、工具或路由策略，都要做回归评测。
建议设置三类门槛：
- 质量门槛：任务成功率、结构正确率、事实与人工评分
- 运行门槛：时延、错误率、限流和故障恢复
- 业务门槛：转化、人工接管、单位成本和用户反馈
模型别名切换应支持小流量灰度、快速回退和变更记录。生产系统不要直接跟随“latest”版本而没有评测。
十一、90 天实施路线图
0—30 天：建立最小治理闭环
盘点所有 Key、模型、应用和账单；统一服务端鉴权；接入请求 ID、用量、成本和错误监控；为两个高频任务建立评测集。
31—60 天：实现多模型路由
完成模型适配、任务路由、限流、重试、熔断和降级；按团队与产品分摊成本；完成一次供应商故障演练。
61—90 天：形成长期运营机制
增加敏感数据分类、租户隔离、版本灰度、质量看板、预算策略与月度复盘；形成模型准入、变更、下线和审计制度。
十二、上线检查清单
- 所有 API Key 存放在服务端并可单独轮换
- 用户、应用、租户、项目和费用归属可识别
- 模型、版本、区域和能力声明有配置记录
- 限流、超时、重试、熔断和降级策略已验证
- 日志字段、脱敏、加密和保留期限明确
- 请求 ID、用量、成本、性能和质量可以追踪
- 高风险工具调用有幂等、审批或人工确认
- 生产模型切换有评测、灰度和回退
- 平台故障、配额不足和预算耗尽完成演练
- 数据导出、模型替换和供应商退出路径可执行
官方文档参考
- OpenAI API：认证、请求 ID 与错误排查
- OpenAI API：数据控制
- Anthropic API：Rate Limits
- Google Cloud：Vertex AI 生成式 AI
- Google Cloud：生成式 AI API 错误处理
如果需要把海外云资源、官方模型账号、统一 API、权限、用量、成本和监控放进同一交付链路，可通过海外云与 AI 模型服务提交模型、调用量、地区和系统需求，由团队协助完成资源交付、接入测试与持续运维。
