arize-evaluator

Arize Evaluator Skill

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

このスキルでは、Arize で LLM-as-judge 評価器を設計、作成、実行する方法を扱います。評価器は判定ロジックを定義し、タスクは実際のデータに対して評価器を実行する方法を定義します。

---

前提条件

タスクをそのまま進め、必要な 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 を実行して名前で選ぶか、ユーザーに尋ねてください
• LLM プロバイダーの呼び出しが失敗（OPENAI_API_KEY / ANTHROPIC_API_KEY がない） → ax ai-integrations list --space SPACE を実行し、プラットフォーム管理の認証情報があるか確認してください。ない場合は、キーをユーザーに提供してもらうか、arize-ai-provider-integration スキルを使用してインテグレーションを作成してください
• セキュリティ： .env ファイルを読み取ったり、ファイルシステムを検索して認証情報を探したりしてはいけません。Arize の認証情報には ax profiles を、LLM プロバイダーのキーには ax ai-integrations を使用してください。これらの方法で認証情報を利用できない場合は、ユーザーに尋ねてください。
• 重要 — 評価結果を決して捏造しないでください： 評価タスクが失敗、中止、またはスコアなしで終了した場合は、失敗したことを明確に報告し、原因を説明してください。「手動評価」を行ったり、品質スコアを捏造したり、パーセンテージを推定したり、エージェントが生成した分析を Arize の評価システムによる結果であるかのように示したりしてはいけません。代わりに、次の方法を提案してください：（1）特定された問題を修正して再試行する、（2）Arize UI から実行する、（3）ax ai-integrations list でインテグレーションの認証情報を確認する、（4）https://arize.com/support からサポートに問い合わせる

---

概念

評価器とは？

評価器は、LLM-as-judge の定義です。次の項目が含まれます。

項目	説明
テンプレート	判定用のプロンプトです。{variable} 形式のプレースホルダー（例：{input}、{output}、{context}）を使用し、タスクの列マッピングを通じて実行時に値が設定されます。
分類の選択肢	出力に使用できるラベルの集合（例：factual / hallucinated）です。デフォルトであり、最も一般的なのは二値分類です。各選択肢には、任意で数値スコアを設定できます。
AI インテグレーション	評価器が判定モデルを呼び出すために使用する、保存済みの LLM プロバイダー認証情報（OpenAI、Anthropic、Bedrock など）です。
モデル	使用する特定の判定モデル（例：gpt-4o、claude-sonnet-4-5）です。
呼び出しパラメーター	{"temperature": 0} のようなモデル設定を指定する任意の JSON です。再現性を高めるため、低い温度を推奨します。
最適化の方向	スコアが高いほど良い（maximize）か、悪い（minimize）かを指定します。UI での傾向の表示方法が設定されます。
データ粒度	評価器をスパン、トレース、セッションのどのレベルで実行するかを指定します。ほとんどの評価器はスパンレベルで実行されます。

評価器にはバージョンが付与されます。プロンプトやモデルを変更するたびに、新しい不変のバージョンが作成されます。最新のバージョンが有効になります。

タスクとは？

タスクは、実際のデータに対して1つ以上の評価器を実行する方法です。タスクは、プロジェクト（ライブのトレース／スパン）またはデータセット（実験の実行）に紐づきます。タスクには次の項目が含まれます。

項目	説明
評価器	実行する評価器のリストです。1つのタスクで複数の評価器を実行できます。
列マッピング	各評価器のテンプレート変数を、スパンまたは実験の実行における実際のフィールドパスに対応付けます（例："input" → "attributes.input.value"）。これにより、評価器をプロジェクト間や実験間で移植できます。
クエリフィルター	評価対象のスパン／実行を選択する SQL 形式の式です（例："span_kind = 'LLM'"）。省略可能ですが、精度を高めるうえで重要です。
継続実行	プロジェクトのタスクの場合、新しいスパンが到着したときに自動でスコアを付けるかどうかを指定します。
サンプリング率	継続実行するプロジェクトのタスクの場合、評価対象とする新しいスパンの割合（0～1）です。

