灰度切换供应商：不中断业务地换掉一家 API 站

为什么不能「直接改 base_url」

把 base_url 从 A 改成 B 看起来是一行改动，但它同时改变了：

• 模型的实际提供方（输出风格、格式遵循、工具调用行为）；
• 延迟特征（影响超时设置）；
• 错误语义（状态码与错误文案可能不同）；
• 计费口径（影响你的成本模型）。

一次性切换意味着这些变化同时生效，而如果出问题，你无法判断是哪一项导致的。

灰度的目的就是把它们拆开。

阶段零：抽象层准备（切换前）

前提条件：所有调用都经过一个统一出口。如果你在代码里散落着十几个 api.openai.com 或某家站的域名，先做收敛。

最小实现：一个配置项 + 一个客户端工厂。

LLM_BASE_URL=...
LLM_API_KEY=...
LLM_MODEL=...

这一步的价值不止于本次迁移 —— 它是所有后续切换的基础。没有它，每次换供应商都是一次全代码搜索替换。

阶段一：影子比对（双发不双用）

做法：同一批请求同时发给 A 和 B，但只使用 A 的结果，把 B 的结果记录下来用于比对。

为什么必须双发：只有同一请求、同一时刻的结果才可比。你先在 A 上跑一批、再在 B 上跑另一批，两批输入不同，无法判断差异来自供应商还是输入。

观察什么：

影子阶段要跑多久：至少覆盖一个完整业务周期（通常是 1–2 周），必须包含高峰期。只在低谷期跑影子，等于没测。

影子阶段的成本：双发意味着双倍花费。这是迁移的必要成本 —— 相比切换失败造成的业务中断，它便宜得多。

如果成本敏感：可以对请求采样（比如只双发 10%），但必须覆盖所有请求类型，不能只采样简单请求。

阶段二：按比例放量

做法：按比例把真实流量切到 B，阶梯式提升。

建议阶梯：1% → 5% → 20% → 50% → 100%，每一级至少观察一个完整业务周期。

为什么不是线性提升：1% → 5% 是 5 倍，5% → 20% 是 4 倍，20% → 50% 是 2.5 倍。早期步长可以大一些（因为样本小、风险小），后期步长要小（因为影响面大）。

切分维度怎么选：

• 按用户/租户：适合多租户系统。同一用户体验一致，出问题影响面可控；
• 按请求类型：适合功能模块清晰的系统。可以先切「非关键路径」；
• 按百分比随机：最简单，但同一用户可能一会儿走 A 一会儿走 B，体验不一致。

建议：优先按用户或按请求类型，不要纯随机。

每一级观察什么：

□ 错误率（对比 A 组）
□ p95 延迟
□ 业务指标（如任务完成率、用户操作成功率）
□ 成本（实际扣费是否符合预期）
□ 你自己的日志里的新增异常类型

触发回滚的条件要事先定好，例如「错误率高于 A 组 2 倍」或「p95 延迟劣化 50%」。不要等到出事再临时决定要不要回滚 —— 那时候的判断容易受情绪影响。

阶段三：全量与收尾

全量切换后至少再观察一个完整业务周期，然后：

1. 不要立刻删除 A 的配置 —— 保留至少一个月，作为回滚通道；
2. 保留 A 的 Key 但设一个小额度 —— 这样它可以长期作为备份存在，而不会在你忘记时被刷；
3. 更新文档与告警：所有提到 A 的地方都要改，包括值班手册。

回滚预案（其实是最重要的一环）

回滚必须是一次配置变更，而不是一次代码发布。

三个要求：

1. 配置可控（能用环境变量或配置中心切换）；
2. 两侧长期共存（不要在切换到 B 后把 A 的凭证删掉）；
3. 演练过一次（真的回滚一次试试，而不是假设它能回滚）。

第 3 项最常被跳过。回滚通道的价值只在于「它真的能用」，而它能不能用，只有演练过才知道。

一个简化版本（适合小团队）

如果上面的流程太重，用一个三人团队也能执行的版本：

1. 把 base_url 收敛到一处（半天）；
2. 影子阶段只跑 2 天，覆盖 1 个高峰期（1 天）；
3. 按 10% → 50% → 100% 三级放量，每级 1 天（3 天）；
4. 保留双配置至少一个月。

总计约一周。核心不能省的是第 1 项（抽象层）和第 4 项（保留回滚通道）—— 前者决定你能不能换，后者决定你换坏了能不能回来。

除此之外都可以简化。