Arize Evaluator Skill

SPACE — すべての --space フラグと ARIZE_SPACE 環境変数は、スペースの名前（例：my-workspace）またはBase64エンコードされたスペースID（例：U3BhY2U6...）を受け入れます。ax spaces list で確認できます。

このスキルは、ArizeでLLM-as-judge evaluatorsを設計、作成、実行することを扱います。evaluatorはjudgeを定義し、taskはそれを実データに対して実行する方法です。

---

前提条件

必要な 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 を実行してプラットフォーム管理の認証情報を確認してください。存在しない場合は、ユーザーにキーの提供またはarise-ai-provider-integrationスキルを使用した統合作成を依頼してください
• セキュリティ： .env ファイルを読み取ったり、ファイルシステムから認証情報を検索したりしないでください。Arizeの認証情報には ax profiles を、LLMプロバイダーキーには ax ai-integrations を使用してください。認証情報がこれらのチャネルを通じて利用できない場合は、ユーザーに依頼してください。
• 重大 — evaluation結果を捏造しないでください： evaluationタスクが失敗した場合、キャンセルされた場合、またはスコアを生成しなかった場合、失敗を明確に報告し、何が間違っていたかを説明してください。「手動evaluation」を実行したり、品質スコアを捏造したり、パーセンテージを推定したり、Arize evaluationシステムから出た如何なるエージェント生成分析も提示してください。代わりに、(1) 特定された問題を修正して再試行する、(2) Arize UIから実行してみる、(3) ax ai-integrations list で統合認証情報を確認する、(4) https://arize.com/support でサポートに連絡する、のいずれかを提案してください

---

概念

Evaluatorとは何か？

evaluatorはLLM-as-judge定義です。以下を含みます：

フィールド	説明
Template	judgeプロンプト。{variable} プレースホルダー（例：{input}、{output}、{context}）を使用します。これはタスクのカラムマッピング経由で実行時に埋められます。
Classification choices	許可された出力ラベルのセット（例：factual / hallucinated）。バイナリがデフォルトで最も一般的です。各選択肢は、オプションで数値スコアを含むことができます。
AI Integration	evaluatorがjudgeモデルを呼び出すために使用する保存されたLLMプロバイダー認証情報（OpenAI、Anthropic、Bedrockなど）。
Model	特定のjudgeモデル（例：gpt-4o、claude-sonnet-4-5）。
Invocation params	モデル設定の任意JSON（例：{"temperature": 0}）。再現性のため、低温度が推奨されます。
Optimization direction	スコアが高いほど良いか（maximize）、悪いか（minimize）。UIでのトレンド描画方法を設定します。
Data granularity	evaluatorがspan、trace、またはsessionレベルで実行されるかどうか。ほとんどのevaluatorはスパンレベルで実行されます。

Evaluatorはバージョン管理されます — プロンプトまたはモデルの変更があるたびに、新しい不変バージョンが作成されます。最新バージョンはアクティブです。

Taskとは何か？

taskは1つ以上のevaluatorを実データに対して実行する方法です。タスクはプロジェクト（ライブトレース/スパン）またはデータセット（experiment実行）に添付されます。タスクには以下が含まれます：

フィールド	説明
Evaluators	実行するevaluatorのリスト。1つのタスクで複数を実行できます。
Column mappings	各evaluatorのテンプレート変数を、スパンまたはexperiment実行の実際のフィールドパスに対応付けます（例："input" → "attributes.input.value"）。これにより、evaluatorを複数のプロジェクトとexperiment間でポータブルにします。
Query filter	SQLスタイルの式で、評価するスパン/実行を選択します（例："span_kind = 'LLM'"）。オプションですが、精度のため重要です。
Continuous	プロジェクトタスクの場合：新しいスパンが到着したときに自動的にスコアするかどうか。
Sampling rate	連続プロジェクトタスクの場合：評価する新しいスパンの割合（0～1）。

---

データGranularity

--data-granularity フラグは、evaluatorがスコアするデータユニットを制御します。デフォルトは span であり、プロジェクトタスク（データセット/experimentタスクではなく）にのみ適用されます。

レベル	評価対象	用途	結果カラムプレフィックス
span（デフォルト）	個々のスパン	Q&Aの正確性、hallucination、関連性	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

