アノテーションキュー

ドキュメント > Agent Observability > 調査 > アノテーションキュー

概要

アノテーションキューは、LLM トレースの人間によるレビューのための構造化されたワークフローを提供します。アノテーションキューを使用して、以下のことを行います。

スパン、メタデータ、ツール呼び出し、入力、出力、評価結果を含む完全なコンテキストでトレースをレビューする
トレースに構造化ラベルと自由形式の観察結果を適用する
失敗パターンを特定して分類する
LLM-as-a-Judge 評価の精度を検証する
テストおよび検証用に、人間が検証したラベル付きのゴールデンデータセットを構築する

アノテーションキューの作成

ステップ 1: キュー設定の構成

AI Observability > Experiment > Annotations に移動し、プロジェクトを選択します。
Create Queue をクリックします。
About タブで、以下を構成します。
- Name: キューの目的を反映した説明的な名前 (例: 「Failed Evaluations Review - Q1 2026」)
- Project: このキューが属する Agent Observability プロジェクト
- Description (オプション): キューの目的やアノテーター向けの特別な指示を説明します
その後、Next をクリックします。
Schema タブで、新しいキューのラベルスキーマを定義します。ラベルを設定するときは、[Preview] ペインを使用して、アノテーターにラベルがどのように表示されるかを確認します。各ラベルを必須に設定でき、オプションで次の項目を追加できます。
- Assessment criteria: アノテーターがそのラベル値の合格/不合格を示せるようにします
- Reasoning: アノテーターが簡単な説明を追加できるようにします
キューの設定を確認し、Create をクリックしてキューを作成します。

ステップ 2: アアノテーション対象のトレースを選択

Trace Explorer から手動でトレースをキューに追加するか、Automation Rules を使用してキューにトレースを自動的に追加できます。

Trace Explorer から手動でキューにトレースを追加します。

AI Observability > Traces に移動します。
利用可能なファセット (評価結果、エラー状態、アプリケーション、時間範囲) を使用してトレースをフィルタリングします。
個別のトレースを選択するか、複数のトレースを一括選択します。
Flag for Annotation をクリックします。
Create New Queue を選択するか、既存のキューを選択します。

トレースを手動で選択する代わりに、Automation Rules を使用して、フィルターとサンプリング基準に基づいてトレースをアノテーションキューに自動的にルーティングします。これにより、手動でトレースを選択することなく、継続的にキューにデータを自動追加できます。サポートされているフィルターフィールドや制限事項など、機能の詳細については Automation Rules を参照してください。

自動化は以降適用されます。ルールに一致する新しいトレースは、到着するとキューにルーティングされます。フィルターに一致する既存のトレースは、遡って追加されません。

自動化ルールにアノテーションキューのアクションを追加するには、

AI Observability > Traces に移動します。
フィルターを適用して、ルーティングするトレース (評価の失敗、レイテンシーのしきい値、特定のアプリケーションなど) を特定します。使用可能なフィールドについては、Automation Rules > Supported filter fields を参照してください。
Automate Query をクリックします。
サンプリングレートを設定します (アノテーションキューの場合は最大 5%。例: 一致するトレースの 2%)。
Actions で、Add to Annotation Queue を選択します。
対象のキューを選択します。
ルールを保存します。

ルールのフィルターに一致するトレースは、到着するとキューに追加されます。アノテーションキューには最大 1,000 件のレコードを保持でき、キューが上限に達すると自動化が一時停止します。

トレースのアノテーション

キューへのアクセス

AI Observability > Experiment > Annotations に移動して、利用可能なすべてのアノテーションキューを表示します。キューをクリックしてトレースリストを表示し、Review をクリックしてアノテーションを開始します。

注: アノテーションタスクが新しく割り当てられると、Datadog はキュー名、割り当てたユーザー、および割り当てられたインタラクションを開くための直接リンクを含むメールを送信します。オプトアウトするには、個人設定のメール購読で Agent Observability のアノテーション割り当てメールを無効にします。

レビューモードには以下が表示されます。

Full trace context (右パネル):
- 入力、出力、メタデータを含む完全なスパンツリー
- ツール呼び出しと中間推論ステップ
- トレースおよび個々のスパンに関する評価結果
Annotation controls (左パネル):
- このキュー用に設定されたラベル
- キュー内の位置を示す進捗インジケーター
- ナビゲーションコントロール (前へ、次へ)

ラベルの適用

各トレースについて:

完全なトレースコンテキストを確認する: 必要に応じてスパンを展開し、入力、出力、ツール呼び出し、および評価結果を確認します。
ラベルを適用する: 評価に基づいて、設定されたラベルを入力します。
アノテーションは自動保存されます。

アノテーションのベストプラクティス

一貫性を保つ:

開始前に、キューの説明とラベルの定義を確認します。
複数のアノテーターが同じキューで作業する場合は、基準について共通認識を確立します。
判断が難しいケースについては、メモに理由を記録します。

