arize-evaluator

Arize Evaluator Skill

SPACE — --space 标志接受空间名称（例如，my-workspace）或 Base64 空间ID（例如，U3BhY2U6...）。使用 ax spaces list 查找你的空间。

此技能介绍如何在 Arize 上设计、创建和运行评估器，包括 LLM-as-judge（模板）评估器和代码评估器（确定性，无需 LLM）。评估器定义评判者；任务则是将评估器应用于真实数据的运行方式。

---

前提条件

直接执行任务——运行所需的 ax 命令。不要预先检查版本、环境变量或配置文件。

如果 ax 命令失败，请根据错误进行排查：

• command not found 或版本错误 → 参阅 references/ax-setup.md
• 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show 检查当前配置文件。如果配置文件缺失或 API 密钥错误，请按照 references/ax-profiles.md 创建或更新配置文件。如果用户没有 API 密钥，请引导他们前往 https://app.arize.com/admin > API Keys
• 空间未知 → 参阅 Space
• LLM 提供商调用失败（缺少提供商凭据）→ 运行 ax ai-integrations list --space SPACE 检查是否存在由平台管理的凭据。如果不存在，请使用 arize-ai-provider-integration 技能——绝不要让用户在聊天中粘贴提供商密钥。
• **安全性：**绝不要读取 .env 文件或搜索文件系统以查找凭据。例外：非机密的 ARIZE_SPACE_ID 行（参见 Space）。使用 ax profiles 管理 Arize 凭据，使用 ax ai-integrations 管理 LLM 提供商密钥。绝不要让用户在聊天中粘贴机密信息。有关缺失凭据的处理方式，请参阅 references/ax-profiles.md。
• **关键——绝不要捏造评估结果：**如果评估任务失败、被取消或未产生分数，请清楚报告失败情况并说明原因。不要执行“人工评估”、编造质量分数、估算百分比，也不要将任何由 Agent 生成的分析说成是 Arize 评估系统的结果。应改为建议：(1) 修复已发现的问题并重试；(2) 尝试从 Arize UI 运行；(3) 使用 ax ai-integrations list 验证集成凭据；(4) 通过 https://arize.com/contact/ 联系支持团队

---

概念

什么是 Evaluator？

evaluator 是一种 LLM-as-judge 定义，包含以下字段：

字段	描述
Template	评判提示词。使用 {variable} 占位符（例如 {input}、{output}、{context}），运行时会通过任务的列映射填充这些占位符。
Classification choices	允许的输出标签集合（例如 factual / hallucinated）。二元分类是默认且最常见的设置。每个选项可以附带一个数值分数。
AI Integration	已存储的 LLM 提供商凭据（OpenAI、Anthropic、Bedrock 等），Evaluator 使用这些凭据调用评判模型。
Model	具体的评判模型（例如 gpt-4o、claude-sonnet-4-5）。
Invocation params	可选的模型设置 JSON，例如 {"temperature": 0}。建议使用较低的 temperature，以便获得可复现的结果。
Optimization direction	分数越高越好（MAXIMIZE）还是越差越好（MINIMIZE）。此设置决定 UI 如何显示趋势。
Data granularity	Evaluator 按 span、trace 还是 session 级别运行。大多数 Evaluator 按 span 级别运行。

Evaluator 会进行版本管理——每次更改提示词或模型都会创建一个新的不可变版本。最新版本处于启用状态。

Code Evaluator 是确定性替代方案——无需 AI 集成或模型，只需使用 Python。它必须以继承 CodeEvaluator 的类运行，而不能是普通函数，并且必须符合其严格的导入路径和 evaluate() 签名约定。任何一项不符合都会导致运行在 0/0/0 处静默取消。编写之前，请参阅 references/cli-reference.md 中的“Custom Python code evaluators”。

Remote Evaluator 会调用客户托管的 HTTP 端点，通过 ax evaluators create-evaluator remote 创建，并需提供 evaluator integration ID。运行 ax evaluators create-evaluator remote --help 查看其标志。

什么是 Task？

task 用于针对真实数据运行一个或多个 Evaluator。Task 会关联到一个项目（实时 traces/spans）或一个数据集（实验运行）。Task 包含以下字段：