traceおよびsession集約のしくみ

trace granularityの場合、同じ context.trace_id を共有するスパンがグループ化されます。evaluatorテンプレートで使用されるカラム値は、judgeモデルに渡す前に、単一文字列にコンマで結合されます（各値は100Kバイトに切り詰められます）。

session granularityの場合、同じトレースレベルのグループ化が最初に発生し、その後トレースが start_time で順序付けされ、attributes.session.id でグループ化されます。セッションレベルの値は合計100Kバイトに制限されます。

{conversation} テンプレート変数

セッション granularityでは、{conversation} は特別なテンプレート変数であり、セッション内のすべてのトレースにわたる {input, output} ターンのJSON配列としてレンダリングされます。これは attributes.input.value / attributes.llm.input_messages（入力側）と attributes.output.value / attributes.llm.output_messages（出力側）から構築されます。

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

マルチevaluatorタスク

タスクは異なるgranularityのevaluatorを含むことができます。実行時、システムは最高の granularity（session > trace > span）をデータ取得に使用し、自動的にevaluatorごとに1つの子実行に分割します。タスクのevaluators JSONの evaluatorごとの query_filter は、さらに含まれるスパンを制限します（例：セッション内のツール呼び出しスパンのみ）。

---

基本的なCRUD

AI Integrations

AI統合は、evaluatorが使用するLLMプロバイダー認証情報を保存します。完全なCRUD — リスト表示、すべてのプロバイダー（OpenAI、Anthropic、Azure、Bedrock、Vertex、Gemini、NVIDIA NIM、カスタム）の作成、更新、削除 — には、arize-ai-provider-integrationスキルを使用してください。

一般的なケース（OpenAI）の簡潔なリファレンス：

# 既存の統合を最初に確認する
ax ai-integrations list --space SPACE

# 存在しない場合は作成
ax ai-integrations create \
  --name "My OpenAI Integration" \
  --provider openAI \
  --api-key $OPENAI_API_KEY

返された統合IDをコピーしてください — ax evaluators create --ai-integration-id に必要です。

Evaluators

# リスト / 取得
ax evaluators list --space SPACE
ax evaluators get ID                    # 名前またはIDを受け入れます
ax evaluators get NAME --space SPACE   # IDの代わりに名前を使用する場合は必須
ax evaluators list-versions NAME_OR_ID
ax evaluators get-version VERSION_ID

# 作成（evaluatorとその最初のバージョンを作成）
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'

# 新しいバージョンを作成（プロンプトまたはモデルの変更用 — バージョンは不変）
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}'

# メタデータのみを更新（プロンプトではなく、名前、説明）
ax evaluators update NAME_OR_ID \
  --name "New Name" \
  --description "Updated description"

# 削除（永続的 — すべてのバージョンを削除）
ax evaluators delete NAME_OR_ID

create の主要フラグ：

フラグ	必須	説明
--name	はい	Evaluator名（スペース内で一意）
--space	はい	作成するスペースの名前またはID
--template-name	はい	Evalカラム名 — 英数字、スペース、ハイフン、アンダースコア
--commit-message	はい	このバージョンの説明
--ai-integration-id	はい	AI統合ID（上記参照）
--model-name	はい	Judgeモデル（例：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。プロジェクトタスクにのみ関連し、データセット/experimentタスクではありません。「Data Granularity」セクションを参照してください。
--direction	いいえ	最適化方向：maximize または minimize。UIでのトレンド描画方法を設定します。
--provider-params	いいえ	プロバイダー固有パラメータのJSONオブジェクト

Tasks

PROJECT_NAME、DATASET_NAME、および evaluator_id はすべて名前またはBase64 IDを受け入れます。

# リスト / 取得
ax tasks list --space SPACE
ax tasks list --project PROJECT_NAME
ax tasks list --dataset DATASET_NAME --space SPACE
ax tasks get TASK_ID

# 作成（プロジェクト — 連続）
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

# 作成（プロジェクト — ワンタイム / 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

# 作成（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" \   # `ax experiments list --space SPACE -o json` からのBase64 ID
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