---

データの粒度

--data-granularity フラグは、評価器がスコアを付けるデータの単位を制御します。デフォルトは span で、プロジェクトのタスクにのみ適用されます（データセット／実験のタスクには適用されず、これらは実験の実行を直接評価します）。

レベル	評価対象	用途	結果列のプレフィックス
span（デフォルト）	個々のスパン	質疑応答の正確性、ハルシネーション、関連性	eval.{name}.label / .score / .explanation
trace	context.trace_id ごとにグループ化した、トレース内のすべてのスパン	エージェントの軌跡、タスクの正確性 — 呼び出しチェーン全体が必要なあらゆるもの	trace_eval.{name}.label / .score / .explanation
session	attributes.session.id ごとにグループ化し、開始時刻順に並べた、セッション内のすべてのトレース	複数ターンの一貫性、全体的なトーン、会話の品質	session_eval.{name}.label / .score / .explanation

トレースおよびセッションの集約方法

トレース粒度では、同じ context.trace_id を持つスパンがまとめてグループ化されます。評価器テンプレートで使用する列の値は、判定モデルに渡す前に、カンマで連結して1つの文字列にします（各値の長さは100K文字に切り詰められます）。

セッション粒度では、まず同じ方法でトレースレベルのグループ化を行い、その後、トレースを start_time 順に並べて attributes.session.id ごとにグループ化します。セッションレベルの値は、合計で100K文字までに制限されます。

{conversation} テンプレート変数

セッション粒度では、{conversation} は特別なテンプレート変数です。セッション内のすべてのトレースについて、attributes.input.value / attributes.llm.input_messages（入力側）と attributes.output.value / attributes.llm.output_messages（出力側）から作成した {input, output} ターンの JSON 配列として展開されます。

スパンまたはトレース粒度では、{conversation} は通常のテンプレート変数として扱われ、他の変数と同様に列マッピングで解決されます。

複数の評価器を含むタスク

1つのタスクに、異なる粒度の評価器を含めることができます。実行時には、データ取得に最も高い粒度（session > trace > span）が使われ、評価器ごとに子ランが自動的に分割されます。タスクの評価器 JSON にある評価器ごとの query_filter によって、対象に含めるスパンをさらに絞り込めます（例：セッション内のツール呼び出しスパンのみ）。

---

基本的な CRUD

AI インテグレーション

AI インテグレーションには、評価器が使用する LLM プロバイダーの認証情報が保存されます。すべてのプロバイダー（OpenAI、Anthropic、Azure、Bedrock、Vertex、Gemini、NVIDIA NIM、カスタム）について、CRUD 操作（一覧表示、作成、更新、削除）を行う方法は、arize-ai-provider-integration スキルを使用してください。

一般的なケース（OpenAI）のクイックリファレンス：

# Check for an existing integration first
ax ai-integrations list --space SPACE

# Create if none exists
ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider openAI \
  --api-key $OPENAI_API_KEY

返されたインテグレーション ID をコピーしてください。ax evaluators create --ai-integration-id に必要です。

評価器

# List / Get
ax evaluators list --space SPACE
ax evaluators get ID                    # accepts name or ID
ax evaluators get NAME --space SPACE   # required when using name instead of ID
ax evaluators list-versions NAME_OR_ID
ax evaluators get-version VERSION_ID

# Create (creates the evaluator and its first version)
ax evaluators create \
  --name "Answer Correctness" \
  --space SPACE \
  --description "Judges if the model answer is correct" \
  --template-name "correctness" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response correctly answers the question.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: correct, incorrect'

# Create a new version (for prompt or model changes — versions are immutable)
ax evaluators create-version NAME_OR_ID \
  --commit-message "Added context grounding" \
  --template-name "correctness" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --classification-choices '{"correct": 1, "incorrect": 0}' \
  --template 'Updated prompt...

