PydanticAI 的 Evals 评估框架实践

PydanticAI 的 Evals 评估框架实践

学习目标

补充理解：

• Dataset/Case/Evaluator 三层评估模型
• OTel Span 捕获 Agent 内部行为
• EvaluationReport 聚合与可视化

前置知识

• 质量门控 — 通用质量门控概念

---

1. 三层评估模型

PydanticAI 的 Evals 框架分为三层：

Dataset[InputsT, OutputT, MetadataT]
    ├── 测试数据集，包含多个 Case
    └── evaluate(task) → 并发执行所有 Case

Case[InputsT, OutputT, MetadataT]
    ├── 单个测试用例
    ├── name, inputs, expected_output, metadata
    └── 可选的 per-case evaluators

Evaluator[InputsT, OutputT, MetadataT]
    ├── 抽象评估器，evaluate(ctx: EvaluatorContext) → EvaluatorOutput
    └── 结果分类：assertions (bool), scores (int/float), labels (str)

2. 评估流程

1. Dataset.evaluate(task) 并发运行所有 Case（max_concurrency 限制）
2. 每个 Case: _run_task_and_evaluators()
   ├── 执行 task 函数
   ├── 捕获 OTel Span（通过 logfire_span()）
   ├── 将 Span 子树存入 EvaluatorContext._span_tree
   └── 运行所有 evaluators（通过 task_group_gather() 并发）
3. 结果聚合 → EvaluationReport

关键特性：评估是并发执行的——需要注意竞态条件。

3. OTel Span 捕获

Evals 利用 OTel Span 捕获 Agent 内部行为：

EvaluatorContext:
    inputs, output, expected_output, metadata
    duration           # 从 OTel Span 计算
    attributes         # Span 属性
    metrics            # Span 指标
    _span_tree         # Span 子树（结构化分析）

优势：无需手动埋点——Agent 运行自动产生 OTel Span，评估器可以分析这些 Span。

4. EvaluationReport

评估结果聚合为 EvaluationReport：

EvaluationReport:
    per_case_results    # 每案例结果
    failures            # 失败案例
    averages            # 平均值
    assertions          # 布尔断言
    scores              # 数值分数
    labels              # 字符串标签

5. 序列化

数据集可保存为 YAML/JSON：

cases:
  - name: test_simple_math
    inputs: "What is 2+2?"
    expected_output: "4"

使用 JSON Schema 验证反序列化——确保加载的测试数据格式正确。

6. 与通用质量门控的差异

维度	通用质量门控	PydanticAI Evals
数据源	手动标注或自动生成	Dataset/Case 结构
评估执行	通常是独立脚本	与 Agent 运行集成，OTel 捕获
结果聚合	通过率/分数	EvaluationReport 多维度
可视化	自定义 Dashboard	Pydantic Logfire 集成