一、为什么要做灰度：模型切换不是换个名字这么简单

很多团队最初接入 Codex 时，只需要一个稳定模型和一个可用入口。等使用场景变多以后，情况会复杂起来：代码**希望更强的推理能力，文档整理希望更低的成本，日志排查希望更快的响应，测试生成希望输出格式更稳定。不同任务对模型的要求不同，一刀切地升级或替换模型，往往会带来新的不确定性。

灰度切换的核心，是不要把全部任务一次性切到新模型，而是先让少量、低风险、可复核的任务进入新通道，观察效果后再逐步扩大。这样即使新模型在某类任务上表现不稳定，也只会影响局部流程，团队可以快速回退。

• 代码**更看重风险识别和依据说明。
• 文档整理更看重结构稳定和成本可控。
• 日志排查更看重响应速度和错误归类。

二、先统一接入入口：灰度必须建立在稳定入口上

灰度切换之前，团队要先确认接入入口统一。如果成员各自保存不同地址、不同 Key、不同模型别名，那么所谓灰度其实没有意义，因为你无法判断一次结果差异来自新模型，还是来自配置不一致。

建议通过灵能API统一管理 Codex 调用入口，并把 https://www.lnsns.com/ 作为内部说明里的官网入口，方便成员核对控制台、模型列表、调用地址和账号状态。统一入口之后，灰度规则才有固定执行位置，后续记录、回滚和复盘也能围绕同一条链路展开。

灰度前置检查

接入入口：*ase **L 是否统一
模型别名：旧模型和新模型命名是否清晰
凭证用途：个人调试、团队任务、自动流程是否分开
任务标签：是否能记录 task_type、role、project
回滚路径：是否能快速切回旧模型
复核人员：谁确认灰度结果，谁决定扩**例

这一步看起来基础，却决定后面能不能排查。没有统一入口，灰度失败时很难定位；没有模型别名，成员会把新旧模型混着叫；没有任务标签，无法判断哪类任务适合扩大流量。

三、设计模型别名：不要把真实模型名写满业务流程

团队做模型路由时，建议使用稳定别名，而不是在每个脚本、文档和提示词里写具体模型名。模型名可能升级，供应来源可能调整，参数策略也可能变化；别名稳定下来后，业务流程只关心任务通道，底层模型可以由中转配置来承接。

例如把代码**通道命名为 codex-review-**in，把轻量文档通道命名为 codex-doc-lite，把日志排查通道命名为 codex-ops-fast。成员看到的是任务用途，不需要知道底层具体切到了哪个模型。

模型别名设计示例

codex-review-**in
- 用途：合并请求**、风险识别、复杂修改建议
- 要求：输出依据充分，允许耗时略高

codex-doc-lite
- 用途：接口文档草稿、字段说明、变更摘要
- 要求：结构稳定，成本可控

codex-ops-fast
- 用途：短日志排查、错误码解释、健康检查
- 要求：响应快，输出短，避免长上下文

codex-gray-candi**te
- 用途：新模型灰度验证
- 要求：只给指定任务使用，必须记录对照结果

• 别名描述用途，不直接暴露底层切换细节。
• 业务脚本调用别名，配置层决定实际模型。
• 灰度候选别名要单独命名，避免误用。

四、流量分层：从 1% 到 100% 不要跳级

灰度比例要小步推进，不建议从 0 直接到全量。第一阶段可以只选内部验证任务，例如固定提示词健康检查、短文档摘要、少量低风险代码**。第二阶段再扩展到真实项目中的部分任务。第三阶段才考虑进入主要工作流。

比例只是表面，更重要的是任务选择。1% 阶段最好选择短输入、可复核、失败影响小的任务；10% 阶段可以加入真实代码**和测试用例草案；50% 阶段才考虑让核心团队成员日常使用；100% 阶段必须建立在质量指标、成本指标和回滚演练都通过的基础上。

灰度推进节奏

阶段 A：1%
- 固定健康检查
- 短文本摘要
- 简单代码解释
- 目标：确认链路、权限、基础输出

阶段 *：10%
- 部分接口文档草稿
- 低风险测试用例生成
- 目标：观察结构稳定性和人工修订量

阶段 C：50%
- 部分真实合并请求**
- 日常文档整理任务
- 目标：比较效率、质量和成本

阶段 D：100%
- 进入主任务通道
- 目标：完成替换，同时保留回退方案

五、对照验证：新模型好不好，不能只凭感觉

灰度验证最怕只看一两次输出，然后觉得“更聪明”或“差不多”。团队需要把验证标准写成可比较的指标。对于 Codex 任务来说，可以从准确性、完整性、可执行性、格式稳定性、耗时、成本和人工修订量几个角度对照。