{input} / {output} / {context}'

# Update metadata only (name, description — not prompt)
ax evaluators update NAME_OR_ID \
  --name "New Name" \
  --description "Updated description"

# Delete (permanent — removes all versions)
ax evaluators delete NAME_OR_ID

create の主なフラグ：

フラグ	必須	説明
--name	はい	評価器名（スペース内で一意）
--space	はい	作成先のスペース名または ID
--template-name	はい	評価列名 — 英数字、スペース、ハイフン、アンダースコアを使用できます
--commit-message	はい	このバージョンの説明
--ai-integration-id	はい	AI インテグレーション ID（上記を参照）
--model-name	はい	判定モデル（例：gpt-4o）
--template	はい	{variable} プレースホルダーを含むプロンプト（bash ではシングルクォートで囲みます）
--classification-choices	はい	選択肢ラベルと数値スコアの対応を示す JSON オブジェクト。例：'{"correct": 1, "incorrect": 0}'
--description	いいえ	人が読める説明
--include-explanations	いいえ	ラベルに加えて推論も含めます
--use-function-calling	いいえ	構造化された関数呼び出し形式の出力を優先します
--invocation-params	いいえ	モデルパラメーターの JSON。例：'{"temperature": 0}'
--data-granularity	いいえ	span（デフォルト）、trace、または session。プロジェクトタスクにのみ関連し、データセット／実験タスクには関係ありません。「データ粒度」セクションを参照してください。
--direction	いいえ	最適化の方向：maximize または minimize。UI での傾向の表示方法を設定します。
--provider-params	いいえ	プロバイダー固有のパラメーターを指定する JSON オブジェクト

タスク

PROJECT_NAME、DATASET_NAME、evaluator_id は、いずれも名前または base64 ID を指定できます。

# List / Get
ax tasks list --space SPACE
ax tasks list --project PROJECT_NAME
ax tasks list --dataset DATASET_NAME --space SPACE
ax tasks get TASK_ID

# Create (project — continuous)
ax tasks create \
  --name "Correctness Monitor" \
  --task-type template_evaluation \
  --project PROJECT_NAME \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

# Create (project — one-time / backfill)
ax tasks create \
  --name "Correctness Backfill" \
  --task-type template_evaluation \
  --project PROJECT_NAME \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

# Create (experiment / dataset)
ax tasks create \
  --name "Experiment Scoring" \
  --task-type template_evaluation \
  --dataset DATASET_NAME --space SPACE \
  --experiment-ids "EXP_ID_1,EXP_ID_2" \   # base64 IDs from `ax experiments list --space SPACE -o json`
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

# Trigger a run (project task — use data window)
ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --wait

# Trigger a run (experiment task — use experiment IDs)
ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID_1" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --wait

# Monitor
ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID
ax tasks wait-for-run RUN_ID --timeout 300
ax tasks cancel-run RUN_ID --force

trigger-run の時刻形式： 2026-03-21T09:00:00 — 末尾に Z は付けません。

trigger-run の追加フラグ：

フラグ	説明
--max-spans	処理する span の上限（デフォルトは 10,000）
--override-evaluations	すでにラベルが付いている span を再採点します
--wait / -w	実行が完了するまで待機します
--timeout	--wait を指定した場合の待機時間（秒、デフォルトは 600）
--poll-interval	待機中のポーリング間隔（秒、デフォルトは 5）

実行ステータスのガイド：

ステータス	意味
completed、0 spans	評価インデックスには 1～2 時間の遅延があります。最近取り込まれた span はまだインデックスに登録されていない可能性があります。少なくとも 2 時間前のデータに対象期間をずらすか、期間を広げて過去のデータをより多く含めてください。
cancelled ~1s	インテグレーションの認証情報が無効です
cancelled ~3min	span は見つかりましたが、LLM の呼び出しに失敗しました — モデル名またはキーを確認してください
completed、N > 0	成功 — UI でスコアを確認してください

