Évaluer des Appels avec des évaluateurs distants

Un évaluateur distant est un évaluateur qui s’exécute sur votre infrastructure plutôt que dans W&B Weave. Lorsqu’un moniteur sélectionne un Appel, le worker d’évaluation de Weave envoie cet Appel à votre point de terminaison HTTPS via une requête HTTP POST, puis enregistre la réponse sous forme de feedback sur cet Appel. Utilisez un évaluateur distant lorsque votre logique d’évaluation ne peut pas s’exécuter dans Weave, par exemple pour vérifier la conformité à une politique à partir de données internes ou pour utiliser un modèle que vous hébergez vous-même. Cette page traite des évaluateurs distants pour les Appels tracés avec @weave.op. Pour évaluer les tours de conversation d’agents dans la vue Agents, consultez Évaluer les tours de conversation d’agents avec un évaluateur distant. Les évaluateurs distants pour les Appels se configurent avec le SDK Python. Le SDK TypeScript n’inclut pas RemoteScorer.

Fonctionnement de l’évaluation à distance

Un Appel est évalué selon la séquence suivante :

Un Appel à une Op surveillée se termine.
Le worker d’évaluation trouve les moniteurs actifs dont les opérations incluent cette Op, puis applique le filtre et le taux d’échantillonnage de chaque moniteur.
Pour chaque RemoteScorer d’un moniteur correspondant, le worker construit une requête schema_version: 1 contenant l’Appel, résout les identifiants d’authentification du scorer, vérifie que l’URL du point de terminaison figure parmi les hôtes autorisés, puis envoie la requête POST.
Le worker valide la réponse et enregistre le résultat sous forme de feedback sur l’Appel. Il enregistre également la tentative d’évaluation en tant qu’Appel, qu’elle ait réussi ou non.

Un scorer distant ne s’exécute que par l’intermédiaire d’un moniteur. Vous ne pouvez pas l’utiliser dans weave.Evaluation ni avec call.apply_scorer(). Ces deux mécanismes appellent la méthode score() du scorer, qui, pour RemoteScorer, lève NotImplementedError, car seul le worker d’évaluation envoie la requête. L’action Score calls de l’interface Weave refuse également un RemoteScorer et affiche le message RemoteScorer requires a monitor. Chaque Appel sélectionné génère une seule requête, envoyée une seule fois. Si la requête expire ou ne reçoit aucune réponse, Weave ne la renvoie pas. Le délai d’expiration par défaut est de 30 secondes.

Activer l’évaluation à distance

L’évaluation à distance est désactivée tant qu’elle n’a pas été activée pour votre organisation ou votre déploiement, et le worker d’évaluation n’appelle le point de terminaison d’un évaluateur que si son hôte figure sur une liste d’autorisation. La procédure d’activation dépend de votre type de déploiement. Cloud mutualisé Pour activer les évaluateurs distants pour une organisation, un administrateur de l’organisation ou un administrateur de la facturation doit :

Ouvrir https://wandb.ai/account-settings/[ORG]/settings, en remplaçant [ORG] par l’organisation propriétaire de votre projet.
Sélectionner l’onglet Remote scoring.
Activer Enable remote scoring.
Sous Allowed hosts, cliquer sur Add host et saisir chaque hôte que les évaluateurs distants sont autorisés à appeler. Lorsque l’évaluation à distance est activée, au moins un hôte est requis pour enregistrer. Laisser le port vide pour autoriser tous les ports de cet hôte.
Cliquer sur Save settings.

Cloud dédié Demandez à W&B d’activer l’évaluation à distance pour votre déploiement et d’en configurer les hôtes autorisés. Autogéré Si vous exécutez W&B Weave dans un déploiement W&B Autogéré, définissez ces variables d’environnement via extraEnv sur chaque worker d’évaluation : le worker d’évaluation en ligne, le worker d’évaluation des appels et le worker d’évaluation des agents.

