把各厂商模型名映射到聚合站别名：如何不弄坏现有脚本

为什么模型名会成为迁移的坑

多数脚本并不是从配置文件读取模型名，而是直接写在代码里：

• model="claude-..." 这类字符串散落在业务代码、单元测试和定时任务里
• 有的脚本用 startswith、endswith、正则或字典键做分支判断
• 日志、监控面板、成本统计表里存着按原始模型名聚合的历史数据

聚合站用一个 API key 调多个厂商模型，模型名由它自己的别名体系决定。直接把 base URL 换掉、模型名不改，通常会得到一个可以诊断的错误；但如果你有兜底逻辑，它可能被静默吞掉，变成用错模型跑完整个批处理。

迁移的重点不是“改字符串”，而是让所有依赖模型名的地方都能正确解析。

先建一张映射表，而不是边改边猜

不要在代码里逐处替换。先在仓库外建一份唯一的事实来源，例如一个 CSV 或 YAML：

models:
  anthropic/claude-sonnet-x: claude-sonnet-x
  openai/gpt-x: gpt-x
  deepseek/deepseek-chat: deepseek-chat

左列写你项目里当前真实出现过的模型字符串，右列写聚合站别名。要点：

• 左列必须是实际出现过的原字符串，用 grep 从代码和历史配置里提取，不要凭记忆写
• 一家厂商同一个能力可能对应多个原始名（版本号、日期后缀、别名），全部列出，别合并
• 别名侧只填目标模型，不做“差不多就行”的模糊合并
• 表里加一列备注，写清每个映射的用途和负责人

这份表同时是迁移清单和回滚依据。它在版本控制里，评审时能对齐。

用固定脚本做校验，而不是靠报错试出来

每条映射验证两件事：别名能被接受，返回的模型标识符合预期。用一个最小请求逐个发一遍，把结果写进校验报告：

• 请求是否成功，失败时记录错误码和错误体
• 响应里的模型字段是什么，是否与预期别名一致
• 是否有内容返回，避免“成功但空响应”被当成通过

注意别把校验脚本写成业务脚本。校验只需要覆盖每个别名一次，用最小 token、最简单的 prompt，不要依赖长上下文、工具调用或多模态输入，否则失败原因会混在一起。

校验通过后再改业务代码。这样出现问题时，你能区分“别名不对”和“脚本逻辑不对”。

改代码时按解析路径分类处理

同样是模型名字符串，不同用法的改法不一样：

直接传参的调用点

最省事的做法是只改常量来源：把硬编码字符串抽成一个常量或配置项，值取自映射表右列。调用点不动，回归测试就能覆盖。

用作分支判断的名字

如果代码里有 if model.startswith("claude") 或者按模型名分派 prompt、参数、并发策略，这里是风险最高的一处。别名可能不再包含原来的厂商前缀，分支会全部落到 else。

处理方式是把“按名字判断”改成“按能力判断”：在映射表或配置里显式声明该模型属于哪一档（是否支持工具调用、上下文级别、是否需要特殊参数），代码读这个字段，而不是解析字符串。

用作统计维度的名字

日志、监控、成本表按模型名聚合时，改别名会让历史数据断成两段。做法是在写入侧同时记录两个字段：请求时使用的别名，以及映射表里的原始名（或业务用途标签），这样报表能跨迁移期对齐。

测试里的名字

测试里的模型名必须换成别名，否则测试要么失败，要么因为 mock 住了调用而假装通过。如果测试断言了请求体里的 model 字段，断言也要同步更新。

上线前后各做一次覆盖检查

迁移前：

• grep 所有原始模型字符串，确认映射表覆盖了全部命中项，包括注释掉的代码和示例配置
• 确认没有用环境变量拼接模型名的地方，拼接会让静态检查漏掉
• 确认没有在运行时从外部接口拉取模型名的逻辑

迁移后：

• 用一份代表性请求回放业务链路，检查返回的模型标识
• 检查兜底逻辑：把别名临时改成一个不存在的名字，确认报错可见而不是静默降级
• 检查日志字段是否同时保留别名与用途标签

第二步常被跳过，但正是它决定了一次错误的模型名会变成告警还是变成沉默的数据事故。

保留回滚路径

映射表是版本控制的，别名切换应当能按表回退。切换前记录一份当前生效的映射快照，出现异常时改回快照即可，不需要再翻代码找散落的字符串。同时把校验脚本留在仓库里，下次厂商侧模型更名时直接复用。