---

ワークフロー A：プロジェクト用の評価器を作成する

ユーザーが 「Playground Traces プロジェクト用の評価器を作成して」 のように依頼した場合に使用します。

ステップ 1：プロジェクト名を確認する

ax spans export ではプロジェクト名を直接指定できるため、ID の検索は不要です。プロジェクト名がわからない場合は、利用可能なプロジェクトを一覧表示します。

ax projects list --space SPACE -o json

"name" が一致するエントリ（大文字と小文字は区別しません）を見つけ、その名前を以降のコマンドで PROJECT として使用します。名前を指定して検証エラーが発生した場合は、代わりにプロジェクトの "id"（base64 文字列）を使用してください。

ステップ 2：評価対象を把握する

ユーザーが評価器の種類（ハルシネーション、正確性、関連性など）を指定している場合 → ステップ 3 に進みます。

指定されていない場合は、実際のデータに基づいて評価器を作成できるよう、最近の span をサンプリングします。

ax spans export PROJECT --space SPACE -l 10 --days 30 --stdout

attributes.input、attributes.output、span の種類、および既存のアノテーションを確認します。失敗のパターン（例：事実の捏造、話題から外れた回答、コンテキストの不足）を特定し、具体的な評価器の案を 1～3 個提示します。ユーザーに選んでもらいます。

各案には、評価器名（太字）、評価対象の一文での説明、二値ラベルのペア（括弧内）を含めます。次の形式で記述します。

1. 名前 — 評価対象の説明。(label_a / label_b)

例：

1. 回答の正確性 — エージェントの回答は、ユーザーの金融に関する質問に正しく答えていますか？（correct / incorrect）
2. ハルシネーション — 回答は、検索されたコンテキストに根拠のない事実を捏造していますか？（factual / hallucinated）

Step 3: AI インテグレーションを確認または作成する

ax ai-integrations list --space SPACE -o json

適切なインテグレーションがある場合は、その ID を控えます。ない場合は、arize-ai-provider-integration スキルを使用して作成します。ジャッジに使用するプロバイダー／モデルをユーザーに尋ねます。

Step 4: 評価器を作成する

以下のテンプレート設計のベストプラクティスを使用します。評価器名と変数は汎用的なものにしてください。プロジェクト固有の接続は、タスク（Step 6）で column_mappings を使用して行います。

ax evaluators create \
  --name "Hallucination" \
  --space SPACE \
  --template-name "hallucination" \
  --commit-message "Initial version" \
  --ai-integration-id INT_ID \
  --model-name "gpt-4o" \
  --include-explanations \
  --use-function-calling \
  --classification-choices '{"factual": 1, "hallucinated": 0}' \
  --template 'You are an evaluator. Given the user question and the model response, decide if the response is factual or contains unsupported claims.

User question: {input}

Model response: {output}

Respond with exactly one of these labels: hallucinated, factual'

Step 5: バックフィル、継続評価、または両方を確認する

推奨する方法： 評価器を有効にして継続的なモニタリングを始める前に、まず少量のバックフィル（過去のスパン約100件）を必ず実行し、評価器を検証してください。これにより、すべての本番スパンをスコアリングする前に、既知のデータでカラムマッピングのエラー、誤ったスパン種別、テンプレートの問題を確認できます。バックフィルで正しくスコアリングされることを確認してから、継続評価を有効にしてください。

タスクを作成する前に、次のように尋ねます。

「次のどれを行いますか？ (a) 過去のスパンに対してバックフィルを実行する（一度限り）。 (b) 今後の新しいスパンに対して継続評価を設定する。 (c) 両方 — まずバックフィルで検証してから、新しいスパンを自動的にスコアリングし続ける。（推奨）」

Step 6: 実際のスパンデータからカラムマッピングを決定する

