AI 开发

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 是否对应预期的 LiteLLM model_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 权限,可按需安装工具,快速验证客户端兼容与故障处理流程。