模型下线后怎么迁移？保留提示词与任务验收基线
从模型下线、改名、权限变化和隐式回退中区分真实原因，建立可复现的提示词与任务基线，按映射、隔离验收、灰度和账单对账完成可回滚迁移。
模型下线、改名或别名失效时，最容易出问题的不是把 model 字段换成一个新字符串，而是旧提示词、输出格式、工具调用和验收标准一起失去可比性。本文给出一套可回滚的迁移流程：先确认生命周期事件，再固定替代模型和映射规则，保留任务基线，最后用隔离流量与账单记录验收。
本文讨论通用 API 网关和客户端接入，不判断任何中转站是否可靠，也不把搜索报告中的品牌、型号或“推荐”措辞当作事实。官方模型目录和弃用页面会随时间变化；写作时只核对了官方资料的页面结构，实际切换仍应以你的供应商、账户和目标版本公告为准。迁移示例使用本地模拟响应，不调用付费 API。
1. 先判定是下线、改名、权限变化还是路由替换
“模型不能调用”可能来自四种完全不同的事件。先把错误时间、请求路径、精确模型 ID、HTTP 状态、响应正文、渠道分组和客户端版本记录下来，再比较变更前后的相同请求。不要看到 404 就直接把模型名改成搜索结果里的近似名称。
| 现象 | 更可能的原因 | 第一份证据 | 不应直接得出的结论 |
|---|---|---|---|
| 模型 ID 返回不存在或已弃用 | 上游下线、版本终止或网关仍保存旧 ID | 官方模型生命周期说明、网关原始错误 | 新 ID 一定与旧模型等价 |
| 列表里没有旧模型，但已有请求仍成功 | 列表缓存、别名或渠道权限差异 | 同一密钥的列表与实际请求时间戳 | 列表缺失就是立即下线 |
| 同一 ID 在一个分组成功、另一个分组被拒绝 | 分组、账户或区域权限变化 | 分组、密钥和上游响应的关联日志 | 服务商把模型整体下线 |
| 请求成功但输出、工具或 JSON 结构变化 | 路由到了替代模型、版本默认值变化或适配器改写 | 返回中的模型字段、网关路由日志和结构化断言 | 只是温度或提示词造成差异 |
先查上游的正式模型页面、弃用公告和网关自己的渠道变更记录。OpenAI 的官方模型目录位于 Models，Anthropic 的模型说明和终止计划分别见 Models overview 与 Model deprecations。这些页面能说明厂商公开的 ID、生命周期或迁移提示，但不能证明你的中转账户、别名映射或实际配额已经同步。
把证据分成“已确认”“仅网关显示”“待供应商确认”三栏。若只有群消息、排行榜或一个成功的短问答，不要把它写成下线事实。相关的模型找不到排错可参考模型列表有但仍不能调用；那篇处理名称、路径和权限，本篇继续处理生命周期变化后的迁移与验收。
2. 冻结旧版本的可复现基线
迁移前先保存旧任务的输入、关键选项和可接受结果。不要只保存一段“你好”，因为它无法暴露工具参数丢失、长上下文截断、结构化输出漂移或安全边界变化。
为每个真实任务建立一条基线记录：
- 记录客户端、SDK、网关、渠道和模型 ID 的版本或提交；对镜像保存 digest，避免
latest在两次测试间变化。 - 保存脱敏后的提示词模板、系统指令、变量样例和停止条件。密钥、个人数据、客户文本和完整业务数据不能直接放入仓库。
- 为答案、JSON、工具调用和错误响应定义断言。固定字段名、类型、枚举值、结束原因和必需的工具参数，而不是只比较全文字符串。
- 记录成本和延迟的测量口径：首字时间、总时长、输入输出计量、重试次数和失败是否计费。没有账单证据时，不把 HTTP 状态推断成扣费结果。
- 为质量保留少量经过授权的代表性样本，并标注预期行为、不能接受的行为和人工复核点。样本集的用途是比较迁移前后，不是宣称模型排名。
把基线输出存成带版本号的 JSON，例如 baseline-2026-10-23.json，同时写入哈希和采集时间。若提示词或工具定义也变化，就生成新基线，而不是把差异归咎于模型。已有的模型回退控制清单可帮助确认网关是否在失败时悄悄改走备用模型；迁移验收必须把这种隐式路由排除或明确记录。
3. 选择替代模型并建立显式映射
替代模型应从任务能力出发，而不是从名称相似出发。先列出硬约束，再列出可以接受的变化：上下文长度、工具调用、结构化输出、流式协议、图像或文件输入、延迟、成本和数据保留要求。某项能力在官方页面没有说明时，标记为“待确认”，不要填成“支持”或“不支持”。
建议维护一张映射表：
| 旧 ID | 替代 ID | 映射生效范围 | 必须复测的变化 | 回滚条件 |
|---|---|---|---|---|
legacy-model | replacement-model | 仅测试分组 | 输出格式、工具调用、长上下文、费用 | 任一硬约束失败 |
| 旧别名 | 固定版本 ID | 生产新请求 | 别名解析、权限、日志中的真实模型 | 无法在日志确认真实 ID |
| 渠道 A 的旧 ID | 渠道 B 的目标 ID | 单一租户或应用 | 认证、区域、计量和错误码 | 账单或审计字段缺失 |
映射应由配置管理，而不是散落在多个客户端。每次请求在日志中保留“客户端请求 ID、网关接收 ID、实际发送 ID、渠道和尝试序号”，并脱敏保存。若网关自动回退，必须让调用方知道是否发生了回退；不能用成功状态掩盖模型变化。参数被适配器丢弃时，按API 参数被忽略的排查方法逐项确认，而不是用更多提示词补救。
不要把旧账户密钥、余额或历史直接复制到新服务商。账户资产和配置迁移是另一类问题，参见更换服务商的迁移清单；它不能证明模型 ID、计费单位或权限在新渠道仍然兼容。
4. 用隔离环境先跑“任务级”验收
先创建独立的测试分组、测试密钥和本地模拟上游。模拟器返回固定的正常、流式中断、工具调用、结构化错误和超时场景，验证客户端与网关的状态机；它不能证明真实模型质量、上游配额或供应商账单。不要为这篇教程安装生产依赖，也不要用真实付费 API 试错。
验收矩阵至少包括：
| 任务 | 本地检查 | 通过条件 |
|---|---|---|
| 普通文本 | 固定输入，比较必需字段和结束原因 | 结构、编码和错误分类保持可处理 |
| 流式输出 | 模拟分片、延迟、断流和重试 | 不重复拼接，不把半截结果标成成功 |
| 工具调用 | 模拟工具选择、参数校验和返回结果 | 工具名、参数类型、调用顺序可解析 |
| 结构化输出 | 返回合法与故意损坏的 JSON | 校验失败进入明确错误路径，不静默修复 |
| 长任务 | 使用脱敏样本测试上下文边界和超时 | 截断、超时、重试都能观测和回滚 |
| 权限与账单 | 用受限测试密钥和固定模拟用量 | 禁止模型被拒绝；本地记录能关联每次尝试 |
每项都保留旧模型与替代模型的结果、请求哈希、实际模型 ID、耗时和错误。全文相似度只能作为辅助信号；工具参数、JSON 类型、引用来源和安全拒答等硬约束应单独断言。发现差异时，先判断是提示词、网关转换、别名、采样参数还是模型本身，不能只看最终文本。
5. 灰度、回滚与上线后的观察
通过隔离验收后，将映射放入小范围灰度。按应用、租户或明确比例切分，请求同时写入旧基线所需的观测字段；不要把同一笔真实付费请求无提示地复制到两条生产线路。灰度期间持续观察失败率、结构化校验失败、工具调用成功率、重试次数、P95 延迟、输入输出用量和每个实际模型 ID 的扣费记录。
预先写好停止条件，例如连续窗口内硬约束失败、错误率超过业务阈值、预算偏差无法解释或审计字段缺失。达到条件时先停止扩大流量，再切回仍然可用的旧映射；如果旧模型已经彻底下线，回滚只能回到最后一个通过验收的替代版本，不能凭空恢复上游能力。回退行为可参考控制 API 模型自动回退，但要为本次迁移保存独立的映射和阈值。
上线后再做一次账单与日志对账：按请求 ID 统计尝试次数，核对失败请求、重试和缓存的计量口径，确认没有把灰度流量计入错误账户。观察窗口结束后，将最终模型 ID、提示词版本、验收结果、已知差异和下一次复核日期写入变更记录。这样下一次模型下线时，团队拥有可复用的任务基线，而不是重新从一条成功问候开始猜测。
参考资料
- OpenAI Models：官方模型目录与能力说明入口，具体可用性仍以账户和接口响应为准。
- Anthropic Models overview：模型能力与版本说明入口。
- Anthropic Model deprecations：弃用和迁移通知入口。