Vue d’ensemble des scorers

Alors que les tests logiciels classiques possèdent des critères de réussite ou d’échec clairement définis, les sorties d’IA sont non déterministes : elles peuvent varier pour une même entrée. Les scorers comblent cet écart en fournissant des métriques quantifiables pour mesurer la qualité des agents.

Les scorers sont des tests automatisés qui évaluent les sorties des agents au moyen de méthodes fondées sur un modèle, des règles ou des statistiques. Ils renvoient des scores, c’est-à-dire des valeurs numériques, généralement comprises entre 0 et 1, qui quantifient la mesure dans laquelle une sortie respecte vos critères d’évaluation. Ces scores vous permettent de suivre objectivement les performances, de comparer différentes approches et d’identifier les axes d’amélioration de vos systèmes d’IA. Vous pouvez personnaliser les scorers avec vos propres prompts et fonctions de notation.

Les scorers peuvent être exécutés dans le cloud afin de capturer des résultats en temps réel. Ils peuvent également intégrer votre pipeline CI/CD, ce qui vous permet de tester et de surveiller vos agents au fil du temps.

📹 Regarder

Regardez la présentation des évaluations Mastra pour découvrir les évaluations et apprendre à raisonner sur la qualité des agents.

Types de scorers

Mastra propose différents types de scorers, chacun répondant à un objectif précis. Voici quelques types courants :

1. Scorers textuels : évaluent l’exactitude, la fiabilité et la compréhension du contexte des réponses de l’agent
2. Scorers de classification : mesurent l’exactitude de la catégorisation des données selon des catégories prédéfinies
3. Scorers d’ingénierie de prompts : explorent l’effet de différentes instructions et de différents formats d’entrée

Installation

Pour accéder aux fonctionnalités de scoring de Mastra, installez le package @mastra/evals.

npm

npm install @mastra/evals@latest

pnpm

pnpm add @mastra/evals@latest

Yarn

yarn add @mastra/evals@latest

Bun

bun add @mastra/evals@latest

Évaluations en direct

Les évaluations en direct vous permettent de noter automatiquement les sorties d’IA en temps réel pendant l’exécution de vos agents et workflows. Au lieu de lancer les évaluations manuellement ou par lots, les scorers s’exécutent de façon asynchrone aux côtés de vos systèmes d’IA et assurent une surveillance continue de la qualité.

Ajouter des scorers aux agents

Vous pouvez ajouter des scorers intégrés à vos agents afin d’évaluer automatiquement leurs sorties. Consultez la liste complète des scorers intégrés pour découvrir toutes les options disponibles.

src/mastra/agents/evaluated-agent.ts

import { Agent } from '@mastra/core/agent'
import { createAnswerRelevancyScorer, createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const evaluatedAgent = new Agent({
  id: 'evaluated-agent',
  scorers: {
    relevancy: {
      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 0.5 },
    },
    safety: {
      scorer: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 1 },
    },
  },
})

Ajouter des scorers aux étapes d’un workflow

Vous pouvez également ajouter des scorers à des étapes individuelles d’un workflow afin d’évaluer les sorties à des points précis de votre processus. Chaque scorer reçoit l’entrée et la sortie propres à l’étape, ce qui vous permet de mesurer la qualité à chaque étape au lieu de noter uniquement la réponse finale :

src/mastra/workflows/content-generation.ts

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
import { customStepScorer } from "../scorers/custom-step-scorer";

const contentStep = createStep({
  id: "content-step",
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
  scorers: {
    customStepScorer: {
      scorer: customStepScorer(),
      sampling: {
        type: "ratio",
        rate: 1, // Score every step execution
      },
    },
  },
  execute: async ({ inputData }) => {
    return { content: await generateContent(inputData.topic) };
  },
});

export const contentWorkflow = createWorkflow({
  id: "content-workflow",
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
})
  .then(contentStep)
  .commit();

Pour l’API scorers au niveau d’une étape, consultez la référence de la classe Step.

Fonctionnement des évaluations en direct

Exécution asynchrone : les évaluations en direct s’exécutent en arrière-plan sans bloquer les réponses de votre agent ni l’exécution de votre workflow. Vos systèmes d’IA conservent ainsi leurs performances tout en restant surveillés.

Contrôle de l’échantillonnage : le paramètre sampling.rate (0-1) détermine le pourcentage de sorties évaluées :

• 1.0 : évaluer chaque réponse (100 %)
• 0.5 : évaluer la moitié des réponses (50 %)
• 0.1 : évaluer 10 % des réponses
• 0.0 : désactiver le scoring

Stockage automatique : tous les résultats de scoring sont automatiquement enregistrés dans la table mastra_scorers de votre base de données configurée, ce qui vous permet d’analyser l’évolution des performances au fil du temps.

Évaluations des traces

En plus des évaluations en direct, vous pouvez utiliser des scorers pour évaluer les traces historiques issues des interactions de vos agents et de vos workflows.

Cette fonctionnalité est particulièrement utile pour analyser les performances passées, déboguer des problèmes ou exécuter des évaluations par lots.

Observabilité requise

Pour noter des traces, vous devez d’abord configurer l’observabilité dans votre instance Mastra afin de collecter les données de trace. Consultez la documentation sur le traçage pour obtenir les instructions de configuration.

Studio

Pour noter des traces, vous devez d’abord enregistrer vos scorers dans votre instance Mastra :

const mastra = new Mastra({
  scorers: {
    answerRelevancy: myAnswerRelevancyScorer,
    responseQuality: myResponseQualityScorer,
  },
})

Une fois les scorers enregistrés, vous pouvez noter les traces de manière interactive dans la section Observabilité de Studio. Ouvrez Studio pour gérer les scorers, examiner les scores et exécuter des expériences.

• Liste des scorers : parcourez tous les scorers enregistrés avec leur description et le nombre d’agents et de workflows auxquels chacun est associé.
• Résultats des scores : sélectionnez un scorer pour afficher une liste paginée de tous les scores qu’il a produits. Cliquez sur une ligne pour ouvrir le panneau de détails, qui présente la valeur du score, le motif, l’entrée, la sortie et les prompts utilisés par le juge. Depuis ce panneau, enregistrez n’importe quel résultat comme élément de dataset pour de futures expériences.
• Onglet Évaluer de l’agent : ouvrez l’onglet Évaluer de n’importe quel agent pour gérer les scorers et les datasets. Vous pouvez également y exécuter des expériences. Les résultats présentent les scores de chaque élément, ainsi que l’état de réussite ou d’échec et les tags de version.
• Notation des traces : dans la section Observabilité, exécutez un scorer sur n’importe quelle trace ou span historique afin d’évaluer les interactions passées. Filtrez les scores par agent ou workflow.

Étapes suivantes

• Utilisez les vérifications rapides pour effectuer des assertions rapides et déterministes sur le texte et l’utilisation des outils
• Ajoutez des seuils bloquants et des verdicts pour imposer des exigences strictes et des seuils de qualité
• Testez les conversations à plusieurs tours dans lesquelles le comportement émerge au fil de tours successifs
• Découvrez comment créer vos propres scorers dans le guide Créer des scorers personnalisés
• Explorez les scorers intégrés dans la section Scorers intégrés
• Testez les scorers avec Studio
• 📹 Atelier sur les évaluations Mastra