Variable d’environnement	Par défaut	Effet
`WF_SCORING_WORKER_REMOTE_SCORING_ENABLED`	`false`	Active les requêtes sortantes vers les évaluateurs distants. Lorsque la valeur est `false`, aucun évaluateur distant ne s’exécute, quels que soient les autres paramètres.
`WF_SCORING_WORKER_REMOTE_HTTP_TIMEOUT_SECONDS`	`30`	Délai d’expiration de chaque requête envoyée à un point de terminaison d’évaluateur.
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_HOSTS`	vide	Liste d’autorisation définie par l’opérateur, composée d’entrées `host` ou `host:port` séparées par des virgules.
`WF_SCORING_WORKER_REMOTE_SCORER_VALIDATE_HOSTS`	`true`	Applique les listes d’hôtes autorisés. Les adresses privées, de bouclage et de métadonnées cloud sont rejetées, quelle que soit la valeur de ce paramètre.
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOW_INSECURE_HTTP`	`false`	Autorise les URL de point de terminaison en `http://`.
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS`	vide	Réseaux CIDR séparés par des virgules, par exemple `10.0.0.0/8`, dont les adresses privées peuvent être appelées par les évaluateurs distants.
`WF_SCORING_WORKER_REMOTE_SCORER_REQUIRE_STRUCTURED_RESULT_SCHEMA`	`true`	Rejette les réponses dont le champ `result` n’est pas au format de score structuré.

Pour afficher les paramètres d’évaluation à distance et les options des évaluateurs dans l’interface Weave, définissez également GORILLA_GATE_WEAVE_REMOTE_SCORING=true sur le serveur W&B. Règles relatives aux hôtes autorisés Le worker de scoring vérifie la conformité de chaque URL de point de terminaison de scorer aux règles suivantes, ainsi que, séparément, celle de l’URL du point de terminaison de jeton OAuth lorsqu’un scorer utilise OAuth :

Une entrée correspond à un hôte exact, avec un port facultatif. Une entrée sans port autorise n’importe quel port sur cet hôte.
Une entrée commençant par *. correspond aux sous-domaines de tout niveau, mais pas au domaine lui-même. *.corp.example.com correspond à a.corp.example.com et à a.b.corp.example.com, mais pas à corp.example.com. Le suffixe qui suit *. doit comporter au moins deux labels ; *.com est donc rejeté. Un caractère générique ne peut pas être associé à une adresse IP.
Lorsqu’il existe à la fois une liste d’autorisation de l’opérateur et une liste d’autorisation de l’organisation, l’URL doit respecter les deux. Une liste d’autorisation de l’opérateur vide n’ajoute aucune restriction. En l’absence de toute liste d’autorisation, le worker rejette tous les hôtes.
Les adresses de bouclage, privées, internes et de métadonnées cloud sont rejetées. En environnement Autogéré, les adresses privées appartenant aux réseaux répertoriés dans WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS sont autorisées.
HTTPS est requis, sauf si le déploiement autorise le HTTP non sécurisé.
Les redirections ne sont pas suivies.

Créer le point de terminaison du scorer

Votre point de terminaison accepte une requête POST JSON envoyée par Weave et renvoie un score au format JSON. Pour une implémentation de référence, consultez la section Exemple de code.

Requête

Weave envoie une requête HTTP POST par cible évaluée à l’URL du point de terminaison du scorer, avec les en-têtes suivants :

En-tête	Valeur
`Content-Type`	`application/json`
`Authorization`	`Bearer [TOKEN]`
`Idempotency-Key`	Une clé dérivée de la cible évaluée, de la version du monitor et de la version du scorer.
`X-Correlation-ID`	Un ID de corrélation pour cette requête.
`X-Weave-Schema-Version`	`1` ou `2`, identique à la valeur de `schema_version` dans le corps.

Weave peut transmettre plusieurs fois la même tentative d’évaluation. Si votre point de terminaison l’exige, utilisez Idempotency-Key pour dédupliquer les requêtes. La clé est stable pour une version de requête donnée : une requête V1 et une requête V2 portant sur le même Call ont donc des clés différentes. Chaque corps de requête contient les champs de premier niveau suivants :

Champ	Description
`schema_version`	Entier, `1` ou `2`.
`scoring_call_id`, `scoring_trace_id`	Identifiants de cette tentative d’évaluation.
`monitor`	`name` et `version_digest` du monitor qui a sélectionné la cible.
`scorer`	`name`, `ref` et `config` (facultatif). `config` est le mappage défini sur le `RemoteScorer`, transmis tel quel.
`triggered_at`	Horodatage ISO 8601 facultatif.

Weave omet les champs facultatifs sans valeur au lieu de les envoyer avec la valeur null. Weave peut ajouter des champs facultatifs à une version sans en modifier le numéro : ignorez donc les champs que vous ne reconnaissez pas. Les corps de requête et de réponse sont limités à 1 Mio chacun et ne contiennent que du texte JSON, jamais d’images, d’audio ni de vidéo. Une cible qui dépasse ces limites n’est pas envoyée et n’est donc pas évaluée. Chaque requête ne contient qu’une seule cible. Pour un appel, schema_version vaut 1 et l’appel évalué se trouve à la racine, sous original_call :

Champ	Description
`project_id`	Le projet, au format `[YOUR-TEAM]/[YOUR-PROJECT]`.
`call_id`, `trace_id`	Identifiants de l’appel évalué.
`op_name`	La réf. de l’Op de l’appel évalué.
`inputs`	Les entrées de l’appel.
`output`	La sortie de l’appel.
`started_at`, `ended_at`	Horodatages au format 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"
}

Réponse

Renvoyez un code HTTP 200 avec un objet JSON comportant deux champs :

schema_version : entier égal à la valeur schema_version de la requête.
result : un objet de score, une liste d’objets de score ou un objet de la forme {"scores": [...]}.

Un objet de score comporte les champs suivants :

Champ	Requis	Description
`value`	Oui	Un tag, sous forme de chaîne de 36 caractères maximum, ou une note, sous forme de nombre compris entre `0.0` et `1.0`.
`reason`	Non	Une chaîne expliquant le score.
`confidence`	Non	Un nombre compris entre `0.0` et `1.0`.

Weave considère toute réponse autre que 200 comme un échec du scorer et n’enregistre aucun feedback pour cette tentative. Weave ne suit pas les redirections et les traite comme des échecs. Weave n’analyse pas le corps d’une réponse d’erreur. Renvoyez un code 4xx pour les requêtes que votre point de terminaison n’acceptera jamais et un code 5xx en cas de problème temporaire. Pour une requête d’appel, la valeur de schema_version dans la réponse est 1. Cette réponse renvoie une notation et un tag :

{
  "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
    }
  ]
}

Authentifier les requêtes provenant de Weave

Weave s’authentifie auprès de votre point de terminaison à l’aide d’un bearer token. La requête ne contient aucun identifiant d’authentification W&B. Le jeton atteste auprès de votre point de terminaison que la requête provient bien de Weave, et non l’inverse. Chaque RemoteScorer utilise l’un des deux modes suivants :

Mode	Ce que fait Weave	Ce que vous configurez
`oauth_client_credentials`	Demande un jeton à votre point de terminaison de jetons OAuth via le flux d’octroi client credentials, en transmettant l’ID client et le secret par authentification HTTP Basic (`client_secret_basic`), puis envoie ce jeton au point de terminaison de votre scorer.	L’URL du point de terminaison de jetons, l’ID client, le nom du secret contenant le secret client et, éventuellement, une portée.
`static_bearer`	Envoie un jeton fixe au point de terminaison de votre scorer.	Le nom du secret contenant le jeton.

Avant d’enregistrer le scorer, stockez le secret client ou le bearer token dans le magasin de secrets de l’équipe propriétaire du projet. La configuration du RemoteScorer ne contient que le nom du secret : le worker d’évaluation récupère sa valeur au moment de l’évaluation.

Enregistrer un évaluateur distant

Un évaluateur distant est un objet RemoteScorer joint à un moniteur. Créez-le avec le SDK Python. Publiez un RemoteScorer, puis activez un Monitor qui le répertorie dans scorers et indique les opérations à évaluer dans op_names. endpoint_url est requis. config et auth_config sont facultatifs.

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

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

# Jeton Bearer statique, lu à partir du secret d’équipe WEAVE_REMOTE_SCORER_BEARER_TOKEN
auth = StaticBearerAuthConfig(
    mode="static_bearer",
    bearer_secret_name="WEAVE_REMOTE_SCORER_BEARER_TOKEN",
)

# Ou, avec des identifiants client 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},  # Transmis à votre point de terminaison sous la forme scorer.config
    auth_config=auth,
)
weave.publish(scorer, name="policy_remote_scorer")

monitor = Monitor(
    name="policy_remote_monitor",
    scorers=[scorer],
    op_names=["generate_response"],  # Noms d’op de ce projet, ou réf. d’op weave:/// complètes
    sampling_rate=1.0,
)
monitor.activate()

Lorsque vous exécutez le code, monitor.activate() publie le monitor en tant que monitor actif et convertit les noms d’Op simples en réf. d’Op complètes pour le projet en cours.

Exemple de code

Le répertoire examples/remote_scorer du dépôt weave constitue l’implémentation de référence du format de requête et de réponse décrit sur cette page. Il est écrit en Python avec FastAPI, mais votre point de terminaison peut utiliser n’importe quel langage, framework ou hébergeur. Pour les appels, les fichiers concernés sont les suivants :

remote_scorer_app.py : une application FastAPI exposant GET /health et POST /score.
scoring_logic.py : l’analyse des requêtes et la logique d’évaluation, indépendantes de tout framework et conçues pour être copiées dans votre propre service. Pour un appel, ce fichier évalue la valeur inputs.message.
auth.py : une vérification du jeton Bearer, réservée au développement, basée sur la variable d’environnement REMOTE_SCORER_DEV_BEARER_TOKEN.
register_remote_scorer.py --op-name : publie un RemoteScorer et active un Monitor pour une op.
trigger_test_trace.py : crée un appel tracé que le moniteur peut sélectionner.
sample_request.json : une requête V1 complète pour un appel.

Pour tester le point de terminaison localement sans Weave, démarrez l’application, puis envoyez-lui l’exemple de requête :

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

L’exemple nécessite Weave 0.53.0 ou une version ultérieure. Un run local vérifie uniquement le comportement requête-réponse que vous avez défini pour le point de terminaison. Le worker de scoring de Weave rejette les adresses de bouclage, et les déploiements hébergés n’autorisent pas le HTTP non sécurisé.

Tester le scorer

Avant de procéder au test, déployez le point de terminaison sur une URL HTTPS figurant parmi les hôtes autorisés, puis enregistrez-le. Déclenchez un Appel évalué et vérifiez le résultat :

Appelez l’Op surveillée au moins une fois.
Vérifiez que votre point de terminaison a bien reçu une requête. Le scoring étant asynchrone, la requête arrive une fois l’Appel terminé.
Dans l’onglet Traces, ouvrez l’Appel et consultez son feedback.

Votre point de terminaison reçoit une requête V1 contenant l’Appel dans original_call, et Weave enregistre le résultat sous forme de feedback sur cet Appel.

Résolution des problèmes

Symptôme	Points à vérifier
Les options de scorer distant n’apparaissent pas dans l’interface utilisateur	Le scoring distant doit être activé dans les paramètres Remote scoring de l’organisation propriétaire, ou par l’administrateur de votre déploiement.
L’URL du point de terminaison est rejetée	L’hôte du scorer et, pour OAuth, l’hôte du point de terminaison de jeton doivent figurer parmi les hôtes autorisés. Vérifiez qu’il n’y a pas de port incorrect, d’URL non HTTPS, ni d’adresse privée ou interne.
Le point de terminaison renvoie `401` ou `403`	Le nom du secret, les identifiants client OAuth, l’audience et la portée, ainsi que la validation des jetons par votre point de terminaison.
La requête de jeton réussit mais le scoring échoue, ou inversement	Vérifiez chaque URL séparément. Le point de terminaison de jeton et celui du scorer sont validés indépendamment et peuvent utiliser des hôtes différents.
Aucun feedback n’apparaît	Le scoring est asynchrone. Vérifiez que l’Appel correspond à l’opération, au filtre et au taux d’échantillonnage du monitor. Weave enregistre chaque tentative sous forme d’Appel de scorer dans l’onglet Traces. Une tentative échouée apparaît comme un Appel de scorer en erreur, accompagné de la cause de l’échec.
Aucun feedback après une réponse `200`	Le `schema_version` de la réponse doit être identique à celui de la requête, et `result` doit utiliser l’une des trois formes structurées.

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

Évaluer des Appels avec des évaluateurs distants

Fonctionnement de l’évaluation à distance

Activer l’évaluation à distance

Créer le point de terminaison du scorer

Requête

Réponse

Authentifier les requêtes provenant de Weave

Enregistrer un évaluateur distant

Exemple de code

Tester le scorer

Résolution des problèmes

​Fonctionnement de l’évaluation à distance

​Activer l’évaluation à distance

​Créer le point de terminaison du scorer

​Requête

​Réponse

​Authentifier les requêtes provenant de Weave

​Enregistrer un évaluateur distant

​Exemple de code

​Tester le scorer

​Résolution des problèmes

Fonctionnement de l’évaluation à distance

Activer l’évaluation à distance

Créer le point de terminaison du scorer

Requête

Réponse

Authentifier les requêtes provenant de Weave

Enregistrer un évaluateur distant

Exemple de code

Tester le scorer

Résolution des problèmes