DeepEval Traced Evals 实战指南将指标挂载到 Trace 与 Span 的单轮评估范式【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalTraced Evals 是 DeepEval 在应用具备可观测性通过框架集成或手动observe埋点产出 Trace时采用的默认单轮single-turn评估路径整次执行构成一个 Trace其内部组件构成一个个 Span组件级指标直接挂载在对应 Span 上而不是拆分成独立的测试形态。本篇基于仓库文档 traced-evals.md结合源码与测试系统讲解如何把指标焊到 Span 上、如何用 pytest 与脚本两种形态运行 traced eval以及如何将结果上报到 Confident AI读完你可以在自己的 Agent / RAG / 工具调用应用中落地完整的追踪即评估闭环。一、Traced Evals 的核心概念Trace 是执行Span 是组件在 DeepEval 的评估体系中传统做法是手工构造LLMTestCase把input、actual_output、retrieval_context等字段喂给指标。而 traced eval 完全反过来先有观测再谈评估。Trace追踪一次端到端的应用执行例如一次完整的 Agent 调用链Span跨度Trace 内部的组件例如一次 LLM 调用、一次检索、一次工具调用或一次子 Agent 执行指标与 Span 绑定组件级指标如检索器的 Contextual Precision、生成 LLM 的 Answer Relevancy被挂载到它们所评估的那个具体 Span上全部留在同一次单轮 tracing eval 里而不是拆成多个独立的 test case。从源码可以确认 Span 的类型体系deepeval/tracing/types.py中定义了SpanType枚举包含agent、llm、retriever、tool四种具名类型types.py外加通用的base类型deepeval/tracing/__init__.py统一导出了observe、trace、trace_manager、flush_traces、a_flush_traces以及next_agent_span、next_llm_span、next_tool_span、next_retriever_span、next_span等全部 APIinit.py。需要说明的是本文聚焦eval-coupled评估耦合一侧把指标挂到 Span 上以及两种 traced eval 的代码形态。至于如何为应用埋点——添加observe、接入框架集成、设置 Span 类型 / tags / metadata——属于deepeval-tracingskill 的范畴仓库中另有 deepeval-tracing 技能文档本文不再展开。二、组件 / Span 级指标把指标挂到对的 Span上指标只有挂在正确的 Span 上才能利用该 Span 携带的输入、输出、上下文等数据完成计算。DeepEval 提供两种挂载方式分别对应集成自动建 Span与手动埋点建 Span两种场景。2.1 集成创建 Span用 next_*_span 预置指标当某个受支持的框架集成如 LangChain、CrewAI、OpenAI Agents 等负责创建 Span 时你无法在 Span 内部执行代码来设置指标此时需要用next_*_span系列上下文管理器为下一个该类型的 Span 预置指标等默认值from deepeval.tracing import next_retriever_span from metrics import RETRIEVER_SPAN_METRICS with next_retriever_span(metricsRETRIEVER_SPAN_METRICS): run_ai_app_with_integration_tracing(golden.input)当集成在with块内部创建第一个retriever类型的 Span 时这些预置的默认值会被一次性消费并应用到该 Span 上。next_*_span家族共四个具名入口按集成实际产生的 Span 类型选择函数匹配的 Span 类型典型场景next_agent_span(...)agent子 Agent / 元 Agent 执行next_llm_span(...)llm生成模型的 LLM 调用next_tool_span(...)tool工具 / 函数调用next_retriever_span(...)retrieverRAG 检索器查询next_span(...)则是不区分类型的通用版本适用于下一个 Span 类型未知或无关紧要的场合。这些上下文管理器不仅接受metrics还接受与update_current_span一致的通用字段input、output、retrieval_context、context、expected_output、tools_called、expected_tools、metadata、name、test_case、metric_collection并且是一站式的每个具名版本还额外接受自身类型专属字段例如next_llm_span支持model、input_token_count、output_token_count、cost_per_input_token、cost_per_output_token、token_intervals、promptnext_retriever_span支持embedder、top_k、chunk_sizenext_agent_span支持available_tools、agent_handoffsnext_tool_span支持descriptioncontext.py。2.2 手动埋点直接挂到 observe 上如果应用使用手动埋点或者集成支持被观测的组件 Span则可以直接把指标传给observe装饰器from deepeval.tracing import observe from metrics import GENERATOR_LLM_SPAN_METRICS observe(typellm, metricsGENERATOR_LLM_SPAN_METRICS) def call_model(messages): ...observe的type参数决定创建的 Span 类型可取值agent、llm、retriever、tool或自定义字符串tracing.py。除了metrics之外还可以传入metric_collection以及随**observe_kwargs透传的类型专属参数——例如observe(typellm, modelgpt-4.1, metrics[AnswerRelevancyMetric()])这在仓库测试 test_openai.py 中有完整示例。observe装饰器对普通同步函数、协程、同步生成器与异步生成器均有支持在Observer.__exit__中Span 的input会回填为函数入参、output回填为函数返回值并依据异常与否把 Span 状态标记为SUCCESS或ERROREDtracing.py。2.3 指标列表命名约定按组件命名不要建全局列表文档明确给出命名规范按组件命名指标列表例如RETRIEVER_SPAN_METRICS、GENERATOR_LLM_SPAN_METRICS、ORDER_LOOKUP_TOOL_SPAN_METRICS。不要为整个应用创建一个全局的组件指标列表。原因是指标与 Span 一一对应全局列表会导致同一个指标被错误地套用到不相关的 Span 上破坏精确评估的语义。2.4 底层原理next_*_span 是如何工作的从 context.py 的实现看next_*_span的机制有三个关键设计一次性消费one-shot每个next_*_span把默认值写入一个ContextVar由集成或其 OTel 处理器在创建第一个匹配类型的 Span 时通过pop_pending_for(span_type)消费掉with块内后续再创建的同类 Span 看到的是已清空的槽位context.py。按类型隔离per-type isolationbase、agent、llm、tool、retriever各自持有独立的ContextVar因此with next_agent_span(...), next_llm_span(...):这种叠加写法是安全无歧义的消费时pop_pending_for会把 base 槽位与类型槽位合并类型槽位的值在重叠时优先更具体者胜出。跨 asyncio 子上下文可见框架 API如Agent.run_sync内部可能调用asyncio.run创建新的 asyncio 上下文而新上下文继承的是父上下文ContextVar的快照在快照里ContextVar.set不会回传到外层。为此实现用一个_PendingSlot可变包装器持有 payload跨上下文共享的是同一个引用消费时直接改payload属性即可让外层与子上下文同时看到已消费状态避免同一份默认值被重复应用context.py。消费后的字典通过apply_pending_to_span以setattr方式写回 Span且只写 Span 实际声明的字段防止跨类型泄漏例如embedder不会落到LlmSpan上。三、两种评估形态pytest 断言式 与 脚本迭代式Traced eval 支持两种代码形态分别面向 CI/CD 与本地迭代。两者的共同点是直接把Golden传入被追踪的应用让应用在运行过程中产出 Trace / Span评估完全基于追踪结果完成。3.1 pytest 形态面向 CI/CD断言即门禁对于 CI/CD优先采用各集成文档中展示的 pytest 形态。先用pytest.mark.parametrize遍历数据集中的Golden把Golden直接传入被追踪的应用最后用assert_test断言pytest.mark.parametrize(golden, dataset.goldens) def test_agent(golden: Golden): run_ai_app_with_integration_tracing(golden.input) assert_test(goldengolden, metricsTRACE_METRICS)assert_test是 evaluate.py 中的核心入口。当传入golden而不传test_case时它走的是trace-scoped分支调用_assert_test_from_current_trace从current_trace_context读取当前活跃的 Traceevaluate.py。该函数会把 Trace 及其 Span 树转换为TraceApi并用Golden的字段与 Trace 上携带的output、expected_output、context、retrieval_context、tools_called、expected_tools组装出对应的LLMTestCase然后深度优先遍历 Span 树把每个 Span 上挂载的指标逐一执行trace_scope.py。assert_test底层逻辑还做了几件工程化的事指标未过阈值或执行出错时assert_test会抛出携带指标明细的AssertionError指标名、得分、阈值、strict 模式、reason直接阻断 CI标记为 flaky 的 test case 失败时只发 warning 不抛异常避免偶发失败阻塞流水线evaluate.py自动跳过 DeepEval 内部 pytest 包装 Span并把用户根 Span 提升为真正的根节点保证上报到后端的 Span 树干净trace_scope.py。3.2 脚本 / 迭代形态用 evals_iterator 流式评估对于脚本或本地迭代循环使用数据集的evals_iterator并同样把Golden传入被追踪的应用for golden in dataset.evals_iterator(metricsTRACE_METRICS): run_ai_app_with_integration_tracing(golden.input)evals_iterator定义在 dataset.py每次yield一个Golden并在此过程中接管 Trace 的采集、指标执行与结果聚合。它支持丰富的配置参数参数作用metrics应用于 Trace 的指标列表例如TRACE_METRICShyperparameters记录本次运行的超参数值可为str/int/float/Promptidentifier本次评估运行的标识符display_config展示配置DisplayConfig含 verbose、进度条等cache_config缓存配置CacheConfig是否写 / 读缓存error_config错误配置ErrorConfig如skip_on_missing_params、ignore_errorsasync_config异步配置AsyncConfigrun_asyncTrue时走异步执行器内部实现上同步与异步分别委托给execute_agentic_test_cases_from_loop/a_execute_agentic_test_cases_from_loop异步模式会维护trace_uuid - Golden的映射保证即使 Trace 数量与 Golden 数量不一致或执行顺序交错每个 Trace 也能关联到正确的 Goldentracing.py。仓库测试对这两种形态均有覆盖TestEvalsIterator验证了同步 / 异步evals_iterator、ErrorConfig(skip_on_missing_paramsTrue/False)与MissingTestCaseParamsError的行为test_configs.pytest_dataset_iterator.py覆盖了同步应用 异步迭代等四种组合test_dataset_iterator.py端到端示例 example_e2e_trace_evals.py 展示了拉取数据集 evals_iterator(metrics[...]) 传入golden.input的完整闭环。3.3 红线不要手工回退到 LLMTestCase文档明确强调除非用户明确选择不启用追踪否则不要把 traced single-turn eval 转换成手工构造的LLMTestCase。理由在于traced eval 的全部价值——精确到组件的指标定位、Span 树结构、上下游数据自动回填——都依赖 Trace 本身一旦手工构造 test case这些信息便全部丢失等于退回到无追踪时代的评估方式。四、Confident AI 结果上报与查看4.1 认证deepeval login 或 CONFIDENT_API_KEY如果用户选择将评估结果上报到 Confident AI需要先确认认证就绪两种方式任选其一已执行过deepeval login交互式登录令牌写入本地配置已导出环境变量CONFIDENT_API_KEY。文档建议在 CI 及其他非交互式运行中优先使用CONFIDENT_API_KEY环境变量避免交互式登录在无 TTY 环境失效。仓库中deepeval login与CONFIDENT_API_KEY的读写、查询与注销逻辑位于 auth/command.py其中也包含了未登录时提示导出CONFIDENT_API_KEY的引导路径。4.2 查看报告deepeval view评估结束后可使用deepeval view在浏览器中打开最近一次的托管报告。其实现逻辑是若已登录则优先打开本地记录的最新 test run 链接否则自动上传并打开对应链接main.py。4.3 底层Trace 是如何被送达 Confident AI 的从源码看Trace 的上报由TraceManager的后台工作线程 队列完成tracing.py每个 Trace / Span 先被转换为 API 模型TraceApi/BaseApiSpan其中每个 Span 的指标被序列化为MetricData携带name、threshold、success、score、reason、strict_mode、flaky、evaluation_model、error、evaluation_cost、input_token_count、output_token_count等字段api.pyTrace 进入队列后由 daemon 工作线程按最小间隔限速异步 POST 到 Confident AI 的 traces 端点进程短命退出时可通过flush_traces(timeout30.0)或异步版a_flush_traces阻塞等待所有排队 Trace 发送完毕避免丢失tracing.py未启用 flush 而进程退出时管理器会打印遗留 Trace警告并提示设置CONFIDENT_TRACE_FLUSH1评估模式下环境标签会被标记为TESTING且每个 Span 的指标会随create_metric_data一并写入 API Spantracing.py。这意味着 traced eval 的评估结果与追踪数据是同一条链路指标得分、耗时、Token 消耗、成本与 Span 树一起送达云端天然具备可回查、可对比的审计能力。五、一次完整 Traced Eval 的数据流小结把上述内容串起来一次 traced eval 的生命周期是注入next_*_span(metrics...)或observe(metrics...)把指标预置 / 绑定到即将创建的 Span 上执行应用集成追踪或手动埋点运行Observer.__enter__/__exit__构建 Span 树并把入参、出参、错误状态写回评估pytest 形态由assert_test(golden..., metricsTRACE_METRICS)触发脚本形态由evals_iterator(metricsTRACE_METRICS)触发——两者都基于活跃 Trace 提取测试数据、按 Span 挂载的指标逐项计算上报Trace / Span / MetricData 经create_trace_api序列化后进入后台队列送达 Confident AI查看deepeval view打开最近一次托管报告可逐 Span 检查指标得分、Token 与成本明细。这套范式让可观测性与评估合二为一代码里不需要为每个指标手工拼装 test case指标天然落在它们所评估的组件上评估结果与执行链路一一对应是 DeepEval 在 Agent / RAG 类应用上推荐的默认单轮评估方式。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考