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

# Hallucination Scorer

La fonction `createHallucinationScorer()` évalue si un LLM génère des informations factuellement correctes en comparant sa sortie au contexte fourni. Ce Scorer mesure les hallucinations en identifiant les contradictions directes entre le contexte et la sortie.

## Paramètres

La fonction `createHallucinationScorer()` accepte un seul objet d'options doté des propriétés suivantes :

**model** (`LanguageModel`): Configuration du modèle utilisé pour évaluer les hallucinations.

**options** (`Options`): Options de configuration.

**options.scale** (`number`): Valeur maximale du score.

**options.context** (`string[]`): Chaînes de contexte statiques à utiliser comme vérité de référence pour détecter les hallucinations.

**options.getContext** (`(params: GetContextParams) => string[] | Promise<string[]>`): Hook permettant de résoudre dynamiquement le contexte à l’exécution. Il prévaut sur le contexte statique. Utile pour le scoring en direct lorsque le contexte, comme les résultats de Tools, n’est disponible qu’au moment de l’exécution du Scorer.

Cette fonction renvoie une instance de la classe MastraScorer. La méthode `.run()` accepte la même entrée que les autres Scorers (consultez la [référence MastraScorer](https://mastra.zisheng.pro/fr/reference/evals/mastra-scorer)), mais la valeur renvoyée inclut les champs propres aux LLM décrits ci-dessous.

## Valeur renvoyée par `.run()`

**runId** (`string`): ID de l'exécution (facultatif).

**preprocessStepResult** (`object`): Objet contenant les affirmations extraites : { claims: string\[] }

**preprocessPrompt** (`string`): Prompt envoyé au LLM pour l’étape de prétraitement (facultatif).

**analyzeStepResult** (`object`): Objet contenant les verdicts : { verdicts: Array<{ statement: string, verdict: 'yes' | 'no', reason: string }> }

**analyzePrompt** (`string`): Prompt envoyé au LLM pour l’étape d’analyse (facultatif).

**score** (`number`): Score d’hallucination (de 0 à la valeur de scale, 0-1 par défaut).

**reason** (`string`): Explication détaillée du score et des contradictions identifiées.

**generateReasonPrompt** (`string`): Prompt envoyé au LLM pour l’étape generateReason (facultatif).

## Détails du scoring

Le Scorer évalue les hallucinations en détectant les contradictions et en analysant les affirmations non étayées.

### Processus de scoring

1. Analyse le contenu factuel :

   - Extrait les affirmations du contexte
   - Identifie les valeurs numériques et les dates
   - Cartographie les relations entre les affirmations

2. Analyse la sortie pour détecter les hallucinations :

   - La compare aux affirmations du contexte
   - Marque les contradictions directes comme des hallucinations
   - Identifie les affirmations non étayées comme des hallucinations
   - Évalue l'exactitude numérique
   - Tient compte du contexte d'approximation

3. Calcule le score d'hallucination :

   - Compte les affirmations hallucinées (contradictions et affirmations non étayées)
   - Divise ce nombre par le nombre total d'affirmations
   - Adapte le résultat à la plage configurée

Score final : `(hallucinated_statements / total_statements) * scale`

### Considérations importantes

- Les affirmations absentes du contexte sont traitées comme des hallucinations

- Les affirmations subjectives sont des hallucinations, sauf si elles sont explicitement étayées

- Les formulations spéculatives (« pourrait », « éventuellement ») concernant des faits PRÉSENTS dans le contexte sont autorisées

- Les formulations spéculatives concernant des faits ABSENTS du contexte sont traitées comme des hallucinations

- Les sorties vides correspondent à zéro hallucination

- L'évaluation numérique tient compte des éléments suivants :

  - Précision adaptée à l'échelle
  - Approximations contextuelles
  - Indicateurs de précision explicites

### Interprétation du score

Pour un score d'hallucination compris entre 0 et 1 :

- **0.0** : aucune hallucination ; toutes les affirmations correspondent au contexte.
- **0.3 à 0.4** : peu d'hallucinations ; quelques contradictions.
- **0.5 à 0.6** : hallucinations modérées ; plusieurs contradictions.
- **0.7 à 0.8** : nombreuses hallucinations ; beaucoup de contradictions.
- **0.9 à 1.0** : hallucination complète ; la plupart ou la totalité des affirmations contredisent le contexte.

Le score représente le degré d'hallucination : plus il est faible, meilleure est la concordance factuelle avec le contexte fourni.

## Exemples

### Contexte statique

Utilisez un contexte statique lorsque vous disposez d'une vérité de référence connue à laquelle comparer la sortie :

```typescript
import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt'

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'The first iPhone was announced on January 9, 2007.',
      'It was released on June 29, 2007.',
      'Steve Jobs introduced it at Macworld.',
    ],
  },
})
```

### Contexte dynamique avec `getContext`

Utilisez `getContext` dans les scénarios de scoring en direct où le contexte provient des résultats de Tools :

```typescript
import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt'
import { extractToolResults } from '@mastra/evals/scorers'

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    getContext: ({ run, step }) => {
      // Extract tool results as context
      const toolResults = extractToolResults(run.output)
      return toolResults.map(t => JSON.stringify({ tool: t.toolName, result: t.result }))
    },
  },
})
```

### Scoring en direct avec un Agent

Associez le Scorer à un agent pour effectuer une évaluation en direct :

```typescript
import { Agent } from '@mastra/core/agent'
import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt'
import { extractToolResults } from '@mastra/evals/scorers'

const hallucinationScorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    getContext: ({ run }) => {
      const toolResults = extractToolResults(run.output)
      return toolResults.map(t => JSON.stringify({ tool: t.toolName, result: t.result }))
    },
  },
})

const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful assistant.',
  evals: {
    scorers: [hallucinationScorer],
  },
})
```

### Évaluation par lots avec `runEvals`

```typescript
import { runEvals } from '@mastra/core/evals'
import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt'
import { myAgent } from './agent'

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: ['Known fact 1', 'Known fact 2'],
  },
})

const result = await runEvals({
  data: [{ input: 'Tell me about topic A' }, { input: 'Tell me about topic B' }],
  scorers: [scorer],
  target: myAgent,
  onItemComplete: ({ scorerResults }) => {
    console.log({
      score: scorerResults[scorer.id].score,
      reason: scorerResults[scorer.id].reason,
    })
  },
})

console.log(result.scores)
```

Pour en savoir plus sur `runEvals`, consultez la [référence runEvals](https://mastra.zisheng.pro/fr/reference/evals/run-evals).

Pour ajouter ce Scorer à un agent, consultez le guide de [présentation des Scorers](https://mastra.zisheng.pro/fr/docs/evals/overview).

## Ressources associées

- [Scorer de fidélité](https://mastra.zisheng.pro/fr/reference/evals/faithfulness)
- [Scorer de pertinence de la réponse](https://mastra.zisheng.pro/fr/reference/evals/answer-relevancy)