# 步骤 3：定义评估器

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

---

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

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

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

1. **内置评估器**——如果标准评估器符合该标准（事实正确性 → `Factuality`，精确匹配 → `ExactMatch`，RAG 忠实度 → `Faithfulness`）。完整目录请参见 `evaluators.md`。
2. **Agent 评估器**（`create_agent_evaluator`）——**所有语义性、定性和应用特定标准的默认选择**。Agent 评估器将由你（编码 agent）在步骤 6 中进行评分，你将在该步骤中全面审查每个条目的追踪记录和输出。对于像"提取结果是否准确捕获了源内容？""是否存在幻觉值？"或"应用是否优雅地处理了嘈杂输入？"这样的标准，这种方法远比自动化评分有效。
3. **手动自定义评估器**——仅用于**机械性、确定性的检查**，即程序化函数可以明确给出正确答案的场景：字段存在性、正则表达式模式匹配、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 中进行评分，你将在该步骤中结合完整上下文审查每个条目的追踪记录和输出——对于准确性、完整性、幻觉检测或错误处理等质量维度，这远比任何自动化方法有效。

```python
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` 中的模块级变量：

```python
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）。使用下面的辅助函数按名称查找。

```python
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`）。

### 模板

```markdown
# 评估器映射

## 使用的内置评估器

| 评估器名称   | 覆盖的标准       | 适用范围                   |
| ------------ | ---------------- | -------------------------- |
| 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 详细信息，然后再猜测修复方法。