パスを推測しないでください。サンプルを取得し、実際にどのフィールドが存在するかを確認します。

ax spans export PROJECT --space SPACE -l 5 --days 7 --stdout

各テンプレート変数（{input}、{output}、{context}）について、対応する JSON パスを見つけます。よくある開始点は次のとおりですが、使用前に必ず実際のデータで確認してください。

テンプレート変数	LLM スパン	CHAIN スパン
input	attributes.input.value	attributes.input.value
output	attributes.llm.output_messages.0.message.content	attributes.output.value
context	attributes.retrieval.documents.contents	—
tool_output	attributes.input.value（フォールバック）	attributes.output.value

スパン種別の整合性を検証する： 評価器のプロンプトが LLM の最終テキストを想定しているのに、タスクが CHAIN スパン（またはその逆）を対象としていると、実行がキャンセルされたり、誤ったテキストがスコアリングされたりすることがあります。タスクの query_filter が、マッピングしたスパン種別と一致することを確認してください。

query_filter はインデックス化された属性でのみ機能します： evaluators JSON の query_filter は、生のスパンストアではなく評価インデックスに対して評価されます。attributes.metadata.* 配下の属性やカスタムキーはインデックス化されていないことがあり、その場合は何も一致しなくても警告なしで処理されます。フィルタリングには、span_kind や attributes.llm.model_name など、よく知られたインデックス化済み属性を使用してください。データが存在するのにフィルタでスパンが0件になる場合は、診断としてフィルタを削除してみてください。

--evaluators JSON の完全な例：

[
  {
    "evaluator_id": "EVAL_ID",
    "query_filter": "span_kind = 'LLM'",
    "column_mappings": {
      "input": "attributes.input.value",
      "output": "attributes.llm.output_messages.0.message.content",
      "context": "attributes.retrieval.documents.contents"
    }
  }
]

テンプレートで参照されているすべての変数にマッピングを指定してください。1つでも省略すると、実行で有効なスコアが生成されません。

Step 7: タスクを作成する

バックフィルのみ（a）：

ax tasks create \
  --name "Hallucination Backfill" \
  --task-type template_evaluation \
  --project PROJECT \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --no-continuous

継続評価のみ（b）：

ax tasks create \
  --name "Hallucination Monitor" \
  --task-type template_evaluation \
  --project PROJECT \
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"input": "attributes.input.value", "output": "attributes.output.value"}}]' \
  --is-continuous \
  --sampling-rate 0.1

両方（c）： 作成時に --is-continuous を使用し、さらに Step 8 でバックフィルの実行を開始します。

Step 8: バックフィルの実行を開始する（リクエストされた場合）

評価インデックスの遅延： 評価インデックスはプライマリトレースストアから非同期で構築されるため、1～2時間遅れることがあります。初回のテスト実行では、少なくとも2時間前までの時間範囲を指定してください。直近1時間以内に取り込まれたスパンに対して --data-end-time を「now」に設定すると、実行は正常に完了しても、スコアリングされるスパンは0件になります。

まず、データが存在する時間範囲を確認します。

ax spans export PROJECT --space SPACE -l 100 --days 1 --stdout   # try last 24h first
ax spans export PROJECT --space SPACE -l 100 --days 7 --stdout   # widen if empty

実際のスパンの start_time／end_time フィールドを使用して、時間範囲を設定します。最初の検証実行では、すばやく結果を確認できるよう --max-spans を約100に制限します。

ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --max-spans 100 \
  --wait

バックフィルの対象を全範囲に広げる前、または継続評価を有効にする前に、スコアと説明を確認してください。

---

ワークフロー B：実験用の評価器を作成する

ユーザーが 「実験用の評価器を作成して」 や 「データセットの実行結果を評価して」 のように依頼した場合に使用します。

ユーザーが「データセット」と言っていても、実験がない場合： タスクの対象には実験が必要です（データセット単体では対象にできません）。次のように尋ねてください。

