メインコンテンツへスキップ

概要

このガイドでは、Weave でアノテーションキューを設定し、選択したトレースについてドメインエキスパートから構造化されたフィードバックを収集する方法を説明します。評価、失敗分析、またはデータセット作成のために専門家によるラベル付きデータが必要な場合は、アノテーションキューを使用してください。アノテーションキューを使用すると、レビュー担当者は Weave UI 全体ではなく、厳選されたトレースのセットに集中することもできます。 アノテーションキューを使用すると、選択したトレースをドメインエキスパート向けに振り分け、フル機能の Weave UI を操作しなくても体系的なレビューを行えます。収集するフィードバックの内容を定義し、レビューが必要なトレースを選択して、完了したアノテーションを後から分析やデータセット作成のためにエクスポートできます。主なユースケースは次のとおりです。
  • 手動でのトレース評価: 専門家 (SME) に、モデル出力の正確性、品質、スタイルを評価してもらいます。
  • 失敗分析: 失敗モード (ハルシネーション、拒否、ループ) にアノテーションを付けて、モデルがどこで問題を起こすかを把握します。
  • ドメインエキスパートによるレビュー: 医療、法務、安全性の専門家が、タスクに特化したインターフェースで内容をレビューできるようにします。
  • データセット作成: アノテーション付きトレースを、評価用またはトレーニング用のデータセットに変換します。

エンドツーエンドのワークフロー

以下のワークフローは、アノテーションキューを使用してレビューを取得する流れをまとめたものです。以下のセクションでは、各ステップを詳しく説明します。
  1. アノテーションフィールドを定義します。
  2. アノテーションキューを作成します。
  3. レビュー用にトレースをキューに読み込みます。
  4. ドメインエキスパートによるレビューの進行状況を監視します。
  5. 完了したアノテーションをフィルターし、エクスポートします。

アノテーションフィールドを定義する

アノテーションキューを作成する前に、まずアノテーションフィールドを定義します。そうすることで、キューのセットアップ時にフィールドを選択できるようになります。アノテーションフィールドは、各トレース項目に対してアノテーターが入力するフィードバックを定義します。フィールドはキューやプロジェクト間で再利用できます。 フィールドタイプには、次のものがあります。
  • 正確性や許容可否などのブール値による判定。
  • 品質や信頼度などの数値または整数値。
  • 失敗モードや意図などのカテゴリラベル。
  • 定性的なフィードバック用の自由記述テキスト。
アノテーションフィールドを作成するには、次の手順に従います。
  1. wandb.ai にアクセスし、プロジェクトを選択します。
  2. Weave プロジェクトのサイドバーで、Annotate をクリックします。Annotate が表示されない場合は、More のメニュー内にある可能性があります。
  3. タブバーで、Fields タブをクリックします。
  4. Fields 表のツールバーで、New Field をクリックします。
  5. Create annotation field モーダルダイアログで、次を設定します。
    • Type: Boolean、Integer、Number、String、またはカテゴリオプション。
    • Name: アノテーターに表示するフィールド名。
    • Description (任意) : このフィールドを評価する際の詳細。アノテーターに表示されます。
  6. Create annotation field をクリックしてフィールドを保存します。
名前、説明、フィールドタイプの入力欄を含むアノテーションフィールド作成ダイアログ。トレース項目をレビューする際にアノテーターが入力するスキーマを定義するために使用されます。
新しいフィールドは Fields タブに表示され、プロジェクト内の任意のアノテーションキューに追加できます。
アノテーションの一貫性を保つため、フィールドは作成後に編集できません。

アノテーションキューを作成する

アノテーションフィールドを定義したら、次のステップは、アノテーターが作業に使用するキューを作成することです。 アノテーションキューは、次の要素で構成されます。
  • アノテーションフィールドのセット
  • アノテーター向けの作業指示を記載したガイドライン
  • レビュー待ちのトレース項目のコレクション
アノテーションキューを作成するには、次の手順を実行します。
  1. Weave プロジェクトのサイドバー で Annotate をクリックします。
  2. タブバーで Queues タブをクリックします。
  3. Queues 表のツールバーで Create Queue をクリックします。
  4. Create Annotation Queue モーダルダイアログで、以下を設定します。
    • Queue name: アノテーターが作業を完了する際に選択するキュー名です。
    • Guidelines (任意): アノテーター向けの追加指示です。
  5. Next をクリックします。
  6. Manage fields をクリックし、このレビュー作業に含めるアノテーションフィールドを選択します。プロジェクト内の既存のすべてのアノテーションフィールドを選択できます。
  7. キューに含めるすべてのフィールドを選択したら、Create Queue をクリックしてキューを保存します。
