arize-experiment

Arize Experiment Skill

SPACE — --space フラグには、スペースの名前（例：my-workspace）または base64 形式のスペース ID（例：U3BhY2U6...）を指定します。ax spaces list で確認できます。

概念

• Experiment = 特定のデータセットバージョンに対する、名前付きの評価実行です。各サンプルにつき 1 つの実行が含まれます
• Experiment Run = データセットの 1 つのサンプルを処理した結果です。モデル出力、任意の評価、任意のメタデータが含まれます
• Dataset = バージョン管理されたサンプルのコレクションです。すべての実験は、データセットと特定のデータセットバージョンに紐づいています
• Evaluation = 実行に関連付けられた名前付きのメトリクス（例：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 を参照）。Arize の認証情報には ax profiles を、LLM プロバイダーのキーには ax ai-integrations を使用してください。チャットに秘密情報を貼り付けるようユーザーに求めないでください。認証情報がない場合は、references/ax-profiles.md を参照してください。
• 重大 — 出力を決して捏造しないでください： 実験を実行する際は、データセットのすべてのサンプルについて、ユーザーが指定した実際のモデル API を呼び出す必要があります。モデルの出力、レイテンシ、評価スコアを捏造、シミュレーション、ハードコードしてはいけません。API を呼び出せない場合（SDK がない、認証情報がない、ネットワークエラーなど）は、そこで停止し、先に進むために必要なものをユーザーに伝えてください。

実験の一覧表示：ax experiments list

実験を参照します。データセットで絞り込むこともできます。出力は標準出力に書き込まれます。

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	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]'

フラグ：ax experiments export --help。

REST と Flight（--all）

• REST（デフォルト）：手間が少なく、Arrow／Flight への依存がなく、標準の HTTPS ポートを使用するため、あらゆる企業プロキシやファイアウォールを通過できます。1 ページあたりの実行数は 500 件までです。
• Flight（--all）：実行数が 500 件を超える実験で必要です。一部の企業ネットワークでブロックされる可能性のある、別のホスト／ポートで gRPC+TLS を使用します。有効な ax プロファイルからリージョンのエンドポイントが提供されます。プロファイルの設定を参照してください。

エージェントの自動エスカレーションルール： 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 ファイル内のインライン評価はスコアとして紐付けられません。 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 には、JSON にシリアライズ可能な値を返すトップレベルの task(dataset_row) 関数を定義する必要があります。

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 を使用します。これはプラットフォーム側の run_experiment タスクを登録し、ローカルコードではなく JSON の --run-configuration（モデル＋メッセージ＋AI 連携）に基づいて、Arize がスケジュールまたはオンデマンドで実行します。ローカル／単発の実行やカスタムロジックには 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 から評価を付与することはできません。「実験を作成」の警告を参照してください。実験の作成後に、ここで評価を記述します。アップサート方式のため、同じ実行に対して同じアノテーションの name を再送信すると、以前の値が上書きされます。1 リクエストにつき最大 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 配列です。各項目で 1 つの実行にアノテーションを付与します。

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

フィールド	型	必須	説明
record_id	string	はい	実験の実行 ID（ax experiments export に含まれる実行の id）です。example_id ではありません
values	array	はい	1 つ以上のアノテーション辞書です。各辞書には name と、score、label、text のいずれか 1 つ以上が必要です
values[].name	string	はい	既存のアノテーション設定の名前（例：correctness）です。UI の列名になります
values[].score	number	いいえ	continuous 設定用です
values[].label	string	いいえ	categorical 設定用です。設定値のいずれかである必要があります
values[].text	string	いいえ	freeform 設定用です

record_id には実行の ID を指定します。この ID は create の後にのみ存在します。そのため、手順は必ず create → export（各実行の id を読み取る）→ アノテーションを作成 → annotate-runs の順になります。

フラグ：ax experiments annotate-runs --help。

実験実行のスキーマ

各実行は、データセットの 1 つの例に対応します。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 を作成し、標準入力から例を読み込み、対象モデルを呼び出して、実行結果を JSON 形式で標準出力に書き込みます。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 にスコアを表示するには必須）。 評価は create のファイルからは取得されません。annotate-runs を使って追加します。このコマンドは各実行結果の id（作成時に割り当てられます）をキーにするため、これらの ID を把握するには、まずエクスポートする必要があります。

7. 実験を構造化データとしてエクスポートし、各実行結果の id と example_id を確認できるようにします。エクスポートした実行結果のレコードに両方のフィールドが含まれていることを確認してください。

8. 構造化 JSON を使って、record_id（実行結果の id）をキーとするアノテーションファイルを作成します。LLM-as-judge、コードチェック、または人間によるレビューで各実行結果を採点・ラベル付けします。スコアを捏造しないでください。まずアノテーション設定を作成します（ここでは、値が correct／incorrect のカテゴリ型 correctness）。アノテーションファイルのスキーマ に示されている形式で出力してください。

9. ax experiments annotate-runs ... --file annotations.json でスコアを追加し、その後、実験をエクスポートまたは確認して、評価が追加されていることを確認します。

2 つの実験を比較する

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 件以上の例がある場合は信頼性があります。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：実験で失敗した実行結果の個々のスパントレースを調べます → 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	各 run にはexample_idとoutputフィールドが必要です
example_id mismatch	example_idには、ax datasets exportのデータセット行にある**トップレベルのid**を指定する必要があります。例のフィールドやadditional_properties内にネストされた値ではありません。データセットをエクスポートし、トップレベルのidフィールドを確認してください。
Runs は作成されたが、UI にスコア／評価が表示されない	作成ファイル内の評価は無視されます。実験の作成後、ax experiments annotate-runsで（runのidをキーとして）追加してください。ワークフローの手順7〜9を参照してください。
annotate-runsは成功を報告するが、何も変わらない	record_idにはexample_idではなく、（ax experiments exportで取得できる）**runの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で実験にrunがあることを確認してください
Dataset not found	リンクされたデータセットが削除された可能性があります。ax datasets get NAME --space SPACEで確認してください

今後使用するための認証情報の保存

references/ax-profiles.mdの「今後使用するための認証情報の保存」セクションを参照してください。