AI 模型弃用与版本控制：保持 API 集成稳定

AI 模型弃用与版本控制是一种实践，旨在追踪您的集成调用了哪些模型标识符、提供商如何随时间推移停用或更改这些标识符，以及您如何保护产品免受这些变更的影响。如果处理不当，常规的提供商更新可能会演变成计划外的停机或输出质量的隐性偏差。

当团队在单个产品中调用多个前沿模型和开源权重模型时，这一点尤为重要。六个月前作为编码智能体首选的模型，今天可能已被替换、重命名或重新定价，而那些假设标识符保持稳定的集成往往会最先崩溃。

关键要点

• 模型弃用遵循提供商的时间表，而非您的时间表。锁定版本化的模型标识符（而非滚动别名）是防止行为发生隐性变更的主要防御手段。
• 自动升级到提供商的默认或“latest”别名是以稳定性换取时效性。仅在拥有能够拦截输出和成本回归的测试套件的情况下才这样做，以确保其在进入生产环境前经过验证。
• TokenLab 的模型目录和 Model Data Center（/models 和 /models/data）发布了按提供商分类的模型标识符列表，开发人员在审计集成实际调用的版本时，可以将这些列表作为参考点。
• 具备弃用弹性的集成会将模型标识符保留在配置或路由层中，与应用程序逻辑分离，这样当收到停用通知时，只需修改一个值，而无需搜索整个代码库。

API 集成中弃用和版本控制的实际含义

对模型 API 的每次请求都包含一个模型标识符（例如 gpt-5.5 或 claude-sonnet-5 这样的字符串），用于告知提供商运行哪个检查点。在模型的生命周期中，这些标识符会发生三种不同的情况：

版本控制 (Versioning)。 提供商会发布带日期或编号的快照（在特定时间点冻结的特定检查点），以及滚动别名（如“latest”这样的名称，它会静默指向提供商当前推荐的检查点）。调用别名意味着您的集成行为可能会在您无需更改代码的情况下发生变化。

弃用 (Deprecation)。 提供商宣布某个特定的模型标识符在特定日期后将停止服务。在该日期之后发出的请求通常会返回错误，而不是路由到替代模型。

停用或下线 (Retirement or sunset)。 标识符被完全移除。一些提供商会在过渡期内将旧标识符重定向到较新的默认模型；另一些则不会。具体行为取决于提供商且会随时间变化，因此在依赖它之前，请务必直接在各提供商的文档中核实当前政策。

理清这三个概念是将模型选择视为运营依赖项（而非发布时的一次性决策）的第一步。

提供商关于模型请求的文档说明

根据 OpenAI 的 API 快速入门文档（观察于 2026-07-14），Responses API 的请求在请求体中将模型指定为字符串参数，并附带输入内容。这证实了开发人员所依赖的基本机制：模型标识符只是请求中传递的数据，而不是内置在 SDK 版本或端点 URL 中的内容。这对版本控制策略来说是个好消息，因为它意味着在请求层面，切换模型只需修改一行代码。

快速入门页面未涵盖的是弃用政策本身：确切的停用日期、过渡窗口，或者旧标识符在截止日期后是报错还是重定向。这些细节存在于每个提供商的模型或弃用文档中，并且变化频繁，因此本文不会重申具体日期。如果您的集成依赖于弃用时间表，请在发布前根据提供商当前发布的政策进行确认，而不是参考博客文章。

OpenAI 的弃用页面提供了一个具体示例。其 2026-06-11 的通知给出了旧版 GPT-5 和 o3 快照的 2026-12-11 停用日期，明确了受影响的 ID（包括 gpt-5-2025-08-07 和 o3-2025-04-16），并列出 gpt-5.5 作为两者的推荐替代方案。请按此顺序阅读弃用条目：公告日期、停用日期、确切受影响的模型 ID，然后是替代方案。在应用程序代码和配置中搜索受影响的 ID，将停用日期与您的部署时间表进行比较，并在该日期之前完成替换测试。

这种相同的请求形态模式（模型字符串加输入）在各大提供商中都很常见，尽管具体的字段名称、默认值和版本控制约定有所不同。请将任何其他提供商的行为视为需要在其自身文档中验证的内容，而不是从 OpenAI 的示例中进行推断。

弃用风险在何处导致生产集成中断

在实践中，弃用和版本控制问题通常表现为以下几种重复出现的模式：

• 滚动别名导致的隐性偏差。 集成调用的是通用别名而不是带日期的版本。提供商将别名更新为新的检查点，而针对旧模型调整的提示词开始产生不同的语气、长度或工具调用行为，且没有任何错误或日志条目可供追踪。
• 锁定版本的硬性截止。 锁定的带日期模型标识符被停用。请求开始返回 4xx 类错误，如果该标识符在代码库中多处使用，修复所需的时间将超出预期。
• 与版本绑定的上下文窗口和定价变更。 新的模型版本可能会带来不同的上下文限制或 Token 定价，这会改变成本，在某些情况下还会改变长运行智能体在单次调用中可容纳的内容。
• 编码智能体和工具调用格式在版本间切换。 工具调用和函数调用模式在不同模型版本间可能会有细微变化，这对构建在 Claude Sonnet 5、Kimi K2.7 Code 或 DeepSeek V4 Pro 等模型上的编码智能体来说是一个特殊风险，因为这些集成依赖于模型可靠地输出结构化工具调用。

这些故障模式都不需要提供商做出任何异常举动。它们将模型标识符视为固定常量而非版本化依赖项所导致的必然结果。

弃用弹性集成的检查清单

在发布或审查模型集成时，请将此作为工作检查清单。

