Claude 3.5 Sonnet 退役后,LiteLLM 迁移验收怎么做?(2026)
Anthropic 官方记录的退役日期是 2025 年 10 月 28 日:Claude 3.5 Sonnet 已不能作为现行生产端点,旧 API 请求不应再被视为可靠调用。迁移验收的获胜方案,是先按官方生命周期文档选定当前可用模型,再验证 LiteLLM 映射、实际编程客户端、代码任务和故障路由;只看到 HTTP 200,不足以放行。(docs.anthropic.com)
仍有 Claude 3.5 Sonnet 模型名或旧配置残留的开发者,可按清单排查并验收迁移。
通过 LiteLLM 统一接入模型的团队,可将本文的检查项纳入模型替换回归。
负责 AI 编程工具链稳定性的工程师,可据此判断客户端功能或任务表现是否退化。
先核实模型状态,再确定迁移目标
“退役”不是“暂时限流”:Anthropic 对模型生命周期的说明明确指出,已退役模型不再可用,针对它的请求会失败。官方记录显示,claude-3-5-sonnet-20240620 于 2025 年 10 月 28 日退役;应在发布前重新查阅生命周期页面,确认备选型号当时仍处于可用状态,不要沿用旧文章中的型号建议。(docs.anthropic.com)
⚠️ 旧别名仍能在客户端下拉列表、配置文件或日志中出现,只能说明该字符串还被保存或传递,不能证明它对应的上游模型仍可调用。迁移时要把“对外别名”和“实际模型 ID”分开核实。
先做一轮配置盘点,避免只修改最显眼的一处:
- 搜索应用配置、环境变量、部署参数和代码仓库,找出旧模型 ID 与团队自定义别名。
- 核对调用方请求中的
model是否对应预期的 LiteLLMmodel_name。 - 再核实
litellm_params.model的 provider 前缀和 API model ID,确认上游指向目标模型。 - 检查实际生效配置来自文件、数据库还是管理界面;若存在覆盖关系,确认修改已加载到运行中的网关。
| 核验层 | 应确认的内容 | 常见误判 |
|---|---|---|
| 客户端别名 | 请求传入的 model 值与网关公开名称一致 |
别名没改,就以为上游也没变 |
| 网关映射 | model_name 映射到预期的 provider 与 API model ID |
只看配置文件,不看运行时生效来源 |
| 上游状态 | 官方生命周期页面仍将目标型号列为可用 | 旧调用曾成功,就认为端点现在仍可用 |
| 变更记录 | 配置版本、模型标识与验收结果可追溯 | 只记录“已切换”,无法复原具体改动 |
LiteLLM 的模型管理文档区分了公开模型名、底层 provider 与映射信息;如果模型定义来自配置文件,变更也应按运行环境的加载方式生效。(docs.litellm.ai)
用真实客户端验证协议和功能
Claude API 迁移不能停在网关健康检查。开发环境里简单请求成功,仍可能掩盖流式响应被客户端误解析、工具调用没有完整往返,或特定参数被新模型拒绝等问题。Anthropic 的迁移与提示文档也提示,模型升级可能伴随行为和配置差异;具体参数支持范围应以目标模型及对应文档为准。(docs.anthropic.com)
按实际生产客户端跑一遍代表性请求,并保留请求与响应记录。下面的项目需要在客户端到 LiteLLM、再到上游的完整链路上检查,而不是只在网关内部调用:
- ✅ 认证:客户端使用的网关凭证有效,网关调用上游时使用预期密钥;日志中不暴露密钥。
- ✅ 流式输出:客户端能持续显示响应,结束事件与异常事件都能被正确处理。
- ✅ 工具调用:模型发起工具调用后,客户端能够执行工具、回传结果,并接收后续回复。
- ✅ 参数与错误:常用请求参数能正常往返;无效模型名、认证失败等错误能被识别,而不是伪装成空回复。
- ✅ 客户端选择器:下拉列表或配置中的模型名称确实路由到新端点,没有继续引用旧别名。
若客户端支持的模型发现、协议或工具能力有专门约束,应再对照客户端官方文档。比如,LiteLLM 的客户端接入说明中,模型发现相关设置需要配套配置;不能从“服务端有模型”直接推出“客户端一定能正确列出并调用它”。(docs.litellm.ai)
用团队代码任务衡量迁移质量
新模型返回结构合法,不等于完成同一项编程任务时表现等价。把团队真实工作中常见的任务整理成可重复执行的回归集,至少覆盖代码解释、修改现有文件、生成测试,以及需要多轮工具调用的工作流。这里不设通用通过率或质量阈值:验收门槛应来自团队现有基线和代码库要求,不应伪造一个适用于所有项目的数字。
每项任务记录模型与配置标识、输入、预期检查项和结果;优先用可验证条件判断,例如变更是否符合需求、测试是否通过、工具是否对正确文件执行操作。若任务依赖特定的输出格式,也应把格式校验纳入测试。迁移前后的文本可以不同,但如果新模型漏做工具步骤、改错文件或无法通过项目测试,应作为功能回归处理,而不是以“模型回答了”判定通过。
| 任务类型 | 验收证据 | 出现问题时的处理 |
|---|---|---|
| 代码解释 | 关键说明与指定文件、函数或行为相符 | 复查提示模板与上下文是否完整 |
| 代码修改 | 变更范围、逻辑与项目约束符合预期 | 检查模型行为差异,必要时调整提示或回滚 |
| 测试生成 | 测试可运行,并覆盖任务要求的行为 | 检查测试框架、依赖和客户端输出处理 |
| 多轮工具调用 | 工具执行、结果回传与后续响应闭环 | 排查工具协议、参数映射和客户端事件处理 |
提醒:固定回归集的价值在于暴露具体变化,不是证明两个模型等价。只挑成功样例、跳过失败任务,或把团队自己的接受标准写成通用性能结论,都会削弱验收结果的参考价值。
验证 LiteLLM 的重试与备用路由
LiteLLM 的路由行为至少要拆成两层理解:同一模型组内的重试,以及失败后切换到备用模型组的 fallback。官方架构说明将二者区分开来,因此验收记录应写清请求是重试了同组部署,还是切换到了备用模型;“最终返回成功”并不能说明主模型调用链正常。(docs.litellm.ai)
按团队路由策略,分别验证主模型限流、认证错误、请求超时和备用模型不可用。不要预设所有错误都应该重试:错误类型、重试策略与 LiteLLM 版本会影响最终行为,具体配置应依据所用版本的官方文档。路由观测也要覆盖实际命中的模型组和最终错误,使排查人员能判断请求是被重试、切换,还是按预期失败。
- 对主模型限流,观察是否按设定重试或转入备用模型,并确认响应和日志能区分两种路径。
- 对认证失败,检查是否被错误地重复请求;上游凭证有误时,盲目重试不能修复认证问题。
- 对超时,确认客户端等待时间、网关超时处理和最终返回错误符合团队约定。
- 对备用模型不可用,验证系统会返回可诊断的最终错误,而不是静默返回空内容或让客户端误判成功。
LiteLLM 路由文档说明了重试与 fallback 的配置机制;请求架构文档进一步说明,重试可发生在同组可用部署之间,fallback 则转向配置中的其他模型组。发布时应再次核对正在使用的版本及其文档,避免把其他版本的行为当成当前配置保证。(docs.litellm.ai)
按放行条件选择上线或回退
验收结果应能回答“哪些条件已经满足、哪些仍有风险”,而不是只留下一个成功状态码。完成上述检查后,可按条件分支决定是否放行:
- 若官方生命周期页面确认目标模型仍可用,模型别名与上游 ID 一致,客户端关键功能通过,代表性任务没有不可接受的回归,故障路由可观测且回滚已演练,则进入团队定义的上线流程。
- 若模型仍可用,但流式输出、工具调用或参数兼容出现问题,则暂停扩大流量,先修正客户端适配或配置,再重跑对应回归项。
- 若任务质量不符合团队基线,或备用路由导致关键流程无法完成,则回滚至此前已验收的配置;备用模型只能视为降级路径,不能默认与原模型等价。
- 若官方状态无法确认、配置来源不清或故障结果无法追踪,则不放行,先补齐证据与观测。
发布记录至少应包含实际模型标识、网关配置变更、客户端版本或配置、回归任务结果、故障场景结果和回滚方式。阈值由团队基于自身历史基线制定;不要用未经验证的延迟、质量百分比或成功率替代真实测试记录。
FAQ:模型退役、配置映射与客户端测试
把验收环境纳入变更记录
模型迁移的判断边界是模型与软件链路,但复现客户端问题时,测试环境也会影响排查结论:本地环境与团队实际开发环境不一致,可能让问题难以重现;临时采购设备会带来资产与维护工作;通用服务器环境也未必能覆盖依赖 macOS 图形界面的客户端流程。若验收需要远程 macOS 环境复现工作流,可根据团队对设备、访问方式和使用周期的要求,比较远程 Mac 方案,并先查看KuzCloud 帮助中心了解相关使用信息。短期测试可能更适合租用;长期稳定重负载或必须连接本地物理设备的场景,则应优先评估自购硬件。
为迁移验收准备一台专属远程 Mac
用 KuzCloud 独占 Mac mini M4 运行回归脚本与代码任务,隔离测试环境,不影响现有工作流。
SSH 或 VNC 直连并拥有完整 root 权限,可按需安装工具,快速验证客户端兼容与故障处理流程。