MastraScorer

La classe MastraScorer est la classe de base de tous les Scorers de Mastra. Elle fournit une méthode .run() standard permettant d'évaluer des paires entrée/sortie et prend en charge les workflows de scoring en plusieurs étapes avec le flux d'exécution preprocess → analyze → generateScore → generateReason.

La plupart des utilisateurs devraient employer createScorer pour créer des instances de Scorer. Il est déconseillé d'instancier directement MastraScorer.

Obtenir une instance de MastraScorer

Utilisez la fonction de fabrique createScorer, qui renvoie une instance de MastraScorer :

import { createScorer } from '@mastra/core/evals'

const scorer = createScorer({
  name: 'My Custom Scorer',
  description: 'Evaluates responses based on custom criteria',
}).generateScore(({ run, results }) => {
  // scoring logic
  return 0.85
})

// scorer is now a MastraScorer instance

Méthode .run()

La méthode .run() est le principal moyen d'exécuter votre Scorer et d'évaluer des paires entrée/sortie. Elle traite les données à travers les étapes que vous avez définies (preprocess → analyze → generateScore → generateReason) et renvoie un objet de résultat détaillé contenant le score, sa justification et les résultats intermédiaires.

const result = await scorer.run({
  input: 'What is machine learning?',
  output: 'Machine learning is a subset of artificial intelligence...',
  runId: 'optional-run-id',
  requestContext: {/* optional context */},
})

Entrée de .run()

input:

any

Données d’entrée à évaluer. Leur type peut varier selon les exigences de votre Scorer.

output:

any

Données de sortie à évaluer. Leur type peut varier selon les exigences de votre Scorer.

runId:

string

Identifiant unique facultatif de cette exécution de scoring.

requestContext:

any

Request Context facultatif provenant de l’agent ou de l’étape de workflow en cours d’évaluation.

groundTruth:

any

Sortie attendue ou de référence facultative à utiliser pour la comparaison pendant le scoring. Transmise automatiquement lors de l’utilisation de runEvals.

Valeur renvoyée par .run()

runId:

string

Identifiant unique de cette exécution de scoring.

score:

number

Score numérique calculé par l’étape generateScore.

reason:

string

Explication du score, si l’étape generateReason a été définie (facultatif).

preprocessStepResult:

any

Résultat de l’étape preprocess, si elle est définie (facultatif).

analyzeStepResult:

any

Résultat de l’étape analyze, si elle est définie (facultatif).

preprocessPrompt:

string

Prompt de prétraitement, s’il est défini (facultatif).

analyzePrompt:

string

Prompt d’analyse, s’il est défini (facultatif).

generateScorePrompt:

string

Prompt de génération du score, s’il est défini (facultatif).

generateReasonPrompt:

string

Prompt de génération de la justification, s’il est défini (facultatif).

judge:

ScorerJudgeResults

Détails d’exécution des étapes du Scorer fondées sur un prompt, le cas échéant (facultatif).

Résultats du juge

L'enregistrement facultatif judge contient des informations sur les appels du modèle juge effectués par les étapes du Scorer fondées sur un prompt. Ses clés connues sont preprocess, analyze, generateScore et generateReason. Chaque clé contient un tableau executions ordonné.

interface ScorerJudgeExecutionBase {
  prompt: string
  judgeModelId: string
  judgeProvider?: string
  attemptCount: number
  modelCallCount: number
  durationMs: number
}

interface ScorerJudgeExecutionSuccess extends ScorerJudgeExecutionBase {
  status: 'success'
  output: JSONValue
  usage: ScorerJudgeUsage
  cost?: {
    amount: number
    unit: string
    source: string
  }
}

interface ScorerJudgeExecutionFailure extends ScorerJudgeExecutionBase {
  status: 'failed'
  output?: JSONValue
  rawOutput?: string
  usage?: ScorerJudgeUsage
  finishReason?: string
  error: {
    name: string
    message: string
    code?: string
  }
}

type ScorerJudgeExecution = ScorerJudgeExecutionSuccess | ScorerJudgeExecutionFailure

interface ScorerJudgeUsage {
  inputTokens?: number
  outputTokens?: number
  totalTokens?: number
  reasoningTokens?: number
  cachedInputTokens?: number
  cacheCreationInputTokens?: number
}

type ScorerJudgeResults = Partial<
  Record<
    'preprocess' | 'analyze' | 'generateScore' | 'generateReason',
    { executions: ScorerJudgeExecution[] }
  >
>

Utilisez la clé de l'étape pour accéder aux détails de l'exécution du juge :

const execution = result.judge?.generateScore?.executions[0]

console.log(execution?.status)
console.log(execution?.judgeModelId)
console.log(execution?.usage?.totalTokens)
console.log(execution?.durationMs)

La valeur status décrit le résultat de l'exécution logique de l'étape de prompt, et non la qualité de la réponse évaluée. Une solution de repli pour sortie structurée qui finit par réussir crée une exécution success avec un attemptCount supérieur à un. Lorsque toutes les tentatives sont épuisées, une exécution failed est créée.

