arize-annotation

Arize Annotation Skill

SPACE — --space フラグは、スペースの名前（例：my-workspace）または base64 エンコードされたスペースのID（例：U3BhY2U6...）を受け付けます。既知の名前は ax spaces get NAME で解決してください。ax spaces list は人が閲覧するためのコマンドです。

このスキルでは、アノテーション設定（ラベルのスキーマ）とアノテーションキュー（人によるレビューのワークフロー）、および Python SDK を使ってプロジェクトのスパンにプログラムでアノテーションを付ける方法を扱います。

対象: Arize での人によるラベリングでは、製品 UI 上で設定によって定義された値をスパン、データセットの例、実験関連レコード、キュー項目に付与します。このスキルでは、ax annotation-configs、ax annotation-queues、および ArizeClient.spans.update_annotations を使ったスパンの一括更新を扱います。

---

前提条件

タスクにすぐ取りかかり、必要な 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 を参照してください
• セキュリティ: .env ファイルを読んだり、ファイルシステム上で認証情報を検索したりしないでください。例外は、シークレットではない ARIZE_SPACE_ID の行です（Space を参照）。Arize の認証情報には ax profiles を、LLM プロバイダーのキーには ax ai-integrations を使用してください。チャットでシークレットを貼り付けるようユーザーに求めないでください。認証情報がない場合は、references/ax-profiles.md を参照してください。

---

アノテーション設定とは？

アノテーション設定は、単一の種類の人によるフィードバックラベルのスキーマを定義します。スパン、データセットレコード、実験の出力、またはキュー項目にアノテーションを付ける前に、そのラベルの設定がスペースに存在している必要があります。

フィールド	説明
名前	説明的な識別子（例：Correctness、Helpfulness）です。スペース内で一意である必要があります。
タイプ	CATEGORICAL（リストから選択）、CONTINUOUS（数値範囲）、または FREEFORM（自由記述テキスト）です。
値	カテゴリ型の場合：ラベル文字列です。ラベルごとに --value を1つ指定します。
最小／最大スコア	連続型の場合：数値の範囲です。
最適化の方向	MAXIMIZE、MINIMIZE、または NONE です。UI で傾向を表示する際に使用されます。

ラベルを適用する場所（サーフェス）

サーフェス	一般的な方法
プロジェクトのスパン	Python SDK の spans.update_annotations（以下を参照）、および／または Arize UI
データセットの例	Arize UI（人によるラベリングのフロー）。設定がスペースに存在している必要があります
実験の出力	UI でデータセットやトレースと一緒にレビューされることがよくあります。arize-experiment、arize-dataset を参照してください
アノテーションキューの項目	ax annotation-queues CLI（以下を参照）、および／または Arize UI。設定が存在している必要があります

ラベルを保存する前提として、関連するアノテーション設定がスペースに存在することを必ず確認してください。

---

基本的な CRUD：アノテーション設定

一覧表示

ax annotation-configs list --space SPACE
ax annotation-configs list --space SPACE -o json
ax annotation-configs list --space SPACE --limit 20
ax annotation-configs list --space SPACE --name "Correctness"   # substring filter

作成 — カテゴリ型

カテゴリ型の設定では、レビュー担当者が選択する固定ラベルのセットを提示します。

ax annotation-configs create categorical \
  --name "Correctness" \
  --space SPACE \
  --value correct \
  --value incorrect \
  --optimization-direction MAXIMIZE

よく使われる二値ラベルの組み合わせ：

• correct / incorrect
• helpful / unhelpful
• safe / unsafe
• relevant / irrelevant
• pass / fail

作成 — 連続型

連続型の設定では、レビュー担当者が定義された範囲内で数値スコアを入力できます。

ax annotation-configs create continuous \
  --name "Quality Score" \
  --space SPACE \
  --min-score 0 \
  --max-score 10 \
  --optimization-direction MAXIMIZE

作成 — 自由記述型

自由記述型の設定では、自由形式のテキストフィードバックを収集します。名前とスペース以外に追加のフラグは必要ありません。

ax annotation-configs create freeform \
  --name "Reviewer Notes" \
  --space SPACE

取得

ax annotation-configs get NAME_OR_ID
ax annotation-configs get NAME_OR_ID -o json
ax annotation-configs get NAME_OR_ID --space SPACE   # required when using name instead of ID

更新

設定タイプごとに専用の更新コマンドがあります。変更されたフィールドのみが更新されます。

自由形式：

ax annotation-configs update freeform NAME_OR_ID --space SPACE --new-name "Updated Name"

連続値：

ax annotation-configs update continuous NAME_OR_ID --space SPACE --min-score 1 --max-score 5 --optimization-direction MINIMIZE