# 実行をトリガー（プロジェクトタスク — データウィンドウを使用）
ax tasks trigger-run TASK_ID \
  --data-start-time "2026-03-20T00:00:00" \
  --data-end-time "2026-03-21T23:59:59" \
  --wait

# 実行をトリガー（experimentタスク — experiment IDを使用）
ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID_1" \   # `ax experiments list --space SPACE -o json` からのBase64 ID
  --wait

# 監視
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	処理されるスパンを制限（デフォルト 10,000）
--override-evaluations	既にラベルを持つスパンを再スコア
--wait / -w	実行が終了するまでブロック
--timeout	--wait で待機する秒数（デフォルト 600）
--poll-interval	待機時のポーリング間隔（秒）（デフォルト 5）

実行ステータスガイド：

ステータス	意味
completed、0スパン	Evalインデックスに1～2時間の遅延があります — 最近取り込まれたスパンはまだインデックスされていない可能性があります。ウィンドウを少なくとも2時間前のデータにシフトさせるか、時間範囲を拡大して、より多くの履歴データをカバーしてください。
cancelled ~1秒	統合認証情報が無効です
cancelled ~3分	スパンが見つかりましたが、LLM呼び出しが失敗しました — モデル名またはキーを確認してください
completed、N > 0	成功 — UI でスコアを確認してください

---

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

ユーザーが「Playground Tracesプロジェクト用のevaluatorを作成する」のような発言をする場合に使用します。

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

ax spans export はプロジェクト名を直接受け入れます — ID検索は必要ありません。プロジェクト名がわからない場合は、利用可能なプロジェクトをリストしてください：

ax projects list --space SPACE -o json

"name" が一致する（大文字小文字を区別しません）エントリを見つけ、その名前を後続のコマンドで PROJECT として使用してください。後で名前の検証エラーが発生した場合は、プロジェクトの "id"（Base64文字列）を使用することにフォールバックしてください。

ステップ2：評価対象を理解する

ユーザーがevaluatorタイプ（hallucination、correctness、relevance など）を指定した場合 → ステップ3にスキップしてください。

そうでない場合、実データに基づくevaluatorを使用するため、最近のスパンをサンプリングしてください：

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

attributes.input、attributes.output、スパン種類、および既存の注釈を検査します。失敗モード（例：幻覚的な事実、トピック外の回答、コンテキストの欠落）を特定し、具体的な1～3つのevaluatorアイデアを提案してください。ユーザーに選ばせてください。

各提案には、evaluator名（太字）、評価対象の1文の説明、括弧内のバイナリラベルペアが含まれている必要があります。各項目を以下のようにフォーマットしてください：

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

例：

1. Response Correctness — エージェントの応答はユーザーの財務クエリに正確に対応していますか？（correct / incorrect）
2. Hallucination — 応答は取得したコンテキストに根拠のない事実を作成していますか？（factual / hallucinated）

ステップ3：AI統合を確認または作成する

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

適切な統合が存在する場合、そのIDをメモしてください。存在しない場合は、arize-ai-provider-integrationスキルを使用して作成します。judgeにどのプロバイダー/モデルを使用したいかをユーザーに尋ねてください。

ステップ4：evaluatorを作成する

以下のテンプレート設計ベストプラクティスを使用してください。evaluator名と変数を汎用的に保ちます — タスク（ステップ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'

ステップ5：尋ねる — backfill、continuous、またはその両方？

推奨されるアプローチ： 常に小規模なbackfill（~100の過去のスパン）で開始して、継続的な監視を有効にする前にevaluatorを検証します。これにより、本番環境のすべてのスパンをスコアする前に、既知のデータでカラムマッピングエラー、間違ったスパン種類、テンプレート問題を検出できます。backfillが正確なスコアリングを確認した後にのみcontinuousを有効にします。

タスクを作成する前に、尋ねてください：

"以下のどちらをしたいですか？ (a) 過去のスパンでbackfillを実行する（ワンタイム）？ (b) 今後の新しいスパンでcontinuous evaluationを設定する？ (c) 両方 — backfillで検証してから、自動的に新しいスパンのスコアリングを継続する？（推奨）"

ステップ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

