主题
第9章 工程化上线能力
9.1 问题场景
从可演示到可上线，差距通常不在模型本身，而在部署、监控、回滚、灰度和稳定性治理。 很多 AI Agent 系统在本地或演示环境里表现很好，但一进入真实业务就会暴露几个问题：
- 不同环境配置不一致，结果复现不了。
- 版本升级后质量回退，却没人第一时间发现。
- 工具、检索、模型、前端状态任何一层出错，都会被用户感知成“系统坏了”。
- 没有快速回滚能力，线上风险被放大。
对于前端工程师来说，这一章并不陌生。你过去做前端发布时，已经接触过很多相似问题：
- 开发、预发、生产环境配置差异。
- 灰度发布与回滚。
- 错误监控与告警。
- 指标看板和事故复盘。
AI Agent 项目的不同之处在于，它的“线上表现”不仅受代码影响，还受提示词（prompt）、模型版本、检索配置、工具依赖和工作流状态共同影响。 因此，工程化上线能力本质上是在建设一个“持续可发布、可监控、可回退、可解释”的系统，而不是一次性把 Demo 推上生产。
前端迁移提示
这一章和前端工程能力高度相关，你原有经验可以直接迁移：
- CI / CD 流程 -> 发布流水线与质量门禁。
- 前端监控平台 -> Agent 成功率、延迟、错误率、成本监控。
- 配置中心与环境变量 -> 模型、检索、工具、特性开关配置治理。
- 线上事故回滚 -> 提示词模板、模型策略、工作流和工具配置回退。
最小项目目标
本章建议先完成一个“灰度上线最小闭环”项目，例如：
- 给一个知识问答 Agent 制定上线前检查清单。
- 设计一组最小线上指标和告警阈值。
- 预演一次模型策略回退或工具开关回退。
参考入口：
- 章节代码片段索引
docs/examples/assets/samples/example-09-release-checklist.jsondocs/examples/assets/screenshots/README.md
9.2 核心原理
发布与回滚闭环图
工程化上线能力的关键，不是“把服务部署出去”而已，而是把“发布前校验、线上可观测、异常可回退、变化可追踪”做成制度化能力。 如果没有这层能力，再好的模型效果也很难长期服务真实业务。
一、可发布：发布流程必须标准化
上线不是“手动点几个按钮”那么简单。 一个最小可发布流程至少应回答：
- 这次改了什么。
- 是否经过自动测试与评测。
- 是否有上线负责人。
- 是否有灰度计划。
- 如果失败，如何回滚。
如果这些都不清楚，线上发布本质上就是在赌运气。
二、可观测：你必须知道线上到底发生了什么
AI Agent 项目上线后，最怕的不是出问题，而是出问题时不知道发生了什么。 因此至少要建设以下观测项：
- 请求成功率。
- 平均延迟与长尾延迟。
- 错误率与错误类型分布。
- 人工介入比例。
- 单次请求成本。
- 关键业务成功率。
三、可回退：任何变更都应可撤回
AI Agent 系统的变更不只是代码，还可能包括：
- 提示词（prompt）模板。
- 模型版本。
- 检索参数。
- 工具开关。
- 工作流节点逻辑。
因此回退方案不能只考虑“代码回滚”，还要考虑配置、模型策略和特性开关回退。
四、灰度优先：不要把生产环境当测试环境
对于高风险变更，建议优先采用：
- 小流量灰度。
- 指标观察。
- 用户分组或场景分组放量。
- 明确的停止放量条件。
这样可以把风险控制在可接受范围内，而不是一次性全量发布。
五、配置治理：环境一致性比想象中更重要
很多线上问题并不是代码本身有错，而是不同环境配置不一致。 在 AI Agent 项目里，尤其需要关注：
- 模型名是否一致。
- Prompt 版本是否一致。
- 检索参数是否一致。
- 工具权限和依赖地址是否一致。
- 特性开关是否按预期启用。
9.3 实操步骤
推荐做法不是先搭很重的运维系统，而是先做“发布清单 + 关键指标 + 回滚演练”这三个最小闭环。 先让系统具备最基本的上线秩序，再逐步扩展更复杂的监控和自动化能力。
步骤 1：定义环境分层和配置规则
至少明确：
- 开发环境干什么。
- 预发环境验证什么。
- 生产环境只允许什么级别的变更。
- 不同环境哪些配置必须一致，哪些可以不同。
步骤 2：建立上线前检查清单
建议最少覆盖：
- 变更范围。
- 自动测试结果。
- 评测结果。
- 风险点。
- 灰度计划。
- 回滚方案。
- 值班与负责人。
参考入口：
docs/examples/assets/samples/example-09-release-checklist.json
步骤 3：定义核心线上指标
第一版最建议先看 3 到 5 个核心指标，而不是一口气建几十个：
- 成功率。
- P95 延迟（长尾延迟）。
- 错误率。
- 请求成本。
- 关键业务指标（例如命中率、人工介入率或用户取消率）。
步骤 4：接入灰度与告警
至少明确：
- 哪些版本走灰度。
- 灰度期间看哪些指标。
- 哪个阈值一触发就暂停放量。
- 哪种错误必须立即回退。
步骤 5：设计回滚方案
回滚方案至少要覆盖：
- 代码版本回滚。
- Prompt / 模型配置回滚。
- 工具开关回滚。
- 工作流策略回退。
步骤 6：做一次桌面演练或真实演练
很多系统“有回滚方案”，但没人实际演练过。 建议至少做一次：
- 模型策略异常演练。
- 工具超时演练。
- 检索配置错误演练。
- 发布后指标异常回滚演练。
步骤 7：同步保留上线证据材料
建议至少保留：
- 上线清单样本：
docs/examples/assets/samples/example-09-release-checklist.json - 截图清单：
docs/examples/assets/screenshots/README.md - 章节片段索引
9.4 常见坑
坑 1：直接在生产环境试验新策略
如果没有灰度和指标观察，风险一旦暴露，影响范围会很大。
坑 2：没有统一配置来源
环境配置散落在不同地方，最终就会出现“本地能复现、预发不一致、线上更不一样”的混乱状态。
坑 3：告警阈值设置不合理
阈值太松会发现太晚，阈值太紧会造成告警疲劳。
坑 4：只会发版，不会回退
很多团队能上线，但真正出现问题时回退路径并不清晰，导致风险持续扩大。
坑 5：只关注代码版本，不关注模型和配置版本
AI Agent 项目的很多问题不是代码引起的，而是 Prompt、模型、工具和检索配置变化引起的。
坑 6：前端不参与线上治理
如果前端不了解线上状态、错误类型和灰度策略，用户看到的问题就很难被正确表达和反馈回来。
9.5 验证方式
工程化上线能力做完后，不能只问“能不能部署”，更要问“是不是能稳定、可控地持续发布”。
一、发布流程可重复
- 同一流程能否稳定重复执行。
- 关键步骤是否有自动化支持。
- 发布记录是否可审计。
二、监控与告警是否有效
- 核心指标是否能实时查看。
- 异常是否能在目标时间内被发现。
- 错误类型是否可归类和追踪。
三、回滚演练是否真实可行
- 是否能在限定时间内切回稳定版本。
- 回滚后指标是否恢复正常。
- 团队是否知道谁负责执行回滚。
四、前端体验是否跟上线策略一致
从前端视角检查：
- 灰度期间用户是否能感知关键风险提示。
- 异常时是否有清晰提示和后续动作。
- 是否有必要的降级或人工介入入口。
五、证据材料
- 上线清单样本：
docs/examples/assets/samples/example-09-release-checklist.json - 截图清单：
docs/examples/assets/screenshots/README.md - 图解配图：
docs/examples/assets/diagrams/chapter-09-release-loop.svg - 章节片段索引
9.6 面试表达
我负责把智能体能力从实验环境带到生产环境，重点建设发布、监控、灰度和回滚闭环。 这样系统具备持续迭代能力，而不是一次性演示成果；一旦线上出现异常，也能在分钟级发现并回退。
实战案例：知识问答系统灰度上线
- 背景：新版本需要上线，但担心全量发布带来服务风险。
- 动作：设计上线前检查清单、灰度放量策略、指标观测和一键回滚方案。
- 结果：上线过程平稳，异常可在分钟级发现并回退，团队对版本发布的把控能力明显提升。
推荐答题框架
如果面试官问“AI Agent 上线和普通服务上线有什么不同”，可以按下面顺序回答：
- 先讲 AI Agent 的变化不只来自代码，还来自模型、提示词（prompt）、检索和工具配置。
- 再讲为什么需要发布清单、灰度、监控和回滚。
- 再讲如何定义核心指标与告警。
- 最后讲前端如何承接异常提示、降级和用户反馈。
9.7 练习任务
- 选一个你当前最熟悉的 Agent 场景，写一份最小上线前检查清单。
- 定义 3 到 5 个核心线上指标，并给出告警阈值建议。
- 设计一次灰度发布方案，说明什么条件下继续放量、什么条件下立即回退。
- 写出一次回滚演练步骤，说明代码、配置和模型策略分别怎么回退。
- 设计一张前端运维结果页或状态页，说明哪些信息给内部团队看，哪些信息给用户看。
9.8 验收清单
- 任务完成率 >= 85%
- 关键指标达标率 >= 90%
- 异常场景通过率 >= 90%
- 至少完成 1 份最小上线前检查清单和 1 份灰度 / 回滚方案。
- 至少保留 1 份上线样本、1 组截图占位清单和 1 份章节代码片段索引。
- 至少能用 2 分钟讲清楚“为什么上线不是部署动作，而是发布、监控、回滚组成的工程闭环”。