AI API 网关的模型弃用操作手册：生命周期结束前的清点、测试、迁移和回滚

硬编码模型 ID 是安静的生产依赖项。它们会一直工作，直到提供商重命名端点、停用过时的快照、更改别名、删除预览模型或引入 API 级别的不兼容性。故障很少表现为一次干净的中断。它表现为架构故障、更高的延迟、意外拒绝、不同的工具调用参数、成本变化或来自租户（其工作负载在仓促迁移后表现不同）的客户票证。

实际的解决方法是将模型 ID 视为托管依赖项，而不是应用程序代码中的静态字符串。在 AI API 网关中，这意味着构建可重复的模型弃用操作手册：清点、检测、评估影响、测试替换、影子流量、逐步推出，并在兼容性中断时快速回滚。

事实、建议和预测

事实：主要模型提供商发布模型目录、版本控制指南、弃用通知和迁移指南。这些资源表明模型可用性不是静态的。一些提供商将便利别名与特定模型 ID 区分开来，并且一些迁移可能包含破坏现有集成的 API 级别差异。

建议：将模型生命周期控制置于网关内。向应用程序团队公开逻辑模型名称，集中跟踪提供程序模型的使用情况，监控弃用源，并在切换生产流量之前运行兼容性测试。

预测：模型生命周期操作将成为 AI 平台工程的正常组成部分。运行多提供商系统的团队将越来越需要模型的依赖样式控制：版本库存、更改窗口、回归检查、回滚计划和客户通知。

失败模式：提供者模型 ID 分散在应用程序代码中

常见的实现很简单：

<前><代码>{ “模型”：“provider-model-preview-2025-06”， “消息”：[ {"role": "user", "content": "将发票字段提取为 JSON。"} ] }

这对于原型来说很容易，但在生产中却存在风险。模型字符串可能会在后端服务、脚本、低代码工作流程、内部工具、客户集成和合作伙伴产品之间重复。当模型接近报废时，没有一个所有者可以回答基本问题：

• 哪些 API 密钥仍在向其发送流量？
• 哪些租户依赖于 JSON 架构、工具调用、流式传输、视觉、音频或长上下文？
• 每日支出和收入敞口是多少？
• 哪些工作负载可以容忍更便宜的模型，哪些需要进行质量审核？
• 团队可以在不重新部署每个应用程序的情况下进行回滚吗？

网关是解决此问题的自然场所，因为它已经看到请求、密钥、租户、提供商、成本、延迟和故障。

第 1 步：创建模型库存表

从耐用的库存开始。不要仅依赖提供商仪表板，因为您需要自己的租户、密钥、计费和工作流程上下文。

实用的model_inventory表可以包括：

逻辑模型名称支持快速
提供商provider_a
provider_model_id model-x-preview-2025-06
端点类型聊天完成
别名_状态 pinned_snapshot |供应商别名 |内部别名
状态活跃 |已弃用 |被封锁 |退休了
replacement_candidates [“支持快速v2”，“支持平衡”]
first_seen_at 时间戳
Last_Seen_at 时间戳
deprecation_announced_at 时间戳
shutdown_at 时间戳
admin_override 文本
Owner_team支持平台

然后将其与使用数据结合起来。对于每个提供者模型和逻辑模型，跟踪：

• 启用的租户和 API 密钥
• 每天的请求数和每天的令牌
• 支出、利润或内部成本分配
• 延迟百分位数，而不仅仅是平均值
• 5xx 率、提供商错误率、超时率和重试率
• 结构化输出使用情况和架构失败率
• 工具调用的使用和工具执行的副作用
• 流媒体使用
• 文本、图像、音频和文件输入等模式
• 上下文长度分布

此清单将弃用公告从恐慌转变为查询。

第 2 步：通过逻辑模型名称进行路由

应用程序团队不需要了解每个提供商的模型生命周期规则。为它们提供代表工作负载意图的稳定逻辑名称：

• 快速支持
• 支持质量
• 编码高级
• 发票提取器-v2
• 内容审核默认

网关将这些名称映射到提供商模型 ID：

<前><代码>{ "逻辑模型": "发票提取器-v2", “路由策略”：{ “主要”：{ “提供商”：“provider_a”， “模型”：“模型-x-stable-2025-09” }, “约束”：{ “requires_json_schema”：正确， “最大输入令牌”：64000， “地区”：“欧盟” } } }

