arize-evaluator

Arize Evaluator Skill

SPACE — 所有 --space 标志和 ARIZE_SPACE 环境变量都接受 space 名称（例如 my-workspace）或 base64 编码的 space ID（例如 U3BhY2U6...）。使用 ax spaces list 查找你的 space。

本 skill 涵盖在 Arize 上设计、创建和运行 LLM-as-judge 评估器。评估器定义 judge；任务则是你针对真实数据运行它的方式。

---

前置条件

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

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

• command not found 或版本错误 → 参见 references/ax-setup.md
• 401 Unauthorized / 缺少 API key → 运行 ax profiles show 检查当前 profile。如果 profile 缺失或 API key 有误，请按照 references/ax-profiles.md 创建/更新它。如果用户没有自己的 key，请引导他们前往 https://app.arize.com/admin > API Keys
• 未知 space → 运行 ax spaces list 按名称选择，或询问用户
• LLM provider 调用失败（缺少 OPENAI_API_KEY / ANTHROPIC_API_KEY）→ 运行 ax ai-integrations list --space SPACE 检查是否有平台托管的凭证。如果不存在，请让用户提供 key，或通过 arize-ai-provider-integration skill 创建集成
• 安全： 切勿读取 .env 文件，也不要在文件系统中搜索凭证。Arize 凭证请使用 ax profiles，LLM provider key 请使用 ax ai-integrations。如果通过这些渠道无法获得凭证，请询问用户。
• 关键——切勿捏造评估结果： 如果评估任务失败、被取消或未产生任何分数，请清楚地报告失败并解释出了什么问题。不要执行“手动评估”、编造质量分数、估计百分比，也不要把任何 Agent 生成的分析当作来自 Arize 评估系统的结果来呈现。而应建议：(1) 修复已识别的问题并重试，(2) 尝试从 Arize UI 运行，(3) 使用 ax ai-integrations list 验证集成凭证，(4) 通过 https://arize.com/support 联系支持团队

---

概念

什么是评估器？

评估器是一个 LLM-as-judge 定义。它包含：

字段	描述
Template	judge 提示词。使用 {variable} 占位符（例如 {input}、{output}、{context}），在运行时通过任务的列映射填充。
Classification choices	允许的输出标签集合（例如 factual / hallucinated）。二分类是默认且最常见的。每个选项可选地带有数值分数。
AI Integration	存储的 LLM provider 凭证（OpenAI、Anthropic、Bedrock 等），评估器用它来调用 judge 模型。
Model	具体的 judge 模型（例如 gpt-4o、claude-sonnet-4-5）。
Invocation params	可选的模型设置 JSON，例如 {"temperature": 0}。为可复现性建议使用低 temperature。
Optimization direction	分数越高越好（maximize）还是越差（minimize）。决定 UI 如何呈现趋势。
Data granularity	评估器是在 span、trace 还是 session 级别运行。大多数评估器在 span 级别运行。

评估器是带版本的——每次提示词或模型变更都会创建一个新的不可变版本。最新版本为活动版本。

什么是任务？

任务是你针对真实数据运行一个或多个评估器的方式。任务会附加到项目（实时 trace/span）或数据集（实验运行）上。一个任务包含：

字段	描述
评估器	要运行的评估器列表。你可以在一个任务中运行多个评估器。
列映射	将每个评估器的模板变量映射到 span 或实验运行上的实际字段路径（例如 "input" → "attributes.input.value"）。正是这一点让评估器可以跨项目和实验通用。
查询过滤器	用于选择要评估哪些 span/运行的 SQL 风格表达式（例如 "span_kind = 'LLM'"）。可选，但对精确性很重要。
持续	针对项目任务：是否在新 span 到达时自动评分。
采样率	针对持续项目任务：要评估的新 span 比例（0–1）。

---

数据粒度

--data-granularity 标志控制评估器评分的单位数据。它默认为 span，且仅适用于项目任务（不适用于数据集/实验任务——这些任务直接评估实验运行）。

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

