arize-experiment

Arize 实验 Skill

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

概念

• 实验 = 针对特定数据集版本进行的一次具名评估，每个示例对应一次运行
• 实验运行 = 处理一个数据集示例后的结果——包括模型输出、可选的评估和可选的元数据
• 数据集 = 一组带版本的示例；每个实验都关联一个数据集及其特定版本
• 评估 = 附加到一次运行的具名指标（例如，correctness、relevance），可包含标签、分数和说明

典型流程：导出数据集 → 处理每个示例 → 收集输出和评估 → 使用这些运行创建实验。

前置条件

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

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

• 出现 command not found 或版本错误 → 查看 references/ax-setup.md
• 出现 401 Unauthorized / 缺少 API 密钥 → 运行 ax profiles show 检查当前配置文件。如果配置文件缺失或 API 密钥有误，请按照 references/ax-profiles.md 创建或更新配置文件。如果用户没有密钥，请引导他们前往 https://app.arize.com/admin > API Keys
• 空间未知 → 查看 Space
• 项目不明确 → 询问用户，或运行 ax projects list -o json --limit 100 并将结果作为可选项展示
• 安全性： 切勿读取 .env 文件或搜索文件系统中的凭据。例外：非机密的 ARIZE_SPACE_ID 行（参见 Space）。使用 ax profiles 管理 Arize 凭据，使用 ax ai-integrations 管理 LLM 提供商密钥。切勿要求用户在聊天中粘贴机密信息。缺少凭据时，请参阅 references/ax-profiles.md。
• 关键——切勿伪造输出： 运行实验时，对于每个数据集示例，都必须调用用户指定的真实模型 API。切勿伪造、模拟或硬编码模型输出、延迟或评估分数。如果无法调用 API（缺少 SDK、缺少凭据、网络错误），请停止并告知用户继续操作所需的条件。

列出实验：ax experiments list

浏览实验，可按数据集筛选。输出将写入 stdout。

ax experiments list
ax experiments list --dataset DATASET_NAME --space SPACE --limit 20   # DATASET_NAME: name or ID (name preferred)
ax experiments list --cursor CURSOR_TOKEN
ax experiments list -o json

标志：ax experiments list --help。

获取实验：ax experiments get

快速查询元数据——返回实验名称、关联的数据集和版本，以及时间戳。

ax experiments get NAME_OR_ID
ax experiments get NAME_OR_ID -o json
ax experiments get NAME_OR_ID --dataset DATASET_NAME --space SPACE   # required when using experiment name instead of ID

标志：ax experiments get --help。

响应字段

字段	类型	说明
id	字符串	实验 ID
name	字符串	实验名称
dataset_id	字符串	关联的数据集 ID
dataset_version_id	字符串	所用的特定数据集版本
experiment_traces_project_id	字符串	存储实验追踪记录的项目
created_at	日期时间	实验的创建时间
updated_at	日期时间	最后修改时间

导出实验：ax experiments export

将所有运行下载到文件。默认使用 REST API；传入 --all 可使用 Arrow Flight 进行批量传输。

# EXPERIMENT_NAME, DATASET_NAME: name or ID (name preferred)
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE
# -> experiment_abc123_20260305_141500/runs.json

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --all
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --output-dir ./results
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[0]'

标志：ax experiments export --help。

REST 与 Flight（--all）

• REST（默认）：使用门槛更低——无需 Arrow/Flight 依赖，使用标准 HTTPS 端口，可通过任何企业代理或防火墙。每页最多 500 次运行。
• Flight（--all）：实验运行次数超过 500 次时必须使用。它通过单独的主机/端口使用 gRPC+TLS，某些企业网络可能会阻止该连接。当前启用的 ax 配置文件会提供区域端点；参见配置文件设置。

Agent 自动升级规则： 如果 REST 导出的运行次数恰好为 500 次，结果很可能已被截断。请使用 --all 重新运行，以获取完整数据集。

输出为运行对象组成的 JSON 数组：

[
  {
    "id": "run_001",
    "example_id": "ex_001",
    "output": "The answer is 4.",
    "annotations": [
      { "name": "correctness", "label": "correct", "updated_at": "2026-03-01T00:00:00Z" }
    ],
    "additional_properties": {
      "eval.relevance.label": "relevant",
      "eval.relevance.score": 1,
      "eval.relevance.explanation": "Directly answers the question"
    }
  }
]

每次运行中的结果位置：

