arize-experiment

Arize 实验 Skill

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

概念

• Experiment（实验） = 针对特定数据集版本的一次命名评估运行，每个示例对应一次 run
• Experiment Run（实验运行） = 处理一个数据集示例的结果——包括模型输出、可选的评估结果和可选的元数据
• Dataset（数据集） = 带版本的示例集合；每个实验都绑定到一个数据集和一个特定的数据集版本
• Evaluation（评估） = 附加到某次 run 上的命名指标（例如 correctness、relevance），可带可选的标签、分数和说明

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

前置条件

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

如果 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 按名称选择，或询问用户
• Project 不明确 → 询问用户，或运行 ax projects list -o json --limit 100 并以可选项形式呈现
• 安全： 切勿读取 .env 文件或在文件系统中搜索凭据。Arize 凭据请使用 ax profiles，LLM 提供商密钥请使用 ax ai-integrations。如果通过这些渠道无法获取凭据，请询问用户。
• 关键——切勿捏造输出： 运行实验时，你必须为每个数据集示例调用用户指定的真实模型 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

标志

标志	类型	默认值	描述
--dataset	string	none	按数据集筛选
--limit, -l	int	15	最大结果数（1-100）
--cursor	string	none	来自上一次响应的分页游标
-o, --output	string	table	输出格式：table、json、csv、parquet 或文件路径
-p, --profile	string	default	配置 profile

获取实验：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

标志

标志	类型	默认值	描述
NAME_OR_ID	string	required	实验名称或 ID（位置参数）
--dataset	string	none	数据集名称或 ID（如果使用实验名称而非 ID 则必填）
--space	string	none	Space 名称或 ID（如果使用数据集名称而非 ID 则必填）
-o, --output	string	table	输出格式
-p, --profile	string	default	配置 profile

响应字段

字段	类型	描述
id	string	实验 ID
name	string	实验名称
dataset_id	string	关联的数据集 ID
dataset_version_id	string	使用的具体数据集版本
experiment_traces_project_id	string	存储实验 trace 的 Project
created_at	datetime	实验创建时间
updated_at	datetime	最后修改时间

导出实验：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]'

标志

标志	类型	默认值	描述
NAME_OR_ID	string	必填	实验名称或 ID（位置参数）
--dataset	string	无	数据集名称或 ID（如果使用实验名称而非 ID 则为必填）
--space	string	无	空间名称或 ID（如果使用数据集名称而非 ID 则为必填）
--all	bool	false	使用 Arrow Flight 进行批量导出（见下文）
--output-dir	string	.	输出目录
--stdout	bool	false	将 JSON 打印到 stdout 而非文件
-p, --profile	string	default	配置配置文件

REST vs Flight（--all）

• REST（默认）：阻力更小——没有 Arrow/Flight 依赖，使用标准 HTTPS 端口，可透过任何企业代理或防火墙。每页限制为 500 条运行。
• Flight（--all）：运行数超过 500 的实验必须使用。在单独的主机/端口（flight.arize.com:443）上使用 gRPC+TLS，某些企业网络可能会阻止。

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

输出是运行对象的 JSON 数组：

[
  {
    "id": "run_001",
    "example_id": "ex_001",
    "output": "The answer is 4.",
    "evaluations": {
      "correctness": { "label": "correct", "score": 1.0 },
      "relevance": { "score": 0.95, "explanation": "Directly answers the question" }
    },
    "metadata": { "model": "gpt-4o", "latency_ms": 1234 }
  }
]

创建实验：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

标志

标志	类型	必填	描述
--name, -n	string	是	实验名称
--dataset	string	是	用于运行实验的数据集
--space, -s	string	否	空间名称或 ID（如果使用数据集名称而非 ID 则为必填）
--file, -f	path	是	包含运行的数据文件：CSV、JSON、JSONL 或 Parquet
-o, --output	string	否	输出格式
-p, --profile	string	否	配置配置文件

通过 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	string	是	此运行对应的数据集示例的 ID
output	string	是	此示例的模型/系统输出

其他列会作为运行上的 additionalProperties 传递。

删除实验：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

标志

标志	类型	默认值	描述
NAME_OR_ID	string	必填	实验名称或 ID（位置参数）
--dataset	string	无	数据集名称或 ID（如果使用实验名称而非 ID 则为必填）
--space	string	无	空间名称或 ID（如果使用数据集名称而非 ID 则为必填）
--force, -f	bool	false	跳过确认提示
-p, --profile	string	default	配置配置文件

实验运行模式

每个运行对应一个数据集示例：

{
  "example_id": "required -- links to dataset example",
  "output": "required -- the model/system output for this example",
  "evaluations": {
    "metric_name": {
      "label": "optional string label (e.g., 'correct', 'incorrect')",
      "score": "optional numeric score (e.g., 0.95)",
      "explanation": "optional freeform text"
    }
  },
  "metadata": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "latency_ms": 1234
  }
}

评估字段

字段	类型	必填	描述
label	string	否	分类分类（例如 correct、incorrect、partial）
score	number	否	数值质量分数（例如 0.0 - 1.0）
explanation	string	否	评估的自由形式推理