字段	描述
Evaluators	要运行的 Evaluator 列表。一个 Task 中可以运行多个 Evaluator。
Column mappings	将每个 Evaluator 的模板变量映射到 span 或实验运行中的实际字段路径（例如，"input" → "attributes.input.value"）。这使 Evaluator 能够在不同项目和实验之间复用。
Query filter	类 SQL 表达式，用于选择要评估的 span/运行（例如，"attributes.openinference.span.kind = 'LLM'"）。使用任务级别的 --query-filter 设置。此项为可选，但对准确性很重要。
Continuous	对于项目 Task：是否在新 span 到达时自动为其评分。
Sampling rate	对于连续运行的项目 Task：要评估的新 span 比例（0–1）。

---

数据粒度

创建 Evaluator 时设置 --data-granularity（ax evaluators create-evaluator template / create-evaluator code），而不是在 Task 上设置——它控制该 Evaluator 每次针对项目 Task运行时所评分的数据单位（不适用于数据集/实验 Task；这些 Task 会直接评估实验运行）。默认值为 span。

级别	评估内容	适用场景	结果列前缀
span（默认）	单个 span	问答正确性、幻觉、相关性	eval.{name}.label / .score / .explanation
trace	按 context.trace_id 分组的 trace 中所有 span	Agent 执行轨迹、任务正确性——任何需要完整调用链的评估	trace_eval.{name}.label / .score / .explanation
session	按 attributes.session.id 分组并按开始时间排序的 session 中所有 trace	多轮连贯性、整体语气、对话质量	session_eval.{name}.label / .score / .explanation

追踪和会话聚合的工作方式

对于追踪粒度，共享同一 context.trace_id 的跨度会被归为一组。传递给评审模型之前，评估器模板使用的列值会以逗号连接成一个字符串（每个值最多截断至 100K 个字符）。

对于会话粒度，系统会先进行相同的追踪级分组，然后按 start_time 对追踪排序，并按 attributes.session.id 分组。会话级值的总长度最多为 100K 个字符。

{conversation} 模板变量

在会话粒度下，{conversation} 是一个特殊的模板变量，会将会话中所有追踪的 {input, output} 轮次渲染为 JSON 数组。数据来自 attributes.input.value / attributes.llm.input_messages（输入侧）以及 attributes.output.value / attributes.llm.output_messages（输出侧）。

在跨度或追踪粒度下，{conversation} 会被视为常规模板变量，并像其他变量一样通过列映射解析。

注意： 要使用 {conversation}，跨度必须包含 attributes.session.id。有关如何从应用程序代码中发出 session.id，包括 Jupyter 笔记本和短时运行脚本所需的 force_flush() 模式，请参阅 arize-instrumentation 技能。

多评估器任务

一个任务可以包含不同粒度的评估器。运行时，系统会使用最高粒度（会话 > 追踪 > 跨度）获取数据，并自动为每个评估器拆分出一个子运行。使用任务级 --query-filter 进行筛选，该筛选器适用于任务中的每个评估器。

---

基本 CRUD

references/cli-reference.md 中提供了 AI 集成、评估器（模板和代码）以及任务的完整命令参考，包括所有标志及其示例。以下工作流会直接列出所需命令。

---

工作流 A：为项目创建评估器

当用户提出类似 “为我的 Playground Traces 项目创建一个评估器” 的需求时，请使用此工作流。

步骤 1：确认项目名称

ax spans export 接受通过 --space SPACE 指定的项目名称，无需查询 ID。若要确认已知名称或获取其 base64 "id"（当名称导致验证错误时使用该 id），请直接获取项目：

ax projects get PROJECT --space SPACE -o json

如果项目名称未知，ax projects list --space SPACE -o json 会列出项目以供浏览；使用匹配的 "name" 作为 PROJECT。

步骤 2：了解要评估的内容

如果用户指定了评估器类型（幻觉、正确性、相关性等）→ 跳到步骤 3。

如果没有指定，请抽取近期跨度样本，根据实际数据设计评估器：

ax spans export PROJECT --space SPACE -l 10 --days 30 --stdout

检查 attributes.input、attributes.output、跨度类型以及现有注释。识别失败模式（例如，编造事实、答非所问、缺少上下文），并提出 1–3 个具体的评估器构想。让用户选择。

