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

# Évaluateur de pertinence du contexte

La fonction `createContextRelevanceScorerLLM()` crée un évaluateur qui détermine dans quelle mesure le contexte fourni est pertinent et utile pour générer les réponses des agents. Elle utilise des niveaux de pertinence pondérés et applique des pénalités au contexte très pertinent non utilisé ainsi qu’aux informations manquantes.

Elle est particulièrement utile dans les cas suivants :

## Évaluation de la génération de contenu

Idéal pour évaluer la qualité du contexte dans :

- les systèmes de chat où l’utilisation du contexte est importante ;
- les pipelines RAG nécessitant une évaluation détaillée de la pertinence ;
- les systèmes où l’absence de contexte affecte la qualité.

## Optimisation de la sélection du contexte

À utiliser pour optimiser :

- une couverture complète du contexte ;
- une utilisation efficace du contexte ;
- l’identification des lacunes de contexte.

## Paramètres

**model** (`MastraModelConfig`): Modèle de langage à utiliser pour évaluer la pertinence du contexte

**options** (`ContextRelevanceOptions`): Options de configuration de l’évaluateur

Remarque : vous devez fournir `context` ou `contextExtractor`. Si les deux sont fournis, `contextExtractor` est prioritaire.

## Valeurs renvoyées par `.run()`

**score** (`number`): Score de pertinence pondéré compris entre 0 et l’échelle (valeur par défaut : 0–1)

**reason** (`string`): Explication lisible par un humain de l’évaluation de la pertinence du contexte

## Détails de la notation

### Notation de la pertinence pondérée

Context Relevance utilise un algorithme de notation avancé qui prend en compte :

1. **Niveaux de pertinence** : chaque élément de contexte est classé selon des valeurs pondérées :

   - `high` = 1.0 (répond directement à la requête)
   - `medium` = 0.7 (information d’appui)
   - `low` = 0.3 (lien indirect)
   - `none` = 0.0 (totalement non pertinent)

2. **Détection de l’utilisation** : détermine si le contexte pertinent a réellement été utilisé dans la réponse

3. **Pénalités appliquées** (configurables avec les options `penalties`) :

   - **Contexte très pertinent non utilisé** : pénalité `unusedHighRelevanceContext` par contexte très pertinent non utilisé (valeur par défaut : 0.1)
   - **Contexte manquant** : jusqu’à `maxMissingContextPenalty` pour les informations manquantes identifiées (valeur par défaut : 0.5)

### Formule de notation

```text
Base Score = Σ(relevance_weights) / (num_contexts × 1.0)
Usage Penalty = count(unused_high_relevance) × unusedHighRelevanceContext
Missing Penalty = min(count(missing_context) × missingContextPerItem, maxMissingContextPenalty)

Final Score = max(0, Base Score - Usage Penalty - Missing Penalty) × scale
```

**Valeurs par défaut** :

- `unusedHighRelevanceContext` = 0.1 (pénalité de 10 % par contexte très pertinent non utilisé)
- `missingContextPerItem` = 0.15 (pénalité de 15 % par élément de contexte manquant)
- `maxMissingContextPenalty` = 0.5 (pénalité maximale de 50 % pour contexte manquant)
- `scale` = 1

### Interprétation du score

- **0.9-1.0** : Excellent — tout le contexte est très pertinent et utilisé
- **0.7-0.8** : Bon — majoritairement pertinent, avec de petites lacunes
- **0.4-0.6** : Mitigé — une part importante du contexte est non pertinente ou inutilisée
- **0.2-0.3** : Faible — le contexte est majoritairement non pertinent
- **0.0-0.1** : Très faible — aucun contexte pertinent n’a été trouvé

### Analyse de la justification

Le champ de justification fournit des informations sur :

- le niveau de pertinence de chaque élément de contexte (high/medium/low/none) ;
- le contexte réellement utilisé dans la réponse ;
- les pénalités appliquées au contexte très pertinent non utilisé (configurables avec `unusedHighRelevanceContext`) ;
- le contexte manquant qui aurait amélioré la réponse (pénalisé avec `missingContextPerItem` jusqu’à `maxMissingContextPenalty`).

