第8章 评测体系建设

8.1 问题场景

很多智能体项目停留在演示层面：现场看起来很聪明，但一改提示词（prompt）、一换模型、一调检索参数，线上体验就会波动。 没有标准化评测，你很难回答下面这些问题：

• 本次发布到底是变好了还是变差了。
• 变差的是哪一类问题。
• 是检索、工具、模型输出，还是前端展示引入了问题。
• 当前版本是否达到可发布门槛。

很多前端工程师刚开始做 AI Agent 项目时，会把“评测”理解成试几个问题看看效果。 这种方式在演示（Demo）阶段勉强够用，但一旦要上线或做团队协作，就很容易失控：

• 你记不住哪些问题以前通过过。
• 你无法客观比较不同版本。
• 你很难说服产品或面试官“这个系统真的更稳了”。

评测体系建设的本质，就是把“主观感觉不错”升级成“有样本、有指标、有回归、有门禁”的工程能力。

前端迁移提示

这一章和前端工程也高度相关，因为你原来就做过很多“质量保证”工作：

• 单元测试 / E2E -> 离线样本回归。
• CI 检查 -> 发布门禁。
• 埋点与漏斗分析 -> 线上行为指标。
• 错误监控 -> 失败样本归类与定位。

最小项目目标

本章建议先完成一个“最小评测闭环”项目，例如：

• 为一个 RAG 问答接口设计 20 条评测样本。
• 输出统一的评测结果 JSON。
• 明确发布阈值与不通过时的处理方式。

参考入口：

• 示例2 RAG接口与评测
• 章节代码片段索引

8.2 核心原理

Eval 闭环图

评测体系的价值，不在于多写几条问题，而在于把“样本 -> 指标 -> 结论 -> 发布动作”串成完整闭环。 如果只有样本，没有统一结果结构和发布规则，评测就很难真正进入工程流程。

一、分层评测：离线评测和线上指标都要有

最小评测体系一般至少有两层：

• 离线评测：固定样本集，便于版本间可比。
• 线上指标：真实用户行为与结果反馈，便于发现真实世界问题。

离线评测解决“改完之后客观变没变”，线上指标解决“用户真实体验有没有问题”。

二、指标必须和业务目标对应

评测指标不是越多越好，而是要能回答业务问题。 例如在问答场景里，最关键的常见指标包括：

• 命中率。
• 引用准确率。
• 拒答准确率。
• 平均延迟。

如果你在做执行型或工作流型 Agent，指标还可能包括：

• 节点成功率。
• 人工介入比例。
• 任务完成率。
• 用户取消率。

三、回归机制：每次改动都要能重跑同一套样本

评测的关键不只是有样本，而是：

• 样本要固定。
• 执行方式要固定。
• 结果结构要固定。
• 门禁标准要固定。

这样你才能真正比较不同版本，而不是每次都换一批问题“凭感觉看效果”。

四、结果结构必须可消费

为了便于前端、发布流程和报告模板使用，评测结果建议统一为稳定的结果结构。 例如你可以直接参考：

• docs/examples/assets/samples/example-02-eval-result.json

这种结构的好处是：

• 前端可以直接做结果展示页。
• 工作流或发布脚本可以自动读取指标。
• 作品集里也能直接展示关键结果。

五、评测最终要服务发布决策

真正成熟的评测，不只是给技术同学看，而是用于回答：

• 这个版本能不能发。
• 哪个指标没达标。
• 哪个模块引入了回退。
• 是临时放行，还是必须修复后再发布。

8.3 实操步骤

推荐做法不是先追求复杂评测平台，而是先做“最小样本集 + 统一结果结构 + 基线阈值”三件事。 先让评测跑起来，再逐步扩展自动化和治理深度。

步骤 1：先定义评测目标

先回答：

• 评测的是哪一条链路。
• 最关键的成功标准是什么。
• 失败时意味着什么业务风险。

如果目标都不清楚，后面的样本和指标会越来越散。

步骤 2：建立最小样本集

建议至少覆盖三类样本：

• 正常问题。
• 边界问题。
• 应该拒答的问题。

如果你在做问答场景，可以直接从：

• docs/guide/assets/ch04-eval-template.jsonl 开始理解最小样本结构。

步骤 3：统一结果格式

评测脚本输出必须可解析、可对比、可展示。 最小结果建议包括：

• 运行 ID。
• 评测集名称。
• 关键指标。
• 简要结论。

你可以直接复用：

• docs/examples/assets/samples/example-02-eval-result.json

步骤 4：建立基线阈值

不要等结果出来后再解释“其实这样也算可以”。 更合理的方式是提前约定阈值，例如：

• 命中率 >= 80%
• 引用准确率 >= 85%
• 不可回答场景拒答率 >= 90%

步骤 5：把评测接入版本迭代

