OpenAI 兼容 API 迁移清单

更换 Base URL 只能证明连通，不能证明兼容。上线前应让同一套代表性请求通过新旧链路，并比较应用可见的全部契约。

发布 2026-08-15 · 更新 2026-08-15 · KeepRouter Editorial · 9 分钟阅读

从请求契约到回滚的 OpenAI 兼容 API 字段级迁移清单 — 兼容性按操作逐项验收，包括流式、工具、错误、用量与回滚。

先给结论：不要因为一个文本请求返回 200 就批准 OpenAI 兼容 API 迁移。应把它当成契约迁移：用来自真实应用的载荷，逐项验证认证、端点路径、模型 ID、请求字段、响应结构、流式事件、工具调用、用量、错误、超时与回滚。

最稳妥的做法，是先从现有集成冻结一套小而有代表性的样本。去掉密钥和敏感数据，但保留消息结构、工具定义、输出约束和边界案例。让同一批样本通过新旧链路，并保存归一化证据，而不是肉眼判断几个答案“看起来差不多”。

迁移证据矩阵

阶段	测试	通过证据
盘点	清点端点与 SDK 调用	每条生成链路和后台任务都有负责人
连通	发送最小非流式请求	认证成功，并记录返回的模型/请求 ID
契约	比较应用实际读取的响应字段	解析器无需未文档化的转换即可拿到必需字段
流式	解析完整流并测试取消	事件顺序受支持，局部输出与结束状态都被正确处理
工具	覆盖零个、一个和多个工具调用	名称、参数、ID 与工具结果完成一轮往返后仍正确
失败	触发错误认证、模型、载荷、限额与超时	应用能正确分类错误及其是否可重试
计量	对照响应 usage 与 Gateway 日志	模型、输入/输出单位、状态和费用可归因
灰度	将有限流量送入新链路	在相同工作负载上评估质量、错误、延迟与成本门槛
回滚	恢复旧路由	有文档的切换方式可以工作，无需临时翻代码

配置只是第一步，不是最后一项测试

很多 OpenAI SDK 客户端允许配置 Base URL：

from openai import OpenAI

client = OpenAI(
    base_url="https://keeprouter.com/v1",
    api_key="sk-kr-your-key",
)
response = client.chat.completions.create(
    model="MODEL_ID_FROM_THE_CATALOG",
    messages=[{"role": "user", "content": "Return exactly: ready"}],
)

当前模型 ID 及其端点兼容性以模型目录为准，支持的路由与请求 Schema 以公开 OpenAPI 文档为准。一个模型支持 Chat Completions，并不能自动证明它也支持 Responses、embeddings、images，或 Chat Completions 的每个可选字段。

可执行上线清单

[ ] 固定测试和生产构建使用的 SDK 版本。
[ ] 只在服务端保存 API Key；若 Gateway 支持权限范围，则创建最小范围 Key。
[ ] 把供应商专属别名替换为目标目录中已核验的模型 ID。
[ ] 同时测试省略可选字段与显式传值；默认值可能不同。
[ ] 测试真实流式解析器，包括已输出部分内容后上游报错的情况。
[ ] 用 Schema 校验 JSON 或结构化输出，而不是只看“像不像合法 JSON”。
[ ] 在启用重试或回退前，让工具副作用具备幂等性。
[ ] 保存请求 ID 与应用关联 ID，但不记录密钥或敏感提示词。
[ ] 明确设置超时、重试、输出与支出上限。
[ ] 用灰度样本对照基线，并在扩大流量前演练回滚。

OpenAI 兼容 API 页面说明集成面，OpenAI SDK 指南提供客户端配置。如果同时考虑从 Chat Completions 切到 Responses，应把两项决策拆开：先读 Responses API 与 Chat Completions，再一次迁移一个契约。

边界：兼容不等于完全相同

OpenAI 的兼容性说明允许响应对象与事件数据新增字段，而且 Responses 与 Chat Completions 本来就采用不同对象结构。独立 Gateway 可以实现 OpenAI 风格接口，却不代表复制每个上游扩展或模型行为。最终验收标准应是你的应用契约，而不是“兼容”这个标签。

常见问题

只改 base_url 就完成迁移了吗？

它可能足以让简单请求连通，但生产验收仍需测试应用依赖的字段、流式事件、工具、错误、限制与用量记录。

可以直接沿用旧供应商的模型 ID 吗？

只有目标平台当前目录明确列出完全相同的 ID 才能沿用。别名与端点资格都应视为目标平台拥有的配置。

参考的一手资料

本文最近复核 2026-08-15