リモート Scorer で Call をスコアリングする

リモート Scorer は、W&B Weave 内ではなく、お客様のインフラストラクチャー上で実行される Scorer です。モニターが Call を選択すると、Weave のスコアリングワーカーがその Call を HTTP POST リクエストでお客様の 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 として記録します。

リモート Scorer はモニター経由でのみ実行されます。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 をクリックします。

専用クラウド デプロイメントでのリモートスコアリングの有効化と、許可するホストの設定を W&B に依頼してください。 セルフマネージド W&B Weave を W&B Self-Managed デプロイメントで実行している場合は、各スコアリングワーカー (オンライン評価ワーカー、Call スコアリングワーカー、エージェントスコアリングワーカー) で extraEnv を使用して以下の環境変数を設定します。

環境変数	デフォルト	効果
`WF_SCORING_WORKER_REMOTE_SCORING_ENABLED`	`false`	リモート Scorer への送信リクエストを有効にします。`false` の場合、他の設定にかかわらず、リモート Scorer は一切実行されません。
`WF_SCORING_WORKER_REMOTE_HTTP_TIMEOUT_SECONDS`	`30`	Scorer エンドポイントへのリクエストごとのタイムアウトです。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_HOSTS`	空	オペレーターが管理する許可リストです。`host` または `host:port` 形式のエントリをカンマ区切りで指定します。
`WF_SCORING_WORKER_REMOTE_SCORER_VALIDATE_HOSTS`	`true`	許可ホストリストによる制限を適用します。プライベートアドレス、ループバックアドレス、クラウドメタデータアドレスは、この設定にかかわらず拒否されます。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOW_INSECURE_HTTP`	`false`	`http://` で始まるエンドポイント URL を許可します。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS`	空	リモート Scorer からの呼び出しを許可するプライベートアドレスの CIDR ネットワーク (`10.0.0.0/8` など) をカンマ区切りで指定します。
`WF_SCORING_WORKER_REMOTE_SCORER_REQUIRE_STRUCTURED_RESULT_SCHEMA`	`true`	`result` が構造化スコア形式になっていない応答を拒否します。

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 は両方の条件を満たす必要があります。オペレーターの許可リストが空の場合、追加の制限はかかりません。許可リストが 1 つも存在しない場合、ワーカーはすべてのホストを拒否します。
ループバック、プライベート、内部、およびクラウドメタデータのアドレスは拒否されます。セルフマネージドでは、WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS に指定したネットワーク内のプライベートアドレスは許可されます。
デプロイメントで安全でない HTTP が許可されている場合を除き、HTTPS が必須です。
リダイレクトには追従しません。

scorer エンドポイントを構築する

エンドポイントは Weave から JSON の POST リクエストを受け入れ、スコアを JSON で返します。リファレンス実装については、サンプルコードを参照してください。

リクエスト

Weave は、スコアリング対象ごとに 1 件の HTTP POST リクエストを、次のヘッダーを付けて Scorer のエンドポイント URL に送信します。

ヘッダー	値
`Content-Type`	`application/json`
`Authorization`	`Bearer [TOKEN]`
`Idempotency-Key`	スコアリング対象、モニターのバージョン、Scorer のバージョンから導出されるキー。
`X-Correlation-ID`	このリクエストの相関 ID。
`X-Weave-Schema-Version`	`1` または `2`。ボディ内の `schema_version` と同じ値です。

Weave は同じスコアリング試行を複数回配信する場合があります。エンドポイントで必要に応じて、Idempotency-Key を使用して重複を排除してください。キーは同じリクエストバージョン内では変わりません。そのため、同じ Call に対する V1 リクエストと V2 リクエストでは、キーが異なります。すべてのリクエストボディには、次のトップレベルフィールドが含まれます。

フィールド	説明
`schema_version`	整数。`1` または `2`。
`scoring_call_id`、`scoring_trace_id`	このスコアリング試行の識別子。
`monitor`	対象を選択したモニターの `name` と `version_digest`。
`scorer`	`name`、`ref`、およびオプションの `config`。`config` は `RemoteScorer` に設定されたマッピングで、変更されずにそのまま渡されます。
`triggered_at`	オプションの ISO 8601 タイムスタンプ。

Weave は、値のないオプションフィールドを null として送信せず、省略します。また、バージョン番号を変更せずにオプションフィールドを追加する場合があるため、認識できないフィールドは無視してください。リクエストボディと応答ボディのサイズ上限はそれぞれ 1 MiB で、内容は JSON テキストのみです。画像、オーディオ、動画が含まれることはありません。これらの制限を超える対象は送信されないため、スコアリングも行われません。1 件のリクエストに含まれる対象は 1 つです。 Call の場合、schema_version は 1 で、スコアリング対象の Call はトップレベルの original_call に格納されます。

フィールド	説明
`project_id`	project (`[YOUR-TEAM]/[YOUR-PROJECT]` 形式) 。
`call_id`, `trace_id`	スコアリング対象の Call の識別子。
`op_name`	スコアリング対象の Call の Op ref。
`inputs`	Call の入力。
`output`	Call の出力。
`started_at`, `ended_at`	ISO 8601 形式のタイムスタンプ。

{
  "schema_version": 1,
  "original_call": {
    "project_id": "[YOUR-TEAM]/[YOUR-PROJECT]",
    "call_id": "018f8d6c-8d5f-7000-8000-000000000001",
    "trace_id": "018f8d6c-8d5f-7000-8000-000000000002",
    "op_name": "weave:///[YOUR-TEAM]/[YOUR-PROJECT]/op/sample_remote_scorer_target:*",
    "inputs": {
      "message": "test message for scoring"
    },
    "started_at": "2026-06-08T12:00:00+00:00",
    "ended_at": "2026-06-08T12:00:01+00:00",
    "output": {
      "reply": "received: test message for scoring",
      "status": "ok"
    }
  },
  "scoring_call_id": "018f8d6c-8d5f-7000-8000-000000000003",
  "scoring_trace_id": "018f8d6c-8d5f-7000-8000-000000000004",
  "monitor": {
    "name": "example_remote_scorer_monitor",
    "version_digest": "monitor-version-digest"
  },
  "scorer": {
    "name": "example_remote_scorer",
    "ref": "weave:///[YOUR-TEAM]/[YOUR-PROJECT]/object/example_remote_scorer:scorer-version-digest",
    "config": {
      "example_threshold": 0.8
    }
  },
  "triggered_at": "2026-06-08T12:00:02+00:00"
}

応答

次の 2 つのフィールドを含む JSON オブジェクトを、HTTP 200 で返します。

schema_version: リクエストの schema_version と同じ値の整数。
result: 1 つのスコアオブジェクト、スコアオブジェクトのリスト、または {"scores": [...]} 形式のオブジェクト。

スコアオブジェクトには次のフィールドがあります。

フィールド	必須	説明
`value`	はい	タグ (36 文字以内の string) または評価 (`0.0` から `1.0` までの数値)。
`reason`	いいえ	スコアの理由を説明する string。
`confidence`	いいえ	`0.0` から `1.0` までの数値。

Weave は、200 以外の応答をすべて Scorer の失敗として扱い、その試行のフィードバックは記録しません。また、リダイレクトには従わず、失敗として扱います。エラー応答の本文は解析されません。エンドポイントが受け付けることのないリクエストには 4xx を、一時的な問題には 5xx を返してください。 Call リクエストの場合、応答の schema_version は 1 です。次の応答は、レーティングとタグをそれぞれ 1 つずつ返します。

{
  "schema_version": 1,
  "result": [
    {
      "value": 1.0,
      "reason": "Message is 32 characters; concise messages score best.",
      "confidence": 1.0
    },
    {
      "value": "concise",
      "reason": "Message length category is concise.",
      "confidence": 0.9
    }
  ]
}

Weave からのリクエストを認証する

Weave は Bearer token を使用してエンドポイントに対して認証を行います。リクエストには W&B の認証情報は含まれません。このトークンは、リクエストが Weave から送信されたものであることをエンドポイント側に証明するためのものです。逆方向の証明には使用されません。各 RemoteScorer は、次の 2 つのモードのいずれかを使用します。

モード	Weave の動作	設定する項目
`oauth_client_credentials`	クライアントクレデンシャルグラントを使用して OAuth トークンエンドポイントにトークンをリクエストします。その際、クライアント ID とシークレットを HTTP Basic 認証 (`client_secret_basic`) で送信します。その後、取得したトークンを Scorer エンドポイントに送信します。	トークンエンドポイントの URL、クライアント ID、クライアントシークレットを保持するシークレットの名前、およびスコープ (オプション)。
`static_bearer`	固定のトークンを Scorer エンドポイントに送信します。	トークンを保持するシークレットの名前。

Scorer を登録する前に、project を所有するチームのシークレットストアにクライアントシークレットまたは Bearer token を保存してください。RemoteScorer の設定に保持されるのはシークレット名のみです。実際の値は、スコアリングワーカーがスコアリング時に解決します。

リモート Scorer を登録する

リモート Scorer は、モニターに関連付けられた RemoteScorer オブジェクトです。Python SDK を使用して作成します。 RemoteScorer をパブリッシュした後、Monitor を有効化します。この Monitor では、scorers にパブリッシュした Scorer を指定し、op_names にスコア付けの対象となる Op の名前を指定します。endpoint_url は必須です。config と auth_config はオプションです。

import weave
from weave.flow.monitor import Monitor
from weave.scorers.remote_scorer import (
    OAuthClientCredentialsConfig,
    RemoteScorer,
    StaticBearerAuthConfig,
)

weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")

# 静的な Bearer token（WEAVE_REMOTE_SCORER_BEARER_TOKEN という名前のチームシークレットから読み込みます）
auth = StaticBearerAuthConfig(
    mode="static_bearer",
    bearer_secret_name="WEAVE_REMOTE_SCORER_BEARER_TOKEN",
)

# OAuth クライアント認証情報を使用する場合:
# auth = OAuthClientCredentialsConfig(
#     mode="oauth_client_credentials",
#     token_endpoint_url="https://idp.example.com/oauth2/token",
#     client_id="weave-remote-scorer",
#     client_secret_name="WEAVE_REMOTE_SCORER_CLIENT_SECRET",
#     scope="score:remote",
# )

scorer = RemoteScorer(
    name="policy_remote_scorer",
    endpoint_url="https://scoring.example.com/weave/score",
    config={"threshold": 0.9},  # scorer.config としてエンドポイントに送信されます
    auth_config=auth,
)
weave.publish(scorer, name="policy_remote_scorer")

monitor = Monitor(
    name="policy_remote_monitor",
    scorers=[scorer],
    op_names=["generate_response"],  # この project 内の Op 名、または完全な weave:/// 形式の Op ref
    sampling_rate=1.0,
)
monitor.activate()

コードを実行すると、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 token を検証する、開発専用のチェックです。
register_remote_scorer.py --op-name: RemoteScorer をパブリッシュし、Op に対する Monitor を有効化します。
trigger_test_trace.py: モニターの選択対象となる、トレースされた Call を作成します。
sample_request.json: Call 用の完全な V1 リクエストです。

Weave を使用せずにローカルでエンドポイントをテストするには、アプリを起動してから、サンプルリクエストを送信します。

python3 -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt
export REMOTE_SCORER_DEV_BEARER_TOKEN="dev-token"
uvicorn remote_scorer_app:app --host 127.0.0.1 --port 8000

curl -sS http://127.0.0.1:8000/score \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-contract-check" \
  -H "X-Correlation-ID: local-contract-check" \
  -H "X-Weave-Schema-Version: 1" \
  --data @sample_request.json

このサンプルには Weave 0.53.0 以降が必要です。ローカルで実行した場合に検証できるのは、エンドポイントに定義したリクエストと応答の動作のみです。 Weave のスコアリングワーカーはループバックアドレスを受け付けず、ホスト型のデプロイメントでは安全でない HTTP は使用できません。

Scorer をテストする

テストの前に、許可されたホストに含まれる HTTPS URL にエンドポイントをデプロイし、登録しておきます。スコアリング対象の Call をトリガーして、結果を確認します。

監視対象の Op を 1 回以上呼び出します。
エンドポイントがリクエストを受信したことを確認します。スコアリングは非同期で実行されるため、リクエストは Call の終了後に届きます。
Traces タブで Call を開き、フィードバックを確認します。

エンドポイントは、original_call に Call を含む V1 リクエストを受信します。Weave は、その結果を該当する Call のフィードバックとして記録します。

トラブルシューティング

症状	確認事項
UI にリモート Scorer のオプションが表示されない	所有元の組織の Remote scoring 設定で、またはデプロイメントの管理者によって、リモートスコアリングが有効になっていることを確認します。
エンドポイント URL が拒否される	Scorer のホスト (OAuth の場合はトークンエンドポイントのホストも) が、許可されたホストに含まれていることを確認します。また、ポートの不一致、HTTPS 以外の URL、プライベートアドレスや内部アドレスの使用がないかを確認します。
エンドポイントが `401` または `403` を返す	シークレット名、OAuth クライアントの認証情報、オーディエンス、スコープ、およびエンドポイント側のトークン検証を確認します。
トークンリクエストは成功するがスコアリングが失敗する (またはその逆)	各 URL を個別に確認します。トークンエンドポイントと Scorer エンドポイントはそれぞれ独立して検証されるため、異なるホストを使用できます。
フィードバックが表示されない	スコアリングは非同期で実行されます。Call がモニターの操作、フィルター、サンプリング率の条件に一致していることを確認します。Weave はすべての試行を Scorer Call として Traces タブに記録します。失敗した試行は、失敗理由を含むエラー状態の Scorer Call として表示されます。
`200` 応答が返されたのにフィードバックが表示されない	応答の `schema_version` がリクエストの値と一致していること、および `result` が 3 つの構造化形式のいずれかに従っていることを確認します。

​リモートスコアリングの仕組み

​リモートスコアリングを有効にする

​scorer エンドポイントを構築する

​リクエスト

​応答

​Weave からのリクエストを認証する

​リモート Scorer を登録する

​サンプルコード

​Scorer をテストする

​トラブルシューティング