模型下线不是意外：把 deprecation 变成计划内的事

一个典型的早晨

7:40，监控报警：核心接口 500。日志里一行：

{"error":{"message":"model_not_found","type":"invalid_request_error"}}

昨天还好好的。你没有改代码，没有升级 SDK，没有换 Key。唯一变化的是上游把那个模型下线了。

这件事每年在每个团队都会发生若干次，而它本来完全可以不发生 —— 因为模型下线从来不是意外：厂商会提前发公告，中转站会收到通知，只是没人把它转成你代码里的一个待办。

下线沿三层传导

第一层：厂商弃用

主流厂商都会给通知期：Anthropic、OpenAI、Google 通常在文档里挂 deprecations 页面，给 3~12 个月；国产厂商周期普遍更短，常见 1~3 个月。

这一层的特点是：信息是公开的，但你不会主动去看。

第二层：中转站移除路由

厂商下线后，中转站模型列表里那条记录会消失。问题在于三种做法差别极大：

• 有些站提前公告，有些站直接消失；
• 有些站保留旧模型名，静默转发到新模型 —— 对你是好事，但你不知道输出已经变了；
• 有些站保留旧名但返回 404，且不告诉你替代品是什么。

这三个分支的差别，决定了你的代码崩不崩。

第三层：你代码里硬编码的模型名

resp = client.chat.completions.create(model="claude-sonnet-5", ...)

这一行是最后一道防线，也是唯一你能完全控制的一层。

先清点自己家里的模型名

在谈迁移之前，先回答一个基本问题：你的项目里一共有多少个模型名？分别在哪些文件里？

# 按自己的命名习惯调整这条正则
grep -rhoE '"(gpt|claude|gemini|qwen|glm|kimi|deepseek|grok|doubao)[a-zA-Z0-9._-]*"' \
  --include=*.py --include=*.ts --include=*.js --include=*.go . \
  | sort | uniq -c | sort -rn

做完这一步，你通常会得到一个比预想更长的清单 —— 包括测试文件、注释、CI 配置，以及某位已经离职的同事留下的脚本。

然后给每一条补上四个字段：

这张表不需要工具，一个 Markdown 文件就够。它的价值不在于好看，而在于下次 404 的时候你有一张表可以查。

要问中转站的四个问题

1. 下线前会不会通知，走什么渠道？ 邮件、站内公告、API，还是完全不通知。
2. 旧模型名会保留多久？ 是立刻 404，还是先转发到替代模型再下线。
3. 有没有 alias？ 比如 claude-sonnet-latest 这种不带小版本的名字。有 alias 意味着厂商换小版本时你不用改代码。
4. 下线后还能不能查历史用量？ 对账和成本回溯需要。

第 3 条性价比最高。用 alias 能省掉大部分迁移工作 —— 但前提是你测过它真的跟着上游走，而不是写死指向某个版本。测法很简单：记下 alias 当前返回的模型标识（多数接口会在响应里带 model 字段），过两周再看一次，变了就说明它在跟随。

迁移不是改个名字

这是最容易低估的一步。换模型后，下面六件事都可能变：

这六项里，只有价格和延迟会被常规监控发现。 其余四项如果不主动测，会以「偶发失败」「输出变短」的形式慢慢显现。

灰度双跑：把风险摊到一周里

不要一次性全量切换。可行的顺序：

1. 影子模式：新模型接在同一份输入上跑，结果只记录不返回，跑 3 天，比对输出差异率；
2. 小流量：5% 流量走新模型，观察错误率与延迟；
3. 按场景切换：先切低风险场景（摘要、分类），后切核心对话；
4. 保留回滚开关：模型名必须能从配置里改，不能硬编码 —— 这是整件事的前提。

第 1 步的差异率怎么算：对同一批 200 条真实输入，让两个模型各跑一遍，人工抽检 20 条。差异率高于 15% 时不要切，先搞清楚差异是「更好」还是「跑偏了」。

小结

1. 模型下线不是故障，是没有转成待办的公告；
2. 它沿「厂商 → 中转站 → 你的代码」三层传导，任何一层没预案都会炸；
3. 先清点自己代码里的模型名，做成一张带「最晚切换日」的表；
4. 优先用 alias，但要验证它真的在跟随上游，而不是写死；
5. 迁移要检查六项，常规监控只能覆盖价格和延迟；
6. 灰度双跑的最小可行版本是「影子模式 3 天加 5% 小流量」，回滚开关是前提。