• annotations：annotate-runs 写入的值（没有时为 null）
• additional_properties["eval.<name>.label|score|explanation"]：来自评估器任务的结果
• 使用 --all 时，注释也会作为扁平键保存：additional_properties["annotation.<name>.label|score|text"]

创建实验：ax experiments create

使用数据文件中的运行创建新实验。

ax experiments create --name "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE --file runs.json
ax experiments create --name "claude-test" --dataset DATASET_NAME --space SPACE --file runs.csv

标志：ax experiments create --help。--dataset 为可选项——省略它即可创建不关联数据集的独立实验（此时必须指定 --space）。

通过 stdin 传递数据

使用 --file - 直接通过管道传入数据——无需临时文件：

echo '[{"example_id": "ex_001", "output": "Paris"}]' | ax experiments create --name "my-experiment" --dataset DATASET_NAME --space SPACE --file -

# Or with a heredoc
ax experiments create --name "my-experiment" --dataset DATASET_NAME --space SPACE --file - << 'EOF'
[{"example_id": "ex_001", "output": "Paris"}]
EOF

运行文件中的必需列

列	类型	必需	描述
example_id	字符串	是	ax datasets export 导出的数据集示例中的顶层 id
output	字符串	是	此示例的模型/系统输出

其他列会作为 additionalProperties 传递到运行中。

example_id 必须是 Arize 行 ID——即导出的每个数据集示例上的顶层 id 字段（ex["id"]）。请勿使用嵌套在示例输入字段或 additional_properties 中的值；错误的值会静默失败，或将运行关联到错误的示例。创建运行前，请先导出数据集并检查顶层 id 字段。

⚠️ 创建文件中的内联评估不会作为分数附加。 create 只读取 example_id 和 output；其他所有列——包括 evaluations 对象——都会作为透传附加字段存储，不会作为实验评估，也不会在 UI 中显示为分数。此操作会静默失败（不会报错）。若要附加分数/标签，请先创建实验，再运行 ax experiments annotate-runs。

在本地运行任务：ax experiments run

与 create（需要预先计算好的输出文件）不同，run 会加载一个 Python 任务函数，对数据集中的每一行执行该函数，并将结果上传为实验。

ax experiments run -n "my-experiment" --dataset DATASET_NAME --space SPACE --task task.py
ax experiments run -n "my-experiment" --dataset DATASET_NAME --space SPACE --task task.py --concurrency 5 --dry-run

task.py 必须定义顶层 task(dataset_row) 函数，并返回可序列化为 JSON 的值：

from anthropic import Anthropic

def task(dataset_row):
    resp = Anthropic().messages.create(
        model="claude-sonnet-4-6", max_tokens=256,
        messages=[{"role": "user", "content": dataset_row["question"]}]
    )
    return resp.content[0].text

--dry-run 会针对前 10 个示例进行测试，不上传结果，以便在完整运行前验证任务。标志：ax experiments run --help。

根据逻辑所在位置选择运行方式。 如果有要执行的本地 Python 任务，请使用 ax experiments run——它会在本机运行 task.py 并上传结果；无需 AI 集成。如果运行需要托管并定期执行，请使用 ax tasks create-run-experiment——它会注册一个由 Arize 按计划或按需执行的平台端 run_experiment 任务，通过 JSON --run-configuration（模型 + 消息 + AI 集成）驱动，而不是使用本地代码。对于本地/临时运行和自定义逻辑，默认使用 ax experiments run；对于定期托管运行，使用任务方式——该路径参见 arize-evaluator 技能。

列出运行：ax experiments list-runs

分页显示实验运行的终端视图（与将运行下载到文件的 export 不同）。

ax experiments list-runs EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --limit 30
ax experiments list-runs EXPERIMENT_ID

标志：ax experiments list-runs --help。

删除实验：ax experiments delete

ax experiments delete NAME_OR_ID
ax experiments delete NAME_OR_ID --dataset DATASET_NAME --space SPACE   # required when using experiment name instead of ID
ax experiments delete NAME_OR_ID --force   # skip confirmation prompt

标志：ax experiments delete --help。

为运行添加标注：ax experiments annotate-runs

这是将评估分数／标签附加到实验并使其显示在 UI 中的必需步骤。 无法通过 create 附加评估；请参阅“创建实验”下的警告。实验创建后，请在此处填写评估。采用 Upsert 语义：对同一次运行重新提交相同的标注 name，会覆盖之前的值。每个请求最多处理 1000 次运行；未匹配的记录 ID 会被静默忽略。

