Skip to main content
Ce guide vous explique comment utiliser EvaluationLogger pour enregistrer des prédictions et des scores depuis votre code Python ou TypeScript existant. Vous pouvez ainsi évaluer les performances de votre modèle dans Weave sans avoir à définir au préalable un jeu de données complet et une suite d’évaluateurs. Adoptez cette approche lorsque votre jeu de données ou vos évaluateurs ne sont pas définis à l’avance, ou lorsque vous devez journaliser des données d’évaluation de manière incrémentielle pendant l’exécution de votre flux de travail. Contrairement à l’objet Evaluation standard, qui nécessite un Dataset prédéfini et une liste d’objets Scorer, EvaluationLogger vous permet de journaliser des prédictions individuelles et leurs scores associés au fur et à mesure qu’ils deviennent disponibles.
Vous préférez une évaluation plus structurée ?Si vous préférez un framework d’évaluation plus encadré, avec des jeux de données et des évaluateurs prédéfinis, consultez le framework Evaluation standard.EvaluationLogger privilégie la flexibilité, tandis que le framework standard apporte un cadre et des repères.

Flux de travail de base

En suivant ces étapes, vous enregistrez une évaluation complète dans Weave, avec des scores par prédiction et une synthèse agrégée que vous pouvez consulter dans l’interface de Weights & Biases.
  1. Initialiser le logger : créez une instance de EvaluationLogger, en fournissant éventuellement des métadonnées sur le model et le dataset. Si vous les omettez, Weave utilise des valeurs par défaut.
    Pour capturer l’utilisation des jetons et le coût des appels LLM (par exemple, OpenAI), initialisez EvaluationLogger avant toute invocation du LLM. Si vous appelez d’abord votre LLM et journalisez les prédictions ensuite, Weave ne capture pas les données de jetons ni de coût.
  2. Journaliser les prédictions : appelez log_prediction() pour chaque paire d’entrée et de sortie de votre système.
  3. Journaliser les scores : utilisez le ScoreLogger renvoyé pour appeler log_score() sur la prédiction. Vous pouvez journaliser plusieurs scores par prédiction.
  4. Terminer la prédiction : appelez toujours finish() après avoir journalisé les scores d’une prédiction afin de la finaliser.
  5. Journaliser la synthèse : une fois toutes les prédictions traitées, appelez log_summary() pour agréger les scores et, si vous le souhaitez, ajouter des métriques personnalisées.
Une fois finish() appelé sur une prédiction, vous ne pouvez plus journaliser de scores pour celle-ci.
Pour un exemple Python illustrant ce flux de travail, consultez l’Exemple de base. Si la sortie et tous les scores sont disponibles en même temps, les utilisateurs de Python peuvent regrouper les étapes 2 à 4 en un appel unique avec log_example().

Exemple de base

L’exemple suivant montre comment utiliser EvaluationLogger pour journaliser des prédictions et des scores directement dans votre code existant. Remplacez [YOUR-TEAM]/[YOUR-PROJECT] par votre entity et votre projet W&B.
La fonction user_model est définie, puis appliquée à une liste d’entrées. Pour chaque exemple :
  • L’entrée et la sortie sont journalisées à l’aide de log_prediction.
  • Un score d’exactitude (correctness_score) est journalisé à l’aide de log_score.
  • finish() finalise la journalisation de cette prédiction.
Enfin, log_summary enregistre les éventuelles métriques agrégées et déclenche la synthèse automatique des scores dans Weave.

Journalisation simplifiée avec log_example()

Utilisez log_example() pour journaliser des entrées, une sortie et des scores en un appel unique. Cette méthode pratique regroupe log_prediction(), log_score() et finish() en une seule étape. Elle s’avère utile lorsque les entrées, les sorties du modèle et les scores sont déjà prêts à être journalisés, par exemple lors d’évaluations par lots ou hors ligne.
L’appel précédent à log_example() équivaut à :
log_example() n’est pas disponible dans le SDK TypeScript de Weave. Les utilisateurs de TypeScript doivent utiliser l’approche basée sur logPrediction() et logScore() présentée dans l’exemple de base.

Utilisation avancée

L’EvaluationLogger offre des modes d’utilisation flexibles qui vont au-delà du flux de travail de base, afin de répondre à des scénarios d’évaluation plus complexes. Les sections suivantes décrivent des techniques avancées, notamment comment utiliser des gestionnaires de contexte pour gérer automatiquement les ressources, lier les traces d’agent aux lignes d’évaluation, séparer l’exécution du modèle de la journalisation, manipuler des données de médias enrichis et comparer côte à côte plusieurs évaluations de modèles.

Utiliser des gestionnaires de contexte