Les exécutions réussies nécessitent un output validé et une valeur usage normalisée. Les exécutions en échec nécessitent un résumé error et incluent uniquement les éléments reçus par l'environnement d'exécution. Une exécution en échec inclut output uniquement lorsque la sortie a été validée avant un échec ultérieur du callback ou de l'orchestration. Mastra n'analyse pas rawOutput pour créer output.

attemptCount compte les appels du juge, y compris une solution de repli pour sortie structurée. modelCallCount compte les étapes du modèle terminées sur l'ensemble de ces tentatives. durationMs couvre l'exécution complète de l'étape de prompt.

Les étapes de fonction ne créent pas d'entrées judge. L'utilisation consignée dans cet enregistrement appartient au modèle juge du Scorer, et non à l'agent ou au workflow évalué. Filtrez selon status lors de l'agrégation des exécutions réussies. Incluez les deux états lors de l'agrégation de toute l'utilisation terminée du Provider. Le champ facultatif cost est présent uniquement dans les exécutions réussies qui indiquent directement un coût, une source et une unité faisant autorité.

Utilisez les métriques Mastra pour interroger l'utilisation agrégée, la latence et le coût estimé sur plusieurs exécutions de Scorers. L'enregistrement judge décrit une seule exécution de Scorer et n'interroge ni les métriques ni les traces.

Exécutions en échec

L'échec d'une étape du Scorer rejette toujours la promesse .run(). Interceptez ScorerRunError afin d'examiner les étapes terminées et les éventuels résultats qu'elles ont produits :

import { ScorerRunError } from '@mastra/core/evals'

try {
  const result = await scorer.run({ input, output })
  console.log(result.score)
} catch (error) {
  if (error instanceof ScorerRunError) {
    console.log(error.failedStep)
    console.log(error.completedSteps)
    console.log(error.result?.score)

    const failedExecution = error.result?.judge?.[error.failedStep]?.executions.find(
      execution => execution.status === 'failed',
    )
    console.log(failedExecution?.error)
  }

  throw error
}

ScorerRunError expose les propriétés suivantes :

failedStep:

ScorerStepName

Étape du Scorer qui a échoué.

completedSteps:

ScorerStepName[]

Étapes du Scorer terminées avant l’échec, dans leur ordre d’exécution.

result:

ScorerRunResultSnapshot | undefined

Sorties des étapes du Scorer terminées et éléments d’exécution du juge provenant des étapes de prompt tentées. Cette propriété est omise lorsqu’aucun de ces éléments n’est disponible.

L'instantané result contient les sorties des étapes terminées et les éléments d'exécution du juge. Par exemple, si generateReason échoue après que generateScore a renvoyé 0, error.result.score vaut 0, l'exécution generateScore possède status: 'success' et l'exécution generateReason possède status: 'failed'. L'exécution reste en échec.

L'échec d'un prompt peut créer error.result avec uniquement l'identité de l'exécution, l'entrée et une entrée judge en échec. Une étape de fonction qui échoue avant de produire un champ du Scorer ne crée pas de résultat.

JSON.stringify(error) utilise la sérialisation standard de MastraError et omet result, y compris les éléments du juge réussis et en échec. Lisez explicitement result lorsque vous avez besoin des artefacts du Scorer ou de la sortie brute en échec.

Le résultat en mémoire d'une expérience peut conserver un score ou une justification terminés provenant d'un Scorer en échec, ainsi que error, failedStep et completedSteps. Le Scorer est toujours considéré comme étant en échec et un score récupéré n'est pas écrit dans l'ancien stockage des scores réussis.

Flux d'exécution des étapes

Lorsque vous appelez .run(), MastraScorer exécute les étapes définies dans l'ordre suivant :

1. preprocess (facultatif) : extrait ou transforme les données
2. analyze (facultatif) : traite l'entrée, la sortie et les données prétraitées
3. generateScore (requis) : calcule le score numérique
4. generateReason (facultatif) : fournit une explication du score

Chaque étape reçoit les résultats des étapes précédentes, ce qui vous permet de créer des pipelines d'évaluation complexes.

Exemple d'utilisation

const scorer = createScorer({
  name: 'Quality Scorer',
  description: 'Evaluates response quality',
})
  .preprocess(({ run }) => {
    // Extract key information
    return { wordCount: run.output.split(' ').length }
  })
  .analyze(({ run, results }) => {
    // Analyze the response
    const hasSubstance = results.preprocessStepResult.wordCount > 10
    return { hasSubstance }
  })
  .generateScore(({ results }) => {
    // Calculate score
    return results.analyzeStepResult.hasSubstance ? 1.0 : 0.0
  })
  .generateReason(({ score, results }) => {
    // Explain the score
    const wordCount = results.preprocessStepResult.wordCount
    return `Score: ${score}. Response has ${wordCount} words.`
  })

// Use the scorer
const result = await scorer.run({
  input: 'What is machine learning?',
  output: 'Machine learning is a subset of artificial intelligence...',
})

console.log(result.score) // 1.0
console.log(result.reason) // "Score: 1.0. Response has 12 words."

Intégration

Les instances de MastraScorer peuvent être utilisées pour les agents et les étapes de workflows.

Consultez la référence createScorer pour en savoir plus sur la définition d'une logique de scoring personnalisée.