### Stratégies d’optimisation

Utilisez les résultats pour améliorer votre système :

- **Filtrer le contexte non pertinent** : supprimez les éléments de faible ou de nulle pertinence avant le traitement.
- **Garantir l’utilisation du contexte** : assurez-vous que le contexte très pertinent est intégré.
- **Combler les lacunes de contexte** : ajoutez les informations manquantes identifiées par l’évaluateur.
- **Équilibrer la taille du contexte** : trouvez la quantité optimale de contexte pour obtenir la meilleure pertinence.
- **Ajuster la sensibilité aux pénalités** : adaptez `unusedHighRelevanceContext`, `missingContextPerItem` et `maxMissingContextPenalty` à la tolérance de votre application au contexte inutilisé ou manquant.

### Différence avec Context Precision

| Aspect                 | Context Relevance                        | Context Precision                             |
| ---------------------- | ---------------------------------------- | --------------------------------------------- |
| **Algorithme**         | Niveaux pondérés avec pénalités          | Précision moyenne (MAP)                       |
| **Pertinence**         | Plusieurs niveaux (high/medium/low/none) | Binaire (oui/non)                             |
| **Position**           | Non prise en compte                      | Essentielle (récompense un placement précoce) |
| **Utilisation**        | Suit et pénalise le contexte inutilisé   | Non prise en compte                           |
| **Éléments manquants** | Identifie et pénalise les lacunes        | Non évalués                                   |

## Configuration de l’évaluateur

### Configuration personnalisée des pénalités

Contrôlez l’application des pénalités au contexte inutilisé et manquant :

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

// Stricter penalty configuration
const strictScorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Einstein won the Nobel Prize for photoelectric effect',
      'He developed the theory of relativity',
      'Einstein was born in Germany',
    ],
    penalties: {
      unusedHighRelevanceContext: 0.2, // 20% penalty per unused high-relevance context
      missingContextPerItem: 0.25, // 25% penalty per missing context item
      maxMissingContextPenalty: 0.6, // Maximum 60% penalty for missing context
    },
    scale: 1,
  },
})

// Lenient penalty configuration
const lenientScorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Einstein won the Nobel Prize for photoelectric effect',
      'He developed the theory of relativity',
      'Einstein was born in Germany',
    ],
    penalties: {
      unusedHighRelevanceContext: 0.05, // 5% penalty per unused high-relevance context
      missingContextPerItem: 0.1, // 10% penalty per missing context item
      maxMissingContextPenalty: 0.3, // Maximum 30% penalty for missing context
    },
    scale: 1,
  },
})

const testRun = {
  input: {
    inputMessages: [
      {
        id: '1',
        role: 'user',
        content: 'What did Einstein achieve in physics?',
      },
    ],
  },
  output: [
    {
      id: '2',
      role: 'assistant',
      content: 'Einstein won the Nobel Prize for his work on the photoelectric effect.',
    },
  ],
}

const strictResult = await strictScorer.run(testRun)
const lenientResult = await lenientScorer.run(testRun)

console.log('Strict penalties:', strictResult.score) // Lower score due to unused context
console.log('Lenient penalties:', lenientResult.score) // Higher score, less penalty
```

### Extraction dynamique du contexte

```typescript
const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract context based on the query
      const userQuery = input?.inputMessages?.[0]?.content || ''
      if (userQuery.includes('Einstein')) {
        return [
          'Einstein won the Nobel Prize for the photoelectric effect',
          'He developed the theory of relativity',
        ]
      }
      return ['General physics information']
    },
    penalties: {
      unusedHighRelevanceContext: 0.15,
    },
  },
})
```

### Facteur d’échelle personnalisé

```typescript
const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: ['Relevant information...', 'Supporting details...'],
    scale: 100, // Scale scores from 0-100 instead of 0-1
  },
})

