> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# メタデータとトレース

> W&B entity を選択し、会話のアイデンティティを維持して、検索可能なコンテキストを付加します。

標準のチャット補完 `metadata` オブジェクトに、プロキシ制御とトレース属性を含めます。このページでは、会話のアイデンティティを維持し、会話全体をサンプリングして、生成される project のトレースを理解する方法を説明します。

<h2 id="reserved-metadata">
  予約済みメタデータ
</h2>

| キー | タイプ | 目的 |
| - | - | - |
| `wandb.entity` | 空でない `string` | project またはプロバイダーを所有するチームまたは個人の entity を選択します |
| `wandb.thread_id` | 空でない `string` | ルーティングの一貫性を保つために推奨される会話識別子 |
| `gen_ai.conversation.id` | 空でない `string` | W\&B のスレッド ID がない場合に使用される、セマンティック規約に基づく会話識別子 |
| `wandb.turn_index` | 負でない `integer` | リプレイ時に、信頼できるソースのターンインデックスを保持します |
| `wandb.project` | `project` または `entity/project` | この送信先で、プロバイダーへの直接 Call のトレースを有効にします |
| `wandb.trace_surface` | `spans`、`calls`、または `both` | トレースが有効な直接 Call に限り、トレースサーフェスを上書きします |
| `user.id` | 空でない `string` | エンドユーザーのアイデンティティをトレースに付加します |
| `wandb.call_shadow` | `boolean` | project にルーティングされたリクエストについて、エージェント スパン に加えて Weave Call もログする。この場合、トレースのストレージが重複します |

`wandb.*` キーはルーティングとログを制御します。プロキシは、プロバイダーにリクエストを送信する前にこれらのキーを削除します。それ以外のメタデータは、プロキシがそのままプロバイダーに転送します。表現可能な場合は、そのメタデータもトレースに追加されます。

<h2 id="conversation-precedence">
  会話の優先順位
</h2>

プロキシは最初に利用可能な識別子を選択します：

1. `wandb.thread_id`
2. `gen_ai.conversation.id`
3. Vapi `call.id`

アプリケーション内の会話で、すべてのプロバイダーへのCallに同じ値を使用してください。これにより、トレースの閲覧が改善され、1つの会話が複数のデータセット分割にまたがるのを防ぎ、重み付きルーティングを安定させます。

<h2 id="sample-complete-conversations">
  会話全体をサンプリングする
</h2>

会話単位のトレースサンプリングを使用すると、会話の一部だけを残すことなく、W\&B Weave に保存する project のトラフィック量を削減できます。リクエスト単位のサンプリングでは、一部のターンだけが保存され、前後のコンテキストが失われる場合があります。その結果、保存されたデータはデバッグやデータセットの作成に役立ちにくくなります。

project のサンプリングを設定するには、次の手順を実行します。

1. Model Distillation で、project の **Routing** ページを開きます。
2. **Models and traffic** で、**Weave trace sampling** に保存する会話の割合を設定します。
3. **Save routing** を選択します。

ルーティング設定を保存すると、プロキシは指定した割合で会話単位のトレースサンプリングを行います。

会話のアイデンティティを持つリクエストについては、プロキシは W\&B entity、Model Distillation の project、会話 ID に基づいて、会話を固定のサンプリンググループに割り当てます。デフォルトのサンプリング率は 100% です。プロキシは、そのアイデンティティを持つすべてのリクエストを保存するか、すべてスキップします。サンプリングの決定は、モデル選択やルーティングのリビジョンには左右されません。トレースをスキップしても、プロキシは推論の応答を返します。

プロキシは、会話のアイデンティティを持たないリクエストを常に保存します。割合を変更すると保存される会話が変わる可能性があるため、実行中の会話の有効期間中はサンプリングの割合を一定に保ってください。

<Accordion title="API: 会話のトレースサンプリングを設定する (PUT /tasks/[PROXY-MODEL-NAME]/routing)">
  Model Distillation を使用せずに会話単位のトレースサンプリングを設定するには、ルーティング API を使用します。

  `[PROXY-MODEL-NAME]` をプロキシモデル名に、`[WANDB-ENTITY]` を W\&B entity に、`[MODEL-REF]` を既存のターゲットモデル参照に置き換えます。

  `trace_sampling_rate` に `0` から `1` までの値を設定します。ルーティングを更新すると設定全体が置き換えられるため、リクエストには既存のターゲットをすべて含めてください。

  ```bash theme={"system"}
  curl --request PUT \
    --url "https://distillation.training.wandb.ai/v1/tasks/[PROXY-MODEL-NAME]/routing" \
    --header "Authorization: Bearer $WANDB_API_KEY" \
    --header "Wandb-Entity: [WANDB-ENTITY]" \
    --header "Content-Type: application/json" \
    --data '{
      "trace_sampling_rate": 0.1,
      "targets": [
        {"model_ref": "[MODEL-REF]", "weight": 1}
      ]
    }'
  ```

  別の project バージョンの場合は、`PUT /v1/tasks/[PROXY-MODEL-NAME]/versions/[PROJECT-VERSION]/routing` を使用します。`[PROXY-MODEL-NAME]` をプロキシモデル名に、`[PROJECT-VERSION]` を project のバージョンに置き換えます。設定が有効になったと判断する前に、新しいルーティングのリビジョンでデプロイメントのステータスが **Applied** になるまで待ってください。
</Accordion>

<h2 id="project-trace-contents">
  Project trace contents
</h2>

project トレースは、以下のルーティング、リクエスト、応答、およびメタデータの詳細を取得します：

* プロジェクト ID (UUID)、プロキシモデル名、およびバージョン
* ルーティングリビジョンおよび選択されたプロバイダーとモデル
* プロキシがプロバイダーに送信する正確なリクエストと、プロキシが再構成する応答。
* トークン使用量、完了理由、タイミング、およびエラーステータス
* 応答が [exact-response cache](/ja/model-distillation/proxy/response-caching) (`cache_hit`) から再生されたかどうか
* 会話、ユーザー、シナリオ、および安全なカスタムメタデータ
* トレース出力のサポートおよび比較のためのプロキシリクエスト ID

正規のエージェントスパンには、詳細を保持するためのリクエストと応答の生コピーが含まれます。データセットの再構成は、正規化された表示列のみに依存しません。

<Warning>
  メッセージやメタデータに認証情報、シークレット、または不要な個人データを入れないでください。トレースデータは、意図的に永続的なトレーニングおよびデバッグ用の入力です。
</Warning>

<Accordion title="API: 会話のアイデンティティ付きでリクエストを送信する (POST /chat/completions)">
  `[PROXY-MODEL-NAME]` をプロキシモデル名に、`[WANDB-ENTITY]` を W\&B entity に、`[CONVERSATION-ID]` を会話の識別子に置き換えてください。

  1 つの会話内のすべてのターンで同じ `wandb.thread_id` を保持します：

  ```bash theme={"system"}
  curl --request POST \
    --url "https://proxy.training.wandb.ai/v1/chat/completions" \
    --header "Authorization: Bearer $WANDB_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "[PROXY-MODEL-NAME]",
      "messages": [{"role": "user", "content": "Classify this request"}],
      "metadata": {
        "wandb.entity": "[WANDB-ENTITY]",
        "wandb.thread_id": "[CONVERSATION-ID]"
      }
    }'
  ```

  プロキシはプロバイダーへのリクエスト送信前に予約済みの `wandb.*` 値を削除します。[ルーティングされたチャット補完を作成する](/ja/model-distillation/reference/proxy/chat-completions/create-a-routed-chat-completion) を参照してください。
</Accordion>