别等 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 的测试用例结构很直接。一个最小例子可以先不用复杂工程化：

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 和监控。这里要先写清权限边界。

如果只是本地验证，起步可以很小：

pip install -U deepeval
deepeval test run test_chatbot.py

如果要登录云端、同步报告或追踪生产数据，就不再是同一个风险级别。你需要明确：

• 是否会上传输入、输出、检索上下文或 trace；
• 是否包含用户数据、内部文档或密钥痕迹；
• 谁能看到评估报告；
• 失败样本是否可以脱敏；
• CI 里是否允许自动同步。

这不是对 DeepEval 的否定，而是所有 eval / observability 工具都应该提前写清的数据边界。

给 AI 宿主的接入规则

如果要让 Claude Code、Codex、Cursor 或其他 AI 宿主使用 DeepEval，我会先给它一段明确规则：

你可以使用 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/