EvaluationLogger prend en charge les gestionnaires de contexte (instructions with) pour les prédictions comme pour les scores. Vous obtenez ainsi un code plus lisible, un nettoyage automatique des ressources et un meilleur suivi des opérations imbriquées, comme les appels à un juge LLM. Dans ce contexte, les instructions with offrent les avantages suivants :
  • Appel automatique de finish() à la sortie du contexte.
  • Meilleur suivi des jetons et des coûts pour les appels LLM imbriqués.
  • Possibilité de définir la sortie après l’exécution du modèle, au sein du contexte de la prédiction.
Cette approche garantit que toutes les opérations imbriquées sont suivies et rattachées à la prédiction parente, ce qui vous permet d’obtenir des données précises sur l’utilisation des jetons et les coûts dans l’interface de Weights & Biases.
En Python, conservez chaque appel d’agent tracé à l’intérieur de son contexte log_prediction(). EvaluationLogger définit les métadonnées du run d’évaluation, de l’exemple et de l’essai sur les spans créés dans ce contexte, et Weave s’appuie sur ces métadonnées pour lier la trace à son résultat d’évaluation.
La liaison automatique entre les évaluations et les spans d’agent n’est disponible qu’en Python. Ni l’EvaluationLogger TypeScript ni Evaluation.evaluate() ne créent de portée d’évaluation active permettant de lier les spans d’agent. En TypeScript, la seule façon de lier un span consiste à définir directement les attributs OTel décrits dans cette section, et uniquement si les deux ID d’appel sont déjà disponibles.
L’exemple suivant utilise le SDK OpenAI Agents. Le même principe s’applique aux autres frameworks d’agents tracés par Weave. Remplacez [YOUR-TEAM]/[YOUR-PROJECT] par votre entity et votre projet W&B.
Si l’agent s’exécute avant le début du contexte de prédiction ou après sa fin, Weave enregistre la trace, mais ne la lie pas au résultat d’évaluation. Weave lie automatiquement une trace à son résultat d’évaluation lorsque l’agent s’exécute dans le contexte log_prediction() et qu’une intégration Weave le trace, comme dans l’exemple de code précédent. Dans le cas contraire, vous devez définir vous-même les deux ID de liaison sur les spans d’agent. La marche à suivre dépend de l’endroit où les spans sont créés :
  • Même processus, avec votre propre instrumentation : définissez les attributs directement sur chaque span.
  • Service distinct : transmettez les deux ID à ce service, puis définissez-les sur les spans qu’il crée.
Lorsque des spans sont créés dans le contexte de log_prediction(), l’EvaluationLogger définit automatiquement tous les attributs. En revanche, si vous envoyez des spans avec votre propre instrumentation OpenTelemetry (OTel), vous devez définir les attributs directement sur chaque span à lier. Vous pouvez définir les attributs suivants pour les évaluations : Envoyez le span vers le même projet Weave que l’évaluation via le point de terminaison /agents/otel/v1/traces. Les attributs de span OTel ne se propagent pas des spans parents aux spans enfants : définissez donc les attributs sur chaque span à lier. Pour plus d’informations sur le point de terminaison : Seuls weave.eval.run_id et weave.eval.predict_and_score_call_id établissent les liens vers l’évaluation et le résultat. L’empreinte de ligne, l’ID d’exemple, l’index d’essai, la catégorie et le nom de l’évaluation apportent du contexte et permettent le filtrage, mais ne créent pas de lien à eux seuls. Pour les deux attributs de liaison, utilisez des ID d’appel Weave, et non des ID de trace ou de span OTel. Vous pouvez obtenir ces deux ID via l’API de requête des résultats d’évaluation. Dans la réponse, chaque évaluation comporte un evaluation_call_id, et chaque essai un predict_and_score_call_id. Les exemples suivants supposent que span est le span OTel de l’opération de l’agent. Remplacez chaque valeur entre crochets par les métadonnées du run d’évaluation et du résultat auxquels le span appartient. L’exemple TypeScript fonctionne, car il définit directement les attributs OTel au lieu de s’appuyer sur une portée de prédiction. Utilisez-le uniquement lorsque vous disposez déjà des deux ID d’appel.
Lorsque votre agent s’exécute en tant que service distinct, le processus d’évaluation et l’agent ne partagent pas de mémoire : Weave ne peut pas définir automatiquement les attributs de liaison, et vous ne pouvez pas accéder directement aux objets span de l’agent. Récupérez plutôt les deux ID d’appel dans le processus d’évaluation, envoyez-les au service, puis définissez-les sur les spans qui y sont créés. Ce modèle distribué basé sur EvaluationLogger est disponible uniquement en Python.
L’entrée dans le contexte log_prediction() crée l’appel Evaluation.predict_and_score avant l’exécution du corps du contexte. Le contexte génère un ScoreLogger (lié à prediction dans l’exemple suivant) qui expose les deux ID d’appel. Laissez le contexte ouvert jusqu’à ce que le service réponde, afin de pouvoir journaliser sa sortie et ses scores dans le même résultat d’évaluation.Dans le processus d’évaluation, remplacez [AGENT-SERVICE-URL] par le point de terminaison qui exécute votre agent, ainsi que [YOUR-TEAM]/[YOUR-PROJECT] :
Dans le service de l’agent, copiez les attributs reçus sur chaque span d’agent que vous souhaitez associer au résultat. La fonction suivante illustre le côté réception avec un span OTel brut. Configurez le service pour qu’il exporte les spans vers le même [YOUR-TEAM]/[YOUR-PROJECT] que l’évaluation.
Dans cet exemple, le span encapsulant est lié au résultat de l’évaluation. Si le framework d’agent crée des spans supplémentaires, copiez également eval_context sur ces spans : dans OTel, les spans enfants n’héritent pas des attributs du span encapsulant.