プロジェクト内のすべてのアノテーションキューは、Annotation Queues ページに一覧表示されます。
プロジェクト内のキュー名、説明、レビューの進捗を含むキューの表を表示し、アノテーションのワークフローをトラッキングする Annotation Queues ページ。
アノテーションキューを作成すると、評価用のフィールドとガイドラインが定義されます。ただし、評価するデータを特定するには、引き続きキューにトレースを追加する必要があります。

キューにトレースを追加する

キューを作成したら、次にレビュー対象にする特定のトレースを追加します。Traces ページから、トレースを アノテーションキュー に直接追加できます。 アノテーションキュー にトレースを追加するには、次の手順に従います。
  1. Weave プロジェクトのサイドバーで、Traces をクリックします。
  2. Traces 表のツールバーで、必要に応じてトレースをフィルターします (例: hallucination スコア、failure mode、特定の op) 。
  3. 表で、アノテーション対象にするトレースを選択します。
  4. 表のアクションバーで、Add to queue をクリックして、選択した行を アノテーションキュー に追加します。
複数の行が選択された Traces 表と、Add to queue や Add to dataset など、選択した行に適用できるアクションを表示する一括アクションバー。
  1. Add to annotation queue モーダルダイアログで、次を設定します。
    • Queue Name: リストで、これらのトレースの追加先となる既存のキュー名を選択します。
    • Select trace data to display: 結果の評価時に アノテーター に表示する Weave の Trace Data 要素を選択します。
      • Inputs: アノテーション時に表示する trace の入力フィールドを選択します。
      • Outputs: アノテーション時に表示する trace の出力フィールドを選択します。
  2. Add [COUNT] traces to annotation queue をクリックして、これらのトレースを アノテーションキュー レビューの一部として割り当てます。
トレースを追加する際は、レビュー対象にする trace の入力項目と、出力またはモデルの応答を制御できるため、アノテーター には正確に判断するために必要なコンテキストだけが表示されます。

レビューの進捗を確認する

トレースが追加されると、アノテーター は作業を開始でき、レビューの進捗を確認できます。アノテーター がレビューを開始できるようにキュー名を共有します。レビュー プロセスの詳細については、アノテーションキュー 内の項目をレビューするを参照してください。 アノテーター に アノテーションキュー への直接リンクを共有するには、次の手順に従います。
  1. Weave プロジェクトのサイドバー で、Annotate をクリックします。
  2. タブバーで、Queues タブをクリックします。
  3. Annotation Queues 表で、キュー項目を開くには対象のキュー名をクリックします。
  4. Queue のヘッダーバーで、link ボタンをクリックしてこのキューへの直接リンクをコピーします。ブラウザーのアドレスバーから URL をコピーすることもできます。
Annotation Queue のヘッダーバーで アノテーションキュー へのリンクをコピーする
Annotation Queues 表では、State 列にレビューの進捗が表示されます。
  • 未開始: キューには項目がありますが、annotation はまだ 1 件も送信されていません。
  • 進行中: 少なくとも 1 つの項目がレビューされています。
  • 完了: すべての項目がレビューされています。
Annotation Queues 表では、Calls with responses 列に、少なくとも 1 件のレビューが送信された項目の割合 (Calls の総数に対する割合) が表示されます。

アノテーションのフィルタリングとエクスポート

アノテーターがレビューを送信すると、その結果得られたフィードバックを分析、評価、またはトレーニングに使用できます。Weave は、完了したアノテーションをトレースの構造化メタデータとして保存します。 できること:
  • キューへの割り当てとアノテーションの完了状況でトレースをフィルターできます。
  • フィルターしたビューを再利用できるように保存できます。
  • アノテーション付きトレースを、評価やトレーニングのワークフロー向けにデータセットへエクスポートできます。
これにより、専門家によるフィードバックをモデルの評価と改善サイクルに直接つなげられます。

注釈付きトレースをフィルターする

