arize-annotation

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 を使用します。これらの方法で認証情報を入手できない場合は、ユーザーに尋ねてください。

---

概念

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

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

フィールド	説明
名前	内容を表す識別子（例：Correctness、Helpfulness）です。スペース内で一意である必要があります。
種類	categorical（リストから選択）、continuous（数値範囲）、または freeform（自由記述）です。
値	categorical の場合：{"label": str, "score": number} のペアの配列です。
最小／最大スコア	continuous の場合：数値の範囲です。
最適化の方向	スコアが高いほど良い（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   # required when using name instead of ID

削除

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 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 [email protected] \
  --instructions "Label each response as correct or incorrect." \
  --assignment-method all   # or: random

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

更新

リスト形式のフラグ（--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

レコードの割り当て

特定のレコードをレビューするユーザーを割り当てます。

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"])

# 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"],
    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 を確認します
Span 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 § 今後の使用に備えた認証情報の保存を参照してください。