这并不意味着隐藏所有提供商详细信息。这意味着将特定于提供商的功能放入网关元数据中，而不是通过产品代码分散它们。一个好的抽象说明了应用程序想要什么和提供者实际上可以做什么。

第 3 步：按计划操作监控弃用

弃用监视器应按计划运行并支持手动覆盖。它应该检查提供程序模型目录、弃用页面、更改日志、发行说明和内部管理条目。并非每个生命周期信号都可以通过干净的机器可读 API 获得，因此允许操作员添加或更正日期。

当监视器检测到生命周期事件时，创建内部记录：

provider_model_id：model-x-preview-2025-06
状态：已弃用
关机时间：2026-02-15
推荐的替代品：
  - 模型-x-稳定-2025-09
  - 型号-y-mini-2025-10
源类型：provider_deprecation_page
信心：确认

然后自动触发影响分析。弃用通知不应出现在聊天频道中，除非有人记得对其进行调查。

第 4 步：生成影响报告

影响报告对于工程、财务、支持和合作伙伴团队来说应该足够具体。包括：

• 已弃用的提供程序模型和受影响的逻辑名称
• 关闭日期和建议的决策截止日期
• 受影响的租户、团队和 API 密钥
• 每日请求量和代币量
• 每日成本、客户结算风险以及利润影响（如果适用）
• 使用该模型的主要端点或产品
• 提示类别或已保存的提示模板
• 使用 JSON 架构、函数或工具调用、流式传输、图像、音频、文件或长上下文
• 当前延迟百分位数和错误率
• 已知的合同或数据驻留限制

对于合作伙伴 API 用户，公开此元数据的过滤版本，以便代理机构、经销商和嵌入式 AI 产品制造商可以在提供商关闭影响下游服务之前向自己的客户发出警告。

第 5 步：按能力构建替代候选名单

不要仅根据品牌名称选择替代品。根据工作量对候选人进行评分。

<表> <标题> 标准要回答的问题 <正文> 上下文窗口它能处理当前的p95输入长度加上预期的增长吗？ 结构化输出它支持工作流程所需的架构行为吗？ 工具调用工具名称、参数形状和调用顺序是否兼容？ 模式是否支持所需的文本、图像、音频、文件或流输入？ 延迟能否满足路由p95或p99的超时预算？ 成本预期的输入、输出和重试成本是多少？ 安全行为拒绝模式会破坏合法的工作流程吗？ 区域和保留是否满足特定于租户的合规性约束？

最新的旗舰型号并不总是最好的替代品。较小的较新模型可以保留大容量工作负载的延迟和成本。对于复杂的编码、提取或推理工作流程，可能需要更强大的模型。 Runbook 应该明确这一点，而不是默认将每次弃用都转变为升级。

第 6 步：运行兼容性评估包

在更改生产路线之前，运行反映实际工作负载风险的评估包。

最小评估集

• 黄金提示：具有预期特征的稳定示例，不一定是一个确切的答案。
• 架构有效性测试：JSON 解析成功、必填字段、枚举值、长度限制和嵌套对象检查。
• 工具调用测试：正确的工具选择、有效的参数、无不安全的重复副作用。
• 安全和拒绝检查：确认合法业务请求仍然完成。
• 成本比较：输入令牌、输出令牌、重试和任何重复调用。
• 延迟比较：p50、p95、p99、超时率以及相关的流式传输第一个令牌延迟。
• 人工审核：对于自动检查不足的高价值或不明确的工作流程是必需的。

对于结构化工作流程，单一的自然语言质量得分是不够的。替换必须产生下游代码可以解析和信任的输出。

第 7 步：安全地影子生产流量

影子测试意味着将生产请求样本复制到候选模型，同时仅将当前模型的答案返回给用户。单独存储候选答案以进行比较。

如果route.shadow_enabled和request.is_safe_to_shadow：
    Primary_response = 调用（当前模型，请求）
    enqueue_shadow_call（候选模型，请求，trace_id）
    返回primary_response

不要对所有内容进行阴影处理。避免重复包含副作用工具调用的请求，除非工具执行层被禁用或模拟。请小心敏感数据、保留规则和租户合同。影子测试增加了临时代币支出，但它提供了来自真实提示的证据，而不仅仅是精心挑选的测试用例。

比较阴影结果：