每条建议必须包含：评估器名称（加粗）、一句话说明评估内容，以及括号中的二元标签对。格式如下：

1. 名称 — 评估内容的说明。（label_a / label_b）

示例：

1. 回答正确性 — Agent 的回答是否正确回应了用户的财务问题？（correct / incorrect）
2. 幻觉 — 回答是否编造了检索到的上下文中没有依据的事实？（factual / hallucinated）

步骤 3：确认或创建 AI 集成

ax ai-integrations list --space SPACE -o json

如果存在合适的集成，请记下其 ID。如果不存在，请使用 arize-ai-provider-integration 技能创建一个。询问用户希望评审使用哪个提供商/模型。

步骤 4：创建评估器

使用以下模板设计最佳实践。评估器名称和变量应保持通用——步骤 6 中的任务会通过 column_mappings 处理特定项目的配置。

ax evaluators create-evaluator template \
  --name "Hallucination" \
  --space SPACE \
  --template-name "hallucination" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"factual": 1, "hallucinated": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response is factual or contains unsupported claims.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: hallucinated, factual'

步骤 5：询问——回填、持续评估，还是两者都要？

推荐做法： 始终先对少量历史跨度（约 100 条）进行回填，以验证评估器，然后再开启持续监控。这样你就能先在已知数据上发现列映射错误、跨度类型错误和模板问题，再对所有未来的生产跨度进行评分。只有在回填确认评分正确后，才启用持续评估。

创建任务前，请询问：

“你希望： (a) 对历史跨度运行一次回填？ (b) 设置对之后新跨度进行持续评估？ (c) 两者都要——先回填进行验证，然后继续自动对新跨度评分？（推荐）”

步骤 6：根据实际跨度数据确定列映射

不要猜测路径。先提取样本并检查实际包含哪些字段：

ax spans export PROJECT --space SPACE -l 5 --days 7 --stdout

对于每个模板变量（{input}、{output}、{context}），找到匹配的 JSON 路径。以下是常见起点——使用前务必根据你的实际数据进行验证：

模板变量	LLM 跨度	CHAIN 跨度
input	attributes.input.value	attributes.input.value
output	attributes.llm.output_messages.0.message.content	attributes.output.value
context	attributes.retrieval.documents.contents	—
tool_output	attributes.input.value（回退）	attributes.output.value

验证跨度类型是否匹配： 如果评估器提示词假定的是 LLM 最终文本，但任务针对的是 CHAIN 跨度（或反之），运行可能会取消或对错误的文本评分。请确保任务上的 query_filter 与映射所用的跨度类型一致。

筛选器会在评估索引上运行： 跨度类型字段是 attributes.openinference.span.kind——span_kind 不是列，因此不会报错，但也不会匹配任何内容。像 attributes.metadata.* 这样的自定义属性也可能未编入索引。如果明明存在数据，筛选器却返回 0 条跨度，请移除筛选器，以确认该时间范围内是否有数据。

完整的 --evaluators JSON 示例：

[
  {
    "evaluator_id": "EVAL_ID",
    "column_mappings": {
      "input": "attributes.input.value",
      "output": "attributes.llm.output_messages.0.message.content",
      "context": "attributes.retrieval.documents.contents"
    }
  }
]

模板引用的每个变量都必须包含映射。遗漏任何一个变量，都会导致运行无法生成有效评分。

步骤 7：创建任务

仅回填 (a)：

ax tasks create-evaluation \
  --name "Hallucination Backfill" \
  --task-type TEMPLATE_EVALUATION \
  --project PROJECT --space SPACE \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --query-filter "attributes.openinference.span.kind = 'LLM'" \
  --no-continuous

仅持续评估 (b)：

ax tasks create-evaluation \
  --name "Hallucination Monitor" \
  --task-type TEMPLATE_EVALUATION \
  --project PROJECT --space SPACE \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --query-filter "attributes.openinference.span.kind = 'LLM'" \
  --is-continuous \
  --sampling-rate 0.1

两者都要 (c)： 创建时使用 --is-continuous，然后在步骤 8 中触发一次回填运行。

步骤 8：触发回填运行（如果需要）

评估索引延迟： 评估索引会从主要追踪存储异步构建，可能延迟1–2 小时。首次测试运行时，请使用至少在 2 小时前结束的时间范围。如果对最近一小时内摄取的跨度将 --data-end-time 设为“now”，运行会成功完成，但评分跨度数为 0。