每个 name 必须是空间中已有的标注配置（请先创建；参阅 arize-annotation 技能），且值必须符合其类型：categorical → label（配置中的某个值，不填写 score）、continuous → score、freeform → text。

ax experiments annotate-runs NAME_OR_ID --file annotations.json --dataset DATASET_NAME --space SPACE
ax experiments annotate-runs NAME_OR_ID --file annotations.csv --dataset DATASET_NAME --space SPACE

标注文件架构

一个 JSON 数组；每一项为一次运行添加标注：

[
  {
    "record_id": "run_001",
    "values": [
      { "name": "correctness", "label": "correct" },
      { "name": "relevance", "score": 0.95 }
    ]
  }
]

字段	类型	必填	描述
record_id	string	是	实验运行 ID（运行的 id，来自 ax experiments export）——不是 example_id
values	array	是	一个或多个标注字典，每个字典都包含 name，以及 score、label 或 text 中至少一项
values[].name	string	是	已有标注配置的名称（例如 correctness）——将成为 UI 中的列
values[].score	number	否	用于连续型配置
values[].label	string	否	用于分类配置；必须是配置中的某个值
values[].text	string	否	用于自由文本配置

record_id 使用运行 ID；该 ID 只有在执行 create 后才会存在。因此，顺序始终是：create → export（读取每次运行的 id）→ 构建标注 → annotate-runs。

标志：ax experiments annotate-runs --help。

实验运行架构

每次运行对应一个数据集示例。执行 create 时，只会使用 example_id 和 output；其他任何内容（例如 metadata）都会作为透传字段存储。关于 export 返回的内容，请参阅导出实验。

{
  "example_id": "required -- the dataset example's top-level id",
  "output": "required -- the model/system output for this example",
  "metadata": { "model": "gpt-4o", "latency_ms": 1234 }
}

工作流

针对数据集运行实验

1. 查找或创建数据集：

   ax datasets list --space SPACE
   ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'
   

2. 导出数据集示例：

   ax datasets export DATASET_NAME --space SPACE
   

3. 为每个示例调用真实模型 API 并收集输出。使用 ax datasets export --stdout 将示例直接通过管道传入推理脚本：

   ax datasets export DATASET_NAME --space SPACE --stdout | python3 infer.py > runs.json
   

   编写 infer.py，从 stdin 读取示例，调用目标模型，并将运行结果 JSON 写入 stdout。从 references/inference-template.py 中的模板开始——复制该文件，检查导出的数据集 JSON 以确认输入字段名称，然后取消注释用户所需的提供商代码块。

   **运行前：**安装 SDK，并设置 API 密钥环境变量。如果无法访问 API，请停止并告知用户。

4. 验证运行结果文件：

   python3 -c "import json; runs=json.load(open('runs.json')); print(f'{len(runs)} runs'); print(json.dumps(runs[0], indent=2))"
   

   每次运行都必须包含 example_id（数据集行顶层的 id）和 output。metadata 为可选项。此处不要放入 evaluations——create 会忽略它们；分数需在下方第 7–9 步中附加。

5. 创建实验：

   ax experiments create --name "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE --file runs.json
   

6. 验证：ax experiments get "gpt-4o-baseline" --dataset DATASET_NAME --space SPACE

   附加评估分数（分数要显示在 UI 中，此步骤为必需）。评估结果不会来自创建文件——你需要使用 annotate-runs 附加评估结果。该命令使用每次运行的 id（在创建时分配）作为索引，因此必须先导出，才能获取这些 ID。

7. 将实验导出为结构化数据，以便查看每次运行的 id 及其对应的 example_id。确认导出的运行记录同时包含这两个字段。

8. 使用结构化 JSON 处理方式构建标注文件，并以 record_id（运行的 id）为索引。通过 LLM-as-judge、代码检查或人工审核，对每次运行进行评分或标注；切勿编造分数。首先创建标注配置（此处为分类型 correctness，取值为 correct/incorrect）。输出的格式请参见标注文件架构。

9. 使用 ax experiments annotate-runs ... --file annotations.json 附加分数，然后导出或检查实验，确认评估结果已附加。

比较两个实验

