> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# フィードバックを収集し、アノテーションを活用する

> UI と SDK を通じて LLM アプリケーションのフィードバックを収集・分析する

LLM アプリケーションを効率的に評価するには、フィードバックを収集して分析するための堅牢なツールが必要です。W\&B Weave は統合されたフィードバックシステムを備えており、ユーザーは UI から直接、または SDK を通じてプログラムから Call に対するフィードバックを提供できます。絵文字のリアクション、テキストコメント、構造化データなど、さまざまな種類のフィードバックがサポートされており、チームは次のことを行えます。

* パフォーマンス監視のための評価用データセットを構築する。
* LLM のコンテンツに関する問題を効果的に特定して解決する。
* ファインチューニングのような高度なタスク向けの例を収集する。

このガイドでは、UI と SDK の両方で Weave のフィードバック機能を使用する方法、フィードバックをクエリして管理する方法、さらに詳細な評価のために人によるアノテーションを使用する方法について説明します。

* [UI でフィードバックを提供する](#provide-feedback-in-the-ui)
* [SDK を通じてフィードバックを提供する](#provide-feedback-through-the-sdk)
* [人によるアノテーションを追加する](#add-human-annotations)

<div id="provide-feedback-in-the-ui">
  ## UI でフィードバックを送信する
</div>

Weave UI では、[Call details パネルから](#from-the-call-details-panel)または[アイコンを使用して](#use-the-icons)、フィードバックを追加したり表示したりできます。

<div id="from-the-call-details-panel">
  ### Call details パネルから
</div>

1. Weave プロジェクトのサイドバーで、**Traces** にアクセスします。
2. フィードバックを追加する Call の行を見つけます。
3. リンクされた Trace 名をクリックして、トレース ツリーと Call details パネルを開きます。
4. Call details のタブバーで、**Feedback** を選択します。
5. フィードバックを追加、表示、または削除します。
   * Call details のフィードバックビューの右上にあるアイコンを使って、*フィードバックを追加または表示します*。
   * *Call details のフィードバック表でフィードバックを表示または削除します。* 該当するフィードバック行の一番右の列にあるごみ箱アイコンをクリックして、フィードバックを削除します。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback_tab.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=49554ca5e7e2d2ad476ac5537db7de75" alt="Call details の Feedback タブのスクリーンショット" width="1266" height="548" data-path="weave/guides/tracking/imgs/feedback_tab.png" />
</Frame>

<div id="use-the-feedback-icons">
  ### フィードバックアイコンを使用する
</div>

Traces 表と各 Call details パネルにあるアイコンを使って、リアクションの追加や削除、メモの追加を行えます。

* *Traces 表*: **Traces** 表の該当する行の **Feedback** 列にあります。
* *Call details パネル*: 各 Call details パネルの右上にあります。

リアクションを追加するには:

1. 絵文字アイコンをクリックします。
2. サムズアップ、サムズダウンを追加するか、さらに絵文字を表示するには **+** アイコンをクリックします。

リアクションを削除するには:

1. 削除したい絵文字リアクションにカーソルを合わせます。
2. そのリアクションをクリックして削除します。

> [Call details パネルの **Feedback** 列](#from-the-call-details-panel)からフィードバックを削除することもできます。

コメントを追加するには:

1. コメントの吹き出しアイコンをクリックします。
2. テキストボックスにメモを入力します。フィードバックメモの最大文字数は 1024 文字です。
3. メモを保存するには、**Enter** キーを押します。メモは追加で入力できます。

<Warning>
  フィードバックメモの最大文字数は 1024 文字です。メモがこの上限を超えると、作成されません。
</Warning>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback_calls.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=8c42c705d075fbad79a6a5b5cb1de321" alt="フィードバック列がある calls グリッドのスクリーンショット" width="3170" height="1589" data-path="weave/guides/tracking/imgs/feedback_calls.png" />
</Frame>

<div id="provide-feedback-through-the-sdk">
  ## SDK を使用してフィードバックを送信する
</div>

フィードバックに関する SDK の使用例は、UI の Call details パネルにある **Use** タブで確認できます。

Weave Python SDK を使用すると、call に対してプログラムから [追加](/ja/weave/reference/python-sdk/trace/feedback#method-add)、[削除](/ja/weave/reference/python-sdk/trace/feedback#method-purge)、および[フィードバックのクエリ](/ja/weave/reference/python-sdk/trace/weave_client#method-get_feedback)を実行できます。TypeScript SDK は現在、フィードバック機能をサポートしていません。

<div id="query-a-projects-feedback">
  ### プロジェクトのフィードバックをクエリする
</div>

SDK を使用して、Weave プロジェクトのフィードバックをクエリできます。SDK は、次のフィードバックのクエリ操作をサポートしています。

* `client.get_feedback()`: プロジェクト内のすべてのフィードバックを返します。
* `client.get_feedback("<feedback_uuid>")`: `<feedback_uuid>` で指定した特定のフィードバックオブジェクトをコレクションとして返します。
* `client.get_feedback(reaction="<reaction_type>")`: 特定のリアクションタイプのすべてのフィードバックオブジェクトを返します。

`client.get_feedback()` では、各フィードバックオブジェクトについて次の追加情報も取得できます。

* `id`: フィードバックオブジェクトの ID。
* `created_at`: フィードバックオブジェクトの作成時刻情報。
* `feedback_type`: フィードバックのタイプ (reaction、note、custom) 。
* `payload`: フィードバックのペイロード。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    # プロジェクト内のすべてのフィードバックを取得します
    all_feedback = client.get_feedback()

    # ID で特定のフィードバックオブジェクトを取得します。
    # API はコレクションを返し、最大で 1 件の項目が含まれる想定です。
    one_feedback = client.get_feedback("<feedback_uuid>")[0]

    # 特定のリアクションを持つすべてのフィードバックオブジェクトを取得します。offset と limit を指定できます。
    thumbs_up = client.get_feedback(reaction="👍", limit=10)

    # 取得後、各フィードバックオブジェクトの詳細を表示します。
    for f in client.get_feedback():
        print(f.id)
        print(f.created_at)
        print(f.feedback_type)
        print(f.payload)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能はまだ TypeScript では利用できません。
    ```
  </Tab>
</Tabs>

<div id="add-feedback-to-a-call">
  ### Call にフィードバックを追加する
</div>

Call の UUID を使って、Call にフィードバックを追加できます。UUID を使って特定の Call を取得するには、[Call の実行中または実行後に UUID を取得](#retrieve-the-call-uuid)してください。SDK では、Call にフィードバックを追加するために次の操作をサポートしています。

* `call.feedback.add_reaction("<reaction_type>")`: 👍 など、サポートされている `<reaction_types>` (絵文字) を 1 つ追加します。
* `call.feedback.add_note("<note>")`: ノートを追加します。
* `call.feedback.add("<label>", <object>)`: `<label>` で指定したカスタム フィードバック `<object>` を追加します。

<Warning>
  フィードバックノートの最大文字数は 1024 文字です。この上限を超えるノートは作成されません。
</Warning>

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    client = weave.init('intro-example')

    call = client.get_call("<call_uuid>")

    # 絵文字リアクションを追加
    call.feedback.add_reaction("👍")

    # ノートを追加
    call.feedback.add_note("this is a note")

    # カスタムのキー/値ペアを追加します。
    # 最初の引数はユーザー定義の "type" 文字列です。
    # フィードバックは JSON でシリアライズ可能であり、シリアライズ後のサイズが 1 KB 未満である必要があります。
    call.feedback.add("correctness", { "value": 5 })
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能は TypeScript ではまだ利用できません。
    ```
  </Tab>
</Tabs>

<div id="retrieve-the-call-uuid">
  #### Call UUID を取得する
</div>

Call の直後にフィードバックを追加する必要がある場合は、Call の実行中または実行後に、プログラムで Call UUID を取得できます。

<div id="during-call-execution">
  ##### Call 実行中
</div>

Call 実行中に UUID を取得するには、現在の Call を取得し、その ID を返します。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}

    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        # 単純な処理を実行
        output = f"Processed {input_value}"
        # 現在の Call ID を取得
        current_call = weave.require_current_call()
        call_id = current_call.id
        return output, call_id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能は TypeScript ではまだ利用できません。
    ```
  </Tab>
</Tabs>

<div id="after-call-execution">
  ##### Call 実行後
</div>

また、`call()` method を使用して operation を実行し、Call の実行後に ID を取得することもできます。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    weave.init("uuid")

    @weave.op()
    def simple_operation(input_value):
        return f"Processed {input_value}"

    # operation を実行し、結果と call ID を取得する
    result, call = simple_operation.call("example input")
    call_id = call.id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能は TypeScript ではまだ利用できません。
    ```
  </Tab>
</Tabs>

<div id="delete-feedback-from-a-call">
  ### call からフィードバックを削除する
</div>

UUID を指定すると、特定の call からフィードバックを削除できます。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    call.feedback.purge("<feedback_uuid>")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能は、TypeScript ではまだ利用できません。
    ```
  </Tab>
</Tabs>

<div id="add-human-annotations">
  ## 人によるアノテーションを追加する
</div>

人によるアノテーションは Weave UI でサポートされています。この機能を使用すると、フィードバックとして追加する人手入力のデータ用に、トレースにカスタムフィールドを作成できます。人によるアノテーションを行うには、まず [UI](#create-a-human-annotation-scorer-in-the-ui) または [API](#create-a-human-annotation-scorer-using-the-api) を使用して Human Annotation スコアラーを作成する必要があります。その後、[UI でそのスコアラーを使用してアノテーションを作成](#use-the-human-annotation-scorer-in-the-ui) したり、[API を使用してアノテーションスコアラーを変更](#modify-a-human-annotation-scorer-using-the-api) したりできます。

<div id="create-a-human-annotation-scorer-in-the-ui">
  ### UI で Human Annotation スコアラーを作成する
</div>

UI で Human Annotation スコアラーを作成するには、次の手順に従います。

1. プロジェクトのサイドバーで、**Assets** にアクセスします。
2. Assets のナビゲーションパネルで、**Scorers** をクリックします。
3. **Scorers** パネルのヘッダーで、**New scorer** をクリックします。
4. **Create Scorer** モーダルダイアログで、次の項目を設定します。
   * `Scorer type` を `Human annotation` に設定
   * `Name`
   * `Description`
   * `Type`。`boolean` や `integer` など、収集するフィードバックのタイプを指定します。
5. **Create scorer** をクリックします。これで、スコアラーを使用してアノテーションを付けられます。

次の例では、人手アノテーターに、LLM が取り込んだドキュメントの種類を選択するよう求めています。そのため、スコア設定で選択する `Type` は、指定可能なドキュメントタイプを含む `enum` です。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/human-annotation-scorer-form.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=7e9dc934d3690d8347bc6d554ebfaf90" alt="Create Scorer モーダルダイアログ" width="3454" height="1862" data-path="weave/guides/tracking/imgs/human-annotation-scorer-form.png" />
</Frame>

<div id="use-the-human-annotation-scorer-in-the-ui">
  ### UI で Human Annotation スコアラーを使用する
</div>

Human Annotation スコアラーを作成すると、Traces ページで使用できるようになります。

スコアラーを使用するには、次の手順を実行します。

1. プロジェクトのサイドバーで、**Traces** にアクセスします。

2. Human Annotation を追加する対象の Call の行を見つけます。

3. リンクされた Trace 名をクリックして、トレース ツリーと Call details パネルを開きます。

4. Call details タブバーの右上で、**Show feedback** ボタンをクリックします。

   <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/marker-icon.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=5c07617fa8509b6f690d83e05b321e0f" alt="Call ヘッダーのマーカー アイコン" width="306" height="84" data-path="weave/guides/tracking/imgs/marker-icon.png" />

   使用可能な Human Annotation スコアラーが、追加の **Annotate** パネルに表示されます。

   <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/full-feedback-sidebar.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=1ab04225479083b7a0f23f99acae8e59" alt="Human Annotation スコアラーのフィードバック パネル" width="3454" height="1862" data-path="weave/guides/tracking/imgs/full-feedback-sidebar.png" />

5. アノテーションを追加します。

6. **Save** をクリックします。

7. Call details パネルのタブバーで、**Feedback** タブをクリックして Feedback 表を表示します。新しいアノテーションが表に表示されます。メインの Traces 表の **Annotations** 列でもアノテーションを確認できます。

   > 最新の情報を表示するには、Traces 表を更新してください。

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/feedback-in-the-table.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=ad77b9b864bc8d5978b4da2f98aa067b" alt="Traces 表での Human Annotation スコアラーのフィードバック" width="3456" height="1569" data-path="weave/guides/tracking/imgs/feedback-in-the-table.png" />
</Frame>

<div id="create-a-human-annotation-scorer-using-the-api">
  ### API を使用して Human Annotation スコアラーを作成する
</div>

API 経由で Human Annotation スコアラーを作成することもできます。各スコアラーはそれぞれ独立したオブジェクトで、個別に作成・更新します。プログラムから Human Annotation スコアラーを作成するには、次の手順を実行します。

1. `weave.flow.annotation_spec` から `AnnotationSpec` クラスをインポートします。
2. `weave` の `publish` method を使用してスコアラーを作成します。

次の例では、2 つのスコアラーを作成しています。1 つ目のスコアラー `Temperature` は、LLM call の知覚温度をスコアリングするために使用します。2 つ目のスコアラー `Tone` は、LLM response のトーンをスコアリングするために使用します。各スコアラーは、対応するオブジェクト ID (`temperature-scorer` と `tone-scorer`) を指定して `save` を使用して作成されます。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    spec1 = AnnotationSpec(
      name="Temperature",
      description="The perceived temperature of the llm call",
      field_schema={
        "type": "number",
        "minimum": -1,
        "maximum": 1,
      }
    )
    spec2 = AnnotationSpec(
      name="Tone",
      description="The tone of the llm response",
      field_schema={
        "type": "string",
        "enum": ["Aggressive", "Neutral", "Polite", "N/A"],
      },
    )
    weave.publish(spec1, "temperature-scorer")
    weave.publish(spec2, "tone-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能はまだ TypeScript では利用できません。
    ```
  </Tab>
</Tabs>

<div id="modify-a-human-annotation-scorer-using-the-api">
  ### API を使用して Human Annotation スコアラーを更新する
</div>

[API を使用して Human Annotation スコアラーを作成する](#create-a-human-annotation-scorer-using-the-api)の続きとして、次の例では `publish` 時に元のオブジェクト ID (`temperature-scorer`) を使用し、`Temperature` スコアラーの更新版を作成します。これにより、すべてのバージョンの履歴を持つ更新済みオブジェクトが作成されます。

> Human Annotation スコアラーのオブジェクト履歴は、**Human annotations** 配下の **Scorers** タブで確認できます。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave
    from weave.flow.annotation_spec import AnnotationSpec

    client = weave.init("feedback-example")

    # スコアラーの新しいバージョンを作成
    spec1 = AnnotationSpec(
      name="Temperature",
      description="llm call の体感温度",
      field_schema={
        "type": "integer",  # <<- タイプを integer に変更
        "minimum": -1,
        "maximum": 1,
      }
    )
    weave.publish(spec1, "temperature-scorer")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```plaintext theme={null}
    この機能はまだ TypeScript では利用できません。
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541-docs-hivemind-launch/IJ5wvwHtTZtWc35M/weave/guides/tracking/imgs/human-annotation-scorer-history.png?fit=max&auto=format&n=IJ5wvwHtTZtWc35M&q=85&s=b440c54573c619f63db4626f6a99a0e6" alt="Human Annotation スコアラーの履歴" width="2686" height="1434" data-path="weave/guides/tracking/imgs/human-annotation-scorer-history.png" />
</Frame>

<div id="use-a-human-annotation-scorer-using-the-api">
  ### API を使用して Human Annotation スコアラーを利用する
</div>

feedback API では、特別な形式の名前と `annotation_ref` フィールドを指定することで、Human Annotation スコアラーを使用できます。`annotation_spec_ref` は、UI で該当するタブを選択して取得するか、`AnnotationSpec` の作成時に取得できます。

<Tabs>
  <Tab title="Python">
    ```python lines theme={null}
    import weave

    client = weave.init("feedback-example")

    call = client.get_call("<call_id>")
    annotation_spec = weave.ref("<annotation_spec_ref_uri>")

    call.feedback.add(
      feedback_type="wandb.annotation." + annotation_spec.name,
      payload={"value": 1},
      annotation_ref=annotation_spec.uri(),
    )
    ```
  </Tab>
</Tabs>