首先，查找有数据的时间范围：

ax spans export PROJECT --space SPACE -l 100 --days 1 --stdout   # try last 24h first
ax spans export PROJECT --space SPACE -l 100 --days 7 --stdout   # widen if empty

使用实际跨度中的 start_time / end_time 字段设置时间范围。首次验证运行时，将 --max-spans 限制在约 100 条，以便快速获得反馈：

ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --max-spans 100 \
  --wait

扩大回填范围或启用持续评估前，请先检查评分和说明。

---

工作流 B：为实验创建评估器

当用户提出类似*“为我的实验创建评估器”或“评估我的数据集运行”*的需求时，使用此工作流。

如果用户提到“数据集”但没有实验： 任务必须针对实验（而不是单独的数据集）。请询问：

“评估任务针对的是实验运行，而不是直接针对数据集。你需要我先帮你在该数据集上创建一个实验吗？”

如果需要，请使用 arize-experiment 技能创建实验，然后返回此处。

步骤 1：查找数据集和实验名称

ax datasets list --space SPACE
ax experiments list --dataset DATASET_NAME --space SPACE -o json

记下数据集名称和要评分的实验名称。后续命令接受名称或 ID，优先使用名称。

步骤 2：了解要评估的内容

如果用户指定了评估器类型 → 跳到步骤 3。

如果没有，请检查最近的一次实验运行，以实际数据为依据创建评估器：

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

查看 output、input、evaluations 和 metadata 字段。找出缺失项（用户关心但尚未涵盖的指标），并提出 1–3 个评估器构想。每条建议都必须包含：评估器名称（加粗）、一句话描述，以及括号中的二元标签对——格式与工作流 A 的步骤 2 相同。

步骤 3：确认或创建 AI 集成

与工作流 A 的步骤 3 相同。

步骤 4：创建评估器

与工作流 A 的步骤 4 相同。变量应保持通用。

步骤 5：根据真实运行数据确定列映射

运行数据的结构与 span 数据不同。请检查：

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

实验运行的常见映射：

• output → "output"（每次运行的顶层字段）
• input → 检查它是在运行数据中，还是嵌入在关联的数据集示例中

如果运行 JSON 中没有 input，请导出数据集示例以查找路径：

ax datasets export DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; ex=json.load(sys.stdin); print(json.dumps(ex[0], indent=2))"

步骤 6：创建任务

--experiment-ids 接受从 ax experiments list --space SPACE -o json 获取的 base64 ID。

ax tasks create-evaluation \
  --name "Experiment Correctness" \
  --task-type TEMPLATE_EVALUATION \
  --dataset DATASET_NAME --space SPACE \
  --experiment-ids "EXP_ID" \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

步骤 7：触发并监控

ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID" \
  --wait

ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID

---

模板设计最佳实践

1. 使用通用且可移植的变量名

使用 {input}、{output} 和 {context}，不要使用与特定项目或 span 属性绑定的名称（例如，不要使用 {attributes_input_value}）。评估器本身应保持抽象；你可以通过任务的 column_mappings 将其映射到特定项目或实验中的实际字段。这样，同一个评估器就能在多个项目和实验中运行，无需修改。

2. 默认使用二元标签

使用恰好两个清晰的字符串标签（例如 hallucinated / factual、correct / incorrect、pass / fail）。二元标签：

• 最便于评判模型稳定地产出
• 在行业中最常见
• 最容易在仪表板中解读

如果用户坚持使用两个以上的选项，也可以，但应优先推荐二元标签，并解释其中的权衡（标签越多 → 歧义越大 → 评审者间可靠性越低）。

3. 明确说明模型必须返回什么

模板必须要求评判模型仅返回标签字符串，不得包含其他内容。使用 --classification-choices 设置标签输出；提示词中的标签字符串必须与其键完全一致（拼写和大小写均相同）。仅在需要自由格式（非分类）输出时，才省略 --classification-choices。

正确示例：

Respond with exactly one of these labels: hallucinated, factual

错误示例（过于开放）：

Is this hallucinated? Answer yes or no.

4. 将温度设得较低