1. 导出两个实验：

   ax experiments export "experiment-a" --dataset DATASET_NAME --space SPACE --stdout > a.json
   ax experiments export "experiment-b" --dataset DATASET_NAME --space SPACE --stdout > b.json
   

   这些示例会读取评估器任务的 correctness 结果（.additional_properties["eval.correctness.score"]）。对于 annotate-runs 的取值，请改用 (.annotations // [] | map(select(.name == "correctness"))[0].score)。
2. 计算正确性分数的平均值（将 a.json 替换为 b.json，以检查另一个实验）：

   jq '[.[] | .additional_properties["eval.correctness.score"]] | add / length' a.json
   

3. 查找结果不同的示例：

   jq -s '.[0] as $a | .[1][] | . as $run | {example_id: $run.example_id, b_score: $run.additional_properties["eval.correctness.score"], a_score: ($a[] | select(.example_id == $run.example_id) | .additional_properties["eval.correctness.score"])}' a.json b.json
   

4. 按评估器统计分数分布（通过／失败／部分通过的数量；检查另一个实验时替换文件）：

   jq '[.[] | .additional_properties["eval.correctness.label"]] | group_by(.) | map({label: .[0], count: length})' a.json
   

5. 查找回归项（在 A 中通过、但在 B 中失败的示例）：

   jq -s '[.[0][] | select(.additional_properties["eval.correctness.label"] == "correct")] as $passed_a | [.[1][] | select(.additional_properties["eval.correctness.label"] != "correct") | select(.example_id as $id | $passed_a | any(.example_id == $id))]' a.json b.json
   

**统计显著性说明：**每个评估器至少有 30 个示例时，结果才较为可靠；少于此数量时，只能将差异视为趋势——n=10 时，5% 的差异可能只是噪声。报告分数时同时给出样本量：jq 'length' a.json。

下载实验结果以供分析

1. ax experiments list --dataset DATASET_NAME --space SPACE -- 查找实验
2. ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE -- 下载到文件
3. 解析：jq '.[] | {example_id, score: .additional_properties["eval.correctness.score"]}' experiment_*/runs.json

将导出结果通过管道传给其他工具

# Count runs
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq 'length'

# Extract all outputs
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[].output'

# Get runs with low scores
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '[.[] | select(.additional_properties["eval.correctness.score"] < 0.5)]'

# Convert to CSV
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq -r '.[] | [.example_id, .output, .additional_properties["eval.correctness.score"]] | @csv'

相关技能

• arize-dataset：创建或导出本实验使用的数据集 → 先使用 arize-dataset
• arize-prompts：在实验前或实验后，将提示词模板存储到 Prompt Hub（ax prompts）并进行版本管理
• arize-prompt-optimization：使用实验结果改进提示词 → 下一步使用 arize-prompt-optimization
• arize-trace：检查实验运行失败时对应的单个 span 跟踪记录 → 使用 arize-trace
• arize-link：为实验运行生成可点击的 UI 跟踪记录链接 → 使用 arize-link

故障排除

问题	解决方案
ax: command not found	请参阅 references/ax-setup.md
401 Unauthorized	API 密钥错误、已过期或无权访问此空间。请使用 references/ax-profiles.md 修复配置文件。
No profile found	尚未配置配置文件。请参阅 references/ax-profiles.md 创建配置文件。
Experiment not found	使用 ax experiments get NAME --dataset DATASET --space SPACE 检查（如果是独立实验，则省略 --dataset）
Invalid runs file	每次运行都必须包含 example_id 和 output 字段
example_id mismatch	example_id 必须是数据集行的 ax datasets export 导出的顶层 id，而不是示例字段或 additional_properties 中嵌套的值。导出数据集并检查顶层 id 字段。
已创建运行，但 UI 中没有分数 / 评估结果	创建文件中的评估结果会被静默忽略。创建实验后，使用 ax experiments annotate-runs 添加评估结果（以运行的 id 为键）——请参阅工作流步骤 7–9。
annotate-runs 报告成功，但没有任何变化	record_id 必须是运行的 id（来自 ax experiments export），而不是 example_id。不匹配的记录 ID 会被静默忽略。
annotate-runs：no annotation config with name '...'	请先创建配置（参阅 arize-annotation 技能）；name 必须与之完全匹配。
annotate-runs：score must not be set 或 label '...' is not one of	值与配置类型不符：类别型配置使用取自其值的 label，连续型配置使用 score，自由格式配置使用 text。
No runs found	导出结果为空——请使用 ax experiments get 确认实验中是否有运行
Dataset not found	关联的数据集可能已被删除；请使用 ax datasets get NAME --space SPACE 检查

保存凭据以供将来使用

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