1. 一次模型下线通知引发的连锁反应10 月 10 日179 个模型要下线。这个数字不是危言耸听是我在后台翻bl model list时实打实数出来的。当时第一反应是跟我关系不大吧毕竟我们线上跑着的模型就那么几个平时也没怎么动过。但手贱往下翻了几页看到upcomingOfflineAt那一列密密麻麻的日期心里咯噔一下——有几个日期就是 10 月 10 日而且里面赫然躺着我们某个业务线半年前接进去的一个模型。这就是我决定给整个项目做一次模型依赖全量体检的起因。说白了模型下线这件事从来不是我不用它就没事而是我不知道我在用它才是真正要命的。一个模型可能藏在某个配置文件里、某个同事两年前写的脚本里、某个第三方 SDK 的默认参数里甚至藏在某段注释掉的代码旁边那个没注释掉的 fallback 分支里。这篇东西写给谁看写给所有手上有项目、项目里调过模型接口、但从来没系统梳理过到底依赖了哪些模型的人。不管你是刚接手一个老项目的萌新还是维护了三年微服务的老油条只要你的代码里出现过模型名称、模型 ID、模型版本号这类东西这篇都值得你花二十分钟看完然后照着做一遍体检。核心就三件事把依赖找全、把影响评估清楚、把迁移核验做扎实。下面我按自己实际操作的顺序一步步拆开讲。2. 模型依赖到底藏在哪些角落2.1 显式依赖配置文件与代码常量最容易找的就是显式依赖。这类依赖通常长这样配置文件里一个model: xxx-v2或者代码里一个const MODEL_ID xxx。它们的特点是看得见只要你 grep 一下模型名就能定位。但这里有个坑模型名不一定是你记忆里的那个。比如我们内部习惯叫它通用对话模型但实际配置里写的是general-chat-pro而bl model list里显示的名字可能是general-chat-pro-20240115。名字对不上grep 就白搭。我的做法是先从bl model list导出全量模型清单拿到每个模型的modelId、modelName、upcomingOfflineAt三个字段然后用脚本去代码库里做模糊匹配。匹配规则不是精确相等而是模型名去掉版本后缀后作为关键词去搜。这样能覆盖大部分命名不一致的情况。# 导出模型清单示意 bl model list --format json models.json # 提取即将下线的模型名作为关键词 cat models.json | jq -r .[] | select(.upcomingOfflineAt ! null) | .modelName offline_keywords.txt拿到关键词列表后对代码库做一次全量扫描while read keyword; do echo $keyword grep -rn --include*.py --include*.yaml --include*.json --include*.env $keyword . done offline_keywords.txt这一步能捞出八成以上的显式依赖。剩下的两成藏在下面要说的隐式依赖里。2.2 隐式依赖SDK 默认值与间接调用隐式依赖是最阴的。我踩过的一个真实案例某个第三方 SDK 在初始化时如果不传模型参数会默认用一个内置模型。这个默认模型就在 10 月 10 日的下线名单里。我们的代码从来没写过这个模型名但它确确实实在用。怎么找这类依赖三个方向第一翻所有第三方库的初始化代码看有没有default_model、fallback_model这类字段。第二看日志。线上日志里通常会打印实际调用的模型名把最近一周的日志捞出来统计出现过的模型名跟下线清单做交集。第三看监控面板。如果你们有按模型维度做的调用量监控那是最直接的证据。提示日志和监控是找隐式依赖的两把利器比翻代码靠谱得多。代码可能骗你但日志不会。2.3 历史遗留注释、脚本与文档里的僵尸依赖还有一类依赖严格来说不算正在使用但会在迁移时给你添乱。比如某个 shell 脚本里写死了模型名虽然这个脚本半年没跑过了但万一哪天有人手动执行一下就会炸。再比如文档里写的示例代码用的是下线模型新同事照着抄也会炸。这类依赖的处理原则是能删就删不能删就改。别留着以后可能有用的念想模型都下线了留着也是死代码。3. 用 upcomingOfflineAt 做影响面分级3.1 三个维度调用量、业务重要性、迁移成本找到依赖只是第一步接下来要判断哪些必须优先处理。我用的分级方法是三个维度打分维度权重说明调用量高日均调用次数直接反映影响范围业务重要性高核心链路还是边缘功能迁移成本中换模型需要改多少代码、测多少用例调用量从监控拿业务重要性跟产品对齐迁移成本自己估。三个维度综合下来把依赖分成 P0、P1、P2 三档。P0 是下线前必须迁完P1 是下线前尽量迁完P2 是下线后再说也行。3.2 按 upcomingOfflineAt 排优先级upcomingOfflineAt这个字段的价值在于它给了你一个明确的时间锚点。我的做法是把所有依赖按这个日期排序日期越近的越优先。如果两个依赖日期相同再按上面的三维度打分排序。这里有个细节upcomingOfflineAt可能是 null表示这个模型暂时没有下线计划。但暂时没有不等于永远没有所以这类依赖也要记录在案只是优先级最低。# 按 upcomingOfflineAt 排序的示意逻辑 deps load_dependencies() deps_with_date [d for d in deps if d.upcoming_offline_at] deps_without_date [d for d in deps if not d.upcoming_offline_at] deps_with_date.sort(keylambda d: d.upcoming_offline_at) final_order deps_with_date deps_without_date3.3 一张表看清所有依赖的状态体检的核心产出是一张依赖清单表。我用的字段如下字段说明模型名实际调用的模型标识调用位置文件路径 行号依赖类型显式 / 隐式 / 遗留日均调用量从监控获取upcomingOfflineAt下线日期优先级P0 / P1 / P2迁移方案目标模型 改动点核验状态未开始 / 进行中 / 已完成这张表是整个体检的作战地图后续所有工作都围绕它展开。建议用表格工具维护别用纯文本不然改起来会疯。4. 迁移核验换模型不是改个名字就完事4.1 迁移前的兼容性评估换模型最怕的是什么是接口一样但行为不一样。同样一个输入老模型返回 A新模型返回 B如果你的下游逻辑对返回值做了强假设就会出问题。我的兼容性评估清单输入格式新模型是否接受同样的参数结构有没有必填项变化输出格式返回字段名、字段类型、嵌套结构是否一致输出内容同样输入下输出语义是否等价这个必须用真实用例跑对比。性能延迟、吞吐量是否满足要求配额新模型的调用配额是否够用注意输出内容的对比不能只看一两个用例要覆盖你的典型场景。我一般会从线上日志里采样 100 条真实请求分别打给老模型和新模型做 diff。4.2 灰度切换与回滚预案迁移不要一把梭。我的做法是先在测试环境全量切换跑完整回归。线上按流量比例灰度从 1% 开始观察 24 小时。逐步放大到 10%、50%、100%。每一步都保留回滚开关出问题一键切回老模型。回滚预案要提前写好别等出事了再想。回滚的关键是老模型在下线前一直可用所以灰度期间老模型不能停。4.3 核验清单迁移后必须确认的 5 件事迁移完成后逐项确认调用量监控里老模型的调用量归零。新模型的调用量、成功率、延迟符合预期。业务指标如转化率、准确率没有异常波动。日志里不再出现老模型名。依赖清单表里该条目的核验状态更新为已完成。这五件事全过了才算真正迁完。少一件都不行。5. 实操中踩过的坑与排查技巧5.1 模型名大小写与版本后缀的坑前面提过命名不一致的问题这里再强调一次。bl model list返回的模型名可能带版本后缀而代码里写的是不带后缀的别名。我的处理方式是维护一张别名映射表把代码里的叫法和清单里的正式名对应起来。这张表一开始靠人工后来发现规律后可以用脚本自动生成。5.2 调用量统计口径不一致监控里的调用量跟日志里的调用量对不上这是常事。原因可能是监控采样、日志丢失、或者统计维度不同。我的建议是以监控为准日志为辅。监控通常更准日志用来定位具体调用位置。5.3 迁移后指标波动的归因迁移后业务指标波动不一定是模型的问题。可能是灰度期间流量分布变化、可能是同期有其他变更、也可能是正常波动。归因时要控制变量最好在迁移前后各留一段观察期对比同期数据。5.4 常见问题速查表问题可能原因排查方向grep 不到模型名命名不一致用别名映射表日志里有调用但代码里找不到隐式依赖查 SDK 默认值迁移后报错输入输出格式不兼容对比接口文档迁移后指标下降模型行为差异采样对比输出回滚失败老模型已下线提前确认下线时间6. 把体检变成常规动作这次体检做完我最大的感受是模型依赖管理不该是一次性的救火而应该是常规动作。我的建议是每季度做一次全量体检每次有模型下线通知时做一次增量体检。体检的产出就是那张依赖清单表持续维护持续更新。另外新项目接入模型时强制要求在依赖清单表里登记。这样下次再有下线通知直接查表就行不用再从头 grep 一遍。这个习惯养成后能省下大量时间。最后分享一个小技巧把bl model list的导出和依赖扫描做成一个定时任务每周跑一次有变化就发通知。这样你永远比下线通知早一步知道风险。我自己是这么做的实测下来很稳再也没被突然下线搞过措手不及。