# 内置评估器

> 从 pixie 源代码文档字符串自动生成。
> 请勿手动编辑——运行 `uv run python scripts/generate_skill_docs.py`。

Autoevals 适配器——封装 `autoevals` 评分器的预制评估器。

本模块提供 :class:`AutoevalsAdapter`，它将 autoevals 的 `Scorer` 接口桥接到 pixie 的 `Evaluator` 协议，以及一组用于常见评估任务的工厂函数。

公共 API（均从 `pixie.evals` 重新导出）：

**核心适配器：** - :class:`AutoevalsAdapter` —— 任意 autoevals `Scorer` 的通用包装器。

**启发式评分器（无需 LLM）：** - :func:`LevenshteinMatch` —— 编辑距离字符串相似度。 - :func:`ExactMatch` —— 精确值比较。 - :func:`NumericDiff` —— 归一化数值差异。 - :func:`JSONDiff` —— 结构化 JSON 比较。 - :func:`ValidJSON` —— JSON 语法/模式验证。 - :func:`ListContains` —— 两个字符串列表之间的重叠。

**嵌入评分器：** - :func:`EmbeddingSimilarity` —— 基于嵌入的余弦相似度。

**LLM 作为评判者的评分器：** - :func:`Factuality`、:func:`ClosedQA`、:func:`Battle`、
:func:`Humor`、:func:`Security`、:func:`Sql`、
:func:`Summary`、:func:`Translation`、:func:`Possible`。

**内容审核：** - :func:`Moderation` —— OpenAI 内容审核检查。

**RAGAS 指标：** - :func:`ContextRelevancy`、:func:`Faithfulness`、
:func:`AnswerRelevancy`、:func:`AnswerCorrectness`。

## 评估器选择指南

根据**输出类型**和评估标准选择评估器：

| 输出类型 | 评估器类别 | 示例 |
| -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------- |
| 确定性输出（标签、是/否、固定格式） | 启发式：`ExactMatch`、`JSONDiff`、`ValidJSON` | 标签分类、JSON 提取 |
| 带有参考答案的开放式文本 | LLM 作为评判者：`Factuality`、`ClosedQA`、`AnswerCorrectness` | 聊天机器人回复、问答、摘要 |
| 带有预期上下文/依据的文本 | RAG：`Faithfulness`、`ContextRelevancy` | RAG 流水线 |
| 带有风格/格式要求的文本 | 通过 `create_llm_evaluator` 自定义 | 语音友好型回复、语气检查 |
| 多维度质量 | 组合多个评估器 | 事实性 + 相关性 + 语气 |
| 依赖追踪的质量（工具使用、路由） | 通过 `create_agent_evaluator` 创建代理评估器 | 工具正确性、多步推理质量 |

关键规则：

- 对于开放式 LLM 文本，**切勿**使用 `ExactMatch`——LLM 输出是非确定性的。
- `AnswerRelevancy` 是**仅限 RAG** 的——需要追踪中的 `context`。没有该值则返回 0.0。对于通用相关性，请使用 `create_llm_evaluator`。
- 不要在缺少 `expected_output` 的条目上使用比较评估器（`Factuality`、`ClosedQA`、
  `ExactMatch`）——它们会产生无意义的分数。

---

## 评估器参考

### `AnswerCorrectness`

```python
AnswerCorrectness(*, client: 'Any' = None) -> 'AutoevalsAdapter'
```

答案正确性评估器（RAGAS）。

判断 `eval_output` 与 `expected_output` 相比是否正确，综合了事实相似度和语义相似度。

**使用场景**：RAG 流水线中的问答场景，当你拥有参考答案并希望获得全面的正确性分数时。

**需要 `expected_output`**：是。
**需要 `eval_metadata["context"]`**：可选（可提高准确性）。

参数：
client：OpenAI 客户端实例。

### `AnswerRelevancy`

```python
AnswerRelevancy(*, client: 'Any' = None) -> 'AutoevalsAdapter'
```

答案相关性评估器（RAGAS）。

判断 `eval_output` 是否直接回应了 `eval_input` 中的问题。