trace 和 session 聚合的工作原理

对于 trace 粒度，共享相同 context.trace_id 的 span 会被分组在一起。评估器模板使用的列值会以逗号连接成单个字符串（每个值截断为 100K 字符），然后再传递给评判模型。

对于 session 粒度，会先进行相同的 trace 级分组，然后按 start_time 对 trace 排序，并按 attributes.session.id 分组。会话级值总计上限为 100K 字符。

{conversation} 模板变量

在 session 粒度下，{conversation} 是一个特殊的模板变量，它会渲染为会话中所有 trace 的 {input, output} 轮次的 JSON 数组，由 attributes.input.value / attributes.llm.input_messages（输入侧）和 attributes.output.value / attributes.llm.output_messages（输出侧）构建而成。

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

多评估器任务

一个任务可以包含不同粒度的评估器。在运行时，系统会使用最高粒度（session > trace > span）来获取数据，并自动拆分为每个评估器一个子运行。任务评估器 JSON 中每个评估器的 query_filter 会进一步缩小包含哪些 span（例如，仅会话中的工具调用 span）。

---

基本 CRUD

AI 集成

AI 集成存储评估器使用的 LLM 提供商凭据。有关完整的 CRUD —— 列出、为所有提供商（OpenAI、Anthropic、Azure、Bedrock、Vertex、Gemini、NVIDIA NIM、自定义）创建、更新和删除 —— 请使用 arize-ai-provider-integration 技能。

常见场景（OpenAI）的快速参考：

# Check for an existing integration first
ax ai-integrations list --space SPACE

# Create if none exists
ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider openAI \
  --api-key $OPENAI_API_KEY

复制返回的集成 ID —— 它是 ax evaluators create --ai-integration-id 所必需的。

评估器

# List / Get
ax evaluators list --space SPACE
ax evaluators get ID                    # accepts name or ID
ax evaluators get NAME --space SPACE   # required when using name instead of ID
ax evaluators list-versions NAME_OR_ID
ax evaluators get-version VERSION_ID

# Create (creates the evaluator and its first version)
ax evaluators create \
  --name "Answer Correctness" \
  --space SPACE \
  --description "Judges if the model answer is correct" \
  --template-name "correctness" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response correctly answers the question.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: correct, incorrect'

# Create a new version (for prompt or model changes — versions are immutable)
ax evaluators create-version NAME_OR_ID \
  --commit-message "Added context grounding" \
  --template-name "correctness" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'Updated prompt...

{input} / {output} / {context}'

# Update metadata only (name, description — not prompt)
ax evaluators update NAME_OR_ID \
  --name "New Name" \
  --description "Updated description"

# Delete (permanent — removes all versions)
ax evaluators delete NAME_OR_ID

create 的关键标志：

标志	是否必需	描述
--name	是	评估器名称（在空间内唯一）
--space	是	要创建到的空间名称或 ID
--template-name	是	评估列名称 — 字母数字、空格、连字符、下划线
--commit-message	是	此版本的描述
--ai-integration-id	是	AI 集成 ID（见上文）
--model-name	是	评判模型（例如 gpt-4o）
--template	是	带 {variable} 占位符的提示词（在 bash 中单引号括起）
--classification-choices	是	将选项标签映射到数值分数的 JSON 对象，例如 '{"correct": 1, "incorrect": 0}'
--description	否	人类可读的描述
--include-explanations	否	在标签旁包含推理说明
--use-function-calling	否	优先使用结构化函数调用输出
--invocation-params	否	模型参数的 JSON，例如 '{"temperature": 0}'
--data-granularity	否	span（默认）、trace 或 session。仅与项目任务相关，与数据集/实验任务无关。参见数据粒度部分。
--direction	否	优化方向：maximize 或 minimize。设定 UI 如何呈现趋势。
--provider-params	否	提供方特定参数的 JSON 对象

任务

PROJECT_NAME、DATASET_NAME 和 evaluator_id 均接受名称或 base64 ID。

