通用方法 · 熟练
参数没改，接口为什么突然 400？
下线模型只是三种变更里最好认的那一种
上一篇讲的是「模型名被关停」—— 那是三种平台变更里最容易发现的一种：名字没了，报错写得很清楚。真正难查的是另外两种：API 版本改了语义（同一个参数名还在，但传 `temperature` 直接 400），和 SDK 大版本改了默认值（你什么都没动，新装的依赖把你指到了新版本）。这一页补的是后两种：三处钉死（依赖大版本 · API 版本头 · 模型名清单），加一组「升级前必跑的金丝雀任务」，加一张变更单 —— 哪天升的、升了什么、回滚点在哪。
方法 · 一图看懂
1
把变更分成三类 — 模型名关停 / API 版本语义变更 / SDK 大版本改默认值，查法完全不同
2
三处钉死 — 依赖锁大版本 · 请求里显式写 API 版本 · 模型名集中在一处配置
3
准备一组金丝雀任务 — 5 个最依赖参数语义的调用（温度、top_p、长文档、引用位置、结构化输出）
4
升级前后各跑一次 — 比的是同一批输入下的输出差异，不是「有没有报错」
5
写一张变更单 — 日期 / 升了什么 / 金丝雀结果 / 回滚到哪一版
原理 · 为什么有效
平台变更之所以难查，是因为它分成三种确定性完全不同的东西：模型名关停有明确日期与明确报错（404 / model not found），API 版本变更有日期但报错指向参数（400 · 你以为是自己的代码写错了），SDK 大版本甚至没有报错 —— 它只是让新装的依赖默认指向新版本，于是同一份代码在两台机器上跑出两种行为。
三者唯一的共同解法是把「平台侧的可变量」压到最小：依赖锁大版本、请求里显式写 API 版本、模型名集中在一处。这三处一钉死，平台一变，变化只会从这三个口子进来 —— 否则它会从任何一个你没想到的地方进来。
而「金丝雀任务」解决的是另一半问题：升级不失败，不等于升级没改变行为。参数语义变了，输出往往只是「稍微不一样」，没有报错、没有日志，只有你某天发现结果不对。所以要有一组固定输入，升级前后各跑一次，比的是差异。
适用场景
适用：把模型接进脚本 / 定时任务 / 内部工具 / 自动化流程的人；用第三方 SDK 或封装库、依赖是自动升级的人；最近遇到过「换了个环境就报 400」「同事那边能跑我这边不能」的人。
⛔ 不适用：只在官方网页端里对话、不写代码不接 API 的人 —— 那是上一篇的范畴（模型名与界面变更）。
⚠️ 前提：愿意接受「升级要排期」这件事 —— 顺手 `pip install -U` 就是这套方法要防的动作。
自测 · 5 问
我的依赖里，有哪个是允许自动升大版本的（`^` / `~` / 不锁版本）？
我的请求里有没有显式写 API 版本，还是靠 SDK 默认值？
模型名是散在十几处，还是集中在一处配置里？
我有没有一组固定输入，能在升级前后跑出可比对的差异？
上一次升级，我知不知道回滚到哪一版？
怎么上手 · 验证步骤
第一次只做两件事：① 把依赖锁到大版本（不是锁死小版本 —— 那会让你永远不升级），② 把模型名从代码里抽出来，集中到一个配置文件或环境变量。然后建一个只有 5 条的金丝雀集：挑你最依赖参数语义的五个调用（一个用温度、一个用 top_p、一个长文档、一个要求引用位置、一个结构化输出），把当前输出存成基线。下次平台发新版时，先跑这 5 条，看差异，再决定升不升 —— 而不是先升、出问题再查。
自检动作：把「三处钉死」写成一行可核的句子 ——「依赖锁 2.x · 请求头写 `2026-10-21` · 模型名在 config.yaml 第 3 行」。能一次说清这三处的具体值，说明这套防线是活的；说不清，说明它还停在「我知道应该锁」的阶段，下一次自动升级照样会穿透。