Traces ページのフィルターコントロールを使用すると、注釈付きのトレースのみを表示できます。 注釈付きのトレースのみを表示するには、次の手順に従います。
  1. Weave プロジェクトのサイドバーで、Traces をクリックします。
  2. Traces 表のツールバーで、Filter をクリックします。
  3. フィルター行に 3 つの値を追加します。
    • Column に「Queue」と入力し、Enter キーを押します。
    • 2 つ目のリストで、Text: “is” を選択します。
    • Select a queue で、アノテーションキュー名を選択します。
  4. さらに「completed」のキュー項目のみに絞り込むには、+ Add Filter をクリックします。
    • Column に「feedback」と入力します。ダイアログに annotations が表示され、annotation field 名が含まれます。キューから必須の field を選択します。
    • 2 つ目のリストで、Other: “is not empty” を選択します。
特定の注釈キューに属するトレースを選択するフィルターを設定している Traces 表。
  1. フィルター行は自動的に適用されます。フィルターエントリを閉じるには、ページ上の別の場所をクリックします。
  2. 任意: すばやくアクセスできるよう、ビューとして保存します。Traces 表のヘッダーで、Save View をクリックします。

注釈付きトレースをデータセットにエクスポートする

データの使用目的に応じて、注釈付きトレースは UI またはプログラムからエクスポートできます。

注釈付きトレースをデータセットに追加する

注釈付きトレースを選択し、データセットに追加をクリックすると、評価用またはトレーニング用データに専門家によるラベルを含めることができます。 注釈付きトレースをデータセットに追加するには、次の手順に従います。
  1. Weaveプロジェクトのサイドバーで、トレースをクリックします。
  2. トレースの表で、エクスポートするトレースを選択します。
  3. 表のツールバーで、データセットに追加をクリックします。画面の指示に従って追加を完了します。
データセットの使用方法について詳しくは、データセットの収集とトラッキングを参照してください。

プログラムからアノテーションにアクセスする

UI ワークフローに加えて、アノテーションデータはプログラムから読み取ることもできます。これは、分析の自動化、カスタム report の作成、アノテーションの後続パイプラインへの統合に役立ちます。アノテーションをプログラムから利用するには、プロジェクト名とキュー ID を把握しておく必要があります。
  • Project: W&B のプロジェクト名 (project または team/project を指定できます) 。W&B のチーム (team/project のような形式) を指定しない場合は、デフォルトのチームが使用されます。
  • Queue ID: アノテーションキューの一意の ID。
キュー ID を検索するには:
  1. Annotation Queues 表で、キューの名を選択してそのアイテムを開きます。
  2. ページ URL の末尾から ID をコピーします。
https://wandb.ai/.../annotation-queues/019c0f63-7acb-7497-8f87-08873368fcd4
この例でのキュー ID は次のとおりです。 019c0f63-7acb-7497-8f87-08873368fcd4 次のコードを使用すると、キュー内のトレース (Call) を順に処理できます。
import weave
from weave.trace_server.trace_server_interface import AnnotationQueueItemsQueryReq

# project とキューの識別子を実際の値に更新してください。
PROJECT = "your-team-name/your-project-name"
QUEUE_ID = "019c0f63-7acb-7497-8f87-08873368fcd4"

# Weave を初期化します。
client = weave.init(PROJECT)

# キュー内の Call から Call ID を取得します。
calls = client.server.annotation_queue_items_query(
    AnnotationQueueItemsQueryReq(
        project_id=PROJECT,
        queue_id=QUEUE_ID,
    )
)

# Call を反復処理して feedback を取得します。
for i, item in enumerate(calls.items):
    call = client.get_call(call_id=item.call_id, include_feedback=True)
    feedback = call.feedback or {}

    # Call の feedback アイテム数を集計します。
    total_feedback_items = len(feedback)

    print(f"\nItem {i}, call_id: {item.call_id}, total feedback items: {total_feedback_items}")

    if not feedback:
        print("No feedback for item")
        continue

    # 最初のアノテーション値を取得します。
    # フィールドのアノテーションは一定の順序で追加されないため、最初のフィールドは毎回異なる場合があります。
    field_name = next(iter(feedback))
    field_value = feedback[0]

    print(f"  {field_name}: {field_value}")
次の Google Colab ノートブックでは、アノテーション データにプログラムでアクセスし、分析レポートを収集する方法を詳しく示しています。