**使用场景**：仅限 RAG 流水线——需要追踪中的 `context`。没有该值则返回 0.0。对于通用（非 RAG）响应相关性，请改用 `create_llm_evaluator` 并编写自定义提示词。

**需要 `expected_output`**：否。
**需要 `eval_metadata["context"]`**：是——**仅限 RAG 流水线**。

参数：
client：OpenAI 客户端实例。

### `Battle`

```python
Battle(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

头对头比较评估器（LLM 作为评判者）。

使用 LLM 将 `eval_output` 与 `expected_output` 进行比较，并根据 `eval_input` 中的指令判断哪个更优。

**使用场景**：A/B 测试场景、比较模型输出、或对备选回复进行排序。

**需要 `expected_output`**：是。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `ClosedQA`

```python
ClosedQA(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

闭卷问答评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 是否与 `expected_output` 相比正确回答了 `eval_input` 中的问题。可选地转发 `eval_metadata["criteria"]` 以用于自定义评分标准。

**使用场景**：答案应与参考答案匹配的问答场景——例如客户支持回答、知识库查询。

**需要 `expected_output`**：是——不要在缺少 `expected_output` 的条目上使用；会产生无意义的分数。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `ContextRelevancy`

```python
ContextRelevancy(*, client: 'Any' = None) -> 'AutoevalsAdapter'
```

上下文相关性评估器（RAGAS）。

判断检索到的上下文是否与查询相关。将 `eval_metadata["context"]` 转发到底层评分器。

**使用场景**：RAG 流水线——评估检索质量。

**需要 `expected_output`**：是。
**需要 `eval_metadata["context"]`**：是（仅限 RAG 流水线）。

参数：
client：OpenAI 客户端实例。

### `EmbeddingSimilarity`

```python
EmbeddingSimilarity(*, prefix: 'str | None' = None, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

基于嵌入的语义相似度评估器。

计算 `eval_output` 和 `expected_output` 嵌入向量之间的余弦相似度。

**使用场景**：比较两段文本的语义含义，而不关心具体措辞。对于改写内容比 Levenshtein 更稳健，但不如 LLM 作为评判者的评估器细致。

**需要 `expected_output`**：是。

参数：
prefix：可选的前缀文本，用于提供领域上下文。
model：嵌入模型名称。
client：OpenAI 客户端实例。

### `ExactMatch`

```python
ExactMatch() -> 'AutoevalsAdapter'
```

精确值比较评估器。

如果 `eval_output` 与 `expected_output` 完全相等，则返回 1.0，否则返回 0.0。

**使用场景**：确定性、结构化的输出（分类标签、是/否回答、固定格式字符串）。**切勿**用于开放式 LLM 文本——LLM 输出是非确定性的，因此精确匹配几乎总是失败。

**需要 `expected_output`**：是。

### `Factuality`

```python
Factuality(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

事实准确性评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 在 `eval_input` 的上下文中是否与 `expected_output` 事实一致。

**使用场景**：需要事实正确性的开放式文本（聊天机器人回复、问答回答、摘要）。对于 LLM 生成的文本，优先于 `ExactMatch`。

**需要 `expected_output`**：是——不要在缺少 `expected_output` 的条目上使用；会产生无意义的分数。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `Faithfulness`

```python
Faithfulness(*, client: 'Any' = None) -> 'AutoevalsAdapter'
```

忠实度评估器（RAGAS）。

判断 `eval_output` 是否忠实于（即是否由）所提供的上下文所支持。转发 `eval_metadata["context"]`。

**使用场景**：RAG 流水线——确保回答不会超出检索到的上下文而产生幻觉。

**需要 `expected_output`**：否。
**需要 `eval_metadata["context"]`**：是（仅限 RAG 流水线）。

参数：
client：OpenAI 客户端实例。

### `Humor`

```python
Humor(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

幽默质量评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 相对于 `expected_output` 的幽默质量。

**使用场景**：评估创意写作、聊天机器人个性或娱乐应用中的幽默效果。

**需要 `expected_output`**：是。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `JSONDiff`

```python
JSONDiff(*, string_scorer: 'Any' = None) -> 'AutoevalsAdapter'
```

结构化 JSON 比较评估器。

递归比较两个 JSON 结构并生成相似度分数。支持嵌套对象、数组和混合类型。

**使用场景**：需要字段级比较的结构化 JSON 输出（例如提取的数据、API 响应模式、工具调用参数）。

**需要 `expected_output`**：是。

参数：
string_scorer：用于字符串字段的可选成对评分器。

### `LevenshteinMatch`

```python
LevenshteinMatch() -> 'AutoevalsAdapter'
```

编辑距离字符串相似度评估器。

计算 `eval_output` 与 `expected_output` 之间的归一化 Levenshtein 距离。完全相同返回 1.0，编辑距离越大分数越低。

**使用场景**：确定性或近似确定性的输出，允许较小的文本变化（例如格式差异、轻微拼写错误）。不适用于开放式 LLM 文本——请改用 LLM 作为评判者的评估器。

**需要 `expected_output`**：是。

### `ListContains`

```python
ListContains(*, pairwise_scorer: 'Any' = None, allow_extra_entities: 'bool' = False) -> 'AutoevalsAdapter'
```

列表重叠评估器。

检查 `eval_output` 是否包含 `expected_output` 中的所有条目。基于重叠比例评分。

**使用场景**：输出为条目列表且完整性至关重要的场景（例如提取的实体、搜索结果、推荐）。

**需要 `expected_output`**：是。

参数：
pairwise_scorer：用于逐对元素比较的可选评分器。
allow_extra_entities：如果为 True，输出中的多余条目不扣分。

### `Moderation`

```python
Moderation(*, threshold: 'float | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

内容审核评估器。

使用 OpenAI 审核 API 检查 `eval_output` 中是否包含不安全内容（仇恨言论、暴力、自残等）。

**使用场景**：任何需要关注输出安全性的应用——聊天机器人、内容生成、面向用户的 AI。

**需要 `expected_output`**：否。

参数：
threshold：自定义标记阈值。
client：OpenAI 客户端实例。

### `NumericDiff`

```python
NumericDiff() -> 'AutoevalsAdapter'
```

归一化数值差异评估器。

计算 `eval_output` 与 `expected_output` 之间的归一化数值距离。完全相同返回 1.0，差异越大分数越低。

**使用场景**：允许近似相等的数值输出（例如价格计算、分数、测量值）。

**需要 `expected_output`**：是。

### `Possible`

```python
Possible(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

可行性/合理性评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 是否是一个合理或可行的回答。

**使用场景**：通用质量检查，当你希望验证输出是否合理而不需要特定参考答案时。

**需要 `expected_output`**：否。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `Security`

```python
Security(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

安全漏洞评估器（LLM 作为评判者）。

使用 LLM 检查 `eval_output` 是否基于 `eval_input` 中的指令存在安全漏洞。

**使用场景**：代码生成、SQL 输出，或任何需要检查输出是否存在注入或漏洞风险的场景。

**需要 `expected_output`**：否。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `Sql`

```python
Sql(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

SQL 等价性评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` SQL 是否与 `expected_output` SQL 语义等价。

**使用场景**：Text-to-SQL 应用，要求生成的 SQL 在功能上与参考查询等价。

**需要 `expected_output`**：是。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `Summary`

```python
Summary(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

摘要质量评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 作为摘要的质量，并与 `expected_output` 中的参考摘要进行比较。

**使用场景**：摘要任务，要求输出必须从源材料中捕获关键信息。

**需要 `expected_output`**：是。

参数：
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `Translation`

```python
Translation(*, language: 'str | None' = None, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
```

翻译质量评估器（LLM 作为评判者）。

使用 LLM 判断 `eval_output` 与目标语言中 `expected_output` 相比的翻译质量。

**使用场景**：机器翻译或多语言输出场景。

**需要 `expected_output`**：是。

参数：
language：目标语言（例如 `"Spanish"`）。
model：LLM 模型名称。
client：OpenAI 客户端实例。

### `ValidJSON`

```python
ValidJSON(*, schema: 'Any' = None) -> 'AutoevalsAdapter'
```

JSON 语法和模式验证评估器。

如果 `eval_output` 是有效 JSON（并且可选地匹配提供的模式），则返回 1.0，否则返回 0.0。

**使用场景**：输出必须是有效 JSON 的场景——可选择性地要求符合特定模式（例如工具调用响应、结构化提取）。

**需要 `expected_output`**：否。

参数：
schema：用于验证的可选 JSON Schema。

---

## 自定义评估器：`create_llm_evaluator`

从提示词模板创建自定义 LLM 作为评判者的评估器的工厂函数。

用法：：

    from pixie import create_llm_evaluator

    concise_voice_style = create_llm_evaluator(
        name="ConciseVoiceStyle",
        prompt_template="""
        你正在评估一个语音代理的回复是否简洁且适合电话沟通。

        用户说：{eval_input}
        代理回复：{eval_output}
        预期行为：{expectation}

        如果回复简洁（少于 3 句）、直接回答问题、并使用适合电话对话的口语化语言，则评分 1.0。
        如果回复冗长、离题、或使用了书面风格格式，则评分 0.0。
        """,
    )

### `create_llm_evaluator`

```python
create_llm_evaluator(name: 'str', prompt_template: 'str', *, model: 'str' = 'gpt-4o-mini', client: 'Any | None' = None) -> '_LLMEvaluator'
```

从提示词模板创建一个自定义的 LLM 作为评判者的评估器。

模板可以引用以下变量（这些变量从 :class:`~pixie.storage.evaluable.Evaluable` 字段填充）：

- `{eval_input}` —— evaluable 的输入数据。单项列表展开为该条目的值；多项列表展开为 `name → value` 对的 JSON 字典。
- `{eval_output}` —— evaluable 的输出数据（规则同 `eval_input`）。
- `{expectation}` —— evaluable 的预期输出

参数：
name：评估器的显示名称（显示在计分卡中）。
prompt_template：包含 `{eval_input}`、`{eval_output}` 和/或 `{expectation}` 占位符的字符串模板。
model：OpenAI 模型名称（默认：`gpt-4o-mini`）。
client：可选预配置的 OpenAI 客户端实例。

返回：
一个满足 `Evaluator` 协议的可调用评估器。

抛出：
ValueError：如果模板使用类似 `{eval_input[key]}` 的嵌套字段访问（仅支持顶层占位符）。

### `create_agent_evaluator`

```python
create_agent_evaluator(name: 'str', criteria: 'str') -> '_AgentEvaluator'
```

创建一个将评分委托给编码代理的评估器。

在 `pixie test` 期间，代理评估器不会自动评分。相反，它们会抛出 `AgentEvaluationPending` 异常，并使用评估标准记录一个 `PendingEvaluation`。编码代理（由步骤 6 指导）审查每个条目的追踪和输出，然后对待处理评估进行评分。

**使用场景**：需要对 LLM 追踪进行全面审查的质量维度——工具调用正确性、多步推理质量、路由决策——这些场景下自动化的 LLM 作为评判者的提示词无法捕捉到细微差异。

**何时不该使用**：简单的文本质量检查（改用 `create_llm_evaluator`）、确定性检查（使用启发式评估器），或任何仅凭输入+输出即可评分而无需追踪上下文的评估标准。

参数：
name：评估器的显示名称（计分卡中显示为 ⏳ 待处理）。
criteria：评估标准——编码代理在审查结果时将遵循的评分说明。请具体且可操作。

返回：
一个满足 `Evaluator` 协议的可调用评估器。其 `__call__` 方法抛出 `AgentEvaluationPending` 异常，而不是返回 `Evaluation`。

示例：

```python
from pixie import create_agent_evaluator

ResponseQuality = create_agent_evaluator(
    name="ResponseQuality",
    criteria="回复直接回应用户的问题，信息准确、结构清晰。"
             "没有幻觉或离题内容。",
)

ToolUsageCorrectness = create_agent_evaluator(
    name="ToolUsageCorrectness",
    criteria="应用根据用户的意图以正确顺序调用了正确的工具。"
             "没有不必要的或遗漏的工具调用。",
)
```