Arize Experiment Skill

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: 名前またはID（名前推奨）
ax experiments list --cursor CURSOR_TOKEN
ax experiments list -o json

フラグ

フラグ	型	デフォルト	説明
--dataset	string	なし	データセットでフィルタリング
--limit, -l	int	15	最大結果数（1-100）
--cursor	string	なし	前回のレスポンスからのページネーションカーソル
-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   # 実験名の代わりにIDを使用する場合は必須

フラグ

フラグ	型	デフォルト	説明
NAME_OR_ID	string	必須	実験名またはID（位置引数）
--dataset	string	なし	データセット名またはID（実験名の代わりにIDを使用する場合は必須）
--space	string	なし	スペース名またはID（データセット名の代わりに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: 名前またはID（名前推奨）
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	yes	実験名
--dataset	string	yes	実験を実行するデータセット
--space, -s	string	no	スペース名またはID（データセット名の代わりにIDを使用する場合は必須）
--file, -f	path	yes	実行を含むデータファイル：CSV、JSON、JSONL、またはParquet
-o, --output	string	no	出力形式
-p, --profile	string	no	設定プロフィール

stdin経由でのデータ渡し

--file - を使用してデータを直接パイプします -- テンポラリファイルは不要：

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

# またはheredocを使用
ax experiments create --name "my-experiment" --dataset DATASET_NAME --space SPACE --file - << 'EOF'
[{"example_id": "ex_001", "output": "Paris"}]
EOF

実行ファイルの必須列

列	型	必須	説明
example_id	string	yes	この実行が対応するデータセット例のID
output	string	yes	この例に対するモデル/システム出力

追加列は実行上の additionalProperties として渡されます。

実験の削除：ax experiments delete

ax experiments delete NAME_OR_ID
ax experiments delete NAME_OR_ID --dataset DATASET_NAME --space SPACE   # 実験名の代わりにIDを使用する場合は必須
ax experiments delete NAME_OR_ID --force   # 確認プロンプトをスキップ

フラグ

フラグ	型	デフォルト	説明
NAME_OR_ID	string	必須	実験名またはID（位置引数）
--dataset	string	なし	データセット名またはID（実験名の代わりにIDを使用する場合は必須）
--space	string	なし	スペース名またはID（データセット名の代わりにIDを使用する場合は必須）
--force, -f	bool	false	確認プロンプトをスキップ
-p, --profile	string	default	設定プロフィール

実験実行スキーマ

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

{
  "example_id": "必須 -- データセット例にリンク",
  "output": "必須 -- この例に対するモデル/システム出力",
  "evaluations": {
    "metric_name": {
      "label": "オプショナル文字列ラベル（例：'correct'、'incorrect'）",
      "score": "オプショナル数値スコア（例：0.95）",
      "explanation": "オプショナルなフリーフォームテキスト"
    }
  },
  "metadata": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "latency_ms": 1234
  }
}

評価フィールド

フィールド	型	必須	説明
label	string	no	分類ラベル（例：correct、incorrect、partial）
score	number	no	数値品質スコア（例：0.0 - 1.0）
explanation	string	no	評価の理由説明

評価ごとに 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
   

   stdin から例を読み込み、ターゲットモデルを呼び出し、実行JSONを stdout に出力する infer.py を作成します。以下のスクリプトはテンプレートです -- 最初にエクスポートされたデータセットJSONを調べて正しい入力フィールド名を見つけ、ユーザーが希望するプロバイダーブロックをアンコメントします：

   import json, sys, time
   
   examples = json.load(sys.stdin)
   runs = []
   
   for ex in examples:
       # エクスポートされたJSONを調べて正しいフィールドを見つけます（例："input"、"question"、"prompt"）
       user_input = ex.get("input") or ex.get("question") or ex.get("prompt") or str(ex)
   
       start = time.time()
   
       # === 実際のモデルAPIをここで呼び出します -- 捏造やシミュレーションはしません ===
       # ユーザーがリクエストしたプロバイダーブロックをアンコメントして調整します：
       #
       # OpenAI (pip install openai  — OPENAI_API_KEY環境変数を使用):
       #   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  — ANTHROPIC_API_KEY環境変数を使用):
       #   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  — GOOGLE_API_KEY環境変数を使用):
       #   from google import genai
       #   resp = genai.Client().models.generate_content(
       #       model="gemini-2.5-pro", contents=user_input
       #   )
       #   output_text = resp.text
       #
       # カスタム / OpenAI互換プロキシ (pip install openai — CUSTOM_BASE_URL + CUSTOM_API_KEY環境変数を使用):
       # これはAzure OpenAI、NVIDIA NIM、ローカルOllama、またはOpenAI互換のエンドポイント（テスト統合プロキシを含む）に使用します。
       # `ax ai-integrations create` の `custom` プロバイダーと一致します。
       #   import os
       #   from openai import OpenAI
       #   resp = OpenAI(
       #       base_url=os.environ["CUSTOM_BASE_URL"],          # 例：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. 実行ファイルを確認します：

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

   各実行は 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 による評価スコアを比較します：

   # 実験AのavErage correctnessスコア
   jq '[.[] | .evaluations.correctness.score] | add / length' a.json
   
   # 実験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. 評価者ごとのスコア分布（パス/フェイル/部分的カウント）：

   # 実験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

エクスポートを他のツールにパイプ

# 実行をカウント
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq 'length'

# すべての出力を抽出
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '.[].output'

# 低スコアの実行を取得
ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | jq '[.[] | select(.evaluations.correctness.score < 0.5)]'

# 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: 失敗した実験実行の個別スパントレースを検査 → 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 list --space SPACE で実験名を確認してください
Invalid runs file	各実行は example_id および output フィールドを持つ必要があります
example_id mismatch	example_id 値がデータセットのIDと一致することを確認してください（確認するためにデータセットをエクスポート）
No runs found	エクスポートが空の結果を返しました -- ax experiments get で実験に実行があることを確認してください
Dataset not found	リンク済みのデータセットが削除されている可能性があります。ax datasets list で確認してください

将来の使用のためにクレデンシャルを保存

references/ax-profiles.md § Save Credentials for Future Use を参照してください。