• 架构有效性
• 工具调用兼容性
• 输出长度
• 每次成功请求的费用
• 延迟分布
• 拒绝和错误模式
• 特定任务的审核结果

第 8 步：推出基于百分比的路由

当候选人通过评估后，逐步推出。首选通过租户、密钥或逻辑模型在网关进行路由控制，而不是重新部署每个应用程序。

保守序列：

1. 仅限内部租户
2. 符合条件的生产流量的 1%
3. 5%
4. 25%
5. 50%
6. 100%

在推出开始之前定义回滚阈值：

<前><代码>rollback_if： schema_failure_rate_increase：">1.0 个百分点" provider_5xx_rate：">2x 基线" p95_latency_increase："> 30%" cost_per_successful_request: ">超出批准预算 25%" tool_argument_validation_failures："> 0.5%" tenant_blocklist_hit：“任何关键租户”

阈值应根据工作负载进行调整。与发票提取管道相比，聊天机器人通常可以容忍更多的措辞变化。后台摘要作业可能比交互式支持助理容忍更高的延迟。

第 9 步：在迁移期间保留账单归属

如果网关仅记录提供商模型 ID，模型迁移可能会扭曲使用情况分析。保留逻辑和物理模型维度：

<前><代码>tenant_id api_key_id 逻辑模型名称 提供者 提供商型号 ID 迁移ID 输入令牌 输出令牌 供应商成本 客户费用 延迟时间 状态 schema_valid

migration_id 很重要。它可以让财务和支持人员在推出窗口期间比较新旧行为。如果替换型号价格更高，企业可以决定是否吸收差价、更新定价、将部分租户转移到较小的型号，或者需要客户批准。

第 10 步：保留审核日志和回滚计划

每次迁移都应该留下记录：

• 已弃用的型号和替换型号
• 受影响的逻辑模型名称
• 决策所有者和审批者
• 影响报告链接
• 评估结果
• 影子流量摘要
• 发布时间戳
• 回滚阈值
• 客户或合作伙伴通知
• 最终状况和经验教训

回滚计划应该是可操作的，而不是空想的。如果旧的提供商模型即将关闭，回滚可能意味着路由到第二个替代候选者、禁用某个功能、使用更严格的提示或暂时限制受影响的租户。在切换之前记录可用选项。

管理权衡

• 固定模型 ID 可以提高再现性，但会增加快照停用时的报废风险。
• 提供商别名可以减少维护，但可能会改变应用程序下的行为，因此它们需要回归监控。
• 网关级抽象简化了迁移，但可以隐藏提供商特定的功能，除非功能元数据是明确的。
• 影子测试可以提高信心，但会增加临时令牌支出，因为请求是重复的。
• 自动迁移可降低中断风险，但如果仅根据价格或通用基准分数选择替代品，则可能会造成语义回归。
• 每租户覆盖可保护重要客户，但会增加运营复杂性和支持负担。
• 严格的兼容性门可保护结构化工作流程，但可能会减缓需要及时或架构更改的更好模型的采用。

实施清单

• 创建提供程序模型和逻辑模型名称的中央清单。
• 尽可能阻止应用团队提供直接提供商模型 ID。
• 添加提供商生命周期监控和手动管理员覆盖。
• 为每个弃用事件生成影响报告。
• 根据功能、成本、延迟、合规性和兼容性对替换进行评分。
• 运行黄金提示、架构检查、工具调用检查、安全检查和成本比较。
• 在暴露替换之前隐藏安全生产流量。
• 按租户、密钥或百分比以及预定义的回滚阈值进行部署。
• 在使用情况分析中跟踪逻辑模型、提供商模型和迁移 ID。
• 当下游客户受到影响时，通过面向合作伙伴的 API 公开弃用元数据。

可行的结论

设计模型弃用流程的最安全时间是在下一次关闭通知之前。从一条规则开始：应用程序请求逻辑模型名称，并且网关拥有提供者映射。然后围绕该规则添加操作层：库存、监控、影响报告、评估、影子流量、分阶段部署、回滚和审核日志。

这将模型迁移从最后一刻的字符串替换转变为托管依赖项工作流程。目标不是永远冻结模型行为。目标是在保持质量、成本、延迟、结构化输出行为和计费归属的同时刻意更改模型。

相关阅读

• 结构化输出和工具调用兼容性检查
• LLM API 的路由控制和回滚行为
• 面向合作伙伴的租户和使用情况元数据