理由を提示する:

特定のラベルを適用した理由を記録するために、自由形式のメモを使用します。
複数のトレースにわたって観察されるパターンをメモします。
理由を記録することで、評価基準を改善し、失敗モードを理解するのに役立ちます。

キューの管理

キューの進捗状況の追跡

[Annotations] リストページには、各キューの進捗バーが表示され、レビュー済みインタラクションと全インタラクションの比率が示されます。これを使用して、キュー全体のアノテーション完了状況を一目で確認できます。

キューアクセスの管理

キューの所有者は、キューの詳細からレビュー担当者リスト、アクセス設定、割り当てを管理します。キューの所有者のみが、レビュー担当者リスト、アクセス設定、または割り当てを変更できます。

アクセス制限は個別に適用されるため、いずれか一方または両方の制限を有効にできます。

レビュー担当者の制限により、未割り当てのインタラクションを指定されたレビュー担当者に限定します。
割り当て担当者の制限により、割り当て済みのインタラクションを割り当てられた担当者に限定します。
両方の制限が有効な場合、レビュー担当者は未割り当てのインタラクションにアノテーションを付け、割り当て担当者は自身に割り当てられたインタラクションにアノテーションを付けます。

キューの所有者はアクセス権を保持し、すべてのインタラクションにアノテーションを付けることができます。

アノテーションラベルによるトレースのフィルタリング

Annotation Labels ファセットを使用して、アノテーションキューで適用されたラベルに基づいてトレースをフィルタリングします。これにより、次のことが可能になります。

特定の失敗モード (例: failure_type: hallucination) でタグ付けされたすべてのトレースを検索します。
下流のレビュー、データセットの作成、またはデータ分析用の CSV エクスポートに使用する、対象を絞ったサンプルを作成します。

キューのスキーマの編集

作成後にキューのラベルスキーマを変更できます。

AI Observability > Experiment > Annotations に移動します。
キューを開きます。
[Details] パネルが非表示の場合は、View Details をクリックします。
Edit をクリックします。
ラベルの追加、削除、または変更を行います。
Save Changes をクリックします。

スキーマを変更しても、すでに適用されているラベルには影響しませんが、アノテーターには今後、更新されたスキーマが表示されます。

アノテーション付きデータのエクスポート

分析やほかのワークフローで使用するために、アノテーション付きトレースをエクスポートします。

AI Observability > Experiment > Annotations に移動します。
キューを開きます。
トレースを選択します (またはすべて選択します)。
Export をクリックします。

ファイルは annotations_<queue-id>.csv としてダウンロードされます。エクスポート API を使用して、プログラムからスパンデータを取得することもできます。

CSV 形式

各行は 1 つのアノテーション付きインタラクションを表します。ファイルは次の固定列で始まります。

列	説明
`Content ID`	アノテーション付きコンテンツの ID (トレース ID やセッション ID など)
`Type`	インタラクションタイプ: `trace`、`experiment_trace`、または `session`
`Input`	入力の概要 (セッションインタラクションの場合は空)
`Output`	出力の概要 (セッションインタラクションの場合は空)
`Expected Output`	Include Expected Output が有効な場合にのみ存在し、実験トレースに対してのみ入力されます。

固定列の後には、レビュアーごと、ラベルごとに 1 セットの列が続きます。レビュアーは表示名のアルファベット順に並べ替えられます (スペースはアンダースコアに置き換えられます)。ラベルは、キューのスキーマで定義された順序に従います。

列	説明
`{reviewer}_{label}`	ラベル値 (文字列、数値、Boolean、または JSON 配列)
`{reviewer}_{label}_assessment`	`pass` または `fail` (そのラベルに対して評価基準が有効な場合)
`{reviewer}_{label}_reasoning`	自由記述の理由 (そのラベルに対して理由の記述が有効な場合)

レビュアーが特定の行にアノテーションを付けていない場合、それらのセルは空になります。

例: レビュアーが Alice Johnson と Bob Smith、ラベルが quality (スコア) と failure_type (カテゴリ) であるキューでは、次のような列ヘッダーが生成されます。

Content ID,Type,Input,Output,Alice_Johnson_quality,Alice_Johnson_quality_assessment,Alice_Johnson_quality_reasoning,Alice_Johnson_failure_type,Alice_Johnson_failure_type_assessment,Alice_Johnson_failure_type_reasoning,Bob_Smith_quality,...

トレース ID またはセッション ID でスパンを取得する

アノテーションデータをエクスポートした後、エクスポート API を使用して CSV 内のトレースまたはセッションの完全なスパンデータを取得し、アノテーションラベルと結合します。

トレース ID 別:

curl -G "https://api.datadoghq.com/api/v2/llm-obs/v1/spans/events" \
  -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
  -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
  --data-urlencode "filter[trace_id]=<TRACE_ID>"

セッション ID 別:

curl -G "https://api.datadoghq.com/api/v2/llm-obs/v1/spans/events" \
  -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
  -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
  --data-urlencode "filter[query]=@session_id:<SESSION_ID>"

