Skip to main content
Ce guide vous montre comment utiliser EvaluationLogger pour enregistrer des prédictions et des scores depuis votre code Python ou TypeScript existant, afin d’évaluer les performances du modèle dans Weave sans devoir d’abord définir un Dataset complet et une suite d’évaluateurs. Utilisez cette approche lorsque votre jeu de données ou vos évaluateurs ne sont pas définis à l’avance, ou lorsque vous devez journaliser les données d’évaluation de façon 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 les scores associés de façon incrémentielle, à mesure qu’ils deviennent disponibles.
Vous préférez une évaluation plus structurée ?Si vous préférez un framework d’évaluation plus prescriptif avec des jeux de données et des évaluateurs prédéfinis, Voir le framework Evaluation standard.EvaluationLogger offre de la flexibilité, tandis que le framework standard apporte structure et orientation.

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 Weave.
  1. Initialisez le logger : Créez une instance de EvaluationLogger, en fournissant éventuellement des métadonnées sur le modèle et le jeu de données. Weave utilise les valeurs par défaut si vous les omettez.
    Pour capturer l’utilisation des jetons et le coût des appels LLM (par exemple, OpenAI), initialisez EvaluationLogger avant toute invocation de LLM. Si vous appelez d’abord votre LLM, puis journalisez les prédictions ensuite, Weave ne capture pas les données de jeton et de coût.
  2. Journalisez les prédictions : Appelez log_prediction() pour chaque paire d’entrée et de sortie de votre système.
  3. Journalisez les scores : Utilisez le ScoreLogger renvoyé pour appeler log_score() pour la prédiction. Plusieurs scores par prédiction sont pris en charge.
  4. Terminez la prédiction : Appelez toujours finish() après avoir journalisé les scores d’une prédiction afin de la finaliser.
  5. Journalisez la synthèse : Une fois toutes les prédictions traitées, appelez log_summary() pour agréger les scores et ajouter des métriques personnalisées facultatives.
Après avoir appelé finish() sur une prédiction, il n’est plus possible d’y journaliser d’autres scores.
Pour voir un exemple Python illustrant ce flux de travail, consultez le Exemple de base. Si la sortie et tous les scores sont disponibles immédiatement, les utilisateurs Python peuvent combiner les étapes 2 à 4 en un appel unique à l’aide de log_example().

Exemple de base

L’exemple suivant montre comment utiliser EvaluationLogger pour journaliser les prédictions et les scores directement dans votre code existant. Remplacez [YOUR-TEAM]/[YOUR-PROJECT] par votre entité 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 enregistrées à l’aide de log_prediction.
  • Un score de correction (correctness_score) est enregistré via log_score.
  • finish() finalise l’enregistrement pour cette prédiction.
Enfin, log_summary enregistre les 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 seul appel. Cette méthode pratique combine log_prediction(), log_score() et finish() en une seule étape. Elle est utile lorsque vous disposez déjà des entrées, des sorties du modèle et des scores à journaliser, par exemple lors d’évaluations par lot ou hors ligne.
L’appel précédent à log_example() équivaut à :
log_example() n’est pas disponible pour le SDK TypeScript de Weave. Les utilisateurs de TypeScript doivent utiliser l’approche logPrediction() et logScore() présentée dans l’exemple de base.

Utilisation avancée

EvaluationLogger offre des modes d’utilisation flexibles au-delà du flux de travail de base pour 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 la gestion automatique des ressources, lier les traces d’agent aux lignes d’évaluation, séparer l’exécution du modèle de la journalisation, utiliser 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. Cela permet d’obtenir un code plus propre, un nettoyage automatique des ressources et un meilleur suivi des opérations imbriquées, comme les appels à un juge LLM. L’utilisation des instructions with dans ce contexte offre les avantages suivants :
  • Appels automatiques à finish() à la sortie du contexte.
  • Meilleur suivi des jetons et des coûts pour les appels LLM imbriqués.
  • Définition de la sortie après l’exécution du modèle dans le contexte de prédiction.
