DeepEval：用 pytest 的姿势评测 AI Agent，六个指标盯住六种失败
DeepEval：用 pytest 的姿势评测 AI Agent，六个指标盯住六种失败
Agent 会"选对工具但传错参数"，也会"完成任务但绕了十个弯"——每种失败都需要专门的指标。
写完一个 AI Agent，你怎么知道它靠不靠谱？手测几个 case 试试感觉？这不叫评测，这叫抽签。Agent 的失败方式和普通 LLM 应用根本不同：它可能选对工具却传错参数，可能制定了完美计划却中途跑偏，可能最终完成了任务但绕了十个弯烧掉一堆 token——每一种失败模式都需要专门的测量。
DeepEval（confident-ai/deepeval，18,463 stars，Python，Apache-2.0）是目前最完整的开源 LLM 评测框架之一，Confident AI 出品、活跃更新。它的 AI Agent 评测体系（官方两篇指南：AI Agent Evaluation 与 AI Agent Evaluation Metrics）把"Agent 怎么测"讲成了体系——三层评测范围、六个专用指标、pytest 风格跑进 CI/CD。这篇文章把它拆给你看。
本文提纲
- DeepEval 是什么：pytest 风格的 LLM 评测框架
- 核心模型：两层 Agent + 三层评测范围
- 六指标体系：每个指标盯一种失败
- 关键工程点：tracing 是前提
- 自定义评测：GEval
- 跑进 CI/CD：pytest 风格
- 和同类工具怎么选
DeepEval 是什么：pytest 风格的 LLM 评测框架
DeepEval 的定位是 "The LLM Evaluation Framework"——开源 LLM 评测框架，Confident AI 公司出品（配套云平台 Confident AI 做评测管理和监控）。它最大的特色是用 pytest 的心智模型做评测：goldens（测试样例）+ metrics（指标）+ assert_test()，评测写起来和写单元测试一样，deepeval test run 一条命令跑全套，天然融进 CI/CD。
最近它还追了个新热点：发布 JevEval（Jev-as-a-Judge）——用 System One 决策模型当 judge 来替代 LLM judge，呼应了决策模型这个新方向。
对 AI Agent，DeepEval 给出的评测框架分两个维度：先理解 Agent 的两层结构，再按三层评测范围选指标。
核心模型：两层 Agent + 三层评测范围
Agent 的两层结构
DeepEval 把 AI Agent 拆成两层，这个划分决定了评测怎么设计：
- 推理层（Reasoning Layer）：LLM 负责——理解用户意图、分解复杂任务、创建策略、决定用哪些工具、以什么顺序。质量受模型选择、prompt 模板（官方认为这是影响推理质量的最重要因素）、温度影响。
- 行动层（Action Layer）：工具负责——从候选中选对工具、生成正确参数、按依赖顺序调用、处理工具输出。质量受可用工具数量（太多让 LLM 困惑，太少留能力缺口）、工具描述（含糊导致选错）、schema（类型和必填字段清晰度）、工具命名影响。
三层评测范围
因为"成功"依赖推理和行动两层，评测分三个互补的 scope：
| 范围 | 看什么 | 适合测什么 |
|---|---|---|
| End-to-end（黑盒） | 只看输入和最终输出，不查内部执行 | 最终结果对不对 |
| Trajectory（轨迹） | 完整有序的执行轨迹——推理、工具调用、观察、中间步骤 | 怎么到达的结果：计划好不好、有没有跑偏 |
| Component-level（组件） | 单个 span 或决策，如选工具并生成参数的那个 LLM span | 单次工具调用决策对不对 |
这个区分是 DeepEval Agent 评测的骨架：不同指标需要不同的 scope——测最终质量用黑盒，测推理和执行用轨迹，测单次工具决策挂到组件上。
六指标体系：每个指标盯一种失败
DeepEval 的 Agent 指标共六个，分三组挂在两层结构和三个 scope 上。核心设计哲学：每个指标针对一种特定失败模式。
推理层指标（Trajectory）
1. PlanQualityMetric——计划本身好不好。从完整轨迹中提取任务和计划，用 LLM judge 评估计划是否逻辑、完整、高效。坏计划导致浪费步骤、漏需求或直接失败。
2. PlanAdherenceMetric——是否遵循自己的计划。官方有句很扎心的话："制定好计划只是成功的一半——执行中途偏离策略的 Agent，破坏的是自己的推理。" 计划好但执行跑偏，这个指标会抓出来。
行动层指标（Component-level）
3. ToolCorrectnessMetric——选对工具了吗。把 LLM span 选的工具和预期工具列表对比。可配置严格度：默认只比工具名，也可以要求输入参数和输出都匹配。
4. ArgumentCorrectnessMetric——参数生成对了吗。算式直接明了：
Argument Correctness = 正确生成的输入参数数 / 工具调用总数执行层指标（Trajectory）
5. TaskCompletionMetric——任务最终完成了吗。这是"Agent 成功的终极度量"——它做了用户要求的事吗？分析完整有序轨迹来判断。
6. StepEfficiencyMetric——完成得高效吗。检查完整轨迹中是否有不必要或绕弯的步骤。官方点破了两者的关系："Agent 可能完成了任务但很低效，浪费 token 和时间；反过来，高效的 Agent 没完成任务则毫无价值。两者都要测。"评分用 AlignmentScore(任务, 执行步骤)。
一张表总结：
| 层 | 职责 | 评测范围 | 指标 |
|---|---|---|---|
| 推理层 | 规划、定策略 | Trajectory | PlanQuality、PlanAdherence |
| 行动层 | 选工具、传参数 | Component-level | ToolCorrectness、ArgumentCorrectness |
| 执行层 | 编排全循环、完成目标 | Trajectory | TaskCompletion、StepEfficiency |
关键工程点：tracing 是前提
六指标里四个是 trajectory 指标——它们要读完整有序的执行轨迹，所以必须有 tracing。这是很多团队踩的第一个坑：想用 TaskCompletionMetric 却没接 tracing，跑不起来。
DeepEval 的做法是用 @observe 装饰器标记 agent 和工具，trajectory 指标通过 evals_iterator(metrics=[...]) 传入，component 指标直接挂在 LLM span 上：
from deepeval.metrics import TaskCompletionMetric, StepEfficiencyMetric
from deepeval.tracing import observe
task_completion = TaskCompletionMetric()
step_efficiency = StepEfficiencyMetric()
@observe(type="agent")
def travel_agent(user_input):
...trajectory 指标不能独立使用，必须配合 evals_iterator 或 observe 装饰器——这是官方文档反复强调的硬性要求。
另一个工程友好点：框架无关。无论你用 LangChain、LangGraph、OpenAI Agents、Pydantic AI、CrewAI、Google ADK、Anthropic 还是 LlamaIndex，官方文档都有对应的手动埋点示例（10+ 框架的可复制代码），instrument 之后指标照常用。
自定义评测：GEval
六个内置指标是通用的，但你的业务总有特殊标准——"Agent 是否保持了专业的客服语气"、"回复是否遵守了公司话术规范"。这时候用 GEval：用 LLM-as-a-judge 按你用自然语言定义的任意标准评分，可以用于黑盒输出也可以挂到具体组件。
GEval 是 DeepEval 的老牌能力（还有配套的 DAG metric 构建器做更复杂的判定流程），加上前面说的 JevEval（决策模型 judge），它的 judge 层现在是三级可选：GEval（通用 LLM judge）/ JevEval（决策模型 judge）/ 自定义 metric（完全自己写）。
跑进 CI/CD：pytest 风格
开发环境过了，怎么防止每次 push 或 PR 时回归？DeepEval 的答案是融进 pytest：
# test_llm_app.py
import pytest
from deepeval import assert_test
from deepeval.dataset import EvaluationDataset, Golden
from deepeval.metrics import TaskCompletionMetric
from deepeval.tracing import observe, update_current_trace
# 1. 加载 goldens 数据集
dataset = EvaluationDataset(
goldens=[Golden(input="What is pi rounded to 2 decimal places?")]
)
# 2. 埋点你的 agent
@observe
def my_ai_agent(query: str) -> str:
answer = "Pi rounded to 2 decimal places is 3.14."
update_current_trace(input=query, output=answer)
return answer
# 3. 对每个 golden 跑评测
@pytest.mark.parametrize("golden", dataset.goldens)
def test_llm_app(golden):
assert_test(golden, [task_completion])然后 deepeval test run 像跑普通测试套件一样跑评测——本地开发、CI/CD 自动化都一样。因为 agent 已被 tracing，测试用例自动构建，不用手动抽取输入输出。
这个模式和我们之前拆过的微软 ai-agent-evals（Foundry 生态 CI 评测）理念一致：评测不过、上线免谈。区别是 DeepEval 框架无关 + 本地可跑，微软方案绑定 Foundry 云服务。
和同类工具怎么选
把 DeepEval 放进坐标系：
- vs LangSmith / Opik：它们是"观测平台优先"（trace + eval + 云服务），DeepEval 是"测试框架优先"（pytest 原生 + 开源本地跑 + 可选云）。想要 CI 里的断言式评测，DeepEval 的 pytest 模型最顺；想要深度 trace 分析平台，LangSmith/Opik 更成熟。
- vs microsoft/ai-agent-evals：微软方案绑定 Foundry，开箱即用但锁生态；DeepEval 框架无关，但要自己埋点。
- vs 自建 eval 脚本：六指标体系 + tracing 集成 + GEval + CI 集成，DeepEval 把重复轮子都造好了；自建的灵活性换的是把这些轮子重造一遍的成本。
对正在认真做 Agent 的团队，DeepEval 的六指标框架本身就是一份评测设计课：不要只测最终输出，把计划质量、计划遵循、工具选择、参数正确性、任务完成、步骤效率分开测——出问题时你才知道坏在哪一层。
参考链接
- DeepEval 指南：AI Agent Evaluation - Agent 评测总览：两层结构、三层范围、框架集成
- DeepEval 指南：AI Agent Evaluation Metrics - 六指标详解：定义、算法、代码示例
- GitHub: confident-ai/deepeval - 18,463 stars，Python，Apache-2.0
- DeepEval 文档 - 全部 metric 与 tracing 文档
- Confident AI - 配套云平台
- 我的 Agent 上生产四关 - Trace/Eval/Guardrail/Token 标准框架
- 我的微软 ai-agent-evals 拆解 - Foundry 生态的 CI 评测方案对比
你的 Agent 评测测到哪一层了？只看最终输出，还是已经拆到工具调用和计划质量？评论区聊聊，觉得有用点个赞让更多做 Agent 的人看到。
作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top
本文首发于 AI人工智能时代，转载请注明出处。
