> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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`](https://mastra.zisheng.pro/fr/reference/evals/create-scorer) 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` :

```typescript
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.

```typescript
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é.

```typescript
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 :

```typescript
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 :

```typescript
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

```typescript
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](https://mastra.zisheng.pro/fr/reference/evals/create-scorer) pour en savoir plus sur la définition d'une logique de scoring personnalisée.