カテゴリ形式：

ax annotation-configs update categorical NAME_OR_ID --space SPACE --value correct --value incorrect --optimization-direction MAXIMIZE

ID ではなく名前を使用する場合は、--space が必須です。各 --value には、カテゴリラベルの完全なリストを指定します。既存のラベルに追加するのではなく、置き換えます。残すラベルごとに --value を繰り返してください。指定しなかったラベルは削除されます。

削除

ax annotation-configs delete NAME_OR_ID
ax annotation-configs delete NAME_OR_ID --space SPACE   # required when using name instead of ID
ax annotation-configs delete NAME_OR_ID --force   # skip confirmation

注： 削除は取り消せません。この設定に関連付けられている注釈キューも製品内で削除されます（キュー自体は残る場合があります。必要に応じて、Arize UI で関連付けを修正してください）。

---

注釈キュー：ax annotation-queues

注釈キューは、レコード（スパン、データセットの例、実験の実行結果）を人間のレビュアーに割り当てます。各キューは、レビュアーが適用できるラベルを定義する1つ以上の注釈設定にリンクされています。

一覧表示／取得

ax annotation-queues list --space SPACE
ax annotation-queues list --space SPACE -o json
ax annotation-queues list --space SPACE --name "Review"   # substring filter

ax annotation-queues get NAME_OR_ID --space SPACE
ax annotation-queues get NAME_OR_ID --space SPACE -o json

作成

--annotation-config-id を少なくとも1つ指定する必要があります。

ax annotation-queues create \
  --name "Correctness Review" \
  --space SPACE \
  --annotation-config-id CONFIG_ID \
  --annotator-email [email protected] \
  --instructions "Label each response as correct or incorrect." \
  --assignment-method ALL   # or: RANDOM

複数の設定やレビュアーを関連付けるには、--annotation-config-id と --annotator-email を繰り返し指定します。

レコードの追加

既存のキューにレコードを追加します（初期レコードを指定する場合は、create でも --record-sources を使用できます）。

ax annotation-queues add-records NAME_OR_ID --space SPACE --record-sources sources.json

ax annotation-queues add-records NAME_OR_ID --space SPACE \
  --record-sources '[{"record_type": "EXAMPLE", "dataset_id": "ds-1", "example_ids": ["ex-1", "ex-2"]}]'

--record-sources は必須で、JSON ファイルのパスまたはインラインの JSON 配列を指定します。各ソースには record_type（SPAN または EXAMPLE）と、タイプ固有のフィールドを指定します。

• スパン： project_id、start_time（ISO 8601）、end_time（ISO 8601）、省略可能な span_ids
• 例： dataset_id、example_ids

更新

一覧を指定するフラグ（--annotation-config-id、--annotator-email）は、指定すると既存の値を完全に置き換えます。新しい値だけでなく、希望するすべての値を渡してください。

ax annotation-queues update NAME_OR_ID --space SPACE --name "New Name"
ax annotation-queues update NAME_OR_ID --space SPACE --instructions "Updated instructions"
ax annotation-queues update NAME_OR_ID --space SPACE \
  --annotation-config-id CONFIG_ID_A \
  --annotation-config-id CONFIG_ID_B

削除

ax annotation-queues delete NAME_OR_ID --space SPACE
ax annotation-queues delete NAME_OR_ID --space SPACE --force   # skip confirmation

レコードの一覧表示

ax annotation-queues list-records NAME_OR_ID --space SPACE
ax annotation-queues list-records NAME_OR_ID --space SPACE --limit 50 -o json

レコードへの注釈の送信

注釈は設定名をキーにしてアップサートされるため、注釈設定ごとに1回呼び出してください。--score、--label、--text のうち少なくとも1つを指定します。

ax annotation-queues annotate-record NAME_OR_ID RECORD_ID \
  --annotation-name "Correctness" \
  --label "correct" \
  --space SPACE

ax annotation-queues annotate-record NAME_OR_ID RECORD_ID \
  --annotation-name "Quality Score" \
  --score 8.5 \
  --text "Response was accurate but slightly verbose." \
  --space SPACE

レコードの割り当て

--email を繰り返して、特定のレコードのレビュー担当者を割り当てます。既存の割り当ては完全に置き換えられるため、毎回すべての担当者を指定してください（--email フラグを指定しない場合、すべての割り当てが解除されます）。

ax annotation-queues assign-record NAME_OR_ID RECORD_ID --email [email protected] --space SPACE

レコードの削除

ax annotation-queues delete-records NAME_OR_ID --space SPACE --record-id REC_1 --record-id REC_2   # max 100; --force skips confirmation