「評価タスクはデータセットに対して直接ではなく、実験の実行結果に対して実行します。まず、そのデータセットで実験を作成しましょうか？」

はいの場合は、arize-experiment スキルを使用して実験を作成し、ここに戻ります。

ステップ 1：データセット名と実験名を確認する

ax datasets list --space SPACE
ax experiments list --dataset DATASET_NAME --space SPACE -o json

データセット名と、スコアを付ける実験名（複数可）をメモします。以降のコマンドでは名前または ID を指定できますが、名前を推奨します。

ステップ 2：評価対象を把握する

ユーザーが評価器の種類を指定している場合 → ステップ 3 に進みます。

指定されていない場合は、最近の実験実行を調べ、実際のデータに基づいて評価器を作成します。

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

output、input、evaluations、metadata フィールドを確認します。ユーザーが重視しているものの、まだ含まれていない指標を特定し、1～3 個の評価器の案を提示します。各案には、評価器の名前（太字）、1 文の説明、括弧内の二値ラベルのペアを含めます。形式はワークフロー A のステップ 2 と同じです。

ステップ 3：AI インテグレーションを確認または作成する

ワークフロー A のステップ 3 と同じです。

ステップ 4：評価器を作成する

ワークフロー A のステップ 4 と同じです。変数名は汎用的なものにします。

ステップ 5：実際の実行データから列のマッピングを決定する

実行データの形状はスパンデータとは異なります。次を確認します。

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2))"

実験の実行結果に対する一般的なマッピング：

• output → "output"（各実行のトップレベルフィールド）
• input → 実行結果にあるか、リンク先のデータセットの例に埋め込まれているかを確認します

input が実行結果の JSON にない場合は、データセットの例をエクスポートしてパスを確認します。

ax datasets export DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; ex=json.load(sys.stdin); print(json.dumps(ex[0], indent=2))"

ステップ 6：タスクを作成する

ax tasks create \
  --name "Experiment Correctness" \
  --task-type template_evaluation \
  --dataset DATASET_NAME --space SPACE \
  --experiment-ids "EXP_ID" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

ステップ 7：実行して監視する

ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID" \   # base64 ID from `ax experiments list --space SPACE -o json`
  --wait

ax tasks list-runs TASK_ID
ax tasks get-run RUN_ID

---

テンプレート設計のベストプラクティス

1. 汎用的で移植可能な変数名を使用する

{input}、{output}、{context} を使用し、特定のプロジェクトやスパン属性に紐づいた名前（例：{attributes_input_value}）は使用しないでください。評価器自体は抽象的なままにし、特定のプロジェクトや実験の実際のフィールドとの接続は、タスクの column_mappings で行います。これにより、同じ評価器を変更せずに複数のプロジェクトや実験で実行できます。

2. 二値ラベルをデフォルトにする

明確な文字列ラベルを 2 つだけ使用します（例：hallucinated / factual、correct / incorrect、pass / fail）。二値ラベルには、次の利点があります。

• 判定モデルが一貫して出力しやすい
• 業界で最も一般的である
• ダッシュボードで最も解釈しやすい

ユーザーが 2 つを超える選択肢を求める場合は対応して構いませんが、まず二値ラベルを推奨し、トレードオフ（ラベルが増える → 曖昧さが増す → 評価者間の信頼性が低下する）を説明してください。

3. モデルの返答内容を明確に指定する

テンプレートでは、判定モデルにラベル文字列のみを返し、それ以外は何も返さないよう指示する必要があります。プロンプト内のラベル文字列は、--classification-choices のラベルと完全に一致していなければなりません（スペルと大文字・小文字の両方）。

良い例：

Respond with exactly one of these labels: hallucinated, factual

悪い例（自由度が高すぎる）：

Is this hallucinated? Answer yes or no.

4. 温度を低く保つ

再現性のあるスコアリングのため、--invocation-params '{"temperature": 0}' を渡します。温度が高いと、評価結果にばらつきが生じます。