# List / Get
ax tasks list --space SPACE
ax tasks list --project PROJECT_NAME
ax tasks list --dataset DATASET_NAME --space SPACE
ax tasks get TASK_ID

# Create (project — continuous)
ax tasks create \
  --name "Correctness Monitor" \
  --task-type template_evaluation \
  --project PROJECT_NAME \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

# Create (project — one-time / backfill)
ax tasks create \
  --name "Correctness Backfill" \
  --task-type template_evaluation \
  --project PROJECT_NAME \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

# Create (experiment / dataset)
ax tasks create \
  --name "Experiment Scoring" \
  --task-type template_evaluation \
  --dataset DATASET_NAME --space SPACE \
  --experiment-ids "EXP_ID_1,EXP_ID_2" \   # base64 IDs from `ax experiments list --space SPACE -o json`
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

# Trigger a run (project task — use data window)
ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --wait

# Trigger a run (experiment task — use experiment IDs)
ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID_1" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --wait

# Monitor
ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID
ax tasks wait-for-run RUN_ID --timeout 300
ax tasks cancel-run RUN_ID --force

trigger-run 的时间格式： 2026-03-21T09:00:00 — 末尾不带 Z。

额外的 trigger-run 标志：

标志	描述
--max-spans	限制处理的 span 数量（默认 10,000）
--override-evaluations	重新评分已有标签的 span
--wait / -w	阻塞直到运行结束
--timeout	使用 --wait 时的等待秒数（默认 600）
--poll-interval	等待时的轮询间隔秒数（默认 5）

运行状态指南：

状态	含义
completed，0 个 span	评估索引滞后 1–2 小时 — 最近摄入的 span 可能尚未被索引。将窗口移到至少 2 小时前的数据，或扩大时间范围以覆盖更多历史数据。
cancelled ~1s	集成凭据无效
cancelled ~3min	找到了 span 但大模型调用失败 — 检查模型名称或密钥
completed，N > 0	成功 — 在 UI 中检查分数

---

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

当用户说类似 “为我的 Playground Traces 项目创建一个评估器” 时使用此流程。

步骤 1：确认项目名称

ax spans export 直接接受项目名称 — 无需查找 ID。如果你不知道项目名称，列出可用项目：

ax projects list --space SPACE -o json

找到 "name" 匹配（不区分大小写）的条目，并在后续命令中将该名称用作 PROJECT。如果之后使用名称遇到验证错误，则回退使用项目的 "id"（一个 base64 字符串）。

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

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

如果未指定，则抽样最近的 span，以基于实际数据构建评估器：

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

检查 attributes.input、attributes.output、span 类型以及任何现有注解。识别失败模式（例如捏造事实、偏离主题的回答、缺少上下文），并提出 1–3 个具体的评估器想法。让用户选择。

每个建议必须包含：评估器名称（粗体）、一句话描述其评判内容，以及括号中的二元标签对。将每个格式化为：

1. Name — 所评判内容的描述。（label_a / label_b）

示例：

1. Response Correctness — Agent 的回答是否正确处理了用户的财务查询？（correct / incorrect）
2. Hallucination — 回答是否捏造了未基于检索上下文的事实？（factual / hallucinated）

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

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

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

步骤 4：创建评估器

使用下方的模板设计最佳实践。保持评估器名称和变量通用——具体任务的接线由步骤 6 通过 column_mappings 处理。

ax evaluators create \
  --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 条历史 span）来验证评估器，然后再开启持续监控。这样可以在对全部未来生产 span 评分之前，在已知数据上发现列映射错误、错误的 span 类型和模板问题。只有在回填确认评分正确后，才启用持续评估。

在创建任务之前，询问：

"你是否希望： (a) 对历史 span 运行一次回填（一次性）？ (b) 对未来的新 span 设置持续评估？ (c) 两者都要——先回填以验证，然后自动持续对新 span 评分？（推荐）"

步骤 6：从真实 span 数据中确定列映射

不要猜测路径。拉取样本并检查实际存在哪些字段：

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