---

スパンへの注釈の適用（Python SDK）

ラベルがすでにある場合（レビュー用エクスポートや外部のラベリングツールなどから取得した場合）は、Python SDK を使用してプロジェクトのスパンに注釈を一括適用します。

import pandas as pd
from arize import ArizeClient

import os

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])

# Build a DataFrame with annotation columns
# Required: context.span_id + at least one annotation.<name>.label or annotation.<name>.score
annotations_df = pd.DataFrame([
    {
        "context.span_id": "span_001",
        "annotation.Correctness.label": "correct",
        "annotation.Correctness.updated_by": "[email protected]",
    },
    {
        "context.span_id": "span_002",
        "annotation.Correctness.label": "incorrect",
        "annotation.Correctness.updated_by": "[email protected]",
    },
])

response = client.spans.update_annotations(
    space_id=os.environ["ARIZE_SPACE_ID"],
    project_name="your-project",
    dataframe=annotations_df,
    validate=True,
)

DataFrame の列スキーマ：

列	必須	説明
context.span_id	はい	注釈を付けるスパン
annotation.<name>.label	いずれか	カテゴリ形式または自由形式のラベル
annotation.<name>.score	いずれか	数値スコア
annotation.<name>.updated_by	いいえ	注釈者の識別子（メールアドレスまたは名前）
annotation.<name>.updated_at	いいえ	エポックからのミリ秒単位のタイムスタンプ
annotation.notes	いいえ	スパンに関する自由形式のメモ

制限事項： 注釈を適用できるのは、送信前31日以内のスパンに限られます。

---

トラブルシューティング

問題	解決方法
ax: command not found	references/ax-setup.md を参照してください
401 Unauthorized	API キーにこのスペースへのアクセス権がない可能性があります。https://app.arize.com/admin > API Keys で確認してください
Annotation config not found	ax annotation-configs list --space SPACE（または ax annotation-configs get NAME_OR_ID --space SPACE）
409 Conflict on create	このスペースには同じ名前がすでに存在します。別の名前を使用するか、既存の設定 ID を取得してください。
キューが見つからない	ax annotation-queues list --space SPACE を実行し、キューの名前または ID を確認してください
レコードがキューに表示されない	キューにリンクされている注釈設定が存在することを確認し、ax annotation-configs list --space SPACE を確認してください
スパン SDK のエラー、またはスパンが見つからない	project_name、space_id、スパン ID を確認し、arize-trace を使用してスパンをエクスポートしてください

---

CLI での一括アノテーション

ax CLI には、Python SDK を使わずに大規模なアノテーションを作成できる一括アノテーションコマンドが用意されています。すべてのコマンドは、最大 1 リクエストあたり 1000 件のアノテーションを含むファイル（CSV、JSON、JSONL、または Parquet）を受け付け、アップサートのセマンティクスを使用します（同じキーを持つ既存のアノテーションは更新され、新しいアノテーションは作成されます）。

リソース	コマンド	スキル
スパン	ax spans annotate PROJECT --space SPACE --file annotations.json	arize-trace
データセットの例	ax datasets annotate-examples NAME_OR_ID --space SPACE --file annotations.json	arize-dataset
実験の実行	ax experiments annotate-runs NAME_OR_ID --space SPACE --dataset DATASET --file annotations.json	arize-experiment

注意点：

• ax spans annotate：時間範囲内に見つからないスパン ID が 1 つでもあると、リクエスト全体が拒否されます。
• ax datasets annotate-examples と ax experiments annotate-runs：一致しないレコード ID は通知なしで無視されます。
• ax experiments annotate-runs：スタンドアロンの実験では --dataset を省略し、--space を指定してください。

ファイル形式の詳細は、リンク先のスキルをご覧ください。

---

関連スキル

• arize-trace：スパン ID と時間範囲を見つけるためにスパンをエクスポートし、ax spans annotate でスパンを一括アノテーションします
• arize-dataset：データセット ID と例 ID を見つけ、ax datasets annotate-examples で例を一括アノテーションします
• arize-evaluator：人間によるアノテーションと並行して、LLM-as-judge による自動評価を行います
• arize-experiment：データセットと評価ワークフローに関連付けられた実験を扱い、ax experiments annotate-runs で実行を一括アノテーションします
• arize-prompts：プロンプトテンプレートを管理し、品質追跡のためにプロンプト出力にアノテーションを付けます
• arize-link：Arize UI のアノテーション設定とキューへのディープリンクを作成します

---

今後の使用に備えて認証情報を保存する

references/ax-profiles.md §「今後の使用に備えて認証情報を保存する」をご覧ください。