arize-experiment

Arize Experiment スキル

SPACE — すべての --space フラグと ARIZE_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 に案内してください
• スペースが不明 → ax spaces list を実行して名前で選ぶか、ユーザーに尋ねてください
• プロジェクトが不明確 → ユーザーに尋ねるか、ax projects list -o json --limit 100 を実行し、選択肢として提示してください
• セキュリティ： .env ファイルを読み取ったり、ファイルシステムを検索して認証情報を探したりしないでください。Arize の認証情報には ax profiles を、LLM プロバイダーのキーには ax ai-integrations を使用してください。これらの方法で認証情報を利用できない場合は、ユーザーに尋ねてください。
• 重大 — 出力を捏造しないでください： 実験を実行する際は、データセットの各サンプルについて、ユーザーが指定した実際のモデル 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

フラグ

フラグ	型	デフォルト	説明
--dataset	string	none	データセットで絞り込みます
--limit, -l	int	15	最大結果数（1～100）
--cursor	string	none	前回の応答から取得したページネーションカーソル
-o, --output	string	table	出力形式：table、json、csv、parquet、またはファイルパス
-p, --profile	string	default	設定プロファイル

実験の取得：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（実験名を使う場合は必須）
--space	string	none	スペース名または ID（データセット名を使う場合は必須）
-o, --output	string	table	出力形式
-p, --profile	string	default	設定プロファイル

応答フィールド

フィールド	型	説明
id	string	実験 ID
name	string	実験名
dataset_id	string	関連付けられたデータセット ID
dataset_version_id	string	使用された特定のデータセットバージョン
experiment_traces_project_id	string	実験トレースが保存されるプロジェクト
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 を標準出力に表示します
-p, --profile	string	default	設定プロファイル

REST と Flight の比較（--all）

• REST（デフォルト）：手軽に利用できます。Arrow／Flight の依存関係が不要で、標準の HTTPS ポートを使用し、あらゆる企業プロキシやファイアウォールを経由して動作します。1 ページあたり最大 500 件の実行に制限されます。
• Flight（--all）：実行数が 500 件を超える実験に必要です。別のホスト／ポート（flight.arize.com:443）で gRPC+TLS を使用するため、一部の企業ネットワークではブロックされる場合があります。

エージェントの自動エスカレーションルール： 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	いいえ	設定プロファイル

標準入力からデータを渡す

--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	設定プロファイル

実験実行のスキーマ

各実行は、1 つのデータセット例に対応します。

{
  "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 つ以上を指定してください。

ワークフロー

データセットに対して実験を実行する

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
   

   標準入力からサンプルを読み込み、対象モデルを呼び出して、runs JSON を標準出力に書き込む infer.py を作成します。以下のスクリプトはテンプレートです。まず、エクスポートしたデータセット JSON を確認して正しい入力フィールド名を見つけてから、使用するプロバイダーのブロックのコメントを解除します：

   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)
   

   実行前に： プロバイダーの SDK（pip install openai／anthropic／google-genai）をインストールし、API キーがシェルの環境変数として設定されていることを確認してください。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

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
   

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. 評価者ごとのスコア分布（合格／不合格／一部合格の件数）：

   # 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
   

統計的有意性に関する注意： スコアの比較は、評価者あたり 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：実験で失敗した run の個別のスパントレースを調べます → arize-trace を使用します
• arize-link：実験の run からトレースへのクリック可能な 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 list --space SPACE で実験名を確認してください
Invalid runs file	各 run に example_id と output フィールドが必要です
example_id mismatch	example_id の値がデータセットの ID と一致していることを確認してください（データセットをエクスポートして検証します）
No runs found	エクスポート結果が空です。ax experiments get で実験に run があることを確認してください
Dataset not found	リンクされたデータセットが削除された可能性があります。ax datasets list で確認してください

認証情報を保存して今後も使用する

references/ax-profiles.md § 認証情報を保存して今後も使用する を参照してください。