Afficher les spans d’agent liés depuis vos évaluations

Pour inspecter les spans liés dans l’interface de Weights & Biases :
  1. Accédez à Forge.
  2. Dans le menu latéral de Weave, cliquez sur Evals.
  3. Sélectionnez votre run d’évaluation.
  4. Dans le panneau de détails de l’évaluation qui s’ouvre, sous l’onglet Évaluation, cliquez sur Voir les spans. La page Agents s’ouvre alors sur l’onglet Spans, filtré sur cette évaluation.
Lorsque vous transmettez des jeux de données bruts comme inputs à log_prediction, Weave réimporte les données à chaque run d’évaluation. Les données sont alors stockées en double, ce qui peut gaspiller de l’espace si le jeu de données est volumineux ou si de nombreuses évaluations le réutilisent. Pour éviter cette duplication, publiez votre jeu de données vers Weave avant de lancer vos évaluations, puis transmettez les lignes du jeu de données publié comme inputs. Weave résout les références aux lignes publiées au moyen de références internes, sans réimporter les données. Vous bénéficiez ainsi de la même expérience liée qu’avec le framework Evaluation standard, dans lequel chaque prédiction renvoie à une ligne de jeu de données précise dans l’interface utilisateur de Weights & Biases. L’exemple suivant publie un jeu de données, le lie dans l’EvaluationLogger, puis le récupère et le parcourt comme n’importe quel autre jeu de données.

Obtenir les sorties avant la journalisation

Vous pouvez d’abord calculer les sorties de votre modèle, puis journaliser séparément les prédictions et les scores. Vous dissociez ainsi la logique d’évaluation de celle de journalisation, ce qui peut rendre le code plus facile à tester et à maintenir lorsque différentes parties de votre système gèrent la génération des prédictions et le calcul des scores.

Journaliser des médias enrichis

Les entrées, les sorties et les scores peuvent contenir des médias enrichis tels que des images, des vidéos, de l’audio ou des tableaux structurés. Journaliser des médias enrichis vous permet d’examiner le contenu réel à côté des scores dans l’interface de Weights & Biases, ce qui facilite l’analyse qualitative des modèles multimodaux. Transmettez un dict ou un objet multimédia aux méthodes log_prediction ou log_score.

Journaliser et comparer plusieurs évaluations

Avec EvaluationLogger, vous pouvez journaliser plusieurs évaluations et les comparer côte à côte dans l’interface Weights & Biases. Cela permet de comparer les performances de différents modèles sur un même jeu de données.
  1. Exécutez l’exemple de code suivant.
  2. Dans l’interface Weights & Biases, ouvrez l’onglet Evals.
  3. Sélectionnez les évaluations que vous souhaitez comparer.
  4. Cliquez sur Compare. Dans la vue Compare, vous pouvez :
    • Choisir les évaluations à ajouter ou à retirer.
    • Choisir les métriques à afficher ou à masquer.
    • Parcourir des exemples précis pour voir comment différents modèles se sont comportés pour une même entrée d’un jeu de données donné.
Pour plus d’informations sur les comparaisons, consultez Comparaisons.
Onglet Evals affichant une liste de runs d’évaluation
Vue de comparaison affichant les métriques de plusieurs runs d’évaluation

Conseils d’utilisation

Les conseils suivants vous aideront à tirer le meilleur parti de EvaluationLogger :
  • Appelez finish() dès que possible après chaque prédiction.
  • Utilisez log_summary pour capturer les métriques qui ne sont pas liées à une prédiction en particulier (par exemple, la latence globale).
  • La journalisation de médias enrichis est utile pour l’analyse qualitative.
Dernière modification le 30 septembre 2026