Pydantic Evals 评测框架实战指南：从 Dataset 到 EvaluationReport 的全流程解析-北京尧图网络

Pydantic Evals 评测框架实战指南从 Dataset 到 EvaluationReport 的全流程解析【免费下载链接】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 是 Pydantic AI 生态本仓库pydantic_evals包中用于系统化测试与评估 AI 系统的评测框架覆盖从简单 LLM 调用到复杂多智能体应用的各种场景。本文基于仓库文档 docs/evals.md 的完整脉络展开并结合 pydantic_evals 源码与测试示例examples/pydantic_ai_examples/evals深入讲解读完你将掌握 Dataset/Case/Evaluator/Experiment 的数据模型、内置与自定义评估器的编写方式、evaluate_sync实验执行的全部关键参数以及评测结果在终端与 Logfire 中的呈现方式。一、设计哲学Code-First 的评测方式Pydantic Evals 遵循Code-First代码优先哲学所有评测组件——数据集、实验、任务、用例Case和评估器Evaluator——都用 Python 代码定义或以 Python 代码加载的序列化数据形式存在。这与依赖 Web 控制台配置评测的平台不同你在代码中编写并运行评测结果可以写盘、在终端直接查看或发送到 Pydantic Logfire 的 Web 界面中可视化。文档同时强调一个现实判断评测是一门新兴的实践emerging practice。与单元测试不同没有人能确切告诉你评测该如何定义官方因此把 Pydantic Evals 设计得“灵活有用但不过度持立场flexible and useful without being too opinionated”。在仓库中pydantic_evals是一个独立的顶层包见 pyproject.toml它不依赖pydantic-ai仅在你需要把评测接入 OpenTelemetry / Logfire 时才需要可选依赖logfire。这一点让它可以单独用于任意“随机函数”stochastic function的评估——包 docstringpydantic_evals/pydantic_evals/__init__.py明确将其定位 toolkit 描述为“评估任意随机函数执行的工具箱”。二、安装pip install pydantic-evals # 或使用 uv uv add pydantic-evals如需在评测中使用 OpenTelemetry 追踪如 span 行为断言或将结果发送到 Logfire则安装 logfire 扩展pip install pydantic-evals[logfire] # 或使用 uv uv add pydantic-evals[logfire]注意pydantic-evals本体不依赖pydantic-ai[logfire]为可选依赖仅在使用追踪类评估器或 Logfire 集成时才必需。三、数据模型Dataset、Case、Experiment 与 EvaluatorPydantic Evals 围绕一个简洁的数据模型构建Dataset (1) ──────────── (Many) Case │ │ │ │ └─── (Many) Experiment ──┴─── (Many) Case results │ └─── (1) Task │ └─── (Many) Evaluator关键关系Dataset → Cases一个 Dataset 包含多个 CaseDataset → Experiments同一个 Dataset 可以随时间被用于多个实验对比不同实现、追踪版本变化Experiment → Case results一次实验执行每个 Case 后生成结果Experiment → Task一次实验评估一个定义好的任务函数Experiment → Evaluators一次实验使用多个 EvaluatorDataset 级评估器对全部 Case 生效Case 级评估器只对所属 Case 生效。数据流执行时发生的事创建 Dataset在 YAML/JSON 或直接以 Python 代码定义 cases 与 evaluators执行实验调用dataset.evaluate_sync(task_function)Case 运行每个 Case 在 Task 上执行评估评估器对每个 Case 的 Task 输出打分结果汇总所有 Case 结果被收集为一份汇总报告EvaluationReport。单元测试类比一个有用的虽非完美隐喻是把评测理解为单元测试框架单元测试Pydantic Evals测试函数CaseEvaluator各自定义一个待测场景包含输入与期望结果测试套件Dataset把相关用例组织在一起定义共享的评估标准运行测试pytestExperimentdataset.evaluate_sync(my_ai_function)测试报告EvaluationReportassert返回bool的 Evaluator与传统单元测试的关键区别在于AI 系统是概率性的。类型检查仍能得到简单的 pass/fail但文本输出的评分往往是定性、分档甚至需要人工/模型裁决的。上述概念在 docs/evals/core-concepts.md 中有更详细的展开包括实验内部五阶段流程Setup → Execution → Case Evaluation → Report Evaluation → Reporting。四、Dataset 与 Case一切从测试数据开始在 Pydantic Evals 中一切始于Dataset与CaseDataset为评估特定任务/函数而设计的一组测试 Case 集合Case单个测试场景对应 Task 的输入可带可选的期望输出、元数据与 Case 专属评估器。from pydantic_evals import Case, Dataset case1 Case( namesimple_case, inputsWhat is the capital of France?, expected_outputParis, metadata{difficulty: easy}, ) dataset Dataset(namecapital_quiz, cases[case1])该示例完整可运行。Case 字段详解结合 pydantic_evals/pydantic_evals/dataset.py 中Case的 dataclass 定义各字段语义如下字段类型说明namestr \| NoneCase 名用于在报告中标识与过滤不填时报告里会显示为Case Ninputs泛型InputsT传给 task 的输入可以是任意类型字符串、dict、Pydantic 模型等metadata泛型MetadataT \| None供评估器通过EvaluatorContext访问的任意元数据expected_output泛型OutputT \| None期望输出供EqualsExpected等评估器比较evaluatorslist[Evaluator]仅对该 Case 生效的评估器在 Dataset 级评估器之外追加执行几个值得注意的实现细节来自源码重复名校验Dataset.__init__会检查 Case 名字出现重复时抛出ValueError: Duplicate case name: ...见 dataset.py#L254-L260expected_output与None的陷阱None表示“未提供”。若某 Case 的期望输出本身是NoneEqualsExpected会跳过该 Case相当于不产生断言要断言 task 返回None应使用显式取值比较的Equals(valueNone)类型安全Dataset泛型化于InputsT、OutputT、MetadataT三个类型参数可保存/加载为 YAML 或 JSON。Dataset 级 vs Case 级评估器评估器可定义在两个层级from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import EqualsExpected, IsInstance dataset Dataset( namecase_level_evaluators, cases[ Case( namespecial_case, inputstest, expected_outputTEST, evaluators[ EqualsExpected(), # 只在这个 Case 上运行 ], ), ], evaluators[ IsInstance(type_namestr), # 对所有 Case 运行 ], )从源码看Dataset.add_evaluator(evaluator, specific_caseNone)提供了动态追加能力specific_case为None时追加到 Dataset 级列表传入 Case 名时只追加到该 Case 的evaluators上找不到对应 Case 会抛ValueError见 dataset.py#L507-L533。数据集的保存与加载、生成等完整指南见 docs/evals/how-to/dataset-management.mdDataset.from_file(path, fmt...)支持从 YAML/JSON 文件加载并可通过custom_evaluator_types参数反序列化自定义评估器见 dataset.py#L556-L595。五、Evaluators如何给结果打分Evaluator 负责分析与打分 Task 在某个 Case 上的表现。评估器有两类确定性代码检查如用正则验证模型输出格式、检测 PII/敏感数据非确定性输出评估评估准确性、precision/recall、幻觉、指令遵循等质量维度。两类都有价值但传统代码检查比需要人工或模型审查的检查更便宜、更容易——这是官方文档明确的成本判断。评估器返回类型评估器evaluate方法的返回类型决定其在报告中的呈现形式来自 docs/evals/core-concepts.md返回类型用途示例bool断言Assertion——pass/fail 检查True→ ✔False→ ✗int/float分数Score——数值质量指标0.95、87str标签Label——类别结果correct、hallucination此外评估器还可以返回带说明文字的EvaluationReason如EvaluationReason(valueTrue, reasonExact match)或在print(include_reasonsTrue)时展示理由也可以返回“名字 → 值”的字典一次产出多项结果。EvaluatorContext评估器看到什么每个评估器都收到一个EvaluatorContext包含nameCase 名可选inputs任务输入metadataCase 元数据可选expected_output期望输出可选outputtask 的实际输出duration任务执行耗时秒span_treeOpenTelemetry spans配置 logfire 时可用attributes/metrics自定义属性与指标字典完整示例内置评估器自定义评估器from dataclasses import dataclass from pydantic_evals.evaluators import Evaluator, EvaluatorContext from pydantic_evals.evaluators.common import IsInstance from simple_eval_dataset import dataset dataset.add_evaluator(IsInstance(type_namestr)) # (1)! dataclass class MyEvaluator(Evaluator): async def evaluate(self, ctx: EvaluatorContext[str, str]) - float: # (2)! if ctx.output ctx.expected_output: return 1.0 elif ( isinstance(ctx.output, str) and ctx.expected_output.lower() in ctx.output.lower() ): return 0.8 else: return 0.0 dataset.add_evaluator(MyEvaluator())通过Dataset.add_evaluator添加内置评估器该自定义评估器根据输出与期望输出的匹配程度返回一个分数。示例完整可运行。内置评估器还支持更简洁的同步evaluate实现——Evaluator基类会把同步方法包装进异步执行路径因此上面示例既可以写async def evaluate也可以直接写def evaluate见 docs/evals.md 第六节的MyEvaluator写法。内置评估器速查当前版本从 pydantic_evals.evaluators 导出的常用评估器评估器用途返回类型成本速度EqualsExpected与expected_output精确相等bool免费即时Equals等于指定值可断言valueNonebool免费即时Contains包含值/子串支持字符串、列表成员、dict 键值对bool reason免费即时IsInstance类型校验按type_name匹配 MRObool reason免费即时MaxDuration执行时长阈值SLA 检查bool免费即时LLMJudgeLLM 按 rubric 评主观质量bool和/或float高慢GEvalG-Eval 思维链打分整数score_rangeint reason高慢HasMatchingSpan基于 OTel span 的行为检查需 logfirebool免费快报告级评估器作用于整次实验的结果集经Dataset(report_evaluators...)传入ConfusionMatrixEvaluator混淆矩阵、PrecisionRecallEvaluatorPR 曲线 AUC、ROCAUCEvaluator、KolmogorovSmirnovEvaluator。完整的参数与行为说明见 docs/evals/evaluators/built-in.md各类型的选型指南见 docs/evals/evaluators/overview.md基于 OTel 轨迹的智能体行为评估工具调用、执行流见 docs/evals/evaluators/span-based.md。最佳实践源自官方文档把快速确定性检查放在前面昂贵的 LLM 评估放在后面先捕获格式/结构问题再评估质量。另注意一个安全相关的实现细节源码中pydantic_evals.evaluators模块显式移除了Python评估器出于安全原因访问它会抛出带说明的ImportError见 evaluators/__init__.py#L71-L76。六、运行实验完整示例与输出执行评估的过程就是“用数据集里的全部 Case 运行一个任务”也就是运行一次实验experiment。把前文的 Dataset 与 Evaluator 示例合并使用Dataset更声明式的evaluators参数from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import Evaluator, EvaluatorContext, IsInstance case1 Case( # (1)! namesimple_case, inputsWhat is the capital of France?, expected_outputParis, metadata{difficulty: easy}, ) class MyEvaluator(Evaluator[str, str]): def evaluate(self, ctx: EvaluatorContext[str, str]) - float: if ctx.output ctx.expected_output: return 1.0 elif ( isinstance(ctx.output, str) and ctx.expected_output.lower() in ctx.output.lower() ): return 0.8 else: return 0.0 dataset Dataset( namecapital_quiz, cases[case1], evaluators[IsInstance(type_namestr), MyEvaluator()], # (2)! ) async def guess_city(question: str) - str: # (3)! return Paris report dataset.evaluate_sync(guess_city) # (4)! report.print(include_inputTrue, include_outputTrue, include_durationsFalse) # (5)! Evaluation Summary: guess_city ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓ ┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩ │ simple_case │ What is the capital of France? │ Paris │ MyEvaluator: 1.00 │ ✔ │ ├─────────────┼────────────────────────────────┼─────────┼───────────────────┼────────────┤ │ Averages │ │ │ MyEvaluator: 1.00 │ 100.0% ✔ │ └─────────────┴────────────────────────────────┴─────────┴───────────────────┴────────────┘ 创建测试 Case创建包含 Case 与评估器的Dataset待评估的任务函数这里用一个返回固定字符串的协程模拟 LLM 调用用evaluate_sync运行评估该函数会把 task 跑过数据集里的全部 Case返回一个EvaluationReport对象用report.print(...)打印报告。示例中关掉 duration 只是为了让输出在多次运行间保持稳定。示例完整可运行。实验执行参数源码级Dataset.evaluate异步与Dataset.evaluate_sync同步包装共享同一套参数见 dataset.py#L281-L324参数说明task待评估的可调用对象接收 Case 的inputs并返回输出支持同步或异步函数name实验名缺省时依次回退到task_name、task 函数名max_concurrency并发 Case 数上限None表示全部并发。实现上通过anyio.Semaphore限流progress是否显示进度条默认True基于 rich 的Progressretry_task/retry_evaluatorstask 执行与评估器执行的RetryConfig重试配置task_name覆盖报告中显示的任务名metadata实验级元数据字典会写入报告与 span 属性repeat每个 Case 重复运行次数1 时结果按原 Case 名分组聚合报告名形如case [1/3]默认 1小于 1 抛ValueErrorlifecycleCaseLifecycle类或工厂用于每 Case 的 setup/teardown 钩子从源码结构看evaluate的整体流程是在一个logfire_span(evaluate {name})中携带gen_ai.operation.nameexperiment等属性用任务组并发执行所有 Case每个 Case 内部由_run_task_and_evaluators依次完成任务执行、计时、Dataset 级 Case 级评估成功的结果进入ReportCase失败的进入ReportCaseFailure。全部 Case 完成后若配置了report_evaluators会在整份EvaluationReport上运行它们产出实验级分析混淆矩阵、PR 曲线、标量指标、表格等。并发控制、批量执行性能调优见 docs/evals/how-to/concurrency.md重试策略见 docs/evals/how-to/retry-strategies.md。一个 Dataset多次实验对比不同实现同一 Dataset 可反复用于不同 task 实现这是评测追踪回归与 A/B 对比的基础示例引自 core-conceptsfrom pydantic_evals import Case, Dataset from pydantic_evals.evaluators import EqualsExpected dataset Dataset( namecomparison_test, cases[Case(inputshello, expected_outputHELLO)], evaluators[EqualsExpected()], ) def task_v1(text: str) - str: return text.upper() def task_v2(text: str) - str: return text.upper() ! report_v1 dataset.evaluate_sync(task_v1) report_v2 dataset.evaluate_sync(task_v2) avg_v1 report_v1.averages() avg_v2 report_v2.averages() print(fV1 pass rate: {avg_v1.assertions if avg_v1 and avg_v1.assertions else 0}) # V1 pass rate: 1.0 print(fV2 pass rate: {avg_v2.assertions if avg_v2 and avg_v2.assertions else 0}) # V2 pass rate: 0典型用途跨版本对比实现、追踪性能随时间变化、A/B 测试不同方案、部署前验证改动。七、EvaluationReport报告结构与程序化访问EvaluationReport是实验的最终产物包含运行 task 与全部评估器的所有数据。其结构来自 core-concepts字段与 reporting 模块对应name实验名cases成功执行的 Case 结果列表failures执行失败的列表analyses报告评估器产出的实验级分析混淆矩阵、PR 曲线、标量、表格experiment_metadata实验元数据trace_id/span_idOpenTelemetry 追踪标识配置 logfire 时可用由evaluate从当前 span context 提取见 dataset.py#L377-L414每个成功 Case 结果ReportCase包含Case 数据name、inputs、metadata、expected_output、output、评估结果scores、labels、assertions、性能数据task_duration、total_duration、自定义metrics/attributes、追踪信息trace_id、span_id以及evaluator_failures错误列表。程序化访问示例for case in report.cases: print(f{case.name}: {case.scores}) # Case 1: {}report.print()的常用开关包括include_input、include_output、include_durations、include_reasons等report.averages()返回聚合统计含断言通过率可跨报告对比。八、Logfire 集成可视化与协作分析使用 Pydantic Logfire 时实验结果会自动出现在 Logfire Web 界面中用于可视化、对比与协作分析。定位上Logfire 是可观测层你在代码中编写并运行评测在 Web UI 中查看与分析结果。结合仓库中 docs/evals/how-to/logfire-integration.md 的说明接入方式是安装pydantic-evals[logfire]扩展并初始化 Logfire此时每次实验产生一个evaluate namespan携带dataset_name、n_cases、gen_ai.operation.nameexperiment等属性EvaluatorContext.span_tree可用从而支撑HasMatchingSpan与基于轨迹的评估器如ToolCorrectness、TrajectoryMatch、MaxToolCalls、MaxModelRequests——这些“agentic”评估器从 evaluators/agentic.py 导出报告对象带trace_id/span_id可将终端报告与 Web 端 trace 关联。九、进阶主题与延伸阅读围绕 docs/evals.md 的“Quick Navigation”仓库提供了成体系的子文档可作为主线之后的深入阅读路径入门Quick Startuppercase_text完整示例与report.print()输出、Core Concepts评估器专题Overview类型选型与 Case 级评估器、Built-in、LLM as a Judge、Custom、Span-Based、Report EvaluatorsHow-ToDataset Management、Dataset Serialization、Concurrency Performance、Retry Strategies、Metrics Attributesincrement_eval_metric/set_eval_attribute二者在 pydantic_evals/__init__.py 中公开导出、Case Lifecycle Hooks示例Simple Validation仓库内还有一组可运行的端到端示例包括数据集生成、自定义评估器、与单元测试结合、模型对比examples/pydantic_ai_examples/evals/agent.py、custom_evaluators.py、models.pyAPI 参考docs/api/pydantic_evals/dataset.mdDataset 全部类、方法与配置项。仓库测试目录 tests/evals 提供了上述功能的测试验证如 test_dataset.py、test_evaluators.py、test_llm_as_a_judge.py、test_online.py 等可作为行为契约的参照。十、小结Pydantic Evals 的核心可以概括为三句话用代码定义“要测什么”Dataset Case Evaluator用evaluate_sync/evaluate回答“现在怎么样”Experiment → EvaluationReport用终端报告或 Logfire 消费结果。它的价值在于类型安全的数据模型、Dataset 级与 Case 级两层评估器、免费且即时的确定性检查与昂贵的 LLM 评估可自由组合、内置并发/重试/重复执行控制以及与 OpenTelemetry/Logfire 的追踪打通——使评测既能像单元测试一样纳入工程流程又能覆盖概率性输出所需的打分与标签维度。【免费下载链接】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），仅供参考

Pydantic Evals 评测框架实战指南：从 Dataset 到 EvaluationReport 的全流程解析

相关推荐

风控的KPI：误伤一个真人值多少钱

AI驱动的人机交互革命：从编程到自然语言操作

SAP催收优先级管理与CDS视图技术解析

更多资讯

Kilo AI Gateway 快速入门：用 Vercel AI SDK、OpenAI SDK、Python 与 cURL 发起你的第一次模型请求

Golang毫秒级定时任务调度器设计与实现

lo.Samples 深度解析：Go 泛型库 lo 中基于 Fisher-Yates 的随机不重复抽样

WinApps 轻量级部署指南：4GB 内存的旧电脑如何跑起 Windows 应用

若依集成MyBatis-Plus实战：架构冲突、避坑指南与性能提效

像老乡鸡那样做香辣鸡杂：炖菜标准化配方、鸡杂料与分步炖煮流程全解析

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？