把现有应用迁移到 OpenAI 兼容 API：一份不踩坑的迁移清单

很多团队早期把业务逻辑写死在某一家大模型厂商的 SDK 上。当要切换到成本更低、或合规更优的渠道时，重写代码成本极高。OpenAI 兼容层（统一 base_url + /v1/chat/completions 协议）正是为了解决这个问题：换一个地址，其余几乎不动。

第一步：统一请求协议

确认目标接口支持 messages 数组、model 字段、temperature、max_tokens、stream 等常用参数。绝大多数 OpenAI 兼容服务都保持相同结构，迁移时无需改业务字段。

第二步：鉴权与密钥管理

把密钥放进环境变量或服务侧密钥库，绝不留进代码与前端。兼容层通常沿用 Bearer Token，只需替换 apiKey 来源，请求头保持不变。

第三步：流式响应处理

若原应用使用 SSE 流式输出，确认目标接口以 data: 行推送增量 token，并以 data: [DONE] 结束。解析层通常可完全复用，只改连接地址。

第四步：错误码与重试

对照 HTTP 状态码（401 鉴权失败、429 限流、5xx 服务异常）建立统一重试与退避策略，避免把渠道差异暴露给终端用户。

第五步：灰度与回滚

用一个配置开关按比例切流，先放 5% 流量观察延迟与错误率，确认平稳后再全量。保留旧渠道配置以便一键回滚。

迁移的本质是把「厂商绑定」变成「协议约定」。一旦走通 OpenAI 兼容层，后续再换渠道就只是改一个 base_url 的事。