> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # createScorer Mastra fournit une factory `createScorer` unifiée qui permet de définir des Scorers personnalisés pour évaluer des paires entrée/sortie. Chaque étape d'évaluation peut utiliser des fonctions JavaScript natives ou des objets de prompt fondés sur un LLM. Les Scorers personnalisés peuvent être ajoutés aux Agents et aux étapes de Workflow. ## Création d'un Scorer personnalisé Utilisez la factory `createScorer` pour définir votre Scorer avec un nom, une description et une configuration facultative du juge. Enchaînez ensuite les méthodes d'étape afin de construire votre pipeline d'évaluation. Vous devez fournir au moins une étape `generateScore`. Les **étapes sous forme d'objet de prompt** sont des configurations exprimées comme des objets avec `description` + `createPrompt` (et `outputSchema` pour `preprocess`/`analyze`). Elles invoquent le LLM juge. Les **étapes sous forme de fonction** sont de simples fonctions qui n'appellent jamais le juge. ```typescript import { createScorer } from '@mastra/core/evals' const scorer = createScorer({ id: 'my-custom-scorer', name: 'My Custom Scorer', // Optional, defaults to id description: 'Evaluates responses based on custom criteria', type: 'agent', // Optional: for agent evaluation with automatic typing judge: { model: myModel, instructions: 'You are an expert evaluator...', }, }) .preprocess({/* step config */}) .analyze({/* step config */}) .generateScore(({ run, results }) => { // Return a number }) .generateReason({/* step config */}) ``` ## Options de `createScorer` **id** (`string`): Identifiant unique du Scorer. Utilisé comme nom si name n'est pas fourni. **name** (`string`): Nom du Scorer. Utilise id par défaut s'il n'est pas fourni. **description** (`string`): Description du rôle du Scorer. **judge** (`object`): Configuration facultative du juge pour les étapes fondées sur un LLM. **judge.model** (`LanguageModel`): Instance du modèle LLM à utiliser pour l'évaluation. **judge.instructions** (`string`): Prompt système ou instructions du LLM. **judge.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Contrôle la manière dont le schéma de sortie structurée du juge parvient au modèle. Utilise 'auto' par défaut, qui emploie la sortie structurée native lorsqu'elle est prise en charge, sinon l'injection du prompt en ligne. Les valeurs explicites remplacent le routage automatique. **judge.inputProcessors** (`Processor[]`): Processors d'entrée appliqués à l'Agent juge interne avant que ses messages n'atteignent le modèle, par exemple pour le masquage ou la validation. **judge.outputProcessors** (`Processor[]`): Processors de sortie appliqués à la sortie de l'Agent juge interne avant son renvoi, par exemple pour la modération ou la transformation. **judge.errorProcessors** (`Processor[]`): Processors d'erreur destinés aux modèles juges qui utilisent l'API de génération actuelle de Mastra. Ils implémentent processAPIError, peuvent examiner les rejets de l'API LLM et demander une nouvelle tentative, par exemple avec StreamErrorRetryProcessor. Les anciens adaptateurs de modèle utilisent generateLegacy() et n'exécutent pas les Processors d'erreur. **judge.maxProcessorRetries** (`number`): Nombre maximal de nouvelles tentatives d'une génération du juge par les Processors d'erreur. L'exécution utilise 10 par défaut lorsque errorProcessors est configuré sans cette valeur. Définissez-la explicitement pour limiter le budget de tentatives. **type** (`string`): Spécification du type d'entrée/sortie. Utilisez 'agent' pour obtenir automatiquement les types d'Agent. Pour des types personnalisés, utilisez plutôt l'approche générique. **prepareRun** (`(run: ScorerRun) => ScorerRun | Promise`): Transforme les données d'exécution du Scorer avant le lancement du pipeline. Utilisez cette fonction pour filtrer les messages, limiter la taille du contexte ou supprimer les champs inutiles au Scorer. L'utilitaire \`filterRun()\` crée cette fonction à partir d'options déclaratives. Peut être asynchrone. Cette fonction renvoie un builder de Scorer sur lequel vous pouvez enchaîner des méthodes d'étape. Consultez la [référence de MastraScorer](https://mastra.zisheng.pro/fr/reference/evals/mastra-scorer) pour plus de détails sur la méthode `.run()` et ses entrées/sorties. Le juge s'exécute uniquement pour les étapes définies comme **objets de prompt** (`preprocess`, `analyze`, `generateScore`, `generateReason` en mode prompt). Si vous utilisez seulement des étapes sous forme de fonction, le juge n'est jamais appelé et aucune sortie de LLM ne peut être examinée. Dans ce cas, vos fonctions doivent produire elles-mêmes le score et la justification. Lorsqu'une étape sous forme d'objet de prompt s'exécute, sa sortie LLM structurée est stockée dans le champ de résultat correspondant (`preprocessStepResult`, `analyzeStepResult` ou la valeur consommée par `calculateScore` dans `generateScore`). ## Nouvelles tentatives des requêtes du juge Utilisez la configuration `errorProcessors` existante du juge pour réessayer les échecs transitoires au sein d'une requête du juge ayant échoué. Cela ne relance ni le Workflow du Scorer, ni la cible de Trace, ni l'élément du lot, ni l'écriture du score, ni une étape du Scorer déjà terminée. `@mastra/core` `1.49.0` n'inclut pas la configuration des Processors d'erreur des Scorers. Avant d'utiliser cette configuration, passez à une version prenant en charge les Processors de Scorer ou rétroportez cette modification ciblée. L'exemple suivant utilise un seul budget limité de nouvelles tentatives. Définissez `maxRetries` du Processor et `judge.maxProcessorRetries` sur la même valeur. Conservez les tentatives du modèle de l'Agent juge interne à leur valeur par défaut de `0` afin qu'elles ne multiplient pas celles du Processor. ```typescript import { createScorer } from '@mastra/core/evals' import { StreamErrorRetryProcessor } from '@mastra/core/processors' const isTransientNetworkError = (error: unknown) => error instanceof Error && /ECONNRESET|ETIMEDOUT|socket hang up/i.test(error.message) const retryProcessor = new StreamErrorRetryProcessor({ maxRetries: 2, maxRetryAfterMs: 30_000, delayMs: ({ retryCount }) => Math.min(1_000 * 2 ** retryCount, 30_000), matchers: [isTransientNetworkError], retryUnknownErrors: false, }) export const responseQuality = createScorer({ id: 'response-quality', description: 'Scores response quality', judge: { model: myModel, instructions: 'Return a score and concise reason.', errorProcessors: [retryProcessor], maxProcessorRetries: 2, }, }) .generateScore({ description: 'Score the response quality.', createPrompt: ({ run }) => `Score: ${run.output}`, }) .generateReason({ description: 'Explain the score.', createPrompt: () => 'Explain the score.', }) ``` Avec cette configuration, une requête ayant échoué donne lieu à trois tentatives au maximum auprès du Provider : la requête initiale et deux nouvelles tentatives du Processor. Si `generateScore` se termine et que `generateReason` rencontre un échec réessayable, seul `generateReason` est relancé. `StreamErrorRetryProcessor` respecte les métadonnées réessayables du Provider et les matchers personnalisés précis. Il conserve `retryUnknownErrors` désactivé par défaut ; les erreurs d'authentification, de requête non valide et de longueur de contexte échouent donc immédiatement, sauf si vous les faites correspondre explicitement. Il limite par défaut les valeurs `Retry-After` à `30_000` millisecondes. Utilisez `maxRetryAfterMs` pour modifier cette limite. Évitez d'ajouter des tentatives externes au Scorer ou au Workflow. Ne combinez pas une valeur non nulle de tentatives du modèle avec ce Processor, sauf si vous acceptez volontairement des tentatives supplémentaires. ### Remplacement des tentatives pour une étape La configuration `judge` d'une étape remplace les champs du juge au niveau du Scorer. Les tableaux de Processors remplacent ceux du Scorer. Omettez `maxProcessorRetries` dans la configuration de l'étape pour hériter de la limite numérique du Scorer. Les nouvelles tentatives coordonnées des Processors nécessitent un modèle juge utilisant l'API de génération actuelle de Mastra. Les anciens adaptateurs appellent [`generateLegacy()`](https://mastra.zisheng.pro/fr/reference/agents/generateLegacy), contournent les Processors d'erreur et utilisent le `maxRetries` distinct du SDK AI de cette API, dont la valeur par défaut est `2`. ## Sécurité des types Vous pouvez préciser les types d'entrée/sortie lors de la création des Scorers afin d'améliorer l'inférence de type et la prise en charge d'IntelliSense : ### Raccourci pour le type Agent Pour évaluer des Agents, utilisez `type: 'agent'` afin d'obtenir automatiquement les types appropriés pour leurs entrées/sorties : ```typescript import { createScorer } from '@mastra/core/evals' // Agent scorer with automatic typing const agentScorer = createScorer({ id: 'agent-response-quality', description: 'Evaluates agent responses', type: 'agent', // Automatically provides ScorerRunInputForAgent/ScorerRunOutputForAgent }) .preprocess(({ run }) => { // run.input is automatically typed as ScorerRunInputForAgent const userMessage = run.inputData.inputMessages[0]?.content return { userMessage } }) .generateScore(({ run, results }) => { // run.output is automatically typed as ScorerRunOutputForAgent const response = run.output[0]?.content return response.length > 10 ? 1.0 : 0.5 }) ``` ### Types personnalisés avec des génériques Pour des types d'entrée/sortie personnalisés, utilisez l'approche générique : ```typescript import { createScorer } from '@mastra/core/evals' type CustomInput = { query: string; context: string[] } type CustomOutput = { answer: string; confidence: number } const customScorer = createScorer({ id: 'custom-scorer', description: 'Evaluates custom data', }).generateScore(({ run }) => { // run.input is typed as CustomInput // run.output is typed as CustomOutput return run.output.confidence }) ``` ### Types Agent intégrés - **`ScorerRunInputForAgent`** - Contient `inputMessages`, `rememberedMessages`, `systemMessages` et `taggedSystemMessages` pour l'évaluation des Agents - **`ScorerRunOutputForAgent`** - Tableau des messages de réponse de l'Agent Ces types offrent l'autocomplétion, la validation à la compilation et une meilleure documentation de votre logique de scoring. ## Scoring des Traces avec les types Agent Lorsque vous utilisez `type: 'agent'`, votre Scorer peut aussi bien être ajouté directement aux Agents que noter les Traces issues de leurs interactions. Le Scorer transforme automatiquement les données de Trace au format d'entrée/sortie approprié de l'Agent : ```typescript const agentTraceScorer = createScorer({ id: 'agent-trace-length', description: 'Evaluates agent response length', type: 'agent', }).generateScore(({ run }) => { // Trace data is automatically transformed to agent format const userMessages = run.inputData.inputMessages const agentResponse = run.output[0]?.content // Score based on response length return agentResponse?.length > 50 ? 0 : 1 }) // Register with Mastra for trace scoring const mastra = new Mastra({ scorers: { agentTraceScorer, }, }) ``` ## Signatures des méthodes d'étape ### preprocess Étape facultative de prétraitement qui peut extraire ou transformer les données avant l'analyse. **Mode fonction :** Function: `({ run, results }) => any` **run.input** (`any`): Enregistrements d'entrée fournis au Scorer. Si celui-ci est ajouté à un Agent, il s'agit d'un tableau de messages utilisateur, par exemple \[{ role: 'user', content: 'hello world' }]. S'il est utilisé dans un Workflow, il s'agit de l'entrée du Workflow. **run.output** (`any`): Enregistrement de sortie fourni au Scorer. Pour les Agents, il s'agit généralement de la réponse de l'Agent. Pour les Workflows, il s'agit de la sortie du Workflow. **run.runId** (`string`): Identifiant unique de cette exécution de scoring. **run.requestContext** (`object`): Request Context de l'Agent ou de l'étape de Workflow évaluée (facultatif). **results** (`object`): Objet vide (aucune étape précédente). Renvoie : `any`\ La méthode peut renvoyer n'importe quelle valeur. Celle-ci sera accessible aux étapes suivantes sous la forme `preprocessStepResult`. **Mode objet de prompt :** **description** (`string`): Description du rôle de cette étape de prétraitement. **outputSchema** (`StandardJSONSchemaV1`): Schéma JSON standard de la sortie attendue de l'étape preprocess. **createPrompt** (`function`): Fonction : ({ run, results }) => string. Renvoie le prompt destiné au LLM. **judge** (`object`): (Facultatif) Juge LLM de cette étape, pouvant remplacer le juge principal. Consultez la section Objet Judge. ### analyze Étape d'analyse facultative qui traite les entrées/sorties et les éventuelles données prétraitées. **Mode fonction :** Function: `({ run, results }) => any` **run.input** (`any`): Enregistrements d'entrée fournis au Scorer. Si celui-ci est ajouté à un Agent, il s'agit d'un tableau de messages utilisateur, par exemple \[{ role: 'user', content: 'hello world' }]. S'il est utilisé dans un Workflow, il s'agit de l'entrée du Workflow. **run.output** (`any`): Enregistrement de sortie fourni au Scorer. Pour les Agents, il s'agit généralement de la réponse de l'Agent. Pour les Workflows, il s'agit de la sortie du Workflow. **run.runId** (`string`): Identifiant unique de cette exécution de scoring. **run.requestContext** (`object`): Request Context de l'Agent ou de l'étape de Workflow évaluée (facultatif). **results.preprocessStepResult** (`any`): Résultat de l'étape preprocess, si elle est définie (facultatif). Renvoie : `any`\ La méthode peut renvoyer n'importe quelle valeur. Celle-ci sera accessible aux étapes suivantes sous la forme `analyzeStepResult`. **Mode objet de prompt :** **description** (`string`): Description du rôle de cette étape d'analyse. **outputSchema** (`StandardJSONSchemaV1`): Schéma JSON standard de la sortie attendue de l'étape analyze. **createPrompt** (`function`): Fonction : ({ run, results }) => string. Renvoie le prompt destiné au LLM. **judge** (`object`): (Facultatif) Juge LLM de cette étape, pouvant remplacer le juge principal. Consultez la section Objet Judge. ### `generateScore` Étape **obligatoire** qui calcule le score numérique final. **Mode fonction :** Function: `({ run, results }) => number` **run.input** (`any`): Enregistrements d'entrée fournis au Scorer. Si celui-ci est ajouté à un Agent, il s'agit d'un tableau de messages utilisateur, par exemple \[{ role: 'user', content: 'hello world' }]. S'il est utilisé dans un Workflow, il s'agit de l'entrée du Workflow. **run.output** (`any`): Enregistrement de sortie fourni au Scorer. Pour les Agents, il s'agit généralement de la réponse de l'Agent. Pour les Workflows, il s'agit de la sortie du Workflow. **run.runId** (`string`): Identifiant unique de cette exécution de scoring. **run.requestContext** (`object`): Request Context de l'Agent ou de l'étape de Workflow évaluée (facultatif). **results.preprocessStepResult** (`any`): Résultat de l'étape preprocess, si elle est définie (facultatif). **results.analyzeStepResult** (`any`): Résultat de l'étape analyze, si elle est définie (facultatif). Renvoie : `number`\ La méthode doit renvoyer un score numérique. **Mode objet de prompt :** **description** (`string`): Description du rôle de cette étape de scoring. **outputSchema** (`StandardJSONSchemaV1`): Schéma JSON standard de la sortie attendue de l'étape generateScore. **createPrompt** (`function`): Fonction : ({ run, results }) => string. Renvoie le prompt destiné au LLM. **judge** (`object`): (Facultatif) Juge LLM de cette étape, pouvant remplacer le juge principal. Consultez la section Objet Judge. En mode objet de prompt, vous devez également fournir une fonction `calculateScore` pour convertir la sortie du LLM en score numérique : **calculateScore** (`function`): Fonction : ({ run, results, analyzeStepResult }) => number. Convertit la sortie structurée du LLM en score numérique. ### `generateReason` Étape facultative qui fournit une explication du score. **Mode fonction :** Function: `({ run, results, score }) => string` **run.input** (`any`): Enregistrements d'entrée fournis au Scorer. Si celui-ci est ajouté à un Agent, il s'agit d'un tableau de messages utilisateur, par exemple \[{ role: 'user', content: 'hello world' }]. S'il est utilisé dans un Workflow, il s'agit de l'entrée du Workflow. **run.output** (`any`): Enregistrement de sortie fourni au Scorer. Pour les Agents, il s'agit généralement de la réponse de l'Agent. Pour les Workflows, il s'agit de la sortie du Workflow. **run.runId** (`string`): Identifiant unique de cette exécution de scoring. **run.requestContext** (`object`): Request Context de l'Agent ou de l'étape de Workflow évaluée (facultatif). **results.preprocessStepResult** (`any`): Résultat de l'étape preprocess, si elle est définie (facultatif). **results.analyzeStepResult** (`any`): Résultat de l'étape analyze, si elle est définie (facultatif). **score** (`number`): Score calculé par l'étape generateScore. Renvoie : `string`\ La méthode doit renvoyer une chaîne qui explique le score. **Mode objet de prompt :** **description** (`string`): Description du rôle de cette étape de justification. **createPrompt** (`function`): Fonction : ({ run, results, score }) => string. Renvoie le prompt destiné au LLM. **judge** (`object`): (Facultatif) Juge LLM de cette étape, pouvant remplacer le juge principal. Consultez la section Objet Judge. Toutes les fonctions d'étape peuvent être asynchrones.