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

# 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

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

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

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

```typescript
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](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).

## 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](https://mastra.zisheng.pro/fr/reference/evals/answer-relevancy) : évalue si les réponses traitent la question
- [Scorer de fidélité](https://mastra.zisheng.pro/fr/reference/evals/faithfulness) : mesure l'ancrage des réponses dans le contexte
- [Scorers personnalisés](https://mastra.zisheng.pro/fr/docs/evals/custom-scorers) : créez vos propres métriques d'évaluation