// Result will be scaled: score: 85 instead of 0.85
```

### Combiner plusieurs sources de contexte

```typescript
const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      const query = input?.inputMessages?.[0]?.content || ''

      // Combine from multiple sources
      const kbContext = knowledgeBase.search(query)
      const docContext = documentStore.retrieve(query)
      const cacheContext = contextCache.get(query)

      return [...kbContext, ...docContext, ...cacheContext]
    },
    scale: 1,
  },
})
```

## Exemples

### Exemple de pertinence élevée

Cet exemple montre une excellente pertinence du contexte : tous les éléments de contexte soutiennent directement la réponse.

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Einstein won the Nobel Prize for his discovery of the photoelectric effect in 1921.',
      'He published his theory of special relativity in 1905.',
      'His general relativity theory, published in 1915, revolutionized our understanding of gravity.',
    ],
    scale: 1,
  },
})

const result = await scorer.run({
  input: {
    inputMessages: [
      {
        id: '1',
        role: 'user',
        content: "What were Einstein's major scientific achievements?",
      },
    ],
  },
  output: [
    {
      id: '2',
      role: 'assistant',
      content:
        "Einstein's major achievements include the Nobel Prize for the photoelectric effect, special relativity in 1905, and general relativity in 1915.",
    },
  ],
})

console.log(result)
// Output:
// {
//   score: 1.0,
//   reason: "The score is 1.0 because all context pieces are highly relevant to Einstein's achievements and were effectively used in generating the comprehensive response."
// }
```

### Exemple de pertinence mitigée

Cet exemple montre une pertinence modérée, certains éléments de contexte étant non pertinents ou inutilisés :

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Solar eclipses occur when the Moon blocks the Sun.',
      'The Moon moves between the Earth and Sun during eclipses.',
      'The Moon is visible at night.',
      'Stars twinkle due to atmospheric interference.',
      'Total eclipses can last up to 7.5 minutes.',
    ],
    scale: 1,
  },
})

const result = await scorer.run({
  input: {
    inputMessages: [
      {
        id: '1',
        role: 'user',
        content: 'What causes solar eclipses?',
      },
    ],
  },
  output: [
    {
      id: '2',
      role: 'assistant',
      content:
        'Solar eclipses happen when the Moon moves between Earth and the Sun, blocking sunlight.',
    },
  ],
})

console.log(result)
// Output with default penalties:
// {
//   score: 0.64,
//   reason: "The score is 0.64 because contexts 1 and 2 are highly relevant and used, context 5 is relevant but unused (10% penalty), while contexts 3 and 4 are irrelevant."
// }

// With custom penalty configuration
const customScorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Solar eclipses occur when the Moon blocks the Sun.',
      'The Moon moves between the Earth and Sun during eclipses.',
      'The Moon is visible at night.',
      'Stars twinkle due to atmospheric interference.',
      'Total eclipses can last up to 7.5 minutes.',
    ],
    penalties: {
      unusedHighRelevanceContext: 0.05, // Lower penalty for unused context
      missingContextPerItem: 0.1,
      maxMissingContextPenalty: 0.3,
    },
  },
})

const customResult = await customScorer.run({
  input: {
    inputMessages: [{ id: '1', role: 'user', content: 'What causes solar eclipses?' }],
  },
  output: [
    {
      id: '2',
      role: 'assistant',
      content:
        'Solar eclipses happen when the Moon moves between Earth and the Sun, blocking sunlight.',
    },
  ],
})

