API 换模型只改 model 就够吗？已有应用的上线验收与回退检查
已有应用更换模型或 API 提供方，一次请求成功不足以判断可以上线。 除了基础协议，还应检查应用依赖的输出、工具动作、文件和会话状态，再决定哪些任务先切换、何时停止，以及能否退回仍可用的旧路径。改变 model 或 base_url 只是配置变更的一部分。
本文面向已经运行的应用，解决发布切换与回退任务；首次选服务可看API 选型指南。官方资料核对于 2026 年 11 月 5 日。以下是工程检查建议与空白台账，没有执行真实迁移，也不代表任何候选服务已通过验收。
先冻结这次到底改了什么
给变更分配一个编号，把旧、新配置分别保存。不要把密钥值写进台账；记录受控的凭证引用即可。
| 配置类别 | 至少记录什么 | 为什么要保留旧值 |
|---|---|---|
| 调用路径 | 提供方、端点、协议、区域（适用时） | 判断功能、资源和数据处理条件是否改变 |
| 模型与客户端 | 请求 model、已证实的版本说明、SDK/适配器版本 | 避免模型和解析器一起变，无法定位原因 |
| 行为输入 | 提示词、参数、工具结构、输入模板的版本 | 区分配置变化与模型输出波动 |
| 应用依赖 | 文件、会话、知识库、回调等实际使用项 | 判断哪些资源需要授权、重建或映射 |
| 发布责任 | 负责人、观察窗口、停止条件与回退目标 | 出现问题时能明确执行处理 |
一次只改变一个可分离因素，更容易定位差异。官方说明不同模型快照之间行为可能变化，建议使用可用的固定版本并做应用评估；API 结构兼容不等于生成结果不变。API 兼容性说明
请求中的别名、响应里的 model 和可核验的底层版本要分开填。拿不到云岚API某条渠道的具体快照证据时填“未知”，不能把一个看起来带版本的名称写成已固定的原厂版本。身份判断的边界见模型与服务验收。
把“不能坏的功能”写成验收契约
不要照抄一张通用功能大全。先列出当前应用确实依赖的行为，再为每项写输入、预期状态和可核对结果。下面的场景是建议，不是已经通过的测试：
| 实际依赖 | 应保留的行为 | 不能只看什么 |
|---|---|---|
| 结构化输出 | 必填字段、类型、拒绝与异常分支可识别 | HTTP 200 或肉眼看起来像 JSON |
| 流式展示 | 应用能区分进行中、完成、中断与错误 | 开始收到几个字符 |
| 工具写动作 | 参数经过校验，执行结果能核对且不重复 | 模型回复“已完成” |
| 文件或连续对话 | 目标路线能使用已授权资料，状态归属清楚 | 旧资源 ID 仍被传入请求 |
| 后台任务 | 状态、通知和最终结果能关联原任务 | 新接口能返回一个任务编号 |
具体协议步骤分别见结构化输出、流式响应和工具执行。本次发布应复用这些验收项，记录实际差异；未使用的功能不必为了清单完整而新增依赖。
OpenAI 关于跨提供方故障切换的官方文章也强调：同名模型和相似接口并不能证明功能可替换。其讨论的第三方模型供应商范围不等于为所有 API 中转服务背书；这里借鉴的是能力核对思路。跨提供方切换设计
先处理资源依赖，再测试连续任务
给每项依赖标明创建位置、所属账号、权限和目标路线是否可用。文件 ID、会话状态、向量库或回调配置都不能仅因接口格式相似就当作通用资源。只有实际使用的项目才进入迁移清单。
建议将依赖分成三类：可由应用重新构造的上下文、经允许后可重新上传或建立的资源、当前无法迁移的服务专属能力。第二类先核对资料是否允许发往目标服务；第三类应保留原路线或明确停止该功能，不能悄悄删掉后仍称迁移成功。
跨提供方改路由不会自动恢复已有状态或已经执行的动作。官方状态与恢复边界 日常上下文与权限问题可继续参考连续对话管理及资料访问检查。
先用固定任务回归，再给真实流量分组
用合成资料或已获准使用的样本，固定输入与业务通过条件。覆盖正常任务、边界输入、拒绝和依赖失败；对于生成文本，区分措辞变化与事实、格式、动作错误，不要求每次逐字一样。
先跑隔离测试。若需要把同一输入发送给新旧两条路线比较，确认两边的数据处理条件都允许；写入型工具应使用测试替身或隔离环境，不能让两条路线各给客户发一次消息。回归只比较答案而绕开实际解析器，仍不能证明应用已经兼容。
通过后按业务可接受的范围选一小组任务，再决定是否增加。组的大小、观察时长和通过阈值由应用负责人设定，本文不提供通用百分比。每次观察同时记录业务通过、错误类别、总等待、实际尝试次数和完成任务成本，不能只盯平均响应时间。
若新路线的容量尚未核对，先做共享 RPM/TPM 与队列预算，不要把所有生产流量当成第一次容量测试。
切换时，正在跑的任务由谁负责？
建议在任务开始时记录它使用的配置版本，并保持该任务的路由归属可追溯。会话也要有明确规则，避免上一轮使用旧提供方的状态 ID，下一轮随机发到另一端。确需切换进行中任务时，先确认可恢复状态和已执行动作，而非直接重发原始请求。
已经展示部分输出，或工具写入结果未知时，先核对实际业务记录；连接断开不证明服务没有执行。官方跨提供方设计文章特别区分尚未产生影响的失败与已经有部分结果的恢复。部分结果与动作恢复
台账应记录原任务 ID、配置版本、尝试次数、已交付输出、动作结果和下一步负责人。超时与去重细节见超时重试排查，不要把发布切换实现成无限跨服务重试。
回退开关存在，不代表真的退得回去
放量前先确认旧路径仍可用、权限未撤销、相关资源还在，并留出承接流量的容量。如果旧模型已经退役，保存旧配置文件也无法让它恢复；此时需要另一个经过验证的方案。
回退演练至少覆盖三种状态：尚未发出的任务、正在执行的任务、已经完成写动作的任务。第一类按既定路由规则安排；第二类先核对状态；第三类保留业务结果，不能因回退再执行一次。配置回退不会撤销已经发生的业务写入，补偿动作需要单独设计和授权。
出现契约不满足、资源不可用或业务结果无法确认时，应停止继续放量并处理原因。把“谁决定停止、谁执行、哪些任务保留原路径、怎样通知业务方”写清楚，比只有一个切换按钮更有用。
用发布台账做出可核对的决定
下载 API 模型迁移与回退验收表。包含变更冻结、功能契约、资源映射、隔离回归、分组切换、在途动作和回退检查；新旧结果及证据栏留空，不是完成记录。
如果准备把云岚API列为候选调用路径，先核对目标模型、协议与当前价格，再注册云岚API，按入门教程建立一条基础请求。之后用自己的应用契约逐项验证，满足条件再增加流量；注册和基础响应成功都不等于完成迁移。已有账号可直接进入控制台。