POST リクエストで Call をお客様の HTTPS エンドポイントに送信し、その応答を対象の Call のフィードバックとして記録します。社内データを使ったポリシーチェックや、自社でホストしているモデルなど、スコアリングロジックを Weave 内で実行できない場合は、リモート Scorer を使用してください。
このページでは、@weave.op でトレースされた Call 向けのリモート Scorer について説明します。Agents ビューでエージェントのターンをスコアリングする方法については、リモート Scorer でエージェントのターンをスコアリングする を参照してください。Call 向けのリモート Scorer は Python SDK で設定します。TypeScript SDK には RemoteScorer は含まれていません。
リモートスコアリングの仕組み
Call は次の順序でスコア付けされます。- モニター対象の Op への Call が終了します。
- スコアリングワーカーは、対象の操作にその Op を含む実行中のモニターを検索し、各モニターのフィルターとサンプリング率を適用します。
- 条件に一致したモニターの各
RemoteScorerについて、ワーカーは Call を含むschema_version: 1のリクエストを構築します。次に Scorer の認証情報を解決し、エンドポイント URL が許可されたホストに含まれるかを確認したうえで、POSTリクエストを送信します。 - ワーカーは応答を検証し、その結果を Call のフィードバックとして書き込みます。また、成否にかかわらず、スコアリングの試行自体も Call として記録します。
weave.Evaluation や call.apply_scorer() では使用できません。どちらも Scorer の score() メソッドを呼び出しますが、リクエストを送信するのはスコアリングワーカーだけであるため、RemoteScorer ではこのメソッドが NotImplementedError を送出します。Weave UI の Score calls アクションでも RemoteScorer は使用できず、RemoteScorer requires a monitor というメッセージが表示されます。選択した Call ごとに 1 つのリクエストが生成され、送信は 1 回のみです。リクエストがタイムアウトした場合や応答がない場合でも、Weave は再試行しません。デフォルトのタイムアウトは 30 秒です。
リモートスコアリングを有効にする
リモートスコアリングは、組織またはデプロイメントで有効化されるまでオフになっています。また、スコアリングワーカーが Scorer のエンドポイントを呼び出すのは、そのホストが許可リストに登録されている場合に限られます。有効化の方法はデプロイメントタイプによって異なります。 Multi-tenant Cloud 組織でリモート Scorer を有効にするには、組織管理者または請求管理者が次の手順を実行します。https://wandb.ai/account-settings/[ORG]/settingsを開きます。[ORG]は、ご利用の project を所有する組織の名前に置き換えてください。- Remote scoring タブを選択します。
- Enable remote scoring をオンにします。
- Allowed hosts で Add host をクリックし、リモート Scorer からの呼び出しを許可するホストをそれぞれ入力します。リモートスコアリングを有効にした状態で保存するには、ホストを 1 つ以上登録する必要があります。ポートを空欄のままにすると、そのホストのすべてのポートが許可されます。
- Save settings をクリックします。
extraEnv を使用して、以下の環境変数を設定してください。
Weave UI にリモートスコアリングの設定と Scorer のオプションを表示するには、W&B サーバーで
GORILLA_GATE_WEAVE_REMOTE_SCORING=true も設定してください。
許可ホストのルール
スコアリングワーカーは、すべての Scorer エンドポイント URL を以下のルールに照らして検証します。Scorer が OAuth を使用する場合は、OAuth トークンエンドポイント URL も個別に検証します。
- エントリはホストに完全一致します。ポートは任意で指定できます。ポートを指定しないエントリは、そのホストのすべてのポートを許可します。
*.で始まるエントリは、任意の階層のサブドメインに一致しますが、ドメイン自体には一致しません。*.corp.example.comはa.corp.example.comやa.b.corp.example.comに一致しますが、corp.example.comには一致しません。*.に続く接尾辞には 2 つ以上のラベルが必要なため、*.comは拒否されます。ワイルドカードは IP アドレスと組み合わせて使用できません。- オペレーターの許可リストと組織の許可リストの両方が存在する場合、URL は両方の条件を満たす必要があります。オペレーターの許可リストが空の場合、追加の制限はありません。許可リストが一つも存在しない場合、ワーカーはすべてのホストを拒否します。
- ループバック、プライベート、内部、およびクラウドメタデータのアドレスは拒否されます。セルフマネージド環境では、
WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRSに指定されたネットワーク内のプライベートアドレスが許可されます。 - デプロイメントで非セキュアな HTTP が許可されていない限り、HTTPS が必須です。
- リダイレクトは追跡しません。
Scorer エンドポイントを構築する
エンドポイントは Weave から JSON のPOST リクエストを受け入れ、JSON 形式でスコアを返します。リファレンス実装については、サンプルコードを参照してください。
リクエスト
Weave は、スコアリング対象ごとに 1 件の HTTPPOST を Scorer のエンドポイント URL に送信します。ヘッダーは次のとおりです。
Weave は同じスコアリング試行を複数回配信する場合があります。必要に応じて、エンドポイント側で
Idempotency-Key を使用して重複を排除してください。このキーはリクエストのバージョンごとに一定であるため、同じ Call に対する V1 リクエストと V2 リクエストではキーが異なります。
すべてのリクエスト本文には、次のトップレベルフィールドが含まれます。
Weave は、値のない省略可能なフィールドを
null として送信せず、フィールド自体を省略します。また、バージョン番号を変更せずに省略可能なフィールドを追加する場合があるため、認識できないフィールドは無視してください。
リクエスト本文と応答本文はそれぞれ 1 MiB までに制限されており、JSON テキストのみで構成されます。画像、オーディオ、動画が含まれることはありません。これらの制限を超える対象は送信されないため、スコアリングされません。1 件のリクエストに含まれる対象は 1 つです。
Call の場合、schema_version は 1 で、スコア付け対象の Call はトップレベルの original_call に格納されます。
応答
次の 2 つのフィールドを含む JSON オブジェクトを、HTTP200 で返します。
schema_version: リクエストのschema_versionと同じ値の整数。result: 1 つのスコアオブジェクト、スコアオブジェクトのリスト、または{"scores": [...]}形式のオブジェクト。
Weave は、
200 以外の応答をすべて Scorer の失敗として扱い、その試行のフィードバックは記録しません。また、リダイレクトには従わず、失敗として扱います。エラー応答の本文は解析されません。エンドポイントが受け入れることのないリクエストには 4xx を、一時的な問題には 5xx を返してください。
Call リクエストの場合、応答の schema_version は 1 です。この応答は、rating とタグをそれぞれ 1 つずつ返します。
Weave からのリクエストを認証する
Weave は、ベアラートークンを使用してエンドポイントへの認証を行います。リクエストには W&B の認証情報は含まれません。このトークンは、リクエストが Weave から送信されたものであることをエンドポイントに証明するためのものであり、その逆の証明には使用されません。各RemoteScorer は、次の 2 つのモードのいずれかを使用します。
Scorer を登録する前に、クライアントシークレットまたはベアラートークンを、project を所有するチームのシークレットストアに保存してください。
RemoteScorer の設定に保持されるのはシークレット名のみです。実際の値は、スコアリングワーカーがスコアリング時に解決します。
リモート Scorer を登録する
リモート Scorer は、モニターに関連付けられたRemoteScorer オブジェクトです。Python SDK を使用して作成します。
まず RemoteScorer を公開し、次に Monitor を有効化します。この Monitor では、scorers に公開した Scorer を指定し、op_names にスコア付けの対象となる Ops を指定します。endpoint_url は必須です。config と auth_config は省略可能です。
monitor.activate() によってモニターが有効な状態で公開され、Op 名のみで指定された箇所が現在の project の完全な Op ref に展開されます。
サンプルコード
weave リポジトリの examples/remote_scorer ディレクトリには、このページで説明するリクエストおよび応答の形式のリファレンス実装が含まれています。Python と FastAPI で記述されていますが、エンドポイントの言語、フレームワーク、ホストは自由に選択できます。Call を対象とする場合は、次のファイルを使用します。
remote_scorer_app.py:GET /healthとPOST /scoreを提供する FastAPI アプリです。scoring_logic.py: フレームワークに依存しないリクエストの解析とスコアリングの処理です。独自のサービスにそのままコピーして使用できるように記述されています。Call の場合は、inputs.messageの値をスコアリングします。auth.py:REMOTE_SCORER_DEV_BEARER_TOKEN環境変数を使用して Bearer トークンを検証する、開発専用のチェックです。register_remote_scorer.py --op-name:RemoteScorerを公開し、Op に対してMonitorを有効化します。trigger_test_trace.py: モニターの選択対象となる、トレースされた Call を作成します。sample_request.json: Call 用の完全な V1 リクエストです。
0.53.0 以降が必要です。ローカルでの run で検証できるのは、エンドポイントに定義したリクエストと応答の動作のみです。 Weave のスコアリングワーカーはループバックアドレスを拒否します。また、ホスト型のデプロイでは安全でない HTTP は許可されていません。
Scorer をテストする
テストの前に、許可されたホストに含まれる HTTPS URL にエンドポイントをデプロイし、登録してください。 スコア付け対象の Call をトリガーし、結果を確認します。- モニター対象の Op を 1 回以上呼び出します。
- エンドポイントがリクエストを受信したことを確認します。スコアリングは非同期で行われるため、リクエストは Call の終了後に届きます。
- Traces タブで Call を開き、フィードバックを確認します。
original_call に Call が格納された V1 リクエストを受信し、Weave はその結果を該当する Call のフィードバックとして記録します。