对照验证建议使用同一组输入，分别走旧模型别名和灰度候选别名。每个任务都要保存输出，并由负责人打分。分数不需要复杂，关键是长期一致。比如 1 到 5 分：1 分表示不可用，3 分表示需要明显人工修订，5 分表示只需轻微调整即可进入流程。

对照评分维度

accuracy：事实是否准确
coverage：是否覆盖任务要求
for**t：输出格式是否稳定
execution：建议是否可执行
latency：耗时是否可接受
cost：成本是否合理
**nual_edit：人工修订量是否下降
risk：是否出现不应出现的结论

通过建议：
- accuracy 平均不低于旧通道
- for**t 明显稳定
- **nual_edit 有下降
- risk 没有新增高风险问题

• 同一输入分别走新旧通道，才有可比性。
• 不要只看漂亮程度，要看能不能进入流程。
• 人工修订量是非常实用的验证指标。

六、准备样本集：灰度前先挑 20 个代表任务

没有样本集，灰度验证会很随意。今天拿一个接口文档试，明天拿一段日志试，后天换一份合并请求，最后很难判断结果到底变好了还是任务本身变了。

建议先准备一组代表任务，数量不用太多，20 个左右就够。样本要覆盖高频场景和容易出错的边界场景：代码**、接口文档、测试用例、日志排查、发布说明各选几条，再加入两三条历史上出现过问题的案例。

灰度样本集建议

代码**：5 条
- 简单改动 2 条
- 跨文件改动 2 条
- 权限或兼容相关 1 条

接口文档：4 条
- 查询接口 1 条
- 写入接口 1 条
- 错误码复杂接口 1 条
- 字段含待确认项 1 条

测试生成：4 条
- 正常路径 1 条
- 边界值 1 条
- 异常路径 1 条
- 回归场景 1 条

日志排查：4 条
- 认证失败 1 条
- 限流 1 条
- 超时 1 条
- 响应格式异常 1 条

发布说明：3 条
- 小版本 1 条
- 配置变更 1 条
- 回滚说明 1 条

• 样本集要固定，避免每次拿不同任务比较。
• 样本要覆盖正常任务，也要覆盖边界任务。
• 历史故障样本很适合用来验证新通道。

七、设置回滚条件：什么时候必须切回旧通道

灰度最大的安全感来自回滚。回滚不是失败的象征，而是流程成熟的表现。没有回滚条件，团队很容易在出现异常后继续观察，直到影响扩大；有回滚条件，值班同学可以按规则处理，不需要现场争论。

回滚条件建议覆盖四类：质量、稳定性、成本、安全。质量方面，如果高风险误判增加或输出经常不遵守格式，就要暂停；稳定性方面，如果超时、失败率、重试次数明显升高，要回退；成本方面，如果同类任务成本超出阈值，要停止扩大；安全方面，如果输出出现敏感信息复述或越权建议，要立即回滚并复查模板。

回滚触发条件

质量触发：
- 对照评分连续低于旧通道
- 关键字段漏写或乱写
- 待确认项被写成确定结论

稳定性触发：
- 失败率超过 10%
- P95 耗时超过旧通道 2 倍
- 同一任务连续重试仍失败

成本触发：
- 单任务平均成本明显升高
- 批处理任务消耗异常

安全触发：
- 输出未脱敏敏感字段
- 给出绕过权限或生产变更建议

️ 八、配置双轨运行：旧通道保留，新通道试跑

灰度期间不要删除旧通道。更稳的方式是双轨运行：旧通道继续承担主要任务，新通道只处理指定比例或指定任务。这样既能收集真实数据，又能在异常时快速切回，不需要临时重建配置。

双轨配置要明确三件事：哪些任务可以走新通道，哪些任务必须留在旧通道，哪些任务需要同时生成对照结果。比如生产事故排查、重要发布说明、客户可见文档，灰度早期不建议直接切到新通道；而内部摘要、低风险文档草稿、固定健康检查则适合先进入新通道。

双轨配置示例

sta*le_channel
- 默认通道
- 覆盖所有正式工作流
- 保留完整监控和复核

gray_channel
- 只接收 allow_gray=true 的任务
- 只允许指定角色使用
- 必须记录输出评分
- 失败后自动回到 sta*le_channel

shadow_compare
- 同一输入同时走新旧通道
- 新通道输出不进入正式流程
- 仅用于质量对照

• 灰度早期，新通道输出不要直接影响正式交付。
• 旧通道要保留到新通道稳定一段时间之后。
• 对照运行可以只保存结果摘要，避免记录过多敏感内容。

九、观察指标：不要只看成功率

成功率很重要，但不足以判断灰度是否成功。一个模型可能成功率很高，但输出经常需要人工重写；也可能耗时略高，但**质量明显更好。灰度判断要结合质量、效率、成本和风险四个维度。