console.log(customResult)
// Output with lenient penalties:
// {
//   score: 0.69, // Higher score due to reduced penalty for unused context
//   reason: "The score is 0.69 because contexts 1 and 2 are highly relevant and used, context 5 is relevant but unused (5% penalty), while contexts 3 and 4 are irrelevant."
// }
```

### Exemple de faible pertinence

Cet exemple montre une faible pertinence du contexte, avec des informations majoritairement non pertinentes :

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'The Great Barrier Reef is located in Australia.',
      'Coral reefs need warm water to survive.',
      'Many fish species live in coral reefs.',
      'Australia has six states and two territories.',
      'The capital of Australia is Canberra.',
    ],
    scale: 1,
  },
})

const result = await scorer.run({
  input: {
    inputMessages: [
      {
        id: '1',
        role: 'user',
        content: 'What is the capital of Australia?',
      },
    ],
  },
  output: [
    {
      id: '2',
      role: 'assistant',
      content: 'The capital of Australia is Canberra.',
    },
  ],
})

console.log(result)
// Output:
// {
//   score: 0.26,
//   reason: "The score is 0.26 because only context 5 is relevant to the query about Australia's capital, while the other contexts about reefs are completely irrelevant."
// }
```

### Extraction dynamique du contexte

Extrayez le contexte au moment de l’exécution en fonction de l’entrée de l’exécution :

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract query from input
      const query = input?.inputMessages?.[0]?.content || ''

      // Dynamically retrieve context based on query
      if (query.toLowerCase().includes('einstein')) {
        return [
          'Einstein developed E=mc²',
          'He won the Nobel Prize in 1921',
          'His theories revolutionized physics',
        ]
      }

      if (query.toLowerCase().includes('climate')) {
        return [
          'Global temperatures are rising',
          'CO2 levels affect climate',
          'Renewable energy reduces emissions',
        ]
      }

      return ['General knowledge base entry']
    },
    penalties: {
      unusedHighRelevanceContext: 0.15, // 15% penalty for unused relevant context
      missingContextPerItem: 0.2, // 20% penalty per missing context item
      maxMissingContextPenalty: 0.4, // Cap at 40% total missing context penalty
    },
    scale: 1,
  },
})
```

### Intégration à un système RAG

Intégrez-le à des pipelines RAG pour évaluer le contexte récupéré :

```typescript
import { createContextRelevanceScorerLLM } from '@mastra/evals'

const scorer = createContextRelevanceScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract from RAG retrieval results
      const ragResults = inputData.metadata?.ragResults || []

      // Return the text content of retrieved documents
      return ragResults.filter(doc => doc.relevanceScore > 0.5).map(doc => doc.content)
    },
    penalties: {
      unusedHighRelevanceContext: 0.12, // Moderate penalty for unused RAG context
      missingContextPerItem: 0.18, // Higher penalty for missing information in RAG
      maxMissingContextPenalty: 0.45, // Slightly higher cap for RAG systems
    },
    scale: 1,
  },
})

// Evaluate RAG system performance
const evaluateRAG = async testCases => {
  const results = []

  for (const testCase of testCases) {
    const score = await scorer.run(testCase)
    results.push({
      query: testCase.inputData.inputMessages[0].content,
      relevanceScore: score.score,
      feedback: score.reason,
      unusedContext: score.reason.includes('unused'),
      missingContext: score.reason.includes('missing'),
    })
  }

  return results
}
```

## Comparaison avec Context Precision

Choisissez l’évaluateur adapté à vos besoins :

| Cas d’utilisation                    | Context Relevance                    | Context Precision                   |
| ------------------------------------ | ------------------------------------ | ----------------------------------- |
| **Évaluation RAG**                   | Lorsque l’utilisation est importante | Lorsque le classement est important |
| **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 pris en compte                |
| **Sensibilité à la position**        | ✗ Indépendante de la position        | ✓ Récompense un placement précoce   |

## Ressources associées

- [Évaluateur Context Precision](https://mastra.zisheng.pro/fr/reference/evals/context-precision) : évalue le classement du contexte avec MAP
- [Évaluateur Faithfulness](https://mastra.zisheng.pro/fr/reference/evals/faithfulness) : mesure dans quelle mesure la réponse est ancrée dans le contexte
- [Évaluateurs personnalisés](https://mastra.zisheng.pro/fr/docs/evals/custom-scorers) : créez vos propres métriques d’évaluation