# OpenAI 兼容 API 迁移清单

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

_发布 2026-08-15 · 更新 2026-08-15 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 9 分钟阅读_

![从请求契约到回滚的 OpenAI 兼容 API 字段级迁移清单](https://keeprouter.com/editorial/blog/openai-compatible-api-migration-checklist.png)

_兼容性按操作逐项验收，包括流式、工具、错误、用量与回滚。_

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

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

## 迁移证据矩阵

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

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

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

```python
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 及其端点兼容性以[模型目录](/models)为准，支持的路由与请求 Schema 以公开 [OpenAPI 文档](/api/openapi.json)为准。一个模型支持 Chat Completions，并不能自动证明它也支持 Responses、embeddings、images，或 Chat Completions 的每个可选字段。

## 可执行上线清单

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

[OpenAI 兼容 API 页面](/zh/features/openai-compatible-api)说明集成面，[OpenAI SDK 指南](/use-cases/openai-sdk)提供客户端配置。如果同时考虑从 Chat Completions 切到 Responses，应把两项决策拆开：先读 [Responses API 与 Chat Completions](/zh/blog/responses-api-vs-chat-completions)，再一次迁移一个契约。

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

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

## 常见问题

### 只改 base_url 就完成迁移了吗？

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

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

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

## 参考的一手资料

_本文最近复核 2026-08-15_

1. [OpenAI API reference](https://developers.openai.com/api/reference/overview)
2. [OpenAI backward compatibility](https://developers.openai.com/api/reference/overview#backwards-compatibility)
3. [KeepRouter OpenAPI](https://keeprouter.com/api/openapi.json)
4. [KeepRouter model catalog](https://keeprouter.com/models)

## 继续阅读

- [OpenAI 兼容 API](https://keeprouter.com/zh/features/openai-compatible-api.md)
- [openai sdk](https://keeprouter.com/use-cases/openai-sdk.md)
- [Responses API 与 Chat Completions：按契约选择，而不是追新](https://keeprouter.com/zh/blog/responses-api-vs-chat-completions.md)
- [errors](https://keeprouter.com/docs/errors.md)

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)