Pydantic Evals 与 Logfire 集成：基于 OpenTelemetry 的可视化评测分析与追踪调试指南

Pydantic Evals 与 Logfire 集成基于 OpenTelemetry 的可视化评测分析与追踪调试指南【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-aiPydantic Evals 使用 OpenTelemetry 记录评测过程的完整追踪trace将评测报告的全部信息与任务函数执行期间的完整调用链span一并导出而 Pydantic Logfire 则提供了开箱即用的可视化分析界面。本文以 docs/evals/how-to/logfire-integration.md 为主体结合仓库源码pydantic_evals/pydantic_evals/与pydantic_evals/pyproject.toml系统讲解从安装配置、数据采集范围、Web UI 查看、失败用例调试到基于 span 的评测器span-based evaluator与最佳实践的完整工作流。读完本文你将掌握如何把评测运行接入任意 OTel 兼容后端并能在 Logfire 中高效定位评测失败根因、对比多次运行结果。概览Pydantic Evals 的可观测性架构Pydantic Evals 的评测过程天然基于 OpenTelemetry 埋点评测运行期间会产生trace其中包含评测报告的全部信息以及任务函数执行过程中的完整追踪这些 trace 可以发送到任何 OpenTelemetry 兼容的后端Pydantic Logfire 是官方推荐的托管可视化方案。从源码看这一机制贯穿评测的每一层整个数据集评测被包裹在一个名为evaluate {name}的 span 中并携带数据集名dataset_name、用例数n_cases、任务名task_name等属性参见 pydantic_evals/pydantic_evals/dataset.py每次任务执行再单独包裹execute {task}span同时通过context_subtree()在内存中收集本次执行产生的全部 span构建成可查询的 span 树参见 pydantic_evals/pydantic_evals/dataset.py每个评测器evaluator的执行也会产生名为evaluator: {evaluator_name}的 span便于在 Logfire 中按 span 名过滤参见 pydantic_evals/pydantic_evals/evaluators/_run_evaluator.py。这些 span 统一通过_utils.py中的logfire_span上下文管理器创建。它基于logfire_apiotel scope 为pydantic-evals实现并在未配置 Logfire 时自动抑制LogfireNotConfiguredWarning警告——这意味着即使没有配置 Logfire评测也能正常运行只是 trace 不会对外发送参见 pydantic_evals/pydantic_evals/_utils.py 与 pydantic_evals/pydantic_evals/_utils.py。安装Logfire 集成是 Pydantic Evals 的可选依赖需要单独安装pip install pydantic-evals[logfire]从 pydantic_evals/pyproject.toml 可以看到该可选依赖组定义为logfire [logfire3.14.1]。如果使用 uv可等价地执行uv add pydantic-evals[logfire]。基础配置在运行评测之前配置 Logfire 即可接入import logfire from pydantic_evals import Case, Dataset # Configure Logfire logfire.configure( send_to_logfireif-token-present, # (1)! ) # Your evaluation code def my_task(inputs: str) - str: return fresult for {inputs} dataset Dataset(namelogfire_demo, cases[Case(nametest, inputsexample)]) report dataset.evaluate_sync(my_task)send_to_logfireif-token-present表示仅当环境变量LOGFIRE_TOKEN存在时才发送数据——本地开发无 Token 时不会报错或阻塞适合 CI 与本地复用同一份代码。配置完成后只要设置了LOGFIRE_TOKEN环境变量评测 trace 就会出现在 Logfire Web UI 中无需任何额外代码。提示如果希望无条件发送例如明确调试网络问题可将配置改为logfire.configure(send_to_logfirealways)。发送到 Logfire 的数据内容运行一次评测后Logfire 会收到四类数据评测元数据Evaluation metadata数据集名称dataset name用例数量number of cases评测器名称evaluator names逐用例数据Per-case data输入与输出inputs and outputs期望输出expected outputs元数据metadata执行耗时execution duration评测结果Evaluation results分数、断言与标签scores, assertions, and labels理由说明reasons若包含评测器失败信息evaluator failures任务执行追踪Task execution traces任务函数产生的所有 OpenTelemetry spans工具调用针对 Pydantic AI agentAPI 调用、数据库查询等外部操作底层实现细节评测结果如何落到 span 属性上从源码可以确认评测结果是以标准 OTel 语义约定的日志事件形式导出的。在 pydantic_evals/pydantic_evals/_otel_emit.py 中每个EvaluationResult会发射一条名为gen_ai.evaluation.result的日志事件携带以下属性属性含义gen_ai.evaluation.name评测项名称gen_ai.evaluation.score.value数值分数bool 会映射为 0.0/1.0并同时写入 labelgen_ai.evaluation.score.label分数标签bool 映射为pass/fail字符串分数直接作为标签gen_ai.evaluation.explanation评测理由或失败信息gen_ai.evaluation.target被评测的函数/agent 名称gen_ai.evaluation.evaluator.source评测器 spec 的 JSON 序列化gen_ai.evaluation.evaluator.version评测器版本若存在error.type评测器失败时的异常类型其中布尔分数的双表示score.value与score.label同时写入是为了让数值查询和分类查询都能生效参见 pydantic_evals/pydantic_evals/_otel_emit.py。此外在线评测online evaluation还会把 OTel baggage 中的键值快照到事件属性中方便跨调用传递上下文。同时pydantic_evals/pydantic_evals/_task_run.py 中的extract_span_tree_metrics会从 span 树中自动汇总标准指标requests调用次数、cost成本读取operation.cost属性以及以gen_ai.usage.为前缀的 token 用量指标并写入评测报告。在 Logfire 中查看结果评测总览Evaluation OverviewLogfire 为评测结果提供了专门的表格视图挂载在根评测 span 上该视图展示用例名称case names通过/失败状态pass/fail status分数与断言scores and assertions执行耗时execution duration快速过滤与排序quick filtering and sorting单个用例详情Individual Case Details点击任意用例即可查看该用例的详细输入与输出便于核对具体行为是否符合预期。完整追踪视图Full Trace View查看评测期间产生的全部 span构成的完整执行追踪该视图特别适用于调试失败的用例debugging failed cases定位性能瓶颈understanding performance bottlenecks分析工具调用模式analyzing tool usage patterns编写基于 span 的评测器writing span-based evaluators分析追踪Analyzing Traces对比多次运行Comparing Runs对同一数据集反复运行不同实现再在 Logfire 中按时间戳或属性过滤对比from pydantic_evals import Case, Dataset def original_task(inputs: str) - str: return foriginal result for {inputs} def improved_task(inputs: str) - str: return fimproved result for {inputs} dataset Dataset(namecomparison, cases[Case(nametest, inputsexample)]) # Run 1: Original implementation report1 dataset.evaluate_sync(original_task) # Run 2: Improved implementation report2 dataset.evaluate_sync(improved_task) # Compare in Logfire by filtering by timestamp or attributes调试失败的用例Debugging Failed Cases快速定位失败用例的推荐步骤在 Logfire 中搜索service_name my_service_evals AND is_exception将my_service_evals替换为你实际使用的 service name查看完整 span 树定位失败发生的具体位置检查 span 属性与日志读取错误信息。基于 Span 的评测Span-Based EvaluationLogfire 集成的最大价值在于解锁了基于 span 的评测器。详细指南见 Span-Based Evaluation。这种评测范式评估的是系统如何执行而非仅仅产生了什么输出例如验证特定工具是否被调用import logfire from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import HasMatchingSpan logfire.configure(send_to_logfireif-token-present) def my_agent(inputs: str) - str: return fresult for {inputs} dataset Dataset( namelogfire_demo, cases[Case(nametest, inputsexample)], evaluators[ HasMatchingSpan( query{name_contains: search_tool}, evaluation_nameused_search, ), ], ) report dataset.evaluate_sync(my_agent)span 树span tree在两个位置同时可用评测器代码中通过ctx.span_tree访问Logfire UI 中以可视化追踪视图呈现。Span 树的底层实现从源码看span 树由 pydantic_evals/pydantic_evals/otel/span_tree.py 中的SpanTree/SpanNode构建SpanTree从内存中的 span 导出器收集已完成 span按start_timestamp排序后重建父子关系根节点是父 span 不在当前集合中的节点参见 pydantic_evals/pydantic_evals/otel/span_tree.pySpanNode提供find、any、count等查询方法以及find_children/find_descendants/find_ancestors系列遍历 API并支持SpanQuery字典式条件查询含not_/and_/or_逻辑组合、stop_recursing_when剪枝等参见 pydantic_evals/pydantic_evals/otel/span_tree.py若未安装logfire或opentelemetry-sdkcontext_subtree会回退为抛出一个SpanTreeRecordingError提示需要安装并配置相应依赖参见 pydantic_evals/pydantic_evals/otel/_context_subtree.py。这解释了为什么 span-based 评测要求先执行pip install pydantic-evals[logfire]并调用logfire.configure()。故障排查Troubleshooting问题一Logfire 中没有数据出现按顺序检查Token 是否设置执行echo $LOGFIRE_TOKEN确认环境变量存在配置是否正确可强制发送以排除if-token-present逻辑import logfire logfire.configure(send_to_logfirealways) # Force sending网络连通性检查防火墙设置是否阻止了对外发送项目是否存在在 Logfire UI 中核对项目名称是否正确。问题二追踪缺少部分 span如果某些 span 缺失确保在导入其他模块之前先配置 Logfireimport logfire logfire.configure() # Must be first原因是 OpenTelemetry 的全局 provider 需要在首次埋点前就绪后配置会导致早期 span 丢失检查插桩instrumentation是否齐全按需启用你希望追踪的所有插桩import logfire logfire.instrument_pydantic_ai() logfire.instrument_httpx(capture_allTrue)instrument_pydantic_ai()用于捕获 Pydantic AI agent 的内部 span工具调用、LLM 调用等instrument_httpx(capture_allTrue)用于捕获所有 HTTP 请求含请求/响应体这正是评测报告里API 调用、数据库查询等 trace 的来源。最佳实践Best Practices1. 尽早配置Configure Early始终在运行评测之前配置 Logfire且配置语句应位于评测相关导入与执行代码之前import logfire from pydantic_evals import Case, Dataset logfire.configure(send_to_logfireif-token-present) # Now import and run evaluations def task(inputs: str) - str: return fresult for {inputs} dataset Dataset(namelogfire_demo, cases[Case(nametest, inputsexample)]) dataset.evaluate_sync(task)2. 使用描述性的服务名与环境名Descriptive Service Names And Environments通过service_name与environment区分不同评测项目与运行环境避免多项目数据混淆import logfire logfire.configure( service_namerag-pipeline-evals, environmentdevelopment, )3. 定期复盘Review Periodically定期查看 Logfire识别失败模式关注持续失败的用例consistently failing cases分析性能趋势performance trends根据洞察调整评测器adjust evaluators based on insights。总结与下一步Logfire 集成让 Pydantic Evals 的评测结果不再只是本地终端里的报告文本而是一套完整、可检索、可对比、可深挖的可观测数据评测元数据、逐用例数据、评测结果与任务执行 trace 全部以标准 OpenTelemetry 格式输出既能发送到 Logfire Web UI 做可视化分析也能在评测器代码内通过ctx.span_tree进行程序化断言。进一步探索的方向Span-Based Evaluation深入使用 OpenTelemetry span 编写行为契约型评测器HasMatchingSpan、SpanQuery、自定义SpanTree遍历等Metrics Attributes通过record_metric/record_attribute见 pydantic_evals/pydantic_evals/_task_run.py或CaseLifecycle.prepare_context见 pydantic_evals/pydantic_evals/lifecycle.py向评测报告与 trace 中添加自定义数据参考 Logfire 官方关于评测 Web UI 的完整使用指南进一步定制仪表盘与告警。仓库相关参考安装依赖定义见 pydantic_evals/pyproject.toml评测运行入口与 span 包裹逻辑见 pydantic_evals/pydantic_evals/dataset.py评测结果事件发射见 pydantic_evals/pydantic_evals/_otel_emit.py。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考