Scorer de précision du contexte

La fonction createContextPrecisionScorer() crée un scorer qui évalue la pertinence et le positionnement des éléments de contexte récupérés pour générer les sorties attendues. Elle utilise la précision moyenne (Mean Average Precision, MAP) pour favoriser les systèmes qui placent les éléments de contexte pertinents plus tôt dans la séquence.

Elle est particulièrement utile dans les cas suivants :

Évaluation des systèmes RAG

Idéal pour évaluer le contexte récupéré dans les pipelines RAG où :

• L'ordre du contexte influe sur les performances du modèle
• Vous devez mesurer la qualité de la récupération au-delà de la simple pertinence
• Un contexte pertinent placé tôt a plus de valeur qu'un contexte pertinent placé plus tard

Optimisation de la fenêtre de contexte

Utilisez ce scorer pour optimiser la sélection du contexte lorsque vous avez :

• Des fenêtres de contexte limitées
• Des contraintes de budget de tokens
• Des tâches de raisonnement en plusieurs étapes

Paramètres

model:

MastraModelConfig

Modèle de langage à utiliser pour évaluer la pertinence du contexte

options:

ContextPrecisionMetricOptions

Options de configuration du scorer

Vous devez fournir context ou contextExtractor. Si les deux sont fournis, contextExtractor est prioritaire.

Valeur renvoyée par .run()

score:

number

Score de précision moyenne compris entre 0 et scale (par défaut, de 0 à 1)

reason:

string

Explication lisible de l'évaluation de la précision du contexte

Détails du calcul du score

Précision moyenne (Mean Average Precision, MAP)

Le scorer de précision du contexte utilise la précision moyenne pour évaluer à la fois la pertinence et le positionnement :

1. Évaluation du contexte : chaque élément de contexte est classé comme pertinent ou non pertinent pour générer la sortie attendue
2. Calcul de la précision : pour chaque contexte pertinent à la position i, précision = relevant_items_so_far / (i + 1)
3. Précision moyenne : additionnez toutes les valeurs de précision, puis divisez le résultat par le nombre total d'éléments pertinents
4. Score final : multipliez le résultat par le facteur d'échelle et arrondissez-le à deux décimales

Formule de calcul du score

MAP = (Σ Precision@k) / R

Where:
- Precision@k = (relevant items in positions 1...k) / k
- R = total number of relevant items
- Only calculated at positions where relevant items appear

Interprétation du score

• 0.9-1.0 : excellente précision : tous les éléments de contexte pertinents figurent au début de la séquence
• 0.7-0.8 : bonne précision : la plupart des éléments de contexte pertinents sont bien positionnés
• 0.4-0.6 : précision moyenne : les éléments de contexte pertinents sont mêlés aux éléments non pertinents
• 0.1-0.3 : faible précision : le contexte pertinent est rare ou mal positionné
• 0.0 : aucun contexte pertinent trouvé

Analyse de la justification

Le champ reason explique :

• Quels éléments de contexte ont été jugés pertinents ou non pertinents
• Comment leur positionnement a influencé le calcul de la MAP
• Quels critères de pertinence précis ont été utilisés lors de l'évaluation

Pistes d'optimisation

Utilisez les résultats pour :

• Améliorer la récupération : filtrer le contexte non pertinent avant le classement
• Optimiser le classement : veiller à ce que le contexte pertinent apparaisse tôt
• Ajuster la taille des chunks : trouver un équilibre entre le niveau de détail du contexte et la précision de sa pertinence
• Évaluer les embeddings : tester différents modèles d'embedding afin d'améliorer la récupération

Exemple de calcul

context : [relevant, irrelevant, relevant, irrelevant]

• Position 0 : pertinent → Précision = 1/1 = 1.0
• Position 1 : ignoré (non pertinent)
• Position 2 : pertinent → Précision = 2/3 = 0.67
• Position 3 : ignoré (non pertinent)

MAP = (1.0 + 0.67) / 2 = 0.835 ≈ 0.83

Configuration du scorer

Extraction dynamique du contexte

const scorer = createContextPrecisionScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract context dynamically based on the query
      const query = input?.inputMessages?.[0]?.content || ''

      // Example: Retrieve from a vector database
      const searchResults = vectorDB.search(query, { limit: 10 })
      return searchResults.map(result => result.content)
    },
    scale: 1,
  },
})

Évaluation d'un contexte volumineux

const scorer = createContextPrecisionScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      // Simulate retrieved documents from vector database
      'Document 1: Highly relevant content...',
      'Document 2: Somewhat related content...',
      'Document 3: Tangentially related...',
      'Document 4: Not relevant...',
      'Document 5: Highly relevant content...',
      // ... up to dozens of context pieces
    ],
  },
})

Exemple

Évaluez la précision de la récupération du contexte d'un système RAG pour différentes requêtes :

src/example-context-precision.ts

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

const scorer = createContextPrecisionScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract context from agent's retrieved documents
      return output.metadata?.retrievedContext || []
    },
  },
})

const result = await runEvals({
  data: [
    {
      input: 'How does photosynthesis work in plants?',
    },
    {
      input: 'What are the mental and physical benefits of exercise?',
    },
  ],
  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 de runEvals.

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

Comparaison avec la pertinence du contexte

Choisissez le scorer adapté à vos besoins :

Cas d'utilisation	Pertinence du contexte	Précision du contexte
Évaluation RAG	Lorsque l'utilisation compte	Lorsque le classement compte
Qualité du contexte	Niveaux nuancés	Pertinence binaire
Détection des éléments manquants	✓ Identifie les lacunes	✗ Non évaluée
Suivi de l'utilisation	✓ Suit l'utilisation	✗ Non prise en compte
Sensibilité à la position	✗ Indépendante de la position	✓ Favorise un placement précoce

Voir aussi

• Scorer de pertinence des réponses : évalue si les réponses traitent la question
• Scorer de fidélité : mesure l'ancrage des réponses dans le contexte
• Scorers personnalisés : créez vos propres métriques d'évaluation