每次改动以下任一项时，都应该重跑回归：

• 提示词（prompt）模板。
• 模型版本。
• 检索参数。
• 重排策略。
• 工具逻辑。
• 输出结构。

步骤 6：补前端结果展示与证据材料

前端建议至少能展示：

• 当前评测版本。
• 关键指标。
• 是否通过门禁。
• 典型失败样本。
• 可下载或查看的结果 JSON。

同时建议保留这些证据材料：

• 评测结果样本：docs/examples/assets/samples/example-02-eval-result.json
• 截图清单：docs/examples/assets/screenshots/README.md
• 章节片段索引
• 示例骨架

步骤 7：把评测能力映射回工程闭环

如果你已经做通最小评测闭环，可以继续映射：

• 第 4-5 章：用于验证 RAG 问答质量。
• 第 6 章：用于验证工作流节点成功率和恢复能力。
• 第 9 章：用于形成发布门禁和回滚依据。

8.4 常见坑

坑 1：只选容易通过的样本

这样会让评测结果严重失真，看起来很好看，但线上一用就暴露问题。

坑 2：指标很多但没有优先级

如果没有“哪个指标最重要”，最后就会在评审时陷入解释和扯皮。

坑 3：评测依赖手工执行

手工跑一次可以，长期依赖手工就很难稳定，也不利于持续迭代。

坑 4：只看平均结果，不看失败样本

很多系统平均分不差，但关键失败样本非常伤业务。 如果不做失败归类，修复效率会很低。

坑 5：只有技术结果，没有发布动作

如果评测结果和“发不发版”无关，团队很快就会把它当成装饰性流程。

坑 6：前端没有参与评测结果设计

前端如果不知道结果字段和失败分类，后续很难把评测结果做成用户可理解、团队可复用的界面和报告。

8.5 验证方式

评测体系建设做完后，不能只看“脚本能不能运行”，更要看它能不能真正支持决策、定位问题和沉淀证据。

一、样本覆盖度

• 是否覆盖正常、边界、拒答场景。
• 是否存在关键高频问题样本。
• 是否保留失败案例。

二、结果稳定性

• 同一版本多次运行结果是否波动可控。
• 关键指标是否能稳定复现。
• 样本结构和结果结构是否始终一致。

三、门禁有效性

• 指标不达标时，流程是否明确阻断或预警。
• 发布前是否能看到客观评测结果。
• 团队是否基于同一套结果做决策。

四、前端可展示性

从前端视角再检查：

• 指标是否适合做成清晰卡片或表格。
• 失败样本是否能被展开查看。
• 用户或团队是否能理解“为什么这版不通过”。

五、证据材料

• 评测结果样本：docs/examples/assets/samples/example-02-eval-result.json
• 截图清单：docs/examples/assets/screenshots/README.md
• 图解配图：docs/examples/assets/diagrams/chapter-08-eval-loop.svg
• 章节片段索引
• 示例骨架

8.6 面试表达

我把评测做成发布门禁，而不是上线后的补救动作。 通过标准样本、统一结果结构和自动回归，我确保每次迭代都能客观证明质量变化，并能快速定位回退来源。

实战案例：版本发布前自动回归评测

• 背景：模型策略更新后，线上体验出现不可预期波动。
• 动作：构建离线评测集、统一结果结构，并接入发布前自动回归流程。
• 结果：每次发布都有量化报告，质量回退可提前拦截，版本讨论也从“凭感觉”转成“看指标和失败样本”。

推荐答题框架

如果面试官问“为什么评测重要”，可以按下面顺序回答：

1. 先讲 AI Agent 输出具有概率性，不能只靠主观感受判断版本优劣。
2. 再讲样本集、指标、结果结构和回归机制。
3. 再讲它如何影响发布决策。
4. 最后讲前端如何展示结果和失败样本，帮助团队协作。

8.7 练习任务

1. 选一条你正在做的链路，定义至少 15 条最小评测样本，覆盖正常、边界和拒答场景。
2. 设计一份统一的评测结果 JSON，至少包含运行 ID、关键指标和简要结论。
3. 设定一组发布门禁阈值，并说明任一指标不达标时应该怎么处理。
4. 参考 示例2 RAG接口与评测，把一个问答或执行型场景做成最小回归评测闭环。
5. 设计一个前端结果页，说明关键指标、失败样本和结论分别展示在哪里。

8.8 验收清单

• 任务完成率 >= 85%
• 关键指标达标率 >= 90%
• 异常场景通过率 >= 90%
• 至少完成 1 组最小评测样本和 1 份统一结果结构。
• 至少保留 1 份评测结果样本、1 组截图占位清单和 1 份章节代码片段索引。
• 至少能用 2 分钟讲清楚“为什么评测不是附加项，而是发布门禁能力”。