É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

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 :

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

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é

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

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.

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 :

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 :

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 :

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é :

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 : évalue le classement du contexte avec MAP
• Évaluateur Faithfulness : mesure dans quelle mesure la réponse est ancrée dans le contexte
• Évaluateurs personnalisés : créez vos propres métriques d’évaluation