Pydantic Evals 快速入门：用 pydantic-ai 生态系统性评估 AI 系统与 Agent

Pydantic Evals 快速入门：用 pydantic-ai 生态系统性评估 AI 系统与 Agent

【免费下载链接】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

Pydantic Evals 是 pydantic-ai 仓库内置的评估框架，用于系统化测试和评估 AI 系统——从简单的 LLM 调用到复杂的多 Agent 应用。本文将以 docs/evals/quick-start.md 为主线，结合pydantic_evals包的源码实现，带你完成安装、跑通第一个评估用例，并深入理解Dataset、Case、Evaluator、EvaluationReport四大核心概念与确定性校验、LLM 裁判、性能测试三大实战场景。读完本文，你将能够为自己的 AI 任务编写类型安全的测试数据集、运行带自动并发的评估实验，并生成包含指标、断言与性能数据的可读报告。

什么是 Pydantic Evals？

从源码包的模块注释（pydantic_evals/pydantic_evals/init.py）可以看出，它是一个"用于评估任意『随机函数』（如 LLM 调用）执行的工具包"，具体能力包括：

• 创建测试数据集：以类型安全的结构化输入与期望输出组织测试用例；
• 运行评估：对 AI 系统批量执行评估，默认自动并发调度；
• 打分：支持确定性检查、LLM 裁判（LLM-as-a-Judge）以及自定义评估器（Evaluator）；
• 生成报告：输出详细的指标、断言与性能数据（基于 rich 渲染表格）；
• 追踪变化：用同一数据集多次运行实验，对比不同实现或追踪随时间的变化；
• 集成 Logfire：通过 OpenTelemetry 实现可视化与协作分析（需安装logfire可选依赖）。

安装

Pydantic Evals 以独立的pydantic-evals发行版发布，基础安装只需要：

pip install pydantic-evals

如果需要 OpenTelemetry 追踪与 Logfire 集成，则安装带可选依赖的版本：

pip install 'pydantic-evals[logfire]'

从 pydantic_evals/pyproject.toml 可以看到该包的最低环境要求与核心依赖：Python>=3.10，运行时依赖pydantic>=2.12、pydantic-ai-slim（与当前仓库同版本）、anyio>=4.7.0、pyyaml>=6.0.2、rich>=13.9.4、logfire-api>=3.14.1。也就是说，pydantic-evals本身依赖 pydantic-ai-slim，用于提供 LLM 模型抽象与评估所需的工具函数。

快速开始：评估一个简单的函数

虽然评估通常用于测试 AI 系统，但 Pydantic Evals 的框架对任何函数调用都适用。为了展示核心功能，官方文档先用一个确定性的简单例子开始——评估一个文本转大写函数：

from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import Contains, EqualsExpected # 创建一个带测试用例的数据集 dataset = Dataset( name='uppercase_tests', cases=[ Case( name='uppercase_basic', inputs='hello world', expected_output='HELLO WORLD', ), Case( name='uppercase_with_numbers', inputs='hello 123', expected_output='HELLO 123', ), ], evaluators=[ EqualsExpected(), # 检查输出是否与 expected_output 完全一致 Contains(value='HELLO', case_sensitive=True), # 检查输出是否包含 "HELLO" ], ) # 定义被评估的函数 def uppercase_text(text: str) -> str: return text.upper() # 运行评估 report = dataset.evaluate_sync(uppercase_text) # 打印结果 report.print() """ Evaluation Summary: uppercase_text ┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓ ┃ Case ID ┃ Assertions ┃ Duration ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩ │ uppercase_basic │ ✔✔ │ 10ms │ ├────────────────────────┼────────────┼──────────┤ │ uppercase_with_numbers │ ✔✔ │ 10ms │ ├────────────────────────┼────────────┼──────────┤ │ Averages │ 100.0% ✔ │ 10ms │ └────────────────────────┴────────────┴──────────┘ """

运行后的终端输出为：

Evaluation Summary: uppercase_text ┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓ ┃ Case ID ┃ Assertions ┃ Duration ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩ │ uppercase_basic │ ✔✔ │ 10ms │ ├─────────────────────────┼────────────┼──────────┤ │ uppercase_with_numbers │ ✔✔ │ 10ms │ ├─────────────────────────┼────────────┼──────────┤ │ Averages │ 100.0% ✔ │ 10ms │ └─────────────────────────┴────────────┴──────────┘

这个例子直观展示了完整的评估闭环：定义数据集 → 定义任务函数 → 执行实验 → 得到报告。两个用例的Assertions列各显示两个 ✔（来自EqualsExpected与Contains两个评估器），底部Averages行给出 100.0% 的断言通过率与平均耗时。

核心概念

理解以下四个核心概念，就能用好 Pydantic Evals：

• Dataset：测试用例与（可选的）评估器的集合；
• Case：单个测试场景，包含输入与可选的期望输出、用例级评估器；
• Evaluator：对任务输出进行打分或校验的函数；
• EvaluationReport：一次评估运行产生的结果。

从源码角度看，这四者分别对应 dataset.py 中的Case（L110-L174）与Dataset（L177-L913）、evaluators 包下的Evaluator基类，以及 reporting/init.py 中的EvaluationReport。

更完整的类比与数据模型说明，请阅读 Core Concepts——它把 Pydantic Evals 与单元测试做了对照：Case+Evaluator相当于测试函数，Dataset相当于测试套件，dataset.evaluate(task)相当于运行pytest，EvaluationReport相当于测试报告。由于 AI 系统是概率性的，评估结果除了简单的通过/失败断言外，还可以是 0.0~1.0 的量化分数、定性标签（如 "good"、"acceptable"、"poor"）或带解释原因的断言。

常见使用场景

确定性校验：结构正确性验证