• 模型标识符位于单一配置层（环境变量、配置文件或路由服务）中，而不是分散在调用点。
• 生产流量使用提供商提供的带日期或版本化的标识符，而不是不合格的“latest”别名，除非您已明确选择接受偏差以换取自动更新。
• 拥有一个自有流程（日历提醒、依赖追踪工单或监控警报）来检查每个提供商的弃用通知，因为这些通知通常会提前发布，而不是立即生效。
• 至少为您最高流量的调用点存在回退模型或路由路径，以便在硬性截止时服务降级，而不是直接中断。
• 在版本变更进入生产环境之前，针对任何候选替代模型运行提示词和工具调用测试套件，特别是对于编码智能体和结构化输出流程。
• 每次模型版本变更时，不仅要检查正确性，还要重新核实成本和上下文窗口假设。
• 团队中有人无需搜索代码即可回答当前每个生产调用点正在使用哪个确切的模型标识符。

示例：锁定与回退路由

锁定特定版本并定义明确的回退是一种简单的模式，可以消除大部分运营层面的意外。下面的示例展示了配置驱动方法的形态：模型标识符是一个值，而不是请求逻辑中硬编码的字符串。

# model_config.py
MODEL_CONFIG = {
    "primary_chat": {
        "provider": "openai",
        "model": "gpt-5.5",          # 锁定到特定的、有文档记录的标识符
        "fallback": "claude-sonnet-5" # 如果主要模型报错或已停用则使用此模型
    },
    "coding_agent": {
        "provider": "anthropic",
        "model": "claude-sonnet-5",
        "fallback": "deepseek-v4-pro"
    },
}

# request.py
import requests
from model_config import MODEL_CONFIG

def call_model(task_key: str, input_text: str):
    cfg = MODEL_CONFIG[task_key]
    try:
        response = requests.post(
            "https://api.openai.com/v1/responses",
            headers={"Authorization": "Bearer $OPENAI_API_KEY"},
            json={"model": cfg["model"], "input": input_text},
            timeout=30,
        )
        response.raise_for_status()
        return response.json()
    except requests.HTTPError as err:
        if err.response.status_code in (404, 410):
            # 模型标识符已停用或未找到：执行故障转移
            return call_model_with_id(cfg["fallback"], input_text)
        raise

这仅作说明之用，并非开箱即用的库。请求 URL、标头和错误代码因提供商而异，在生产环境中使用此模式之前，请务必根据 OpenAI API 快速入门等当前提供商文档确认确切的请求形态和错误语义。

决策表：锁定、别名或路由

策略	含义	适用场景	主要风险
锁定到带日期版本	调用确切的、版本化的模型标识符	受监管或高风险流程，输出一致性比保持最新更重要	提供商停用该版本时出现硬性截止；需要自有升级流程
使用提供商的滚动别名	调用如“latest”这样的通用名称，提供商会随时间重定向它	低风险、高容忍度的用例，如内部工具或草稿生成	隐性行为和成本偏差，且没有代码变更来标记它
通过配置或网关层路由	应用程序调用内部名称；该层将其解析为提供商模型，并带有回退逻辑	多模型产品、编码智能体，或在 GLM-5.2、Qwen3.7 Plus 或 Gemini 3.5 Flash 等模型间进行比较的团队	维护路由层本身增加了运营复杂性

对于大多数调用多个模型或提供商的生产集成，路由层值得增加复杂性，因为它将弃用通知转化为配置变更，而不是代码审计。

TokenLab 如何呈现模型版本信息

TokenLab 的 模型目录 和 Model Data Center 按提供商列出了模型标识符，开发人员在审计集成当前调用内容以及跨类别（如前沿文本模型、编码智能体、低成本路由、图像生成和视频生成）存在哪些替代方案时，可以将这些列表作为参考点。这是一个列表展示界面，而非弃用通知服务，因此它不能替代直接检查每个提供商自身的弃用政策。对于那些思考如何使模型元数据在不断演进的模型领域中保持机器可读的团队，智能体可读的模型真相 中的讨论以及 智能体优先的 API 设计 的更广泛论点，涵盖了结构化、最新的模型数据对人类开发人员和代表他们调用这些 API 的智能体为何重要的相关内容。

局限性

本文基于 OpenAI API 快速入门中记录请求参数的方式以及 TokenLab 公共模型界面的结构，描述了模型版本控制和弃用的一般模式。它没有说明任何模型的具体弃用日期、停用窗口或定价变更，因为这些细节由提供商控制、变化频繁，且未在本文使用的来源中确定。在依赖特定的截止日期或回退行为之前，请直接根据相关提供商的当前文档进行确认。

常见问题解答

锁定模型版本是否保证它永远不会被弃用？ 不。锁定到特定的带日期标识符可以避免滚动别名带来的隐性偏差，但提供商仍可能在其自己的时间表上停用该特定版本。锁定为您带来的是可预测的故障模式（在已知日期报错），而不是不可预测的故障模式（隐性行为变更）。

我如何知道我所依赖的模型何时会被弃用？ 请直接查看特定提供商自己的文档以及弃用或变更日志页面，因为时间表是特定于提供商的且会发生变化。将任何第三方摘要（包括本文）视为验证的起点，而不是确切日期的来源。

我应该始终使用可用的最新模型版本吗？ 不要自动这样做。较新的版本可能会更改输出格式、工具调用行为、上下文窗口或成本。在切换生产流量之前，请针对您现有的提示词和工具调用套件测试候选替代模型，特别是对于编码智能体和结构化输出工作流。

要检查模型 ID 是否仍被列为当前版本，请使用 TokenLab Model Data Center 作为时间点标识符参考。它不是提供商文档或弃用通知服务，因此请根据提供商自己的通知确认停用日期。