É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 recourir à 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 Call est évalué selon la séquence suivante :

Un Call vers un Op surveillé se termine.
Le worker d’évaluation recherche les moniteurs actifs dont les opérations incluent cet 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 le Call, résout les identifiants d’authentification de l’évaluateur, 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 le Call. Il enregistre également la tentative d’évaluation en tant que Call, qu’elle ait réussi ou non.

Un évaluateur distant s’exécute uniquement via 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() de l’évaluateur, qui lève NotImplementedError pour RemoteScorer, car seul le worker d’évaluation envoie la requête. L’action Score calls de l’interface Weave rejette également un RemoteScorer avec le message RemoteScorer requires a monitor. Chaque Call 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 relance pas. Le délai d’expiration par défaut est de 30 secondes.

Activer l’évaluation à distance

L’évaluation à distance reste 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 pouvoir enregistrer. Laisser le port vide pour autoriser n’importe quel port sur 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 vers 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, tels que `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 d’évaluateur 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 d’évaluation vérifie la conformité de chaque URL de point de terminaison d’évaluateur, ainsi que, séparément, celle de l’URL du point de terminaison de jeton OAuth lorsqu’un évaluateur utilise OAuth, aux règles suivantes :

Une entrée correspond à un hôte exact, avec un port facultatif. Une entrée sans port autorise n’importe quel port de cet hôte.
Une entrée commençant par *. correspond aux sous-domaines de n’importe quel 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 contenir au moins deux libellés : *.com est donc rejeté. Un caractère générique ne peut pas être combiné à 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 satisfaire aux 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 déploiement 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.
Le protocole 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 de l’évaluateur

Votre point de terminaison accepte une requête POST au format 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 de l’évaluateur, 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 de l’évaluateur.
`X-Correlation-ID`	Un identifiant de corrélation pour cette requête.
`X-Weave-Schema-Version`	`1` ou `2`, identique à `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 comporte 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, facultativement, `config`. `config` est le mappage défini sur le `RemoteScorer`, transmis tel quel.
`triggered_at`	Horodatage ISO 8601 facultatif.

Lorsqu’un champ facultatif n’a pas de valeur, Weave l’omet au lieu de l’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 contient une seule cible. Pour un Appel, schema_version vaut 1 et l’Appel évalué se trouve au niveau 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 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 au 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 string de 36 caractères maximum, ou une note, sous forme de nombre compris entre `0.0` et `1.0`.
`reason`	Non	Une string qui justifie 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 de l’évaluateur 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 des réponses 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, le schema_version de la réponse est 1. Cette réponse renvoie une note 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 jeton de porteur (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 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 par identifiants client (client credentials grant), 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 évaluateur.	L’URL du point de terminaison de jetons, l’ID client, le nom du secret qui contient le secret client et, éventuellement, une portée.
`static_bearer`	Envoie un jeton fixe au point de terminaison de votre évaluateur.	Le nom du secret qui contient le jeton.

Avant d’enregistrer l’évaluateur, stockez le secret client ou le jeton de porteur 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ésout la 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éférence dans scorers et indique les ops à évaluer dans op_names. Le paramètre endpoint_url est requis. Les paramètres 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 depuis le secret d’équipe WEAVE_REMOTE_SCORER_BEARER_TOKEN
auth = StaticBearerAuthConfig(
    mode="static_bearer",
    bearer_secret_name="WEAVE_REMOTE_SCORER_BEARER_TOKEN",
)

# Ou utilisez plutôt 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 dans 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’ops de ce projet, ou réf. complètes d’ops weave:///
    sampling_rate=1.0,
)
monitor.activate()

Lorsque vous exécutez le code, monitor.activate() publie le moniteur en tant que moniteur actif et convertit les noms d’ops simples en réf. d’ops 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 qui expose GET /health et POST /score.
scoring_logic.py : l’analyse des requêtes et l’évaluation, indépendantes de tout framework, 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 à partir de la variable d’environnement REMOTE_SCORER_DEV_BEARER_TOKEN, réservée au développement.
register_remote_scorer.py --op-name : publie un RemoteScorer et active un Monitor pour un 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 en local 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 de 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 l’évaluateur

Avant de lancer le 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 au moins une fois l’op surveillé.
Vérifiez que votre point de terminaison a bien reçu une requête. L’évaluation étant asynchrone, la requête n’arrive qu’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 sous original_call, et Weave enregistre le résultat comme feedback de cet Appel.

Dépannage

Symptôme	Éléments à vérifier
Les options d’évaluateur distant n’apparaissent pas dans l’interface utilisateur	L’évaluation distante est activée 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 de l’évaluateur et, pour OAuth, l’hôte du point de terminaison de jeton figurent 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 d’authentification du 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 l’évaluation échoue, ou inversement	Chaque URL séparément. Le point de terminaison de jeton et celui de l’évaluateur sont validés indépendamment et peuvent utiliser des hôtes différents.
Aucun feedback n’apparaît	L’évaluation 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 d’évaluateur dans l’onglet Traces. Une tentative en échec apparaît comme un appel d’évaluateur en erreur, accompagné de la raison de l’échec.
Aucun feedback après une réponse `200`	Le `schema_version` de la réponse est identique à celui de la requête, et `result` adopte l’une des trois formes structurées.

​Fonctionnement de l’évaluation à distance

​Activer l’évaluation à distance

​Créer le point de terminaison de l’évaluateur

​Requête

​Réponse

​Authentifier les requêtes provenant de Weave

​Enregistrer un évaluateur distant

​Exemple de code

​Tester l’évaluateur

​Dépannage