5. デバッグには --include-explanations を使用する

初期設定時には必ず説明を含め、ラベルを大規模に信頼して使用する前に、判定モデルが正しく推論していることを確認できるようにします。

6. bash ではテンプレートをシングルクォートで囲む

シングルクォートを使用すると、シェルによる {variable} プレースホルダーの展開を防げます。ダブルクォートを使用すると問題が発生します。

# Correct
--template 'Judge this: {input} → {output}'

# Wrong — shell may interpret { } or fail
--template "Judge this: {input} → {output}"

7. --classification-choices は常にテンプレートのラベルに合わせる

--classification-choices のラベルは、--template 内で参照されるラベルと完全に一致していなければなりません（スペルと大文字・小文字の両方）。--classification-choices を省略すると、タスクの実行が「missing rails and classification choices」というエラーで失敗します。

トラブルシューティング

問題	解決方法
ax: command not found	references/ax-setup.md を参照してください
401 Unauthorized	API キーにこのスペースへのアクセス権がない可能性があります。https://app.arize.com/admin > API Keys で確認してください
Evaluator not found	ax evaluators list --space SPACE
Integration not found	ax ai-integrations list --space SPACE
Task not found	ax tasks list --space SPACE
project and dataset-id are mutually exclusive	タスクの作成時には、どちらか一方のみを使用してください
experiment-ids required for dataset tasks	create と trigger-run に --experiment-ids を追加してください
sampling-rate only valid for project tasks	データセットタスクから --sampling-rate を削除してください
ax spans export で検証エラーが発生する	通常はプロジェクト名を使用できます。それでも検証エラーが発生する場合は、ax projects list --space SPACE -o json で base64 エンコードされたプロジェクト ID を調べ、代わりに id フィールドを使用してください
テンプレートの検証エラー	bash では --template '...' のようにシングルクォートを使用してください。二重の {{var}} ではなく、単一の {var} を使用してください
実行が pending のまま停止する	ax tasks get-run RUN_ID を実行してから、ax tasks cancel-run RUN_ID を実行してください
実行が約 1 秒で cancelled になる	インテグレーションの認証情報が無効です。AI インテグレーションを確認してください
実行が約 3 分で cancelled になる	スパンは検出されましたが、LLM の呼び出しに失敗しました。モデル名が間違っているか、キーが無効です
実行が completed で、スパンが 0 件	時間範囲を広げてください。評価インデックスに古いデータが含まれていない可能性があります
UI にスコアが表示されない	column_mappings を、スパン／実行の実際のパスに合わせて修正してください
スコアがおかしい	--include-explanations を追加し、いくつかのサンプルで評価者の推論を確認してください
スパンの種類が一致せず、評価者が実行をキャンセルする	query_filter と column_mappings を、LLM スパンと CHAIN スパンに合わせてください
trigger-run で時刻形式エラーが発生する	2026-03-21T09:00:00 を使用してください。末尾に Z は付けません
実行に失敗する：「missing rails and classification choices」	ax evaluators create に --classification-choices '{"label_a": 1, "label_b": 0}' を追加してください。ラベルはテンプレートと一致する必要があります
実行が completed で、すべてのスパンがスキップされる	クエリフィルターに一致するスパンはありますが、カラムマッピングが間違っているか、テンプレート変数を解決できません。サンプルスパンをエクスポートしてパスを確認してください
query_filter を設定しているのに、スコアが付いたスパンが 0 件	フィルター属性が評価インデックスに登録されていない可能性があります。attributes.metadata.* やカスタム属性は、インデックスに登録されていないことがよくあります。代わりに span_kind または attributes.llm.model_name を使用するか、フィルターを削除して時間範囲内にスパンが存在することを確認してください。

キャンセルされた実行の診断

タスクの実行がキャンセルされた場合（ステータスが cancelled）、次のチェックリストを順番に確認します。

1. インテグレーションの認証情報を確認する

