Arize Annotation Skill

SPACE — すべての --space フラグと ARIZE_SPACE 環境変数は、スペース名（例：my-workspace）またはBase64エンコードされたスペースID（例：U3BhY2U6...）を受け入れます。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 に案内してください
• スペースが不明 → ax spaces list を実行して名前で選択するか、ユーザーに確認してください
• セキュリティ： .env ファイルを読まないでください。また、ファイルシステムで認証情報を検索しないでください。Arize の認証情報には ax profiles を、LLM プロバイダーキーには ax ai-integrations を使用してください。これらのチャネルを通じて認証情報が利用できない場合は、ユーザーに尋ねてください。

---

コンセプト

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

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

フィールド	説明
名前	わかりやすい識別子（例：Correctness、Helpfulness）。スペース内で一意である必要があります。
タイプ	categorical（リストから選択）、continuous（数値範囲）、または freeform（自由テキスト）。
値	カテゴリの場合：{"label": str, "score": number} のペアの配列。
最小/最大スコア	連続の場合：数値の範囲。
最適化方向	より高いスコアが良い場合は maximize、悪い場合は minimize。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 create \
  --name "Correctness" \
  --space SPACE \
  --type categorical \
  --value correct \
  --value incorrect \
  --optimization-direction maximize

一般的なバイナリラベルペア：

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

作成 — 連続

連続設定により、レビュアーは定義された範囲内で数値スコアを入力できます。

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

作成 — 自由形式

自由形式設定は、オープンエンドのテキストフィードバックを収集します。名前、スペース、タイプ以外の追加フラグは不要です。

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

取得

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   # 名前の代わりにIDを使用する場合に必須

削除

ax annotation-configs delete NAME_OR_ID
ax annotation-configs delete NAME_OR_ID --space SPACE   # 名前の代わりにIDを使用する場合に必須
ax annotation-configs delete NAME_OR_ID --force   # 確認をスキップ

注： 削除は取り消しできません。この設定へのアノテーションキュー関連付けも製品内で削除されます（キューは残ることがあります；必要に応じて Arize UI でアソシエーションを修正してください）。

---

アノテーションキュー：ax annotation-queues

アノテーションキューは、レコード（スパン、データセット例、実験実行）を人間レビュアーにルーティングします。各キューは、レビュアーが適用できるラベルを定義する1つ以上のアノテーション設定にリンクされています。

リスト表示 / 取得

ax annotation-queues list --space SPACE
ax annotation-queues list --space SPACE -o json

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

作成

少なくとも1つの --annotation-config-id が必須です。

ax annotation-queues create \
  --name "Correctness Review" \
  --space SPACE \
  --annotation-config-id CONFIG_ID \
  --annotator-email reviewer@example.com \
  --instructions "各レスポンスを正確または不正確としてラベルします。" \
  --assignment-method all   # または: random

--annotation-config-id と --annotator-email を繰り返して、複数の設定またはレビュアーを追加します。

更新

リストフラグ（--annotation-config-id、--annotator-email）が提供される場合、既存の値を完全に置き換えるため、新しい値だけでなく、すべての望ましい値を渡してください。

ax annotation-queues update NAME_OR_ID --space SPACE --name "新しい名前"
ax annotation-queues update NAME_OR_ID --space SPACE --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   # 確認をスキップ

レコードをリスト表示

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 "レスポンスは正確でしたが、やや冗長でした。" \
  --space SPACE

レコードを割り当て

特定のレコードをレビューするためにユーザーを割り当てます：

ax annotation-queues assign-record NAME_OR_ID RECORD_ID --space SPACE

レコードを削除

ax annotation-queues delete-records NAME_OR_ID --space SPACE

---

スパンへのアノテーションの適用（Python SDK）

Python SDK を使用して、既にラベルがある場合（例：レビューエクスポートまたは外部ラベリングツールから）に、プロジェクトスパンにアノテーションを一括適用します。

import pandas as pd
from arize import ArizeClient

import os

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

# アノテーション列を含むDataFrameを構築
# 必須：context.span_id + 少なくとも1つの annotation.<name>.label または annotation.<name>.score
annotations_df = pd.DataFrame([
    {
        "context.span_id": "span_001",
        "annotation.Correctness.label": "correct",
        "annotation.Correctness.updated_by": "reviewer@example.com",
    },
    {
        "context.span_id": "span_002",
        "annotation.Correctness.label": "incorrect",
        "annotation.Correctness.updated_by": "reviewer@example.com",
    },
])

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

DataFrameカラムスキーマ：

カラム	必須	説明
context.span_id	はい	アノテーションするスパン
annotation.<name>.label	いずれか1つ	カテゴリまたは自由形式のラベル
annotation.<name>.score	いずれか1つ	数値スコア
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 を使用してスパンをエクスポート

---

関連スキル

• arize-trace: スパンIDと時間範囲を見つけるためにスパンをエクスポート
• arize-dataset: データセットIDと例IDを見つける
• arize-evaluator: 人間によるアノテーションとともに自動化されたLLM-as-judge
• arize-experiment: データセットと評価ワークフローに関連付けられた実験
• arize-link: Arize UI内のアノテーション設定とキューへのディープリンク

---

今後の使用のために認証情報を保存

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