步骤 3：定义评估器

为什么需要这一步：在完成应用的仪器化（步骤 2）之后，现在你需要将每个评估标准映射到具体的评估器——在需要的地方实现自定义评估器——以便数据集（步骤 4）可以通过名称引用它们。

3a. 将标准映射到评估器

步骤 1c 中的每个评估标准——包括用户在提示中指定的任何维度——都必须有对应的评估器。 如果用户要求了"事实准确性、完整性和偏见性"，你就需要三个评估器（或者一个覆盖全部三者的多标准评估器）。不要静默地丢弃任何被请求的维度。优先选择那些能够衡量 pixie_qa/00-project-analysis.md 中确定的困难问题/失败模式的评估器——这些比通用的质量评估器更有价值。

对于每个评估标准，按照以下决策顺序选择评估器：

内置评估器——如果标准评估器符合该标准（事实正确性 → Factuality，精确匹配 → ExactMatch，RAG 忠实度 → Faithfulness）。完整目录请参见 evaluators.md。
Agent 评估器（create_agent_evaluator）——所有语义性、定性和应用特定标准的默认选择。Agent 评估器将由你（编码 agent）在步骤 6 中进行评分，你将在该步骤中全面审查每个条目的追踪记录和输出。对于像"提取结果是否准确捕获了源内容？""是否存在幻觉值？"或"应用是否优雅地处理了嘈杂输入？"这样的标准，这种方法远比自动化评分有效。
手动自定义评估器——仅用于机械性、确定性的检查，即程序化函数可以明确给出正确答案的场景：字段存在性、正则表达式模式匹配、JSON Schema 验证、数值阈值、类型检查。切勿将手动自定义评估器用于语义质量评估——如果检查需要对内容是否正确、相关或完整做出判断，则应改用 Agent 评估器。

区分结构性标准与语义性标准：对于每个标准，问自己："能否通过一个简单的程序化规则来检查，并且该规则总能给出正确答案？"如果能 → 使用手动自定义评估器。如果不能 → 使用 Agent 评估器。大多数应用特定的质量标准是语义性的，而非结构性的。

对于开放式 LLM 文本，切勿使用 ExactMatch——LLM 输出是非确定性的。

AnswerRelevancy 是仅限 RAG 的——它需要在追踪记录中存在 context 值。缺少该值时返回 0.0。对于一般的相关性，请使用带有明确标准的 Agent 评估器。

3b. 实现自定义评估器

如果任何标准需要自定义评估器，请立即实现。将自定义评估器放置在 pixie_qa/evaluators.py 中（如果数量较多，可放在子模块中）。

Agent 评估器（`create_agent_evaluator`）——默认选择

对于所有语义性、定性和基于判断的标准，请使用 Agent 评估器。这些评估器将由你（编码 agent）在步骤 5d 中进行评分，你将在该步骤中结合完整上下文审查每个条目的追踪记录和输出——对于准确性、完整性、幻觉检测或错误处理等质量维度，这远比任何自动化方法有效。

from pixie import create_agent_evaluator

extraction_accuracy = create_agent_evaluator(
    name="ExtractionAccuracy",
    criteria="提取的数据准确反映了源内容。所有字段都包含源中的正确值——没有幻觉值、"
             "编造值或占位符值。将 final_answer 与 fetched_content "
             "和 parsed_content 进行比较，以验证每个声称的事实。",
)

noise_handling = create_agent_evaluator(
    name="NoiseHandling",
    criteria="应用正确忽略了源中的导航装饰、样板文本、广告和其他非内容元素。"
             "提取的数据仅包含与用户提示相关的信息，而不包含页面结构中的噪音。",
)

schema_compliance = create_agent_evaluator(
    name="SchemaCompliance",
    criteria="输出包含提示中请求的所有字段，且具有适当的类型和非空值。"
             "缺失字段、必需数据的空值或包含通用占位符文本的字段表示失败。",
)

在数据集中通过 filepath:callable_name（例如 "pixie_qa/evaluators.py:extraction_accuracy"）引用 Agent 评估器。

在 pixie test 运行期间，Agent 评估器在控制台中显示为 ⏳。它们将在步骤 5d 中进行评分。

编写有效的标准：criteria 字符串是你在步骤 5d 中将要遵循的评分细则。请使其具体且可操作：

不好："检查输出是否良好"——过于模糊，难以一致评分
不好："响应应该准确"——没有说明要与什么进行比较
好："将提取的字段与源 HTML/文档进行比较。每个字段必须在源中有对应的段落。标记任何无法追溯到源内容的字段值。"
好："应用应保留源文档的结构层次。如果源有章节/子章节，提取结果应反映该嵌套结构，而不是将所有内容扁平化为单一层级。"

手动自定义评估器——仅用于机械性检查

仅在确定性的程序化检查中使用手动自定义评估器**，即简单函数能够明确给出正确答案的场景。示例包括：字段存在性、正则匹配、JSON Schema 验证、数值范围检查、类型验证。

