别等 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 的测试用例结构很直接。一个最小例子可以先不用复杂工程化pythonfrom deepeval.test_case import LLMTestCasecase 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 比最终答案更适合调 AgentDeepEval 说明书里提到端到端评估和可追踪评估两种模式。对普通聊天机器人最终答案评估已经有价值对 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 和监控。这里要先写清权限边界。如果只是本地验证起步可以很小bashpip install -U deepevaldeepeval test run test_chatbot.py如果要登录云端、同步报告或追踪生产数据就不再是同一个风险级别。你需要明确- 是否会上传输入、输出、检索上下文或 trace- 是否包含用户数据、内部文档或密钥痕迹- 谁能看到评估报告- 失败样本是否可以脱敏- CI 里是否允许自动同步。这不是对 DeepEval 的否定而是所有 eval / observability 工具都应该提前写清的数据边界。## 给 AI 宿主的接入规则如果要让 Claude Code、Codex、Cursor 或其他 AI 宿主使用 DeepEval我会先给它一段明确规则text你可以使用 DeepEval 设计 LLM 应用评估但必须先说明1. 被评估对象是 RAG、Agent、聊天机器人还是单个 prompt2. 失败样本是什么3. 每个 metric 对应哪类失败4. 阈值为什么这样设置5. 是否需要 trace6. 是否涉及云端同步、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/