ax ai-integrations list --space SPACE -o json

評価器で使用されているインテグレーション ID が存在し、有効な認証情報が設定されていることを確認します。インテグレーションが削除されている場合や API キーの有効期限が切れている場合、実行は約 1 秒以内にキャンセルされます。

2. モデル名を確認する

ax evaluators get EVALUATOR_NAME --space SPACE -o json

model_name フィールドを確認します。入力ミスや非推奨のモデルが指定されていると、LLM 呼び出しが失敗し、実行は約 3 分後にキャンセルされます。

3. サンプルのスパン／実行をエクスポートし、パスを column_mappings と比較する

プロジェクトタスクの場合：

ax spans export PROJECT --space SPACE -l 1 --days 7 --stdout | python3 -m json.tool

実験タスクの場合：

ax experiments export EXPERIMENT_NAME --dataset DATASET_NAME --space SPACE --stdout | python3 -c "import sys,json; runs=json.load(sys.stdin); print(json.dumps(runs[0], indent=2)) if runs else print('No runs')"

エクスポートした JSON パスをタスクの column_mappings と比較します。各テンプレート変数について、マッピング先のパスが実際に存在することを確認します。よくある不一致は次のとおりです。

• 実験の実行で output を attributes.output.value にマッピングしている（output のみにする必要があります）
• 実際のパスが attributes.llm.input_messages である CHAIN スパンの input を attributes.input.value にマッピングしている
• フィルター対象のスパン種別に存在しないパスに context をマッピングしている

4. data_start_time がエポック値でないことを確認する

trigger-run で開始時刻に 0、1970-01-01、または空文字列を指定した場合、時間範囲は無効です。必ず実際のスパンのタイムスタンプを使って設定してください。

ax spans export PROJECT --space SPACE -l 5 --days 30 --stdout | python3 -c "
import sys, json
spans = json.load(sys.stdin)
for s in spans:
    print(s.get('start_time', 'N/A'), s.get('end_time', 'N/A'))
"

5. スパン種別が評価器のスコープと一致することを確認する

評価器が --data-granularity trace を指定して作成されているにもかかわらず、タスクの query_filter が span_kind = 'LLM' の場合、条件に一致するデータが見つからず、実行がキャンセルされることがあります。粒度とフィルターが一致していることを確認します。

6. すべてのテンプレート変数が解決されることを確認する

評価器のテンプレート内のすべての {variable} に、null ではない値に解決される対応する column_mappings エントリーが必要です。実際のスパンを使って解決結果をテストします。

ax spans export PROJECT --space SPACE -l 3 --days 7 --stdout | python3 -c "
import sys, json
spans = json.load(sys.stdin)
# Replace these paths with your actual column_mappings values
mappings = {'input': 'attributes.input.value', 'output': 'attributes.output.value'}
for i, span in enumerate(spans):
    print(f'--- Span {i} ---')
    for var, path in mappings.items():
        parts = path.split('.')
        val = span
        for p in parts:
            val = val.get(p) if isinstance(val, dict) else None
        status = 'FOUND' if val else 'MISSING'
        print(f'  {var} ({path}): {status} — {str(val)[:80] if val else \"null\"}')
"

すべてのスパンでいずれかの変数が MISSING と表示される場合は、カラムマッピングを修正するか、別のスパン種別を対象とするよう query_filter を調整します。

---

関連スキル

• arize-ai-provider-integration：LLM プロバイダーのインテグレーションに関する CRUD 操作（認証情報の作成、更新、削除）
• arize-trace：カラムパスと時間範囲を特定するためのスパンのエクスポート
• arize-experiment：実験の作成と、実験のカラムマッピング用の実行のエクスポート
• arize-dataset：実行データに入力フィールドが含まれていない場合に、データセットのサンプルをエクスポートして入力フィールドを特定
• arize-link：Arize UI の評価器とタスクへのディープリンク

---

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

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