不要将手动自定义评估器用于语义质量评估。 如果检查需要对内容是否正确、相关、完整或文笔优美做出判断，请改用 Agent 评估器。判定标准："正则表达式、字符串匹配或比较运算符能否完美实现这个检查？"如果不能，则属于语义性检查——请使用 Agent 评估器。

自定义评估器可以是同步或异步函数。将它们赋值给 pixie_qa/evaluators.py 中的模块级变量：

from pixie import Evaluation, Evaluable

def my_evaluator(evaluable: Evaluable, *, trace=None) -> Evaluation:
    score = 1.0 if "expected pattern" in str(evaluable.eval_output) else 0.0
    return Evaluation(score=score, reasoning="...")

在数据集中通过 filepath:callable_name 引用："pixie_qa/evaluators.py:my_evaluator"。

访问 eval_metadata 和捕获的数据：自定义评估器通过 Evaluable 字段访问每个条目的元数据和 wrap() 输出：

evaluable.eval_metadata —— 来自条目 eval_metadata 字段的字典（例如 {"expected_tool": "endCall"}）
evaluable.eval_output —— 包含所有 wrap(purpose="output") 和 wrap(purpose="state") 值的 list[NamedData]。每个项包含 .name（str）和 .value（JsonValue）。使用下面的辅助函数按名称查找。

def _get_output(evaluable: Evaluable, name: str) -> Any:
    """按名称从 eval_output 中查找 wrap 值。"""
    for item in evaluable.eval_output:
        if item.name == name:
            return item.value
    return None

def call_ended_check(evaluable: Evaluable, *, trace=None) -> Evaluation:
    expected = evaluable.eval_metadata.get("expected_call_ended") if evaluable.eval_metadata else None
    actual = _get_output(evaluable, "call_ended")
    if expected is None:
        return Evaluation(score=1.0, reasoning="eval_metadata 中无 expected_call_ended")
    match = bool(actual) == bool(expected)
    return Evaluation(
        score=1.0 if match else 0.0,
        reasoning=f"期望 call_ended={expected}，实际得到 {actual}",
    )

ValidJSON 与字符串期望值的冲突

当数据集的 expectation 字段中存在值时，ValidJSON 会将其视为 JSON Schema。如果你的条目使用字符串期望值（例如用于 Factuality），将 ValidJSON 添加为数据集级别的默认评估器会导致失败——它无法将纯字符串验证为 JSON Schema。要么仅将 ValidJSON 应用于具有对象/布尔值期望值的条目，要么在数据集依赖字符串期望值时省略它。

3c. 生成评估器映射文档

将标准到评估器的映射写入 pixie_qa/03-evaluator-mapping.md。该文档连接了评估标准（步骤 1c）和数据集（步骤 4）。

关键：使用与 evaluators.md 参考文档中完全一致的评估器名称——内置评估器使用其短名称（例如 Factuality、ClosedQA），自定义评估器使用 filepath:callable_name 格式（例如 pixie_qa/evaluators.py:ConciseVoiceStyle）。

模板

# 评估器映射

## 使用的内置评估器

| 评估器名称   | 覆盖的标准       | 适用范围                   |
| ------------ | ---------------- | -------------------------- |
| Factuality   | 事实准确性       | 所有条目                   |
| ClosedQA     | 答案正确性       | 含有 expected_output 的条目 |

## Agent 评估器

| 评估器名称                                   | 覆盖的标准               | 适用范围  | 源文件                  |
| -------------------------------------------- | ------------------------ | --------- | ----------------------- |
| pixie_qa/evaluators.py:extraction_accuracy   | 内容与源的准确性对照     | 所有条目  | pixie_qa/evaluators.py  |
| pixie_qa/evaluators.py:noise_handling        | 导航/样板文本噪音        | 所有条目  | pixie_qa/evaluators.py  |

## 手动自定义评估器（仅限机械性检查）

| 评估器名称                                   | 覆盖的标准       | 适用范围  | 源文件                  |
| -------------------------------------------- | ---------------- | --------- | ----------------------- |
| pixie_qa/evaluators.py:required_fields_present | 必填字段检查     | 所有条目  | pixie_qa/evaluators.py  |

## 适用范围总结

- **数据集级别默认**（适用于所有条目）：Factuality、pixie_qa/evaluators.py:extraction_accuracy
- **条目特定**（适用于子集）：ClosedQA（仅适用于含有 expected_output 的条目）

输出

pixie_qa/evaluators.py 中的自定义评估器实现（如果需要任何自定义评估器）
pixie_qa/03-evaluator-mapping.md——标准到评估器的映射

评估器选择指南：参见 evaluators.md 获取完整的内置评估器目录和 create_agent_evaluator 参考。

如果在实现评估器时遇到意外错误（导入失败、API 不匹配），请先阅读 evaluators.md 获取权威的评估器参考，以及 wrap-api.md 获取 API 详细信息，然后再猜测修复方法。

10 KiB Raw Permalink Blame History Unescape Escape