传入 --invocation-params '{"temperature": 0}'，以便获得可复现的评分。较高的温度会给评估结果带来噪声。

5. 使用 --include-explanations 进行调试

初始设置期间，始终包含解释，以便在大规模信任这些标签之前，验证评判模型的推理是否正确。

6. 在 bash 中用单引号传入模板

单引号可防止 shell 对 {variable} 占位符进行插值。使用双引号会导致问题：

# Correct
--template 'Judge this: {input} → {output}'

# Wrong — shell may interpret { } or fail
--template "Judge this: {input} → {output}"

---

故障排除

问题	解决方案
ax: command not found	请参阅 references/ax-setup.md
401 Unauthorized	API 密钥可能无权访问此空间。请前往 https://app.arize.com/admin > API Keys 验证
Evaluator not found	ax evaluators get NAME_OR_ID --space SPACE（ax evaluators list --space SPACE 用于人工浏览）
Integration not found	ax ai-integrations get NAME_OR_ID --space SPACE（list 用于人工浏览）
Task not found	ax tasks get TASK_ID（ax tasks list --space SPACE 用于人工浏览）
project and dataset-id are mutually exclusive	创建任务时只能使用其中一项
experiment-ids required for dataset tasks	在 create 和 trigger-run 中添加 --experiment-ids
sampling-rate only valid for project tasks	从数据集任务中移除 --sampling-rate
project '...' not found 或 ax spans export 验证错误	添加 --space SPACE；如果问题仍然存在，请通过 ax projects get PROJECT --space SPACE -o json 查找 base64 项目 ID，并改用 id 字段
模板验证错误	在 bash 中使用单引号括起 --template '...'；使用单花括号 {var}，而非 {{var}}
运行卡在 pending 状态	运行 ax tasks get-run RUN_ID；然后运行 ax tasks cancel-run RUN_ID
运行状态为 completed，但跨度数为 0	扩大时间范围；评估索引可能不包含较早的数据
分数看起来不对	添加 --include-explanations，并检查几个样本的评判器推理
trigger-run 时间格式错误	使用 2026-03-21T09:00:00——末尾不要加 Z
运行失败：“missing rails and classification choices”	在 ax evaluators create-evaluator template（新建）或 create-evaluator-version template（现有）中添加 --classification-choices '{"label_a": 1, "label_b": 0}'——标签必须与模板匹配
运行状态为 completed，但所有跨度都已跳过	查询筛选器匹配到了跨度，但列映射有误或模板变量无法解析——导出一个示例跨度并检查路径
已设置 query_filter，但评分跨度数为 0，或出现 No data found	使用 attributes.openinference.span.kind，而非 span_kind。自定义属性可能未编入索引。移除筛选器，以确认指定时间范围内是否存在跨度。
对错误类型的跨度进行了评分	在任务的 --query-filter 中设置跨度类型筛选器，而不是使用每个评估器单独的 query_filter
自定义 代码 评估器运行约 3 秒后取消，结果为 0/0/0（成功/错误/跳过）	导入路径或 evaluate() 签名错误——请参阅 references/cli-reference.md 中 Custom Python code evaluators 下的“CRITICAL”提示。必须从 arize.experimental.datasets.experiments.evaluators.base 导入（而非 arize.experiments），并声明命名的 evaluate() 参数，不能只使用 **kwargs。

诊断已取消的运行

对于已取消的运行（约 1 秒或约 3 分钟）、错误的跨度类型和列映射不匹配，请按顺序完成检查清单（凭据 → 模型名称 → 列映射/路径检查 → 时间范围 → 跨度类型 → 变量解析），详见 references/troubleshooting.md。

---

相关技能

• arize-ai-provider-integration：完整管理 LLM 提供商集成的增删改查（创建、更新、删除凭据）
• arize-trace：导出跨度，以发现列路径和时间范围
• arize-experiment：创建实验并导出运行，以获取实验列映射
• arize-dataset：导出数据集示例，以便在运行未提供输入字段时查找这些字段
• arize-prompts：在 Prompt Hub 中管理提示词模板；与评估器搭配使用，为已版本化的提示词评分
• arize-link：指向 Arize UI 中评估器和任务的深层链接

---

保存凭据以供将来使用

请参阅 references/ax-profiles.md § 保存凭据以供将来使用。