メタデータとトレース

標準のチャット補完 metadata オブジェクトに、プロキシ制御とトレース属性を含めます。このページでは、会話のアイデンティティを維持し、会話全体をサンプリングして、生成される project のトレースを理解する方法を説明します。 OpenAI SDK では metadata が組み込みのリクエストパラメーターとしてサポートされているため、extra_body を使う必要はありません。ただし、metadata パラメーターに対応していない古いリリースの openai Python パッケージでは、引き続き extra_body={"metadata": {...}} を指定する必要があります。

予約済みメタデータ

キー	タイプ	用途
`gen_ai.conversation.id`	空でない `string`	W&B Weave におけるスティッキールーティング、会話サンプリング、会話のグループ化に使用する会話識別子
`forge.project_version`	`"2"` などの `string`、または `integer`	project のバージョンを選択します。`OpenAI-Project` ヘッダーが必要です。バージョン 1 を使用する場合は省略します
`forge.turn_index`	0 以上の `integer`	リプレイ時に、信頼できるソースのターンインデックスを保持します
`user.id`	空でない `string`	エンドユーザーのアイデンティティをトレースに付加します
`forge.call_shadow`	`boolean`	project にルーティングされたリクエストについて、Agent Span に加えて Weave Call もログします。この場合、トレースストレージが重複して消費されます

forge.* および wandb.* キーは、プロキシの制御用に予約されています。プロキシはリクエストをプロバイダーに送信する前にこれらのキーを削除し、カスタムトレース属性としても記録しません。それ以外のメタデータは、プロキシがプロバイダーに転送します。また、表現可能な場合は、そのメタデータをトレースにも追加します。 forge. または wandb. で始まる独自のメタデータキーは使用しないでください。プロキシはこれらを制御用のキーとして扱います。また、routing_mode、task_version、alias など、プロキシ自身が記録する名前と重複するカスタムメタデータも、トレースには記録されません。さらに Agent Span では、error.type と、gen_ai.conversation.id 以外の gen_ai.* キーも記録されません。ただし、これらのキーもプロキシからプロバイダーには引き続き転送されます。

会話の優先順位

会話識別子は、OpenTelemetry での名前である gen_ai.conversation.id として送信してください。プロキシは最初に利用可能な識別子を選択します：

gen_ai.conversation.id
Vapi call.id

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

会話全体をサンプリングする

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

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

ルーティング設定を保存すると、プロキシは指定した割合で会話単位のトレースサンプリングを行います。会話のアイデンティティを持つリクエストについては、プロキシは Weights & Biases entity、Model Distillation の project、会話 ID に基づいて、会話を固定のサンプリンググループに割り当てます。デフォルトのサンプリング率は 100% です。プロキシは、そのアイデンティティを持つすべてのリクエストを保存するか、すべてスキップします。サンプリングの決定は、モデル選択やルーティングのリビジョンには左右されません。トレースをスキップしても、プロキシは推論の応答を返します。プロキシは、会話のアイデンティティを持たないリクエストを常に保存します。割合を変更すると保存される会話が変わる可能性があるため、実行中の会話の有効期間中はサンプリングの割合を一定に保ってください。

API: 会話のトレースサンプリングを設定する (PUT /projects/[PROJECT-ALIAS]/routing)

Model Distillation を使用せずに会話単位のトレースサンプリングを設定するには、ルーティング API を使用します。[PROJECT-ALIAS] を project のエイリアスに、[WANDB-ENTITY] を Weights & Biases entity に、[MODEL-REF] を既存のターゲットモデル参照に置き換えます。trace_sampling_rate に 0 から 1 までの値を設定します。ルーティングを更新すると設定全体が置き換えられるため、リクエストには既存のターゲットをすべて含めてください。

curl --request PUT \
  --url "https://forge.coreweave.com/api/distillation/v1/projects/[PROJECT-ALIAS]/routing" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "Forge-Entity: [WANDB-ENTITY]" \
  --header "Content-Type: application/json" \
  --data '{
    "trace_sampling_rate": 0.1,
    "targets": [
      {"model_ref": "[MODEL-REF]", "weight": 1}
    ]
  }'

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

project のトレースの内容

project のトレースには、次のルーティング、リクエスト、応答、メタデータの詳細が取得されます。

project ID (UUID)、project エイリアス、バージョン。
ルーティングのリビジョン、および選択されたプロバイダーとモデル。
ルーティングモード (routing_mode)。プロキシがターゲットを選択した場合は weighted、リクエストで provider/model のモデルのオーバーライドが指定された場合は override になります。
プロキシがプロバイダーに送信する正確なリクエストと、プロキシが再構成した応答。
トークン使用量、終了理由、タイミング、エラーステータス。
応答が完全一致応答キャッシュから再生されたかどうか (cache_hit)。
会話、ユーザー、シナリオ、および安全なカスタムメタデータ。
サポートへの問い合わせやトレース出力の比較に使用するプロキシのリクエスト ID。

正規の Agent Span には、詳細を保持するためにリクエストと応答の生のコピーが含まれます。そのため、データセットの再構成は正規化された表示用の列だけに依存しません。プロキシは、project のリクエストごとに 1 つの Agent Span を書き込みます。Weave の Agents ビューは、これらのスパンを gen_ai.conversation.id に基づいて会話ごとにグループ化します。Weave の Threads ビューは Call のみを読み取るため、project のトラフィックがそこに表示されるのは、forge.call_shadow で Call も記録したリクエストに限られます。モデルのオーバーライドも project のトラフィックであるため、project のトレースから構築したデータセットにはオーバーライドが含まれる場合があります。データセットからオーバーライドを除外するには、metadata: {"routing_mode": "weighted"} でフィルターします。なお、このフィルターでは、プロキシが routing_mode の記録を開始する前に書き込まれたトレースも除外されます。

メッセージやメタデータに、認証情報、シークレット、不要な個人データを含めないでください。トレースデータは、トレーニングやデバッグの入力として使用するため、意図的に永続的に保存されます。

API: 会話のアイデンティティを指定してリクエストを送信する (POST /chat/completions)

[WANDB-ENTITY] を Weights & Biases の entity に、[WANDB-PROJECT] を project の Weights & Biases プロジェクト名 (エイリアスではありません) に、[CONVERSATION-ID] を会話の識別子に置き換えます。1 つの会話内のすべてのターンで、同じ gen_ai.conversation.id を使用します。

curl --request POST \
  --url "https://proxy.training.coreweave.com/v1/chat/completions" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "OpenAI-Project: [WANDB-ENTITY]/[WANDB-PROJECT]" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "router",
    "messages": [{"role": "user", "content": "Classify this request"}],
    "metadata": {
      "gen_ai.conversation.id": "[CONVERSATION-ID]"
    }
  }'

バージョン 1 以外のバージョンに固定するには、metadata に "forge.project_version": "2" を追加します。プロキシは、リクエストをプロバイダーに送信する前に、予約済みの forge.* の値を削除します。詳しくは、ルーティングされたチャット補完を作成するを参照してください。

​予約済みメタデータ

​会話の優先順位

​会話全体をサンプリングする

​project のトレースの内容

予約済みメタデータ

会話の優先順位

会話全体をサンプリングする

project のトレースの内容