wehub-skill-sync
17 KiB
内置评估器
从 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
AnswerCorrectness(*, client: 'Any' = None) -> 'AutoevalsAdapter'
答案正确性评估器（RAGAS）。
判断 eval_output 与 expected_output 相比是否正确，综合了事实相似度和语义相似度。
使用场景：RAG 流水线中的问答场景，当你拥有参考答案并希望获得全面的正确性分数时。
需要 expected_output：是。
需要 eval_metadata["context"]：可选（可提高准确性）。
参数： client：OpenAI 客户端实例。
AnswerRelevancy
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
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
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
ContextRelevancy(*, client: 'Any' = None) -> 'AutoevalsAdapter'
上下文相关性评估器（RAGAS）。
判断检索到的上下文是否与查询相关。将 eval_metadata["context"] 转发到底层评分器。
使用场景：RAG 流水线——评估检索质量。
需要 expected_output：是。
需要 eval_metadata["context"]：是（仅限 RAG 流水线）。
参数： client：OpenAI 客户端实例。
EmbeddingSimilarity
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
ExactMatch() -> 'AutoevalsAdapter'
精确值比较评估器。
如果 eval_output 与 expected_output 完全相等，则返回 1.0，否则返回 0.0。
使用场景：确定性、结构化的输出（分类标签、是/否回答、固定格式字符串）。切勿用于开放式 LLM 文本——LLM 输出是非确定性的，因此精确匹配几乎总是失败。
需要 expected_output：是。
Factuality
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
Faithfulness(*, client: 'Any' = None) -> 'AutoevalsAdapter'
忠实度评估器（RAGAS）。
判断 eval_output 是否忠实于（即是否由）所提供的上下文所支持。转发 eval_metadata["context"]。
使用场景：RAG 流水线——确保回答不会超出检索到的上下文而产生幻觉。
需要 expected_output：否。
需要 eval_metadata["context"]：是（仅限 RAG 流水线）。
参数： client：OpenAI 客户端实例。
Humor
Humor(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
幽默质量评估器（LLM 作为评判者）。
使用 LLM 判断 eval_output 相对于 expected_output 的幽默质量。
使用场景：评估创意写作、聊天机器人个性或娱乐应用中的幽默效果。
需要 expected_output：是。
参数： model：LLM 模型名称。 client：OpenAI 客户端实例。
JSONDiff
JSONDiff(*, string_scorer: 'Any' = None) -> 'AutoevalsAdapter'
结构化 JSON 比较评估器。
递归比较两个 JSON 结构并生成相似度分数。支持嵌套对象、数组和混合类型。
使用场景：需要字段级比较的结构化 JSON 输出（例如提取的数据、API 响应模式、工具调用参数）。
需要 expected_output：是。
参数： string_scorer：用于字符串字段的可选成对评分器。
LevenshteinMatch
LevenshteinMatch() -> 'AutoevalsAdapter'
编辑距离字符串相似度评估器。
计算 eval_output 与 expected_output 之间的归一化 Levenshtein 距离。完全相同返回 1.0，编辑距离越大分数越低。
使用场景：确定性或近似确定性的输出，允许较小的文本变化（例如格式差异、轻微拼写错误）。不适用于开放式 LLM 文本——请改用 LLM 作为评判者的评估器。
需要 expected_output：是。
ListContains
ListContains(*, pairwise_scorer: 'Any' = None, allow_extra_entities: 'bool' = False) -> 'AutoevalsAdapter'
列表重叠评估器。
检查 eval_output 是否包含 expected_output 中的所有条目。基于重叠比例评分。
使用场景：输出为条目列表且完整性至关重要的场景（例如提取的实体、搜索结果、推荐）。
需要 expected_output：是。
参数： pairwise_scorer：用于逐对元素比较的可选评分器。 allow_extra_entities：如果为 True，输出中的多余条目不扣分。
Moderation
Moderation(*, threshold: 'float | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
内容审核评估器。
使用 OpenAI 审核 API 检查 eval_output 中是否包含不安全内容（仇恨言论、暴力、自残等）。
使用场景：任何需要关注输出安全性的应用——聊天机器人、内容生成、面向用户的 AI。
需要 expected_output：否。
参数： threshold：自定义标记阈值。 client：OpenAI 客户端实例。
NumericDiff
NumericDiff() -> 'AutoevalsAdapter'
归一化数值差异评估器。
计算 eval_output 与 expected_output 之间的归一化数值距离。完全相同返回 1.0，差异越大分数越低。
使用场景：允许近似相等的数值输出（例如价格计算、分数、测量值）。
需要 expected_output：是。
Possible
Possible(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
可行性/合理性评估器（LLM 作为评判者）。
使用 LLM 判断 eval_output 是否是一个合理或可行的回答。
使用场景：通用质量检查，当你希望验证输出是否合理而不需要特定参考答案时。
需要 expected_output：否。
参数： model：LLM 模型名称。 client：OpenAI 客户端实例。
Security
Security(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
安全漏洞评估器（LLM 作为评判者）。
使用 LLM 检查 eval_output 是否基于 eval_input 中的指令存在安全漏洞。
使用场景：代码生成、SQL 输出，或任何需要检查输出是否存在注入或漏洞风险的场景。
需要 expected_output：否。
参数： model：LLM 模型名称。 client：OpenAI 客户端实例。
Sql
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
Summary(*, model: 'str | None' = None, client: 'Any' = None) -> 'AutoevalsAdapter'
摘要质量评估器（LLM 作为评判者）。
使用 LLM 判断 eval_output 作为摘要的质量，并与 expected_output 中的参考摘要进行比较。
使用场景：摘要任务，要求输出必须从源材料中捕获关键信息。
需要 expected_output：是。
参数： model：LLM 模型名称。 client：OpenAI 客户端实例。
Translation
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
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
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
create_agent_evaluator(name: 'str', criteria: 'str') -> '_AgentEvaluator'
创建一个将评分委托给编码代理的评估器。
在 pixie test 期间，代理评估器不会自动评分。相反，它们会抛出 AgentEvaluationPending 异常，并使用评估标准记录一个 PendingEvaluation。编码代理（由步骤 6 指导）审查每个条目的追踪和输出，然后对待处理评估进行评分。
使用场景：需要对 LLM 追踪进行全面审查的质量维度——工具调用正确性、多步推理质量、路由决策——这些场景下自动化的 LLM 作为评判者的提示词无法捕捉到细微差异。
何时不该使用：简单的文本质量检查（改用 create_llm_evaluator）、确定性检查（使用启发式评估器），或任何仅凭输入+输出即可评分而无需追踪上下文的评估标准。
参数： name：评估器的显示名称（计分卡中显示为 ⏳ 待处理）。 criteria：评估标准——编码代理在审查结果时将遵循的评分说明。请具体且可操作。
返回：
一个满足 Evaluator 协议的可调用评估器。其 __call__ 方法抛出 AgentEvaluationPending 异常，而不是返回 Evaluation。
示例：
from pixie import create_agent_evaluator
ResponseQuality = create_agent_evaluator(
name="ResponseQuality",
criteria="回复直接回应用户的问题，信息准确、结构清晰。"
"没有幻觉或离题内容。",
)
ToolUsageCorrectness = create_agent_evaluator(
name="ToolUsageCorrectness",
criteria="应用根据用户的意图以正确顺序调用了正确的工具。"
"没有不必要的或遗漏的工具调用。",
)