Évaluations et scorers

L’API d’évaluation a été regroupée autour du nouveau système de scorers, avec des conventions de nommage et des exigences de configuration mises à jour.

Modifications

De getScorers à listScorers

La méthode getScorers() a été renommée listScorers(). Cette modification respecte la convention de nommage de l’ensemble de l’API, selon laquelle les méthodes de récupération au pluriel utilisent le préfixe list.

Pour effectuer la migration, remplacez tous les appels à getScorers() par listScorers().

- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/mastra-plural-apis .

De runExperiment à runEvals

La fonction runExperiment() a été renommée runEvals() afin d’indiquer clairement qu’elle exécute des évaluations.

Pour effectuer la migration, remplacez les appels à la fonction runExperiment par runEvals.

- import { createScorer, runExperiment } from '@mastra/core/evals';
+ import { createScorer, runEvals } from '@mastra/core/evals';
  import { myAgent } from './agents/my-agent';

  const scorer = createScorer({
    id: 'helpfulness-scorer',
    // ...
  });

- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
+ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/evals-run-experiment .

De getScorerByName à getScorerById

La méthode getScorerByName() a été renommée getScorerById(). Les scorers exigent désormais un champ id à la place de name. Cette modification s’inscrit dans la convention générale de l’API qui utilise id pour identifier les entités.

Pour effectuer la migration, mettez à jour les appels de méthode et la configuration des scorers afin d’utiliser id au lieu de name.

  const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
    // ...
  });
  
- const scorer = mastra.getScorerByName('helpfulness-scorer');
+ const scorer = mastra.getScorerById('helpfulness-scorer');

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/evals-scorer-by-name .

Configuration des scorers : de name à id

Les scorers exigent désormais un champ id au lieu de name. Le champ name est maintenant facultatif. Cette modification assure la cohérence avec les autres entités Mastra.

Pour effectuer la migration, mettez à jour les définitions des scorers afin d’utiliser id comme champ obligatoire.

  const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
+   name: 'Helpfulness Scorer', // optional
    // ...
  });

API de stockage des scores selon le modèle listScoresBy*

Les API de stockage des scores ont été renommées pour suivre le modèle listScoresBy*. Cette modification respecte les conventions générales de nommage de l’API de stockage.

Pour effectuer la migration, mettez à jour les méthodes d’interrogation des scores afin d’utiliser le nouveau modèle de nommage.

- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
+ const scores = await storage.listScoresByScorerId({
+   scorerId: 'helpfulness-scorer',
+ });

// Also available:
// - listScoresByRunId
// - listScoresByEntityId  
// - listScoresBySpan

Imports des scorers prédéfinis vers le chemin scorers/prebuilt

Les imports de scorers prédéfinis ont été regroupés sous le chemin unique @mastra/evals/scorers/prebuilt, au lieu des chemins distincts scorers/llm et scorers/code. Cette modification simplifie les imports et clarifie l’organisation des scorers prédéfinis.

Pour effectuer la migration, mettez à jour les instructions d’import afin d’utiliser le nouveau chemin scorers/prebuilt.

  // LLM-based scorers
- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
+ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';

  // Code-based scorers
- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
+ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/evals-prebuilt-imports .

Types de messages des scorers : de UIMessage à MastraDBMessage

Les types d’entrée et de sortie des scorers utilisent désormais MastraDBMessage[] au lieu de UIMessage. Cette modification aligne les scorers sur le format de message conservé en base de données afin d’assurer la cohérence dans tout le framework.

Pour effectuer la migration, mettez à jour les implémentations des scorers afin d’utiliser les types MastraDBMessage et d’accéder au contenu des messages via la structure content imbriquée.

  import type {
    ScorerRunInputForAgent,
    ScorerRunOutputForAgent
  } from '@mastra/core/evals';

- // ScorerRunInputForAgent uses UIMessage[]
- const inputMessages: UIMessage[] = run.input.inputMessages;
+ // ScorerRunInputForAgent now uses MastraDBMessage[]
+ import type { MastraDBMessage } from '@mastra/core/agent';
+ const inputMessages: MastraDBMessage[] = run.input.inputMessages;

Structure du contenu des messages au format imbriqué

Les appels de Tool et le contenu textuel sont désormais accessibles via un objet content imbriqué, plutôt que par des propriétés de message à plat. Cette structure imbriquée correspond au format des messages en base de données et à ses types.

Pour effectuer la migration, accédez aux appels de Tool via message.content.toolInvocations et au texte via message.content.content, ou utilisez la fonction utilitaire getTextContentFromMastraDBMessage().

+ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
+
  const run = await scorer.run(testRun);

  // Accessing text content
- const text = message.content;
+ const text = getTextContentFromMastraDBMessage(message);
+ // or directly: message.content.content

  // Accessing tool invocations
- const toolCalls = message.toolInvocations;
+ const toolCalls = message.content.toolInvocations;

Suppressions

Ancien code d’évaluation

L’ancien code d’évaluation a été supprimé de @mastra/core. Cela comprend les anciennes métriques d’évaluation, les modules de scorer et de juge, ainsi que le code d’évaluation automatique fondé sur des hooks. Cette modification simplifie la base de code en éliminant les approches d’évaluation obsolètes.

Pour effectuer la migration, utilisez la nouvelle API d’évaluations et de scorers dans @mastra/core/evals ou @mastra/evals.

- // Legacy evals APIs
+ import { createScorer, runEvals } from '@mastra/core/evals';
+ 
+ const scorer = createScorer({
+   id: 'my-scorer',
+   // Use new scorer API
+ });

Paramètre générique TMetrics de l’Agent

Le paramètre générique TMetrics a été supprimé de AgentConfig et du constructeur Agent. Les métriques et scorers se configurent désormais via l’API des scorers, au lieu de faire partie du système de types de l’Agent. Cette modification simplifie la signature de type de l’Agent.

Pour effectuer la migration, supprimez le paramètre générique TMetrics et configurez les scorers avec leur API.

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Exports de types liés aux évaluations

Plusieurs exports de types liés aux évaluations ont été supprimés, notamment DeprecatedOutputOptions, Metric et les types d’options des processeurs. Ces types sont désormais internes ou ont été remplacés par la nouvelle API des scorers. Cette modification réduit la surface de l’API.

Pour effectuer la migration, supprimez les références à ces types et utilisez la nouvelle API des scorers.

- import type {
-   DeprecatedOutputOptions,
-   Metric,
-   LanguageDetectorOptions,
-   ModerationOptions,
- } from '@mastra/core';
+ // Use new scorers API types
+ import type { Scorer } from '@mastra/core/evals';

Fonction de test createUIMessage

La fonction utilitaire de test createUIMessage() a été supprimée et remplacée par createTestMessage(). La nouvelle fonction crée des objets MastraDBMessage avec une structure de contenu imbriquée et prend en charge les appels de Tool facultatifs. Cette modification aligne les utilitaires de test sur le nouveau format de message.

Pour effectuer la migration, remplacez les appels à createUIMessage() par createTestMessage() et adoptez les types MastraDBMessage.

- import { createUIMessage } from '@mastra/evals';
+ import { createTestMessage } from '@mastra/evals';

  // Creating test messages
- const message = createUIMessage({
-   id: 'test-1',
+ const message = createTestMessage({
+   id: 'test-1', // optional, defaults to 'test-message'
    role: 'user',
    content: 'Hello',
    toolInvocations: [], // optional
  });