质量看评分和待确认项；效率看耗时和人工修订量；成本看单任务平均消耗和重试消耗；风险看高风险误判、敏感输出和格式不稳定。只有这些指标一起看，才能判断是否值得扩**例。

灰度观察指标

质量：
- 平均评分
- 高风险误判次数
- 输出格式合规率
- 待确认项准确率

效率：
- 平均响应耗时
- P95 响应耗时
- 人工修订时间
- 一次通过比例

成本：
- 单任务平均成本
- 重试带来的额外成本
- 长上下文任务占比

风险：
- 敏感信息输出次数
- 越权建议次数
- 回滚触发次数

• 只看成功率会漏掉质量问题。
• 只看质量会忽略成本和耗时。
• 灰度决策要看组合指标。

十、发布决策：扩**例前先开一次短评审

灰度从 10% 扩到 50%，或者从 50% 扩到全量之前，建议开一次短评审。评审不需要很长，但要把事实摆清楚：样本数量、任务类型、评分结果、失败原因、成本变化、人工修订量、回滚演练是否通过。

灰度评审清单

[ ] 样本集是否跑完
[ ] 新旧通道是否使用同一输入
[ ] 质量评分是否达到阈值
[ ] 输出格式是否稳定
[ ] 失败样本是否已归类
[ ] 回滚条件是否清楚
[ ] 回滚动作是否演练过
[ ] 成本变化是否可接受
[ ] 负责人是否确认扩**例
[ ] 是否通知相关角色

短评审的价值，是让扩**例变成团队决策，而不是某个人觉得可以。尤其是涉及主任务通道时，最好保留评审记录，后续出现异常时可以回看当时依据。

十一、回滚演练：真正需要时才不会手忙脚乱

很多团队写了回滚方案，但从来没演练过。真正出问题时才发现：旧模型别名没保留，配置缓存没刷新，任务队列里还有新通道请求，文档里没人知道谁有权限切换。灰度上线前至少要***小范围回滚演练。

演练可以很简单：选一个非关键任务，把它从稳定通道切到灰度通道，确认记录正常；再触发一次模拟失败，把它切回稳定通道，确认任务能继续执行、日志能看到切换、负责人能收到通知。

回滚演练步骤

1. 选择一个低风险任务
2. 标记 allow_gray=true
3. 观察它是否进入灰度通道
4. 人工触发回滚条件
5. 切回 sta*le_channel
6. 检查后续任务是否走旧通道
7. 检查日志是否记录切换时间和操作人
8. 记录演练结果和待修正问题

• 没有演练过的回滚方案，只能算纸面方案。
• 回滚动作要能被普通值班同学执行。
• 回滚后要确认队列里没有残留灰度任务。

️ 十二、灰度复盘：把一次切换变成下次模板

灰度结束后，不管是否全量，都应该写一份复盘。复盘不是长篇报告，而是把这次切换留下的经验整理成下一次可复用模板。比如哪些样本最有代表性，哪些指标最敏感，哪些任务不适合早期灰度，哪类错误需要提前加到回滚条件里。

复盘最好包含三部分：结论、证据、改进。结论说明是否继续扩大或保持观察；证据列出样本、指标和异常；改进记录下次要调整的样本集、路由规则、提示词模板、权限边界或告警阈值。

灰度复盘模板

本次目标：验证新通道是否适合进入代码**主流程
灰度范围：10% 真实**任务   20 个固定样本
核心结论：继续观察 / 扩**例 / 回滚
主要证据：评分、耗时、成本、失败样本
异常记录：哪些任务表现不稳定
回滚情况：是否触发，是否顺利
规则更新：模型别名、任务范围、阈值、手册
下次动作：负责人、截止日期、下一阶段比例

• 复盘要留下下一次可以复制的清单。
• 异常样本不要丢，它们是后续验证的好材料。
• 灰度规则每改一次，都要同步到团队手册。

✅ 十三、收尾：灰度的本质是给团队留选择权

Codex 接入 API中转站 后，模型能力会不断变化，团队任务也会不断扩展。真正稳的做法不是永远固定一条通道，也不是每次有新模型就立刻全量切换，而是建立灰度、对照、回滚和复盘机制。

落地时可以按这个顺序推进：先通过灵能API统一入口和模型别名；再准备固定样本集和对照评分表；然后从 1% 低风险任务开始灰度；观察质量、耗时、成本和风险；达到阈值后再扩**例；最后把回滚演练和灰度复盘写进团队手册。

当这套流程跑通后，API中转站 的价值会从“能接入”升级为“能治理”。团队既能享受新模型带来的效率提升，也能在异常出现时保留退路。对长期使用 Codex 的团队来说，这种可控性往往比单次输出更重要。

• 用别名隔离底层模型变化。
• 用样本集验证真实质量。
• 用回滚条件保护正式流程。