为每个模板变量（{input}、{output}、{context}）找到匹配的 JSON 路径。常见起点——使用前务必在你的实际数据上验证：

模板变量	LLM span	CHAIN span
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

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

query_filter 只对已索引的属性有效： 评估器 JSON 中的 query_filter 是针对评估索引求值的，而不是原始 span 存储。attributes.metadata.* 下的属性或自定义键可能未被索引，会静默地匹配不到任何内容。请使用已知的已索引属性（如 span_kind 或 attributes.llm.model_name）进行过滤。如果某个过滤器在数据存在的情况下仍返回 0 条 span，可尝试移除该过滤器作为诊断步骤。

完整的 --evaluators JSON 示例：

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

为模板引用的每一个变量都包含映射。遗漏一个会导致运行无法产生有效评分。

步骤 7：创建任务

仅回填 (a)：

ax tasks create \
  --name "Hallucination Backfill" \
  --task-type template_evaluation \
  --project PROJECT \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

仅持续 (b)：

ax tasks create \
  --name "Hallucination Monitor" \
  --task-type template_evaluation \
  --project PROJECT \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

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

步骤 8：触发回填运行（如被请求）

评估索引延迟： 评估索引是从主 trace 存储异步构建的，可能延迟 1–2 小时。对于首次测试运行，请使用至少在过去 2 小时结束的时间窗口。如果你把 --data-end-time 设为"现在"，而对过去一小时内摄入的 span 运行，运行会成功完成但评分为 0 条 span。

首先找出哪个时间范围有数据：

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

使用真实 span 的 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 → 检查它是在运行本身上，还是嵌入在关联的数据集示例中

如果 input 不在运行的 JSON 上，请导出数据集示例以找到路径：

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：创建任务

ax tasks create \
  --name "Experiment Correctness" \
  --task-type template_evaluation \
  --dataset DATASET_NAME --space SPACE \
  --experiment-ids "EXP_ID" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

步骤 7：触发并监控

ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --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 中的标签完全匹配（拼写相同、大小写相同）。

好的示例：

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}"

7. 始终将 --classification-choices 设置为与模板标签匹配

--classification-choices 中的标签必须与 --template 中引用的标签完全匹配（拼写相同、大小写相同）。省略 --classification-choices 会导致任务运行失败，并报错“missing rails and classification choices”。

---

故障排查

问题	解决方案
ax: command not found	参见 references/ax-setup.md
401 Unauthorized	API key 可能无权访问该 space。请在 https://app.arize.com/admin > API Keys 验证
Evaluator not found	ax evaluators list --space SPACE
Integration not found	ax ai-integrations list --space SPACE
Task not found	ax tasks list --space SPACE
project and dataset-id are mutually exclusive	创建 task 时只能使用其中一个
experiment-ids required for dataset tasks	在 create 和 trigger-run 中添加 --experiment-ids
sampling-rate only valid for project tasks	从 dataset task 中移除 --sampling-rate
ax spans export 出现验证错误	通常使用 project 名称即可；如果仍出现验证错误，请通过 ax projects list --space SPACE -o json 查找 base64 project ID，并改用 id 字段
模板验证错误	在 bash 中使用单引号的 --template '...'；使用单花括号 {var}，而非双花括号 {{var}}
Run 卡在 pending	执行 ax tasks get-run RUN_ID；然后执行 ax tasks cancel-run RUN_ID
Run 约 1s 后变为 cancelled	Integration 凭证无效 — 检查 AI integration
Run 约 3min 后变为 cancelled	找到了 span，但 LLM 调用失败 — model 名称错误或 key 无效
Run completed，0 个 span	扩大时间窗口；eval index 可能未覆盖较旧的数据
UI 中没有分数	修正 column_mappings，使其匹配 span/run 上的真实路径
分数看起来不对	添加 --include-explanations，并检查几个样本上的 judge 推理
Evaluator 因 span 类型错误而取消	将 query_filter 和 column_mappings 与 LLM 及 CHAIN span 匹配
trigger-run 出现时间格式错误	使用 2026-03-21T09:00:00 — 不要带末尾的 Z
Run 失败："missing rails and classification choices"	在 ax evaluators create 中添加 --classification-choices '{"label_a": 1, "label_b": 0}' — 标签必须与模板匹配
Run completed，所有 span 均被跳过	查询过滤器匹配到了 span，但 column mappings 错误或模板变量无法解析 — 导出一个样本 span 并验证路径
设置了 query_filter 但 0 个 span 被评分	该过滤器属性可能未在 eval index 中建立索引。attributes.metadata.* 和自定义属性通常未建立索引。请改用 span_kind 或 attributes.llm.model_name，或移除过滤器以确认窗口内存在 span。

