POST, puis enregistre la réponse comme feedback sur ce tour. Le résultat s’affiche sous forme de tag ou de score dans l’onglet Signals de la vue Agents.
Cette page traite des évaluateurs distants pour les tours de conversation d’agent. Pour évaluer les Appels tracés avec @weave.op, consultez Évaluer les Appels avec des évaluateurs distants. Les évaluateurs distants se configurent avec le SDK Python ou l’interface Weave. Le SDK TypeScript n’inclut pas RemoteScorer.
Fonctionnement de l’évaluation des tours de conversation d’agent
Un tour de conversation d’agent est évalué selon la séquence suivante :- Un tour de conversation se termine. Lorsqu’un span racine (un span sans parent) se termine, Weave le considère comme un tour de conversation terminé et émet un événement
weave.genai.turn_ended. - Le worker d’évaluation des agents charge les signaux actifs du projet qui ciblent
weave.genai.turn_ended, puis applique à chaque signal ses filtres et son taux d’échantillonnage. - Pour chaque
RemoteScorerd’un signal correspondant, le worker construit une requêteschema_version: 2à partir du span du tour de conversation, messages compris, 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êtePOST. - Le worker valide la réponse et enregistre le résultat sous forme de feedback sur le tour de conversation. Les tags et les scores s’affichent dans l’onglet Signals.
Monitor dont le champ op_names vaut ["weave.genai.turn_ended"], que vous le créiez dans l’interface utilisateur ou avec le SDK.
Le worker relance une tentative ayant échoué avec la même Idempotency-Key, dans la limite de trois tentatives au cours des 30 secondes qui suivent la première. Une réponse 5xx, 408 ou 429 entraîne une nouvelle tentative. Un dépassement de délai consomme la totalité des 30 secondes : une requête expirée n’est donc pas relancée. Les autres réponses 4xx ne sont pas relancées non plus. Si votre point de terminaison ne peut pas évaluer un tour de conversation à temps, renvoyez rapidement 503 plutôt que de laisser la requête expirer, afin que Weave la relance. L’évaluation des tours de conversation d’agent exige le format de résultat structuré, car Weave stocke les tags et les scores sous forme de colonnes de feedback typées.
Activer l’évaluation distante
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.
extraEnv sur chacun des workers d’évaluation : le worker d’évaluation en ligne, le worker d’évaluation des appels et le worker d’évaluation des agents.
Pour afficher les paramètres d’évaluation distante 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.comcorrespond àa.corp.example.comet àa.b.corp.example.com, mais pas àcorp.example.com. Le suffixe qui suit*.doit contenir au moins deux libellés :*.comest 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_CIDRSsont 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êtePOST 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 HTTPPOST par cible évaluée à l’URL du point de terminaison de l’évaluateur, avec les en-têtes suivants :
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 :
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.
Une requête de tour de conversation d’agent comporte deux numéros de version. Le champ de premier niveau schema_version correspond à la version de l’enveloppe, qui vaut 2 pour les tours de conversation d’agent. Les données évaluées se trouvent dans scoring_target, une union taguée comportant trois champs :
type: le type de cible.agent_turnpour un tour de conversation. Le contrat définit égalementcall, que l’évaluation des tours de conversation d’agent n’envoie jamais.schema_version: la version de la charge utile pour ce type. Elle est numérotée indépendamment de la version de l’enveloppe. La charge utileagent_turnest en version1.payload: les données correspondant à ce type.
scoring_target.type et de scoring_target.schema_version pour déterminer comment évaluer la charge utile. Renvoyez un code 4xx pour toute combinaison que votre point de terminaison ne prend pas en charge, par exemple call si vous n’évaluez que les tours de conversation d’agent.
La charge utile agent_turn en version 1 comporte les champs suivants :
Un tour de conversation qui se termine sans statut explicite est reçu avec
status.code défini sur UNSET. Traitez UNSET comme un tour de conversation terminé normalement et ERROR comme le signal d’échec. Chaque message de input et de output comporte les champs role, content et finish_reason. content contient du texte brut, ou un tableau de parties encodé en JSON lorsque le message comporte du contenu structuré, comme des appels d’outil.
1.
Réponse
Renvoyez un code HTTP200 avec un objet JSON comportant deux champs :
schema_version: entier égal auschema_versionde la requête.result: un objet de score, une liste d’objets de score ou un objet de la forme{"scores": [...]}.
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 portant sur un tour de conversation d’agent, le schema_version de la réponse est 2. L’exemple suivant renvoie un seul objet de score :
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. ChaqueRemoteScorer utilise l’un des deux modes suivants :
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.
Créer un signal d’évaluateur distant
Créez le signal dans l’interface Weave ou avec le SDK Python. Dans les deux cas, vous obtenez unRemoteScorer associé à un moniteur qui cible weave.genai.turn_ended.
Interface Weave
Créez le signal depuis la vue Agents :- Dans la barre latérale du projet Weave, cliquez sur Agents.
- Dans la barre d’onglets, cliquez sur Signals.
- Cliquez sur New signal, puis sur Remote scorer.
- Dans le volet latéral Remote scorer, Scored by est défini sur Remote scorer. Configurez les champs suivants :
- Scorer name : le nom affiché dans la colonne Scorer du tableau Signals. 128 caractères maximum.
- Scoring endpoint URL : l’URL à laquelle Weave envoie la requête
POST. - Authentication : Static bearer ou OAuth client credentials. Pour un jeton porteur statique, sélectionnez ou saisissez le Bearer token secret name. Pour OAuth, saisissez le Token endpoint URL, le Client ID, le Client secret name et, si nécessaire, le Scope. Les champs de secret attendent des noms de secrets d’équipe, et non leurs valeurs.
- Config (JSON, optional) : un objet JSON transmis à votre point de terminaison dans
scorer.config. - Only score turns matching (facultatif) : développez Advanced, puis ajoutez des filtres pour limiter les tours de conversation évalués par le signal, par exemple selon le nom de l’agent, la version de l’agent, le nom de l’opération, le nom de l’outil ou le code de statut. Pour évaluer tous les tours de conversation, laissez ce champ vide. Weave combine plusieurs filtres avec une logique
AND. - Sample rate (facultatif) : développez Advanced, puis définissez la proportion de tours de conversation correspondants que le signal évalue.
- Cliquez sur Create signal.
SDK Python
Publiez unRemoteScorer, puis activez un Monitor qui le répertorie dans scorers et cible weave.genai.turn_ended dans op_names.
OAuthClientCredentialsConfig dans auth_config.
Exemple de code
Le répertoireexamples/remote_scorer du dépôt weave constitue l’implémentation de référence de ce contrat et fait foi pour l’exemple de code. Dans cet exemple, un seul point de terminaison accepte les requêtes Appel V1, les requêtes Appel V2 et les requêtes de tour de conversation d’agent V2. Pour les tours de conversation d’agent, les fichiers concernés sont les suivants :
remote_scorer_app.py: une application FastAPI qui exposeGET /healthetPOST /score.auth.py: une vérification du jeton Bearer, réservée au développement, basée sur la variable d’environnementREMOTE_SCORER_DEV_BEARER_TOKEN.scoring_logic.py: extrait le contenu de l’une ou l’autre enveloppe avecextract_scoring_target, puis évalue le dernier message de sortie du tour de conversation.sample_request_v2_agent_turn.json: une requête complète de tour de conversation d’agent V2.register_remote_scorer.py --agent-turn: publie unRemoteScoreret active un moniteur pour les tours de conversation d’agent terminés.trigger_test_agent_turn.py: journalise un tour de conversation avecweave.conversation.log_turn.
0.53.0 ou une version ultérieure. Une exécution en local ne vérifie que le contrat.
Tester le signal
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. Journalisez un tour de conversation terminé, puis consultez l’onglet Signals. L’évaluation étant asynchrone, le résultat n’apparaît qu’au bout de quelques instants.scoring_target.type est défini sur agent_turn, et Weave enregistre le résultat en tant que feedback associé à ce tour de conversation.