スパン種類のアライメントを検証してください： evaluatorプロンプトがLLM最終テキストを想定していますが、タスクがCHAINスパンをターゲットしている場合（またはその逆）、実行がキャンセルされたり、間違ったテキストをスコアしたりすることがあります。タスクの query_filter がマップされたスパン種類と一致していることを確認してください。

query_filter はインデックス付き属性でのみ機能します： タスクのevaluators JSONの query_filter は、rawスパンストアではなく、evalインデックスに対して評価されます。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つを省略すると、実行は有効なスコアを生成しません。

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

Backfillのみ（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

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 を使用し、ステップ8でもbackfill実行をトリガーします。

ステップ8：backfill実行をトリガーする（要求された場合）

Evalインデックスの遅延： evalインデックスはプライマリトレースストアから非同期に構築され、1～2時間の遅延がある可能性があります。最初のテスト実行では、少なくとも2時間前のデータで終了する時間ウィンドウを使用してください。--data-end-time を「今」に設定し、最後の1時間に取り込まれたスパンの場合、実行は成功しますが、0スパンがスコアされます。

まずデータがある時間範囲を見つけてください：

ax spans export PROJECT --space SPACE -l 100 --days 1 --stdout   # 最初に過去24時間を試す
ax spans export PROJECT --space SPACE -l 100 --days 7 --stdout   # 空の場合は拡大

実スパンからの 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

スコアと説明を確認してから、完全なbackfillを拡大するか、continuousを有効にしてください。

---

ワークフローB：experimentのためのevaluatorを作成する

ユーザーが「experimentの用にevaluatorを作成する」または「dataset実行を評価する」のような発言をする場合に使用します。

ユーザーが「dataset」と言うが、experimentはない場合： タスクはdataset（単独ではなく）に対してターゲットする必要があります。尋ねてください：

"Evaluationタスクはdataset直接ではなく、experiment実行に対して実行されます。最初にそのdatasetでexperimentを作成するのを支援しましょうか？"

yesの場合、arize-experimentスキルを使用して1つを作成し、ここに戻ってきてください。

ステップ1：datasetとexperiment名を見つける

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

datasetの名前と、スコアするexperiment名をメモしてください。これらは後続のコマンドで名前またはIDを受け入れます — 名前が推奨されます。

ステップ2：評価対象を理解する

ユーザーがevaluatorタイプを指定した場合 → ステップ3にスキップしてください。

そうでない場合は、最近のexperiment実行を検査してevaluatorをベースにしてください：

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つのevaluatorアイデアを提案します。各提案は、evaluator名（太字）、1文の説明、括弧内のバイナリラベルペアを含む必要があります — ワークフローA、ステップ2と同じ形式。

ステップ3：AI統合を確認または作成する

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

ステップ4：evaluatorを作成する

ワークフロー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))"

experiment実行の一般的なマッピング：

• output → "output"（各実行のトップレベルフィールド）
• input → 実行上にあるか、リンクされたdataset例に埋め込まれているかを確認

input が実行JSONに含まれていない場合は、dataset例をエクスポートしてパスを見つけてください：

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" \   # `ax experiments list --space SPACE -o json` からのBase64 ID
  --evaluators '[{"evaluator_id": "EVAL_ID", "column_mappings": {"output": "output"}}]' \
  --no-continuous

ステップ7：トリガーして監視する

ax tasks trigger-run TASK_ID \
  --experiment-ids "EXP_ID" \   # `ax experiments list --space SPACE -o json` からのBase64 ID
  --wait

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

---

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

1. 汎用的でポータブルな変数名を使用する

{input}、{output}、{context} を使用します — 特定のプロジェクトまたはスパン属性に関連する名前ではなく（例：{attributes_input_value} を使用しません）。evaluator自体は抽象的のままです。タスクの column_mappings は、特定のプロジェクトまたはexperimentの実際のフィールドにそれを配線する場所です。これにより、同じevaluatorを複数のプロジェクトとexperiment間で修正なしで実行できます。

2. デフォルトでバイナリラベルを使用する

2つの明確な文字列ラベルを正確に使用します（例：hallucinated / factual、correct / incorrect、pass / fail）。バイナリラベルは：

• judgeモデルが一貫して生成するのが最も簡単
• 業界で最も一般的
• ダッシュボードで最も簡単に解釈

