AI API 版本化策略：不破坏客户端的演进之道
AI API 有个传统 API 没有的麻烦：上游模型升级完全不受你控制。GPT-5 出了新版本、DeepSeek 换了推理引擎、某个模型突然调整了输出格式——你的 API 行为随之改变，而你的客户毫无防备。版本化，就是在这条「你控制不了的上游」和「你得罪不起的下游」之间，建一道缓冲。
这篇文章讲清楚四件事：版本放哪里（URL / Header / 参数）、模型版本和 API 版本怎么解耦、向后兼容的工程纪律、以及弃用（deprecation）的完整流程。最后从聚合网关的视角，说说我们 DrAI 是怎么给 40+ 模型的上游变化兜底的。
一、为什么 AI API 更需要版本化
传统 API 的版本化防的是「我改了接口」，AI API 的版本化防的是「模型改了行为」。三类变化必须被版本化兜住：
- 行为漂移：模型厂商调整默认参数、推理引擎升级导致输出风格变化——接口没变，语义变了。
- 格式演进：厂商引入新的流式事件类型、新的 usage 字段、甚至调整错误码——解析逻辑会崩。
- 模型下线：旧模型退役，不提前规划，客户端会在某个早晨突然收到 404。
没有版本缓冲的 AI API，本质上把「上游的每一次变化」直接传导给「下游的每一个客户」。版本化不是洁癖，是 SLA 的一部分。
二、版本放哪里：URL vs Header vs 参数
| 方案 | 优点 | 缺点 | 适用 |
|---|---|---|---|
| URL 路径（/v1/chat/completions） | 直观、缓存/CDN 友好、日志可读 | URL 膨胀、迁移成本高 | 大版本、长期稳定接口 |
| 自定义 Header（X-API-Version） | URL 干净、细粒度演进 | 不可见、易被忽略、调试麻烦 | 小版本、渐进式发布 |
| 查询参数（?version=） | 实现最简单 | 污染缓存键、语义弱 | 内部服务、临时方案 |
行业共识是混合策略：URL 路径管「破坏性大版本」，Header 管「行为演进」。OpenAI 兼容生态的事实标准是 URL 版本（/v1/chat/completions），你的聚合层最好保持这个形状——这也是我们 DrAI 网关保持 /v1 前缀的原因：兼容性本身就是卖点，客户端换 base_url 就能切换供应商。
三、模型版本与 API 版本：解耦的艺术
AI API 版本化的精髓是把「模型版本」和「API 契约版本」拆成两个维度：
- API 版本：你的接口契约（请求字段、响应结构、错误码），由你控制，破坏性变更才升版本。
- 模型版本：模型的行为版本（gpt-5、gpt-5-2026-xx、deepseek-r1-v3……），由厂商控制，你负责映射与兜底。
正确做法：客户端声明「模型别名」（如 gpt-5），网关解析为具体模型快照，并允许客户端用完整快照 ID 锁定行为（gpt-5-2026-08-01）。模型升级时：默认别名平滑迁移到新快照，锁定快照的客户端不受影响。这就把「上游模型升级」从「事故」变成了「可计划的发布」。模型选择的更多细节见《GPT-5-mini 还是 GPT-5？》。
四、向后兼容的工程纪律
兼容性不是「尽量不改」，而是一套可执行的纪律：
- 只加不删：新字段、新枚举值、新端点随便加；删字段、改默认值、收紧校验是破坏性变更，必须升版本。
- 响应宽容：解析端对未知字段要忽略而非报错（客户端代码对「多出来的字段」要宽容）。
- 默认值冻结：同一个请求在不同版本下行为一致——新行为只对新版本生效，别悄悄改旧版本默认值。
- 契约测试兜底：把「版本 X 的响应结构」固化成契约测试，每次变更跑全量，谁破坏了兼容性立刻暴露。
- 错误也要兼容：错误码、错误信息结构是契约的一部分。新增错误码要进文档，别把「限流」从 429 改成 503。
五、弃用流程：公告、过渡与 Sunset
版本化的另一半是「优雅地杀死旧版本」。完整的弃用流程：
# 响应头：告知客户端版本将在何时失效
HTTP/1.1 200 OK
X-API-Version: 2025-09
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Link: <https://api.dr-ai.top/v2/chat/completions>; rel="successor-version"- 提前 90 天以上公告：邮件 + 控制台横幅 + changelog，三个渠道同步。
- 全程带 Sunset 头：旧版本每个响应都带失效时间，客户端可以在代码里自动告警。
- 迁移期双跑：给客户提供「新版本影子流量」能力，客户端把同一请求打到新旧两个版本，对比差异后再切换。
- 给宽限期：到期后先降级（返回 429 + 迁移提示）再硬下线，别直接 404。
- 留个「最后版本」：对重要客户保留冻结的旧版本（收费更高），比强制迁移更体面。
这套流程对聚合平台尤其重要：你同时是「下游」（对模型商）和「上游」（对客户），两个方向的弃用都要管理。API 密钥与接入安全里说的审计能力，在迁移期就是排查利器——知道谁还在用旧版本，迁移才能精准推进。
六、客户端侧的演进
版本化的另一半责任在客户端：
- SDK 固定版本：锁 SDK 版本 + 读 changelog，别用「latest」自动升级到破坏性版本。
- 解析宽容：未知字段忽略、未知枚举降级、缺失字段走默认值——好客户端永远不会被「新增字段」打死。
- 监控 Sunset：把响应里的 Sunset 头解析出来，失效前 30 天自动建工单。
- 灰度切换：流量按百分比切到新版本，配合影子对比，出问题 5 分钟回滚。
七、网关与聚合平台的版本实践
用聚合网关（如 DrAI）时，版本化多了一层「厂商差异屏蔽」：上游模型商 A 的 v2 可能对应 B 的 v1.5，网关负责把「你对外的一个契约」映射到「各家各版本的上游」。这对你的好处是：上游变化被网关消化，你只需要跟随网关的版本节奏；上游模型退役时，网关会提前公告替代模型，你的代码可能一行都不用改。这也是「一个 Key 调 40+ 模型」背后真正的工程价值——《AI API 入门指南》里讲了这类平台的接入方式。
八、常见坑
- 版本号没意义：v1 里堆了三年破坏性变更，等于没版本化——破坏性变更必须推动版本升级。
- 模型别名裸奔：让客户端直接依赖「最新模型」的隐式行为，升级即事故，务必提供快照锁定。
- 只公告不追踪：发了邮件就完事，没人统计旧版本流量——弃用要数据驱动。
- 文档不同步：版本化最大的隐性成本是文档，每个版本的请求/响应示例都要可运行、可对照。
- 忘了内部调用方：自己的其他服务也可能是 API 的客户端，内部调用同样要过版本管理。
版本化做得好的 AI API，升级是「可计划的发布」；做不好的，升级是「事故」。从今天起给 API 立好版本规矩，你的客户会感谢你。想先体验一个「版本演进不用操心」的聚合平台？注册 DrAI，上游模型怎么变，你的代码都不用慌。