诊断已取消的运行

当任务运行被取消（状态为 cancelled）时，请按顺序执行以下检查清单：

1. 检查集成凭据

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

确认评估器使用的集成 ID 存在且凭据有效。如果集成已被删除或 API 密钥已过期，运行会在约 1 秒内取消。

2. 验证模型名称

ax evaluators get EVALUATOR_NAME --space SPACE -o json

检查 model_name 字段。拼写错误或已弃用的模型会导致大模型调用失败，运行会在约 3 分钟后取消。

3. 导出一个示例 span/run，并将路径与 column_mappings 进行比较

对于项目任务：

ax spans export PROJECT --space SPACE -l 1 --days 7 --stdout | python3 -m json.tool

对于实验任务：

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)) if runs else print('No runs')"

将导出的 JSON 路径与任务的 column_mappings 进行比较。对于每个模板变量，确认映射的路径确实存在。常见的不匹配情况：

• 在实验运行中将 output 映射到 attributes.output.value（应仅为 output）
• 当实际路径为 attributes.llm.input_messages 时，将 CHAIN span 上的 input 映射到 attributes.input.value
• 将 context 映射到被过滤的 span 类型上不存在的路径

4. 检查 data_start_time 不是 epoch

如果 trigger-run 使用的开始时间为 0、1970-01-01 或空字符串，则时间窗口无效。始终从真实的 span 时间戳推导：

ax spans export PROJECT --space SPACE -l 5 --days 30 --stdout | python3 -c "
import sys, json
spans = json.load(sys.stdin)
for s in spans:
    print(s.get('start_time', 'N/A'), s.get('end_time', 'N/A'))
"

5. 验证 span 类型与评估器范围匹配

如果评估器创建时使用了 --data-granularity trace，但任务的 query_filter 为 span_kind = 'LLM'，运行可能找不到符合条件的数据并取消。确保粒度和过滤器保持一致。

6. 检查所有模板变量都能解析

评估器模板中的每个 {variable} 都必须有对应的 column_mappings 条目，且能解析为非空值。针对真实 span 测试解析：

ax spans export PROJECT --space SPACE -l 3 --days 7 --stdout | python3 -c "
import sys, json
spans = json.load(sys.stdin)
# Replace these paths with your actual column_mappings values
mappings = {'input': 'attributes.input.value', 'output': 'attributes.output.value'}
for i, span in enumerate(spans):
    print(f'--- Span {i} ---')
    for var, path in mappings.items():
        parts = path.split('.')
        val = span
        for p in parts:
            val = val.get(p) if isinstance(val, dict) else None
        status = 'FOUND' if val else 'MISSING'
        print(f'  {var} ({path}): {status} — {str(val)[:80] if val else \"null\"}')
"

如果某个变量在所有 span 上都显示 MISSING，请修复列映射或将 query_filter 调整为针对不同的 span 类型。

---

相关技能

• arize-ai-provider-integration：大模型提供商集成的完整 CRUD（创建、更新、删除凭据）
• arize-trace：导出 span 以发现列路径和时间范围
• arize-experiment：创建实验并导出运行，用于实验列映射
• arize-dataset：导出数据集示例，以便在运行缺少输入字段时找到它们
• arize-link：指向 Arize UI 中评估器和任务的深层链接

---

保存凭据以供将来使用

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