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.

context:

string[]

Chaînes de contexte statiques à utiliser comme vérité de référence pour détecter les hallucinations.

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), 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 :

src/example-static-context.ts

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 :

src/example-dynamic-context.ts

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 :

src/example-live-scoring.ts

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

src/example-batch-evals.ts

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.

Pour ajouter ce Scorer à un agent, consultez le guide de présentation des Scorers.

Ressources associées

• Scorer de fidélité
• Scorer de pertinence de la réponse