每次评估中至少应存在 label、score 或 explanation 之一。

工作流

针对数据集运行实验

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 读取示例，调用目标模型，并将 runs JSON 写入 stdout。下面的脚本是一个模板——首先检查导出的数据集 JSON 以找到正确的输入字段名，然后取消注释用户想要的 provider 代码块：

   import json, sys, time
   
   examples = json.load(sys.stdin)
   runs = []
   
   for ex in examples:
       # Inspect the exported JSON to find the right field (e.g. "input", "question", "prompt")
       user_input = ex.get("input") or ex.get("question") or ex.get("prompt") or str(ex)
   
       start = time.time()
   
       # === CALL THE REAL MODEL API HERE — never fabricate or simulate ===
       # Uncomment and adapt the provider block the user requested:
       #
       # OpenAI (pip install openai  — uses OPENAI_API_KEY env var):
       #   from openai import OpenAI
       #   resp = OpenAI().chat.completions.create(
       #       model="gpt-4o",
       #       messages=[{"role": "user", "content": user_input}]
       #   )
       #   output_text = resp.choices[0].message.content
       #
       # Anthropic (pip install anthropic  — uses ANTHROPIC_API_KEY env var):
       #   import anthropic
       #   resp = anthropic.Anthropic().messages.create(
       #       model="claude-sonnet-4-6", max_tokens=1024,
       #       messages=[{"role": "user", "content": user_input}]
       #   )
       #   output_text = resp.content[0].text
       #
       # Google Gemini (pip install google-genai  — uses GOOGLE_API_KEY env var):
       #   from google import genai
       #   resp = genai.Client().models.generate_content(
       #       model="gemini-2.5-pro", contents=user_input
       #   )
       #   output_text = resp.text
       #
       # Custom / OpenAI-compatible proxy (pip install openai — uses CUSTOM_BASE_URL + CUSTOM_API_KEY env vars):
       # Use this for Azure OpenAI, NVIDIA NIM, local Ollama, or any OpenAI-compatible endpoint,
       # including a test integration proxy. Matches the `custom` provider in `ax ai-integrations create`.
       #   import os
       #   from openai import OpenAI
       #   resp = OpenAI(
       #       base_url=os.environ["CUSTOM_BASE_URL"],          # e.g. https://my-proxy.example.com/v1
       #       api_key=os.environ.get("CUSTOM_API_KEY", "none"),
       #   ).chat.completions.create(
       #       model=os.environ.get("CUSTOM_MODEL", "default"),
       #       messages=[{"role": "user", "content": user_input}]
       #   )
       #   output_text = resp.choices[0].message.content
   
       latency_ms = round((time.time() - start) * 1000)
       runs.append({
           "example_id": ex["id"],
           "output": output_text,
           "metadata": {"model": "MODEL_NAME", "latency_ms": latency_ms}
       })
       print(f"  {ex['id']}: {latency_ms}ms", file=sys.stderr)
   
   json.dump(runs, sys.stdout, indent=2)
   

   运行之前： 安装 provider SDK（pip install openai / anthropic / google-genai），并确保 API key 已在 shell 中设置为环境变量。如果你无法访问 API，请停止并告知用户需要什么。

4. 验证 runs 文件：

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

   每个 run 必须包含 example_id 和 output。可选字段：evaluations、metadata。

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

比较两个实验

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
   

2. 按 example_id 比较评估分数：

   # Average correctness score for experiment A
   jq '[.[] | .evaluations.correctness.score] | add / length' a.json
   
   # Same for experiment B
   jq '[.[] | .evaluations.correctness.score] | add / length' b.json
   

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

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

4. 每个 evaluator 的分数分布（pass/fail/partial 计数）：

   # Count by label for experiment A
   jq '[.[] | .evaluations.correctness.label] | group_by(.) | map({label: .[0], count: length})' a.json
   

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

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

统计显著性说明： 每个 evaluator ≥ 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: .evaluations.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(.evaluations.correctness.score < 0.5)]'

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

相关技能

• arize-dataset：创建或导出此实验所针对的数据集 → 首先使用 arize-dataset
• arize-prompt-optimization：使用实验结果改进提示词 → 下一步是 arize-prompt-optimization
• arize-trace：检查失败实验运行的单个 span trace → 使用 arize-trace
• arize-link：从实验运行生成指向 trace 的可点击 UI 链接 → 使用 arize-link

故障排除

问题	解决方案
ax: command not found	参见 references/ax-setup.md
401 Unauthorized	API key 错误、已过期，或无权访问此 space。使用 references/ax-profiles.md 修复该 profile。
No profile found	未配置 profile。参见 references/ax-profiles.md 创建一个。
Experiment not found	使用 ax experiments list --space SPACE 验证实验名称
Invalid runs file	每个 run 必须包含 example_id 和 output 字段
example_id mismatch	确保 example_id 值与数据集中的 ID 匹配（导出数据集以验证）
No runs found	导出返回为空 -- 通过 ax experiments get 验证实验是否有 runs
Dataset not found	链接的数据集可能已被删除；使用 ax datasets list 检查

保存凭据以供将来使用

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