Scorer Context Recall

La fonction createContextRecallScorer() crée un Scorer qui évalue dans quelle mesure le contexte récupéré couvre les affirmations d'une réponse de référence fiable. Elle mesure l'exhaustivité de la récupération en vérifiant quelle proportion des affirmations de la référence peut être attribuée au contexte récupéré.

Ce Scorer nécessite une réponse de référence fiable, ce qui le rend adapté aux jeux de données étiquetés dans les environnements de CI ou de test. Lorsque groundTruth n'est pas fourni lors de l'exécution, le Scorer renvoie un score de 0 au lieu de lever une erreur.

Évaluation de la récupération RAG

Idéal pour évaluer l'exhaustivité de la récupération dans les pipelines RAG lorsque :

• vous devez vérifier que le système de récupération obtient toutes les informations nécessaires ;
• vous disposez de jeux de données étiquetés avec des réponses correctes connues ;
• vous souhaitez détecter les régressions dans les résultats renvoyés par le système de récupération.

Tests fondés sur des jeux de données

À utiliser pour exécuter des évaluations sur des ensembles de tests sélectionnés :

• pipelines de CI comprenant des questions étiquetées avec une référence fiable ;
• tests A/B de stratégies de récupération ;
• comparaison de modèles d'embedding en matière de couverture.

Paramètres

model:

MastraModelConfig

Modèle de langage à utiliser pour évaluer l'attribution des affirmations

options:

ContextRecallMetricOptions

Options de configuration du Scorer

Vous devez fournir context ou contextExtractor. Lorsque les deux sont fournis, contextExtractor n'est utilisé que si l'entrée et la sortie de l'exécution ont le format d'un agent (MastraDBMessage[]) ; sinon, le Scorer se rabat sur context.

Valeur renvoyée par .run()

score:

number

Score de rappel compris entre 0 et scale (0 à 1 par défaut), représentant la proportion d'affirmations de la référence fiable couvertes par le contexte

reason:

string

Explication lisible indiquant quelles affirmations de la référence fiable ont été trouvées ou non dans le contexte

Détails du calcul du score

Attribution des affirmations

Context Recall utilise une évaluation par LLM en deux étapes, suivie d'un calcul de score déterministe :

1. Extraction des affirmations : la réponse de référence fiable est décomposée en affirmations atomiques
2. Vérification de l'attribution : chaque affirmation est confrontée au contexte de récupération afin de vérifier qu'il la corrobore

Le score est ensuite calculé comme le rapport entre les affirmations attribuées et le nombre total d'affirmations, multiplié par scale.

Formule de calcul du score

Context Recall = attributed_claims / total_claims × scale

Where:
- attributed_claims = number of ground-truth claims supported by the context
- total_claims = total number of claims extracted from the ground truth
- Attribution is binary: a claim is either supported (yes) or not (no)

Interprétation du score

Ces plages supposent que scale conserve sa valeur par défaut de 1. Si vous utilisez une échelle personnalisée, multipliez-les en conséquence.

• 0.9-1.0 : excellent rappel ; le contexte couvre presque toutes les affirmations de la référence fiable
• 0.7-0.8 : bon rappel ; la plupart des affirmations sont couvertes, avec quelques lacunes mineures
• 0.4-0.6 : rappel moyen ; des informations importantes manquent dans le contexte
• 0.1-0.3 : faible rappel ; la plupart des affirmations de la référence fiable ne figurent pas dans le contexte
• 0.0 : aucun rappel ; aucune affirmation de la référence fiable ne figure dans le contexte

Analyse de la justification

Le champ reason explique :

• quelles affirmations de la référence fiable ont été trouvées dans le contexte ;
• quelles affirmations manquaient et quelles lacunes d'information existent ;
• quels extraits précis du contexte corroborent les affirmations attribuées.

Pistes d'optimisation

Utilisez les résultats pour :

• Améliorer la récupération : identifier les types d'informations omis par le système de récupération
• Ajuster la taille des chunks : vérifier que les chunks contiennent suffisamment de détails pour couvrir les affirmations de la référence fiable
• Évaluer les embeddings : tester différents modèles d'embedding pour améliorer la couverture des informations
• Étendre la base de connaissances : ajouter des documents couvrant les affirmations fréquemment omises

Exemple de calcul

Référence fiable : « Einstein est né en 1879. Il a développé la relativité. Il a reçu le prix Nobel. »

Affirmations extraites : 3

• « Einstein est né en 1879 » → attribuée (le contexte mentionne sa date de naissance)
• « Einstein a développé la relativité » → attribuée (le contexte couvre la relativité)
• « Einstein a reçu le prix Nobel » → non attribuée (le contexte ne mentionne pas le prix Nobel)

Rappel = 2/3 = 0,67

Configuration du Scorer

Extraction dynamique du contexte

const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      const query = input?.inputMessages?.[0]?.content || ''
      const searchResults = vectorDB.search(query, { limit: 10 })
      return searchResults.map(result => result.content)
    },
    scale: 1,
  },
})

Évaluation d'un contexte statique

const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Document 1: Einstein was born on 14 March 1879 in Ulm, Germany.',
      'Document 2: Einstein published the theory of special relativity in 1905.',
      'Document 3: Einstein moved to the United States in 1933.',
    ],
  },
})

Exemple

Évaluez l'exhaustivité de la récupération RAG par rapport à un jeu de données étiqueté :

src/example-context-recall.ts

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

const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract context from tool invocation results in the agent output
      return output
        .filter(msg => msg?.role === 'assistant')
        .flatMap(msg => msg?.content?.toolInvocations ?? [])
        .filter((tool: any) => tool.state === 'result')
        .map((tool: any) => JSON.stringify(tool.result))
    },
  },
})

const result = await runEvals({
  data: [
    {
      input: 'What are the health benefits of green tea?',
      groundTruth:
        'Green tea contains antioxidants that reduce inflammation, L-theanine that improves focus, and catechins that boost metabolism.',
    },
    {
      input: 'How does photosynthesis work?',
      groundTruth:
        'Photosynthesis converts sunlight into chemical energy using chlorophyll in chloroplasts, producing glucose and oxygen from carbon dioxide and water.',
    },
  ],
  scorers: [scorer],
  target: myAgent,
  onItemComplete: ({ scorerResults }) => {
    console.log({
      score: scorerResults[scorer.id].score,
      reason: scorerResults[scorer.id].reason,
    })
  },
})

console.log(result.scores)

Pour plus de détails sur runEvals, consultez la référence de runEvals.

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

Comparaison avec Context Precision

Choisissez le Scorer adapté à vos besoins :

Cas d'utilisation	Context Recall	Context Precision
Mesure effectuée	Couverture de la référence fiable	Pertinence des chunks récupérés
Direction	Référence fiable → contexte	Contexte → référence fiable
Sensible à la position	Non	Oui (récompense un placement précoce)
Nécessite une référence fiable	Oui	Oui
Mode d'échec détecté	Informations manquantes	Bruit non pertinent

Utilisez-les ensemble pour obtenir une vue complète de la qualité de la récupération : la précision détecte les éléments inutiles dans le contexte, tandis que le rappel en détecte les lacunes.

Ressources associées

• Scorer Context Precision : évalue si le contexte récupéré est pertinent et bien classé
• Scorer Context Relevance : évalue l'utilisation et la qualité du contexte
• Scorer Faithfulness : mesure l'ancrage de la réponse dans le contexte
• Scorers personnalisés : créez vos propres métriques d'évaluation