系列：AI Agent 工程实践
上一篇：第 31 篇《Agent 如何部署》
下一篇：第 33 篇《Agent 如何监控》

一、开场：一次全量切换的事故

某团队新版 Agent 提示词优化了，测试也过了。周五晚上直接把流量 100% 切到新版本。周一上班，投诉爆了：新版本在某个边缘场景答非所问，而旧版本没问题。因为没有灰度，所有用户第一时间踩雷；没有快速回滚，修复等了半天。

上篇（31）讲"怎么让它活着"，这篇讲"怎么把活的版本交给用户才安全"——上线。

二、问题背景：直接全量 vs 渐进发布

直接全量：

# 配置里写死版本
agent_version: v2   # 一键切，所有流量进 v2

渐进发布： 流量按比例、按人群逐步释放，每个阶段都有"刹车"。

差别：全量切 = 赌；渐进发布 = 用可控代价验证。

三、错误尝试：三种上线翻车

错误 1：直接全量切，无回滚

版本一换，出问题只能"再发一版修复"，中间所有用户受影响。最怕的是"新版本引入的 bug 比修的还多"。

错误 2：不做版本区分

新老逻辑靠 if 硬改代码，回滚要改代码重新部署，慢且易错——发布变成高风险动作。

错误 3：无对照，不知好坏

上了新版本，靠"感觉变好了"，没有量化对比，劣化无人知，等客诉才暴露。

四、关键观察：上线 = 受控释放 + 可观测回滚

上线不是部署完开流量，而是一个带闸门的流水线。每个阶段都是一道安全阀：

• v1（内部/小流量）：先让内部人或 1% 用户踩，问题先暴露给自己人。
• 灰度（5%~10%）：扩大到真实小比例用户，验证稳定性与基本质量。
• A/B（对照）：新旧同跑，量化对比关键指标，证明"新比旧好"。
• 全量：确认无劣化、成本可控，才 100% 切。

关键：每个阶段都能一键回滚到上一版，回滚是配置开关而不是重新发版。这才是"上线"和"部署"的本质区别——部署让它能跑，上线让风险可控。

五、最终方案：四阶段上线流水线

v1 内部验证
   ↓  (无 P0 故障)
灰度 5%~10%
   ↓  (成功率/延迟达标)
A/B 对照实验
   ↓  (核心指标不劣化甚至有提升)
全量 100%
   ↓  全程可回滚 ──────────┐
        (任一步异常) ───────┘ 回滚到上一稳定版

版本管理三件套：版本号（每个发布打标）、路由权重（流量分配）、回滚开关（feature flag 或路由回指旧版）。三者齐备，上线才从"心跳游戏"变成"工程动作"。

六、架构图（Mermaid）

七、代码与配置示例

用路由权重做灰度（伪配置）：

releases:
  v1: { weight: 90, endpoint: agent-v1 }
  v2: { weight: 10, endpoint: agent-v2 }   # 灰度 10%
# 异常时把 v2.weight 改回 0 即回滚，无需重新部署

用 feature flag 控制新逻辑：

def build_prompt(user_input, flags):
    if flags.enabled("new_prompt_v2"):     # 开关决定走哪版
        return PROMPT_V2
    return PROMPT_V1                        # 关掉即回滚

A/B 指标对比（必须量化）：

# 同一批请求，新旧各跑一份，对比
metrics_v1 = run_experiment(v1, dataset)
metrics_v2 = run_experiment(v2, dataset)
assert metrics_v2.success_rate >= metrics_v1.success_rate - 0.01

八、设计权衡：何时不必灰度

场景	建议	理由
面向公网、高频	必走完整流水线	翻车影响大
内部工具、低频	v1 小流量即可	影响面小
仅修复 bug	灰度可缩短	风险低
提示词大改	必做 A/B	质量难凭感觉

反过度工程：内部小工具不必照搬大厂四阶段，但回滚开关一定要有——这是底线，不是奢侈品。再小的发布，也要能在一分钟内退回上一个好版本。

九、总结

• ✅ 直接全量切 = 赌，一次翻车影响所有用户。
• ✅ 三种翻车：无回滚、不做版本区分、无对照。
• ✅ 上线 = 受控释放 + 可观测回滚，四阶段 v1→灰度→A/B→全量。
• ✅ 版本号 + 路由权重 + 回滚开关，三件套让回滚成配置而非发版。
• ✅ 底线：回滚开关必须有，哪怕跳过灰度。

下一篇，全量之后——上线了要看什么才叫"稳"。（33）

---

参考资料（带用途说明）

• 本系列（31）Agent 如何部署：本文假设服务已部署，讲部署后的流量释放。
• 本系列（30）Agent 如何做测试：A/B 对照依赖（30）的 Golden Dataset 与回归测试。
• 本系列（29）成本控制：A/B 实验需同时对比成本，避免"质量好了但烧钱翻倍"。
• 本系列（33）Agent 如何监控：灰度和全量阶段靠（33）的指标判断是否达标。
• LaunchDarkly 文档（launchdarkly.com）：feature flag 与渐进发布的工程实践参考。

---

本文是 AI Agent 工程实践系列的第 32 篇（第四阶段第十二篇）。

---

系列导航

上一篇：第 31 篇《Agent 如何部署》
下一篇：第 33 篇《Agent 如何监控》