别等 Agent 上线后补评估：先用 DeepEval 写失败样本
# 别等 Agent 上线后补评估：先用 DeepEval 写失败样本
很多团队接入 AI Agent、RAG 或客服机器人时，最容易晚一步做的事情就是评估。先把模型、prompt、工具调用、RAG 检索串起来，等 demo 能跑，再补一个“评估模块”。这条路看起来快，但问题也很明显：上线前你并不知道系统在哪些地方会稳定失败，只知道它在几个样例里看起来还行。
DeepEval 适合解决的不是“给模型打一个漂亮分数”，而是把 LLM 应用的质量检查变成一组可以反复运行的测试。Doramagic 的 DeepEval 项目说明书把它整理成几个关键面：`LLMTestCase` 测试用例、`GEval`、`AnswerRelevancyMetric`、`TaskCompletionMetric`、幻觉检测、`deepeval test run`、`deepeval generate golden`、trace / integrations，以及本地评估和 Confident AI 云端同步之间的边界。
我会把 DeepEval 放在 Agent 工作流里的“发布前闸门”，不是上线后的报表层。
## 先写失败样本，而不是先挑指标
很多人一上来会问：我应该用 G-Eval、answer relevancy，还是 hallucination metric？这个问题不坏，但顺序错了。
更好的起点是先写失败样本：
- RAG 明明检索到了上下文，但回答没有引用关键事实；
- Agent 工具调用成功了，但调用了错误工具；
- 输出语气很自信，但 `retrieval_context` 里没有支撑；
- 任务走完了，但中间 trace 显示重复尝试或走错分支；
- 模型回答“看起来对”，但违反了产品政策、权限边界或用户约束。
这些样本先写出来，指标才有意义。否则阈值只是一个数字，无法解释为什么 0.7 合格、0.69 不合格。
## 最小可用测试用例
DeepEval 的测试用例结构很直接。一个最小例子可以先不用复杂工程化：
```python
from deepeval.test_case import LLMTestCase
case = LLMTestCase(
input="用户问：退款政策是什么？",
actual_output="用户可以在 30 天内免费退款。",
expected_output="我们提供 30 天全额退款，且不收取额外费用。",
retrieval_context=[
"All customers are eligible for a 30 day full refund at no extra costs."
],
)
```
这类用例的价值不在代码有多复杂，而在它强迫你把输入、实际输出、期望输出和检索上下文分开。对 RAG 或 Agent 来说，这个拆分很重要：输出不应该只看自然语言是否顺眼，还要看它是否真的使用了允许使用的上下文。
## 指标要贴近失败类型
DeepEval 提供的指标很多，但我不会一开始就把所有指标都塞进 pipeline。先按失败类型选：
- 如果担心答案脱离问题，用 `AnswerRelevancyMetric`。
- 如果担心 Agent 没有完成任务，用 `TaskCompletionMetric`。
- 如果需要自定义判断标准，用 `GEval` 写清 criteria。
- 如果是 RAG 场景，必须把 `retrieval_context` 纳入测试，而不是只看最终回答。
一个实用规则是：每个指标必须对应一个“失败时该谁修”的问题。失败后应该能判断是 prompt、检索、工具路由、测试数据，还是产品边界没写清楚。如果指标失败后只能得到“模型表现不好”，那这个指标还不够具体。
## trace 比最终答案更适合调 Agent
DeepEval 说明书里提到端到端评估和可追踪评估两种模式。对普通聊天机器人，最终答案评估已经有价值；对 Agent，更重要的是路径。
一个 Agent 最终回答正确，不代表过程可靠。它可能：
- 先调用了不该调用的工具；
- 对同一个步骤重试多次；
- 在低置信检索结果上继续推理；
- 把中间错误吞掉，只输出一个顺滑结论。
所以评估 Agent 时，我会要求 trace 至少能回答四个问题：
1. 选择了哪个工具；
2. 使用了哪些上下文；
3. 哪一步失败或重试；
4. 最终回答引用了哪些证据。
没有 trace 的评估，很容易只是在评估文案质量。
## golden 生成不能替代人工复核
`deepeval generate golden` 很适合降低测试集启动成本。它支持从文档、上下文、空白输入或已有 golden 扩展测试用例。这个能力很有用，但也容易被误用。
我不会把生成出的 golden 直接当真值。更安全的做法是：
- 先生成 20 到 50 条候选；
- 人工删掉语义重复、答案含糊、来源不清的样本；
- 标出 5 到 10 条“必须失败时报警”的关键样本；
- 每次 prompt、检索器、工具路由或模型版本变化后，优先跑这组关键样本。
这样 DeepEval 才像回归测试，而不是一次性评测截图。
## 云端同步和本地评估要分清
DeepEval 支持本地评估，也支持登录 Confident AI 后同步报告、数据集、trace 和监控。这里要先写清权限边界。
如果只是本地验证，起步可以很小：
```bash
pip install -U deepeval
deepeval test run test_chatbot.py
```
如果要登录云端、同步报告或追踪生产数据，就不再是同一个风险级别。你需要明确：
- 是否会上传输入、输出、检索上下文或 trace；
- 是否包含用户数据、内部文档或密钥痕迹；
- 谁能看到评估报告；
- 失败样本是否可以脱敏；
- CI 里是否允许自动同步。
这不是对 DeepEval 的否定，而是所有 eval / observability 工具都应该提前写清的数据边界。
## 给 AI 宿主的接入规则
如果要让 Claude Code、Codex、Cursor 或其他 AI 宿主使用 DeepEval，我会先给它一段明确规则：
```text
你可以使用 DeepEval 设计 LLM 应用评估，但必须先说明：
1. 被评估对象是 RAG、Agent、聊天机器人，还是单个 prompt；
2. 失败样本是什么；
3. 每个 metric 对应哪类失败；
4. 阈值为什么这样设置；
5. 是否需要 trace；
6. 是否涉及云端同步、API key 或用户数据。
不要把 LLM-as-a-Judge 分数当成绝对真值。
不要把生成的 golden 样本直接当人工标注。
不要声称本地已经安装或跑通，除非有单独运行日志。
```
这段规则比“帮我加 DeepEval”更有用。它把评估从一个工具安装任务，变成一个发布前质量合同。
## 我会怎么开始
第一天不要做复杂平台化。我会先选一个真实场景，例如 RAG 问答或客服任务，写 10 条测试：
- 3 条正常成功样本；
- 3 条容易幻觉的样本；
- 2 条检索上下文缺失样本；
- 1 条权限边界样本；
- 1 条空结果样本。
然后只接一个指标，不接一堆指标。先让失败能被解释，再扩展到更多 metric、trace、golden 生成和 CI。
DeepEval 的价值不在“让 AI 看起来更可控”，而在让失败变得更早、更具体、更容易复现。对 Agent 来说，这比上线后多看一个平均分重要得多。
## 资料角色
- 上游项目：confident-ai/deepeval，负责真实代码、安装命令、release 和 API 事实，https://github.com/confident-ai/deepeval
- Doramagic 项目页：把 DeepEval 整理成可带走、可装载、可验证的能力资产，https://doramagic.ai/zh/projects/deepeval/
- Doramagic 说明书：适合在接入前阅读测试用例、指标、trace、golden 生成、pitfall 和边界提示，https://doramagic.ai/zh/projects/deepeval/manual/