测试 AI 系统是否产生结构正确的输出，使用IsInstance校验类型、Contains校验关键内容：

from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import Contains, IsInstance dataset = Dataset( name='dict_validation', cases=[ Case(inputs={'data': 'required_key present'}, expected_output={'result': 'success'}), ], evaluators=[ IsInstance(type_name='dict'), Contains(value='required_key'), ], )

IsInstance通过检查类型的__name__/__qualname__并沿 MRO（方法解析顺序）逐级比对来判断输出类型（实现见 evaluators/common.py），支持内建类型、自定义类与 Pydantic 模型。Contains则针对不同数据类型有不同行为（见 common.py）：字符串做子串包含检查（可通过case_sensitive=False忽略大小写），列表/元组做成员检查，字典做键值对检查，对 Pydantic 模型类则会先转成字典再检查。

LLM 裁判评估：主观质量判定

用 LLM 评估准确率、有用性等主观质量：

from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import LLMJudge dataset = Dataset( name='llm_judge_test', cases=[ Case(inputs='What is the capital of France?', expected_output='Paris'), ], evaluators=[ LLMJudge( rubric='Response is accurate and helpful', include_input=True, model='anthropic:claude-sonnet-4-6', ) ], )

LLMJudge是内置的 LLM 裁判评估器，其关键参数（实现见 common.py）：

• rubric（必填）：评估标准描述；
• model：使用的评判模型，支持模型实例或'provider:model'形式的模型名；若未指定则使用默认评判模型（源码中默认值为'openai:gpt-5.2'，可通过set_default_judge_model覆盖）；
• include_input/include_expected_output：是否将任务输入、期望输出拼入裁判提示词；
• model_settings：自定义模型设置；
• score/assertion：配置输出模式——默认返回带原因的布尔断言；可改为仅输出 0.0~1.0 分数，或同时输出分数与断言，还可通过evaluation_name自定义结果名称。

性能测试：满足性能要求

确保系统满足性能要求，使用MaxDuration：

from pydantic_evals import Case, Dataset from pydantic_evals.evaluators import MaxDuration dataset = Dataset( name='performance_test', cases=[ Case(inputs='test input', expected_output='test output'), ], evaluators=[ MaxDuration(seconds=2.0), ], )

MaxDuration检查ctx.duration（任务执行时间，单位秒）是否不超过阈值，seconds参数同时接受浮点数或datetime.timedelta（如MaxDuration(seconds=timedelta(milliseconds=500))），可用于 SLA 合规、性能回归测试与超时校验。

源码级深入：一次实验的完整流程

从Dataset.evaluate的实现（dataset.py）可以看出实验执行的完整链路：

1. 参数校验与任务名解析：repeat必须 >= 1、max_concurrency必须 >= 1；实验名称默认取任务函数名，可通过name或task_name覆盖；
2. 并发调度：通过anyio.Semaphore限制并发度，max_concurrency为None时所有用例并发执行；同时用 richProgress显示进度条（progress=False可关闭）；
3. 逐用例执行（_run_task_and_evaluators，L1083-L1219）：对每个用例执行任务函数并记录耗时，然后并行运行该用例的评估器（case 级评估器 + dataset 级评估器），把结果按类型分组为断言（bool）、分数（int/float）、标签（str）；
4. 汇总报告：成功结果归入report.cases，执行抛出异常的结果归入report.failures（含错误消息与堆栈）；
5. 报告级评估：如果配置了report_evaluators，则在整个报告上运行，产出混淆矩阵、PR 曲线、标量指标、表格等实验级分析（见 evaluators/report-evaluators.md）。

evaluate_sync只是evaluate的同步封装（L417-L473），内部通过run_until_complete运行同一套异步逻辑。此外，evaluate还支持以下进阶参数：

• retry_task/retry_evaluators：任务与评估器的重试配置（复用 pydantic-ai 的RetryConfig，底层基于 tenacity）；
• repeat：每个用例重复运行的次数，>1 时结果按原始用例名分组聚合（report.averages()会先对每组求平均再汇总），适合统计概率性系统的稳定性；
• metadata：实验级元数据，会写入报告与 OpenTelemetry span；
• lifecycle：每用例的CaseLifecycle钩子，支持 setup、prepare_context、teardown 阶段的自定义逻辑。

EvaluationReport（reporting/init.py）除了print()输出表格外，还提供程序化访问接口：report.cases（逐用例结果，含scores、labels、assertions、task_duration、total_duration等）、report.failures、report.analyses、report.averages()（跨用例的均值聚合，含断言通过率）。print()还支持传入baseline报告做差异对比渲染，便于版本间指标追踪。

内置评估器速查

完整的内置评估器清单与参数见 Native Evaluators，DEFAULT_EVALUATORS注册表定义于 common.py。下表摘录常用项：

报告级评估器还包括ConfusionMatrixEvaluator（分类混淆矩阵）与PrecisionRecallEvaluator（带 AUC 的 PR 曲线）。最佳实践是组合使用：先用IsInstance、Contains、MaxDuration等快速确定性检查快速失败，再对通过基础检查的输出运行LLMJudge等昂贵的 LLM 评估。

更进一步

本文是 Pydantic Evals 的入口，继续深入可以阅读：

• Core Concepts：数据模型与评估流程详解；
• Native Evaluators：全部内置评估器的参数参考；
• Custom Evaluators：编写自己的评估逻辑（@dataclass+ 继承Evaluator+ 实现evaluate，支持同步/异步、多结果字典、EvaluationReason原因说明）；
• Dataset Management：数据集的保存、加载与 LLM 生成（YAML/JSON 序列化、JSON Schema 生成、generate_dataset）；
• Examples: Simple Validation：常见场景的实战示例。

【免费下载链接】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