DeepEval 怎么评估 Agent 的完整执行轨迹而不是只看最终输出【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval你手里有一个会调工具、走多步推理的 Agent但只看它的最终回答无法判断它是否遵循了自己的计划、是否走了冗余步骤、中间某一步是否出错。DeepEval 的 trajectory-based evaluation轨迹评估就是为这个场景设计的它把 Agent 从接收任务到产出结果之间的整条执行链——计划、LLM 调用、工具调用、重试、子 Agent 交接——作为一个整体打分。适用前提是 Python 或 TypeScript 环境并且 Agent 已经或准备接入 DeepEval 的 tracing没有 tracing 就没有轨迹可供评估。轨迹评估、端到端评估和组件级评估的区别在于指标能看到的范围官方文档端到端评估把应用当黑盒只评可观察的输入输出轨迹评估看进 Agent 内部但把整条有序的 span 链当作一个执行单元来评组件级评估只评某一个 span单次检索、工具或 LLM 调用。三种方式可以在同一次评估中组合使用但本文只聚焦轨迹这一条路径。准备安装 DeepEval 并登录Python 环境[inspect]子模块提供终端里的 trace-tree TUI官方建议只在开发环境安装pip install -U deepeval[inspect]TypeScript 环境trace-tree TUI 随包自带npm install deepeval然后在对应环境中登录登录会把结果关联到 Confident AI 用于存储和查看deepeval login # Python npx deepeval login # TypeScript轨迹指标由 LLM 充当裁判本地跑评估时需要提供裁判模型所需的密钥官方 CI 示例中用的是OPENAI_API_KEY。第一步创建评估数据集用一个EvaluationDataset存放若干Golden每个Golden的input就是发起一次 Agent 运行的任务输入。下面的取值直接来自数据集加载文档/evaluation-datasets.mdx)的示例请替换为你 Agent 实际要执行的任务from deepeval.dataset import Golden, EvaluationDataset goldens [ Golden(inputWhat is your name?), Golden(inputChoose a number between 1 and 100), # ... ] dataset EvaluationDataset(goldensgoldens)注意一个EvaluationDataset只能装单轮 golden 或多轮 golden 中的一种混合文件会报错。第二步给 Agent 接入 tracing轨迹评估要求tracing/evaluation-llm-tracing.mdx)。手动接入的方式是用observe包住 Agent 的顶层函数嵌套的observe函数会自然形成 span 树再用update_current_trace写入 trace 级别的输入输出。下面的同步示例中my_ai_agent内部answer ...一行是占位需要替换成你真实的 LLM 调用其余部分可直接使用from deepeval.evaluate import AsyncConfig from deepeval.tracing import observe, update_current_trace from deepeval.metrics import TaskCompletionMetric observe() def my_ai_agent(query: str) - str: answer ... # call your LLM here update_current_trace(inputquery, outputanswer) return answer for golden in dataset.evals_iterator( metrics[TaskCompletionMetric()], async_configAsyncConfig(run_asyncFalse), ): my_ai_agent(golden.input)如果你用的是主流框架可以换成对应的一行式集成被捕获为 span 的每次决策、工具调用和嵌套操作都会成为轨迹的一部分框架接入方式LangChain / LangGraph把deepeval的CallbackHandler传入invoke/ainvoke的config{callbacks: [...]}OpenAI把from openai import OpenAI换成from deepeval.openai import OpenAIAnthropic把from anthropic import Anthropic换成from deepeval.anthropic import AnthropicPydantic AI给Agent传入instrumentDeepEvalInstrumentationSettings()CrewAI创建 crew 前调用一次instrument_crewai()并用deepeval的Crew、Agent替换Strands / AgentCore / LlamaIndex / OpenAI Agents / Google ADK各自的一次instrument_*()或 trace processor 注册TypeScript 侧对应的是observe/updateCurrentTrace手动接入或各框架的 handler。Python 的循环支持 Async 和 Sync 两种写法Async 是默认且更快的模式每个 golden 用asyncio.create_task(...)dataset.evaluate(task)并发跑Sync 通过AsyncConfig(run_asyncFalse)一次跑一个 golden适合调试、限流严格的 provider 或 Jupyter 事件循环问题。第三步选择轨迹指标并运行评估把轨迹指标传给evals_iterator()然后对每个 golden 调用一次你的被追踪 Agent。迭代器会为每个 golden 捕获一条 trace在 Agent 跑完后评估完整轨迹并把每个指标的分数和原因与 trace 一起存进本次 test run——这样你才能把一个失败对应到产生它的那条具体执行路径。from deepeval.metrics import ( TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, ) metrics [ TaskCompletionMetric(), StepEfficiencyMetric(), PlanAdherenceMetric(), ] for golden in dataset.evals_iterator(metricsmetrics): my_ai_agent(golden.input)TypeScript 版本的等价写法来自轨迹评估文档import { TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, } from deepeval/metrics; const metrics [ new TaskCompletionMetric(), new StepEfficiencyMetric(), new PlanAdherenceMetric(), ]; for await (const golden of dataset.evalsIterator({ metrics })) { await myAiAgent((golden as Golden).input); }这三个指标分别判断什么三个指标都是 referenceless不需要标注期望输出且输出评分理由均由 LLM 判分指标回答的问题计算方式TaskCompletionMetric/metrics-task-completion.mdx)结果任务达成了吗从 trace 中用 LLM 抽取 Task 和 Outcome不显式指定task时自动推断打分AlignmentScore(Task, Outcome)StepEfficiencyMetric/metrics-step-efficiency.mdx)路径步骤经济吗抽取 Task 后评估执行步骤AlignmentScore(Task, Execution Steps)会惩罚并非完成任务所严格必需的动作重复、重试、绕路PlanAdherenceMetric/metrics-plan-adherence.mdx)过程遵循计划了吗从 trace 的thinking/reasoning中抽取 Plan打分AlignmentScore((Task, Plan), Execution Steps)三者覆盖不同的失败模式Agent 可能达成结果但路径臃肿也可能路径精简却没达成目标或者执行偏离了自己的计划——官方 FAQ 的结论是run both即同时跑结果维度和过程维度的指标。常用可选参数三个指标基本一致默认值来自各自的指标文档threshold最低通过阈值默认0.5设为None可只打分不判通过model裁判模型OpenAI 的 GPT 模型名或任意DeepEvalBaseLLM自定义模型task仅 TaskCompletion显式固定评估目标不传则从 trace 推断include_reason默认True输出评分理由strict_mode默认False设为True时强制二值分完美为 1否则 0并把阈值覆盖为 1verbose_mode默认False设为True时把计算中间步骤打印到控制台flaky默认False标记指标为 flakyasync_mode仅 Python默认True控制measure()内的并发执行。一个需要留意的默认行为如果 trace 里没有能从thinking或reasoning中抽出的计划PlanAdherenceMetric会默认以 1 分通过。文档的 FAQ 解释一个意外的满分通常意味着你的 trace 没有暴露出 reasoning——这不是执行很好而是没有可评估的计划。确认评估结果deepeval inspect每次evals_iterator()运行都会保存在本地。运行下面命令在终端里查看 Agent 的完整执行轨迹包括每个 span 的分数和指标理由deepeval inspect # Python npx deepeval inspect # TypeScript[inspect]子模块就是为这个 TUI 准备的。这是轨迹评估的主要本地验证方式你可以沿着 span 树看到某个低分指标对应到具体哪一段执行路径。可选把轨迹评估放进 CI 测试官方文档给出了把同一套数据集、被追踪 Agent 和指标放进 pytest 的写法。某个轨迹指标低于阈值时测试失败从而阻止回归上线from deepeval.metrics import ( TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, ) from deepeval.dataset import EvaluationDataset, Golden from deepeval import assert_test from app import my_ai_agent import pytest dataset EvaluationDataset( goldens[Golden(inputPlan a three-day trip to Paris)] ) metrics [ TaskCompletionMetric(), StepEfficiencyMetric(), PlanAdherenceMetric(), ] pytest.mark.parametrize(golden, dataset.goldens) def test_agent_trajectory(golden: Golden): my_ai_agent(golden.input) assert_test(goldengolden, metricsmetrics)deepeval test run test_agent_trajectory.pyTypeScript 侧则用 vitest 的expect(golden).toPass(metrics, { task: ... })以npx deepeval test run agent-trajectory.test.ts运行。注意 CI 中 Agent 必须保持被 instrumentation否则断言捕获不到完整 trace更完整的流水线配置见 unit testing in CI/CD 文档。限制与已知约束tracing 是硬性前提StepEfficiencyMetric和PlanAdherenceMetric是 trace-only 指标不能脱离 trace 单独使用必须放在evals_iterator或observe中TaskCompletion 同样需要从 trace 抽取 Task 和 Outcome。指标只在评估上下文运行在evaluate()/assert_test()之外调用被observe装饰的函数时指标不会运行此时控制台出现的 trace 日志可用CONFIDENT_TRACE_VERBOSE0和CONFIDENT_TRACE_FLUSH0关闭。短生命周期进程trace 由后台 worker 线程上报进程在最后一次追踪调用后立即退出可能丢失上报可调用deepeval.flush_traces(timeout30.0)等待上报完成。轨迹指标与组件级指标可以在同一次追踪运行中混合轨迹指标传给迭代器或测试断言组件指标挂到具体 span 上。想继续深入时参考指标总览含阈值与自定义 LLM 用法和 Agent 快速上手/getting-started-agents.mdx)含各框架集成与子 Agent 评估。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepEval 怎么评估 Agent 的完整执行轨迹而不是只看最终输出
DeepEval 怎么评估 Agent 的完整执行轨迹而不是只看最终输出【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval你手里有一个会调工具、走多步推理的 Agent但只看它的最终回答无法判断它是否遵循了自己的计划、是否走了冗余步骤、中间某一步是否出错。DeepEval 的 trajectory-based evaluation轨迹评估就是为这个场景设计的它把 Agent 从接收任务到产出结果之间的整条执行链——计划、LLM 调用、工具调用、重试、子 Agent 交接——作为一个整体打分。适用前提是 Python 或 TypeScript 环境并且 Agent 已经或准备接入 DeepEval 的 tracing没有 tracing 就没有轨迹可供评估。轨迹评估、端到端评估和组件级评估的区别在于指标能看到的范围官方文档端到端评估把应用当黑盒只评可观察的输入输出轨迹评估看进 Agent 内部但把整条有序的 span 链当作一个执行单元来评组件级评估只评某一个 span单次检索、工具或 LLM 调用。三种方式可以在同一次评估中组合使用但本文只聚焦轨迹这一条路径。准备安装 DeepEval 并登录Python 环境[inspect]子模块提供终端里的 trace-tree TUI官方建议只在开发环境安装pip install -U deepeval[inspect]TypeScript 环境trace-tree TUI 随包自带npm install deepeval然后在对应环境中登录登录会把结果关联到 Confident AI 用于存储和查看deepeval login # Python npx deepeval login # TypeScript轨迹指标由 LLM 充当裁判本地跑评估时需要提供裁判模型所需的密钥官方 CI 示例中用的是OPENAI_API_KEY。第一步创建评估数据集用一个EvaluationDataset存放若干Golden每个Golden的input就是发起一次 Agent 运行的任务输入。下面的取值直接来自数据集加载文档/evaluation-datasets.mdx)的示例请替换为你 Agent 实际要执行的任务from deepeval.dataset import Golden, EvaluationDataset goldens [ Golden(inputWhat is your name?), Golden(inputChoose a number between 1 and 100), # ... ] dataset EvaluationDataset(goldensgoldens)注意一个EvaluationDataset只能装单轮 golden 或多轮 golden 中的一种混合文件会报错。第二步给 Agent 接入 tracing轨迹评估要求tracing/evaluation-llm-tracing.mdx)。手动接入的方式是用observe包住 Agent 的顶层函数嵌套的observe函数会自然形成 span 树再用update_current_trace写入 trace 级别的输入输出。下面的同步示例中my_ai_agent内部answer ...一行是占位需要替换成你真实的 LLM 调用其余部分可直接使用from deepeval.evaluate import AsyncConfig from deepeval.tracing import observe, update_current_trace from deepeval.metrics import TaskCompletionMetric observe() def my_ai_agent(query: str) - str: answer ... # call your LLM here update_current_trace(inputquery, outputanswer) return answer for golden in dataset.evals_iterator( metrics[TaskCompletionMetric()], async_configAsyncConfig(run_asyncFalse), ): my_ai_agent(golden.input)如果你用的是主流框架可以换成对应的一行式集成被捕获为 span 的每次决策、工具调用和嵌套操作都会成为轨迹的一部分框架接入方式LangChain / LangGraph把deepeval的CallbackHandler传入invoke/ainvoke的config{callbacks: [...]}OpenAI把from openai import OpenAI换成from deepeval.openai import OpenAIAnthropic把from anthropic import Anthropic换成from deepeval.anthropic import AnthropicPydantic AI给Agent传入instrumentDeepEvalInstrumentationSettings()CrewAI创建 crew 前调用一次instrument_crewai()并用deepeval的Crew、Agent替换Strands / AgentCore / LlamaIndex / OpenAI Agents / Google ADK各自的一次instrument_*()或 trace processor 注册TypeScript 侧对应的是observe/updateCurrentTrace手动接入或各框架的 handler。Python 的循环支持 Async 和 Sync 两种写法Async 是默认且更快的模式每个 golden 用asyncio.create_task(...)dataset.evaluate(task)并发跑Sync 通过AsyncConfig(run_asyncFalse)一次跑一个 golden适合调试、限流严格的 provider 或 Jupyter 事件循环问题。第三步选择轨迹指标并运行评估把轨迹指标传给evals_iterator()然后对每个 golden 调用一次你的被追踪 Agent。迭代器会为每个 golden 捕获一条 trace在 Agent 跑完后评估完整轨迹并把每个指标的分数和原因与 trace 一起存进本次 test run——这样你才能把一个失败对应到产生它的那条具体执行路径。from deepeval.metrics import ( TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, ) metrics [ TaskCompletionMetric(), StepEfficiencyMetric(), PlanAdherenceMetric(), ] for golden in dataset.evals_iterator(metricsmetrics): my_ai_agent(golden.input)TypeScript 版本的等价写法来自轨迹评估文档import { TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, } from deepeval/metrics; const metrics [ new TaskCompletionMetric(), new StepEfficiencyMetric(), new PlanAdherenceMetric(), ]; for await (const golden of dataset.evalsIterator({ metrics })) { await myAiAgent((golden as Golden).input); }这三个指标分别判断什么三个指标都是 referenceless不需要标注期望输出且输出评分理由均由 LLM 判分指标回答的问题计算方式TaskCompletionMetric/metrics-task-completion.mdx)结果任务达成了吗从 trace 中用 LLM 抽取 Task 和 Outcome不显式指定task时自动推断打分AlignmentScore(Task, Outcome)StepEfficiencyMetric/metrics-step-efficiency.mdx)路径步骤经济吗抽取 Task 后评估执行步骤AlignmentScore(Task, Execution Steps)会惩罚并非完成任务所严格必需的动作重复、重试、绕路PlanAdherenceMetric/metrics-plan-adherence.mdx)过程遵循计划了吗从 trace 的thinking/reasoning中抽取 Plan打分AlignmentScore((Task, Plan), Execution Steps)三者覆盖不同的失败模式Agent 可能达成结果但路径臃肿也可能路径精简却没达成目标或者执行偏离了自己的计划——官方 FAQ 的结论是run both即同时跑结果维度和过程维度的指标。常用可选参数三个指标基本一致默认值来自各自的指标文档threshold最低通过阈值默认0.5设为None可只打分不判通过model裁判模型OpenAI 的 GPT 模型名或任意DeepEvalBaseLLM自定义模型task仅 TaskCompletion显式固定评估目标不传则从 trace 推断include_reason默认True输出评分理由strict_mode默认False设为True时强制二值分完美为 1否则 0并把阈值覆盖为 1verbose_mode默认False设为True时把计算中间步骤打印到控制台flaky默认False标记指标为 flakyasync_mode仅 Python默认True控制measure()内的并发执行。一个需要留意的默认行为如果 trace 里没有能从thinking或reasoning中抽出的计划PlanAdherenceMetric会默认以 1 分通过。文档的 FAQ 解释一个意外的满分通常意味着你的 trace 没有暴露出 reasoning——这不是执行很好而是没有可评估的计划。确认评估结果deepeval inspect每次evals_iterator()运行都会保存在本地。运行下面命令在终端里查看 Agent 的完整执行轨迹包括每个 span 的分数和指标理由deepeval inspect # Python npx deepeval inspect # TypeScript[inspect]子模块就是为这个 TUI 准备的。这是轨迹评估的主要本地验证方式你可以沿着 span 树看到某个低分指标对应到具体哪一段执行路径。可选把轨迹评估放进 CI 测试官方文档给出了把同一套数据集、被追踪 Agent 和指标放进 pytest 的写法。某个轨迹指标低于阈值时测试失败从而阻止回归上线from deepeval.metrics import ( TaskCompletionMetric, StepEfficiencyMetric, PlanAdherenceMetric, ) from deepeval.dataset import EvaluationDataset, Golden from deepeval import assert_test from app import my_ai_agent import pytest dataset EvaluationDataset( goldens[Golden(inputPlan a three-day trip to Paris)] ) metrics [ TaskCompletionMetric(), StepEfficiencyMetric(), PlanAdherenceMetric(), ] pytest.mark.parametrize(golden, dataset.goldens) def test_agent_trajectory(golden: Golden): my_ai_agent(golden.input) assert_test(goldengolden, metricsmetrics)deepeval test run test_agent_trajectory.pyTypeScript 侧则用 vitest 的expect(golden).toPass(metrics, { task: ... })以npx deepeval test run agent-trajectory.test.ts运行。注意 CI 中 Agent 必须保持被 instrumentation否则断言捕获不到完整 trace更完整的流水线配置见 unit testing in CI/CD 文档。限制与已知约束tracing 是硬性前提StepEfficiencyMetric和PlanAdherenceMetric是 trace-only 指标不能脱离 trace 单独使用必须放在evals_iterator或observe中TaskCompletion 同样需要从 trace 抽取 Task 和 Outcome。指标只在评估上下文运行在evaluate()/assert_test()之外调用被observe装饰的函数时指标不会运行此时控制台出现的 trace 日志可用CONFIDENT_TRACE_VERBOSE0和CONFIDENT_TRACE_FLUSH0关闭。短生命周期进程trace 由后台 worker 线程上报进程在最后一次追踪调用后立即退出可能丢失上报可调用deepeval.flush_traces(timeout30.0)等待上报完成。轨迹指标与组件级指标可以在同一次追踪运行中混合轨迹指标传给迭代器或测试断言组件指标挂到具体 span 上。想继续深入时参考指标总览含阈值与自定义 LLM 用法和 Agent 快速上手/getting-started-agents.mdx)含各框架集成与子 Agent 评估。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