データセットへの追加

アノテーション付きトレースを実験評価用のデータセットに転送します。

AI Observability > Experiment > Annotations に移動します。
キューを開きます。
転送するトレースを選択します。
Add to Dataset をクリックします。
データセットの expected output を設定します。
- From interaction: 各トレースの実際の出力を使用します。実験トレースの場合、Expected output を選択して、実験のソースデータセットから元の期待出力を使用することもできます。
- From annotation label: アノテーターが適用した値を使用します。1 つ以上のラベルを選択します。レコードの expected_output は、選択内容に基づいて構築されます。
既存のデータセットを選択するか、データセットを作成します。

期待出力 がアノテーションラベルから構築される場合、エクスポートされる値はラベル名をキーとする JSON オブジェクトになります (例: { "is_harmful": false, "tone": ["neutral"], "topics": ["safety", "policy"] })。ラベルを1つ選択した場合でも、複数選択した場合でも、同じ形式が適用されます。カテゴリラベルは、シングルセレクトかマルチセレクトかに関わらず、常に選択されたオプションの配列としてエクスポートされます。

アノテーター間でアノテーション値を集計する方法

複数のアノテーターが同じトレースにアノテーションを付けた場合、各ラベルの値はコンセンサスによって集計されます。

ラベルタイプ	集計
Boolean	多数決 (同数の場合は `true` を優先)
カテゴリカル	積集合: すべてのアノテーターが選択したオプションのソート済みセット
スコア	平均
テキスト	回答リスト

カテゴリカルラベル (単一選択または複数選択) の場合、集計値はすべてのアノテーターが選択したオプションのソート済み配列となります。アノテーターの選択が 1 つでも異なる場合、値は空の配列となります。アノテーターが 1 名のみの場合でも、結果は常に配列となります。

**例: カテゴリカル (コンセンサス)。**3 名のアノテーターがtoneを評価し、全員が一致する場合、

アノテーター A: polite
アノテーター B: polite
アノテーター C: polite

集計結果: ["polite"]。

**例: カテゴリカル (不一致)。**3 名のアノテーターが tone を評価し、1 名が異なる場合、

アノテーター A: polite
アノテーター B: rude
アノテーター C: polite

集計結果: []。rude はすべてのアノテーターのセットに含まれていないため、積集合は空になります。

**例: カテゴリカル (複数選択)。**3 名のアノテーターがtopicsにタグ付けします (それぞれ複数のオプションを選択できます)。

アノテーター A: ["safety", "policy"]
アノテーター B: ["safety", "billing"]
アノテーター C: ["safety", "policy"]

集計結果: ["safety"]。safety のみがすべてのアノテーターのセットに含まれます。policy は B の選択に含まれず、billing は A と C の選択に含まれません。

**例: テキスト。**2 名のアノテーターがメモを残します。

アノテーター A: "Confusing phrasing"
アノテーター B: "Tone too casual"

集計結果: ["Confusing phrasing", "Tone too casual"]。すべてのアノテーターの値が保持されます。

アノテーターごとの生の値は、アノテーターの識別情報とともに各レコードのメタデータに保持されます。デフォルトのコンセンサスがワークフローに合わない場合は、別の戦略 (中央値、加重投票、レビュアーによる選択など) を使用して再計算できます。

期待出力として選択されなかったラベルも、メタデータとして各トレースに含まれます。

実験でのデータセットの使用に関する詳細については、データセットを参照してください。

キューの削除

キューを削除するには、

AI Observability > Experiment > Annotations に移動します。
キューを開きます。
[Details] パネルの Delete をクリックします。

キューを削除すると、キューとラベルの関連付けは削除されますが、Agent Observability の基盤となるトレースは削除されません。トレースは引き続き Trace Explorer でアクセスできます。

API の使用

アノテーションキューはプログラムで管理できます。以下のエンドポイントは Agent Observability API リファレンスで利用できます。

エンドポイント	説明
アノテーションキューの一覧表示	組織内のすべてのアノテーションキューを一覧表示します。
アノテーションキューの作成	アノテーションキューを作成します。`name` および `project_id` は必須です。作成時にラベルを定義するためのオプションの `annotation_schema` を含めます。
アノテーションキューの更新	キューの `name`、`description`、または `annotation_schema` を部分的に更新します。
アノテーションキューの削除	ID を指定してアノテーションキューを削除します。
キューにインタラクションを追加	レビューのために、1 つ以上のトレースをアノテーションキューに追加します。
キューからインタラクションを削除	インタラクション ID を指定して、キューから特定のインタラクションを削除します。
アノテーション付きインタラクションを取得	キューのすべてのインタラクションと、それらに適用されたアノテーションラベルを取得します。
ラベルスキーマを取得	キュー用に構成されたラベルスキーマを取得します。
ラベルスキーマの更新	キューのラベルスキーマを作成または置換します。