Cette approche garantit que toutes les opérations imbriquées sont suivies et attribuées à la prédiction parente, ce qui vous fournit des données précises sur l’utilisation des jetons et les coûts dans l’interface Weave.
En Python, conservez chaque appel d’agent tracé dans son contexte log_prediction(). EvaluationLogger ajoute aux spans créés dans ce contexte les métadonnées du run d’évaluation, de l’exemple et du trial, que Weave utilise pour associer la trace à son résultat d’évaluation.
L’association automatique des évaluations aux spans d’agent est disponible uniquement en Python. Ni EvaluationLogger en TypeScript ni Evaluation.evaluate() ne créent de portée d’évaluation active permettant d’associer les spans d’agent. En TypeScript, vous pouvez associer un span uniquement en définissant directement les attributs OTel décrits dans cette section, et seulement lorsque les deux ID d’appel sont déjà disponibles.
L’exemple suivant utilise le SDK OpenAI Agents. Le même schéma s’applique aux autres frameworks d’agents tracés par Weave. Remplacez [YOUR-TEAM]/[YOUR-PROJECT] par votre entité 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 l’associe pas au résultat d’évaluation. Weave associe 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. Sinon, vous devez définir vous-même les deux ID d’association sur les spans d’agent. La procédure dépend de l’emplacement où les spans sont créés :
  • Même processus, instrumentation personnalisée : définissez les attributs directement sur chaque span.
  • Service distinct : envoyez 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 log_prediction(), EvaluationLogger définit automatiquement tous les attributs. En revanche, si vous envoyez des spans à l’aide de votre propre instrumentation OpenTelemetry (OTel), vous devez définir directement les attributs sur chaque span à lier. Vous pouvez définir les attributs suivants pour les évaluations : Envoyez le span au 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 avec l’évaluation et le résultat. Le digest de ligne, l’ID d’exemple, l’index de trial, la catégorie et le nom de l’évaluation ajoutent du contexte et permettent le filtrage, mais ne créent pas de lien à eux seuls. Utilisez des ID d’appel Weave pour les deux attributs de liaison, et non des ID de trace ou de span OTel. Vous pouvez obtenir les deux ID à partir de l’API de requête des résultats d’évaluation. Chaque évaluation de la réponse possède un evaluation_call_id, et chaque trial possède 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 appartient le span. L’exemple TypeScript fonctionne car il définit directement les attributs OTel au lieu de s’appuyer sur un contexte de prédiction. Utilisez-le uniquement lorsque les deux ID d’appel sont déjà disponibles.
Lorsque votre agent s’exécute dans un service distinct, le processus d’évaluation et l’agent ne partagent pas la même 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 EvaluationLogger distribué est uniquement disponible 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 (associé à prediction dans l’exemple suivant) qui expose les deux ID d’appel. Gardez le contexte ouvert jusqu’au retour du service afin de pouvoir journaliser sa sortie et ses scores sur 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 de l’agent que vous souhaitez associer au résultat. La fonction suivante illustre la partie réception avec un span OTel brut. Configurez le service pour exporter les spans vers le même [YOUR-TEAM]/[YOUR-PROJECT] que l’évaluation.
Le span d’encapsulation de cet exemple est lié au résultat d’évaluation. Si le framework de l’agent crée des spans supplémentaires, copiez également eval_context sur ces spans. OTel n’hérite pas des attributs de span du span d’encapsulation.

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

Pour inspecter les spans liés dans l’interface Weave :
  1. Accédez à wandb.ai.
  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 Evaluation, cliquez sur Voir les spans. La page Agents s’ouvre, avec l’onglet Spans filtré sur cette évaluation.
Lorsque vous passez des jeux de données bruts comme inputs à log_prediction, Weave réimporte les données à chaque run d’évaluation. Cela stocke des donné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 d’exécuter des évaluations, puis passez les lignes du jeu de données publié comme inputs. Weave résout les références aux lignes publiées à l’aide de références internes au lieu de réimporter les données. Cette technique vous offre la même expérience de liaison que le framework Evaluation standard, où chaque prédiction renvoie à une ligne précise du jeu de données dans l’interface Weave. L’exemple suivant publie un jeu de données, y crée un lien dans 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. Cela sépare la logique d’évaluation de celle de la journalisation, ce qui peut faciliter les tests et la maintenance du code lorsque différentes parties de votre système gèrent la génération des prédictions et l’attribution des scores.

Journaliser des médias enrichis

Les entrées, les sorties et les scores peuvent inclure des médias enrichis, comme des images, des vidéos, des fichiers audio ou des tableaux structurés. La journalisation de médias enrichis vous permet d’inspecter le contenu réel à côté des scores dans l’interface Weave, ce qui est utile pour l’analyse qualitative des modèles multimodaux. Passez un dictionnaire ou un objet média aux méthodes log_prediction ou log_score.

Journaliser et comparer plusieurs évaluations

Avec EvaluationLogger, vous pouvez journaliser et comparer plusieurs évaluations côte à côte dans l’interface Weave. Cela est utile pour évaluer les performances de différents modèles sur le même jeu de données.
  1. Exécutez l’exemple de code suivant.
  2. Dans l’interface Weave, ouvrez l’onglet Evals.
  3. Sélectionnez les évaluations que vous souhaitez comparer.
  4. Cliquez sur Compare. Dans la vue de comparaison, vous pouvez :
    • Choisir quelles évaluations ajouter ou supprimer.
    • Choisir quelles métriques afficher ou masquer.
    • Parcourir des exemples précis pour voir comment différents modèles se sont comportés pour la même entrée dans un jeu de données donné.
Pour plus d’informations sur les comparaisons, voir Comparisons.
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 aident à tirer le meilleur parti de EvaluationLogger :
  • Appelez finish() rapidement après chaque prédiction.
  • Utilisez log_summary pour enregistrer des métriques qui ne sont pas liées à une prédiction individuelle (par exemple, la latence globale).
  • La journalisation des médias enrichis est utile pour l’analyse qualitative.