wehub-skill-sync
505 lines
17 KiB
Markdown
505 lines
17 KiB
Markdown
# 内置评估器
|
||
|
||
> 从 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="应用根据用户的意图以正确顺序调用了正确的工具。"
|
||
"没有不必要的或遗漏的工具调用。",
|
||
)
|
||
```
|