ユーザーが2つ以上の選択肢を主張する場合、それで問題ありません — ただし最初にバイナリを推奨し、トレードオフを説明してください（より多くのラベル → より多くの曖昧性 → より低い相互評価者信頼性）。

3. モデルが返すべきものについて明示的である

テンプレートは、judge モデルにラベル文字列のみを返すことを明確に指示する必要があります — 何もしません。プロンプト内のラベル文字列は、--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 を使用する

初期設定中は、常に説明を含めて、大規模にラベルを信頼する前に、judge が正しく推論しているかを検証できます。

6. bashでプロンプトを単一引用符で渡す

単一引用符は、シェルが {variable} プレースホルダーを解釈するのを防ぎます。二重引用符は問題を引き起こします：

# 正しい
--template 'Judge this: {input} → {output}'

# 間違い — シェルは { } を解釈するか、失敗する可能性があります
--template "Judge this: {input} → {output}"

7. 常に --classification-choices をテンプレートラベルに一致させるように設定する

--classification-choices のラベルは、--template で参照されるラベルと正確に一致する必要があります（同じ綴り、同じケース）。--classification-choices を省略すると、タスク実行は「rails と 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	タスク作成時は1つのみを使用
experiment-ids required for dataset tasks	create と trigger-run に --experiment-ids を追加
sampling-rate only valid for project tasks	dataset タスクから --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 を実行してください
実行 cancelled ~1秒	統合認証情報が無効です — AI統合を確認してください
実行 cancelled ~3分	スパンが見つかりましたが、LLM呼び出しが失敗しました — モデル名またはキーが悪いです
実行 completed、0スパン	時間ウィンドウを拡大します。evalインデックスは古いデータをカバーしない可能性があります
UI でスコアなし	column_mappings を修正して、スパン/実行上の実際のパスと一致させてください
スコアが間違って見える	--include-explanations を追加して、数個のサンプルでjudgeの推論を検査してください
Evaluatorが間違ったスパン種類でキャンセル	query_filter と column_mappings をLLM vs CHAINスパンに一致させてください
trigger-run で時間形式エラー	2026-03-21T09:00:00 を使用してください — 末尾の Z なし
実行失敗：「rails と classification choices がない」	ax evaluators create に --classification-choices '{"label_a": 1, "label_b": 0}' を追加します — ラベルはテンプレートと一致する必要があります
実行 completed、すべてのスパンスキップ	クエリフィルターはスパンと一致しましたが、カラムマッピングが間違っているか、テンプレート変数が解決されません — サンプルスパンをエクスポートしてパスを確認してください
query_filter が設定されていますが、0スパン がスコアされました	フィルター属性はevalインデックスでインデックスされていない可能性があります。attributes.metadata.* およびカスタム属性は頻繁にインデックスされません。代わりに span_kind または attributes.llm.model_name を使用するか、フィルターを削除してスパンがウィンドウに存在することを確認します。

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

タスク実行がキャンセルされた場合（ステータス cancelled）、以下のチェックリストを順序付けて従ってください：

1. 統合認証情報を確認

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

evaluatorによって使用される統合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

experimentタスクの場合：

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 と比較します。各テンプレート変数について、マップされたパスが実際に存在することを確認します。一般的な不一致：

• experiment実行上の attributes.output.value へのマッピング output（output のみであるべき）
• CHAINスパンで attributes.input.value にマッピング input（実際のパスは attributes.llm.input_messages）
• スパン種類に存在しないパスへのマッピング 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. スパン種類が evaluator スコープと一致することを確認

evaluator が --data-granularity trace で作成され、タスクの query_filter が span_kind = 'LLM' の場合、実行は適格なデータを見つけず、キャンセルされる可能性があります。granularityとフィルターが一貫していることを確認します。

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

evaluatorテンプレートのすべての {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)
# これらのパスを実際のcolumn_mappings値に置き換えます
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: experimentを作成し、experiment カラムマッピング用に実行をエクスポート
• arize-dataset: 実行がそれらを省略するときの入力フィールドを見つけるためにdatasetの例をエクスポート
• arize-link: Arize UI内のevaluatorおよびタスクへのディープリンク

---

将来の使用のための認証情報を保存する

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