Scorer d'alignement du prompt

La fonction createPromptAlignmentScorerLLM() crée un Scorer qui évalue dans quelle mesure les réponses des Agents correspondent aux prompts utilisateur selon la compréhension de l'intention, le respect des exigences, l'exhaustivité de la réponse et l'adéquation du format.

Paramètres

model:

MastraModelConfig

Modèle de langage à utiliser pour évaluer l'alignement entre le prompt et la réponse

options:

PromptAlignmentOptions

Options de configuration du Scorer

Valeur de retour de .run()

score:

number

Score d'alignement multidimensionnel compris entre 0 et scale (par défaut 0-1)

reason:

string

Explication lisible de l'évaluation de l'alignement du prompt, accompagnée d'une ventilation détaillée

.run() renvoie un résultat de la forme suivante :

{
  runId: string,
  score: number,
  reason: string,
  analyzeStepResult: {
    intentAlignment: {
      score: number,
      primaryIntent: string,
      isAddressed: boolean,
      reasoning: string
    },
    requirementsFulfillment: {
      requirements: Array<{
        requirement: string,
        isFulfilled: boolean,
        reasoning: string
      }>,
      overallScore: number
    },
    completeness: {
      score: number,
      missingElements: string[],
      reasoning: string
    },
    responseAppropriateness: {
      score: number,
      formatAlignment: boolean,
      toneAlignment: boolean,
      reasoning: string
    },
    overallAssessment: string
  }
}

Détails du scoring

Configuration du Scorer

Vous pouvez personnaliser le Scorer d'alignement du prompt en ajustant le paramètre d'échelle et le mode d'évaluation selon vos besoins de scoring.

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    scale: 10, // Score from 0-10 instead of 0-1
    evaluationMode: 'both', // 'user', 'system', or 'both' (default)
  },
})

Analyse multidimensionnelle

L'alignement du prompt évalue les réponses selon quatre dimensions principales, avec un scoring pondéré qui s'adapte au mode d'évaluation :

Mode utilisateur ('user')

Évalue uniquement l'alignement avec les prompts utilisateur :

1. Alignement de l'intention (poids de 40 %) : indique si la réponse traite la demande principale de l'utilisateur
2. Respect des exigences (poids de 30 %) : indique si toutes les exigences de l'utilisateur sont satisfaites
3. Exhaustivité (poids de 20 %) : indique si la réponse est suffisamment détaillée pour les besoins de l'utilisateur
4. Adéquation de la réponse (poids de 10 %) : indique si le format et le ton correspondent aux attentes de l'utilisateur

Mode système ('system')

Évalue uniquement la conformité aux directives système :

1. Alignement de l'intention (poids de 35 %) : indique si la réponse suit les directives comportementales du système
2. Respect des exigences (poids de 35 %) : indique si toutes les contraintes système sont respectées
3. Exhaustivité (poids de 15 %) : indique si la réponse respecte toutes les règles système
4. Adéquation de la réponse (poids de 15 %) : indique si le format et le ton correspondent aux spécifications système

Mode combiné ('both' - par défaut)

Combine l'évaluation de l'alignement utilisateur et système :

• Alignement utilisateur : 70 % du score final (avec les poids du mode utilisateur)
• Conformité au système : 30 % du score final (avec les poids du mode système)
• Fournit une évaluation équilibrée de la satisfaction de l'utilisateur et du respect du système

Formule de scoring

Mode utilisateur :

Weighted Score = (intent_score × 0.4) + (requirements_score × 0.3) +
                 (completeness_score × 0.2) + (appropriateness_score × 0.1)
Final Score = Weighted Score × scale

Mode système :

Weighted Score = (intent_score × 0.35) + (requirements_score × 0.35) +
                 (completeness_score × 0.15) + (appropriateness_score × 0.15)
Final Score = Weighted Score × scale

Mode combiné (par défaut) :

User Score = (user dimensions with user weights)
System Score = (system dimensions with system weights)
Weighted Score = (User Score × 0.7) + (System Score × 0.3)
Final Score = Weighted Score × scale

Justification de la répartition des poids :

• Mode utilisateur : donne la priorité à l'intention (40 %) et aux exigences (30 %) pour satisfaire l'utilisateur
• Mode système : équilibre la conformité comportementale (35 %) et les contraintes (35 %)
• Mode combiné : la répartition 70/30 garantit que les besoins de l'utilisateur restent prioritaires tout en maintenant la conformité au système

Interprétation du score

• 0.9-1.0 = Excellent alignement dans toutes les dimensions
• 0.8-0.9 = Très bon alignement avec des lacunes mineures
• 0.7-0.8 = Bon alignement, mais certaines exigences ou certains éléments sont absents
• 0.6-0.7 = Alignement moyen avec des lacunes visibles
• 0.4-0.6 = Mauvais alignement avec des problèmes importants
• 0.0-0.4 = Très mauvais alignement ; la réponse ne traite pas efficacement le prompt

Quand utiliser chaque mode

Mode utilisateur ('user') - À utiliser pour :

• Évaluer les réponses du service client selon la satisfaction des utilisateurs
• Tester la qualité de la génération de contenu du point de vue de l'utilisateur
• Mesurer dans quelle mesure les réponses traitent les questions des utilisateurs
• Se concentrer uniquement sur le respect de la demande, sans contraintes système

Mode système ('system') - À utiliser pour :

• Auditer la sécurité de l'IA et la conformité aux directives comportementales
• Vérifier que les Agents respectent la voix de la marque et les exigences de ton
• Valider le respect des politiques et des contraintes relatives au contenu
• Tester la cohérence du comportement au niveau du système

Mode combiné ('both') - À utiliser pour les cas suivants (par défaut, recommandé) :

• Évaluation complète des performances des Agents IA
• Équilibre entre satisfaction de l'utilisateur et conformité au système
• Surveillance en production lorsque les exigences de l'utilisateur et du système sont toutes deux importantes
• Évaluation globale de l'alignement entre le prompt et la réponse

Cas d'utilisation courants

Évaluation de la génération de code

Idéal pour évaluer :

• La réalisation des tâches de programmation
• La qualité et l'exhaustivité du code
• Le respect des exigences de codage
• Les spécifications de format (fonctions, classes, etc.)

// Example: API endpoint creation
const codePrompt = 'Create a REST API endpoint with authentication and rate limiting'
// Scorer evaluates: intent (API creation), requirements (auth + rate limiting),
// completeness (full implementation), format (code structure)

Évaluation du suivi des instructions

Parfait pour :

• Vérifier la réalisation des tâches
• Contrôler le respect des instructions en plusieurs étapes
• Vérifier la conformité aux exigences
• Évaluer le contenu pédagogique

// Example: Multi-requirement task
const taskPrompt =
  'Write a Python class with initialization, validation, error handling, and documentation'
// Scorer tracks each requirement individually and provides detailed breakdown

Validation du format du contenu

Utile pour :

• Vérifier la conformité aux spécifications de format
• Contrôler le respect du guide de style
• Vérifier la structure de la sortie
• Contrôler l'adéquation de la réponse

// Example: Structured output
const formatPrompt =
  'Explain the differences between let and const in JavaScript using bullet points'
// Scorer evaluates content accuracy AND format compliance

Qualité des réponses des Agents

Mesurez dans quelle mesure vos Agents IA suivent les instructions des utilisateurs :

const agent = new Agent({
  id: 'coding-assistant',
  name: 'CodingAssistant',
  instructions: 'You are a helpful coding assistant. Always provide working code examples.',
  model: 'openai/gpt-5.6-sol',
})

// Evaluate comprehensive alignment (default)
const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'both' }, // Evaluates both user intent and system guidelines
})

// Evaluate just user satisfaction
const userScorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'user' }, // Focus only on user request fulfillment
})

// Evaluate system compliance
const systemScorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'system' }, // Check adherence to system instructions
})

const result = await scorer.run(agentRun)

Optimisation du prompt engineering

Testez différents prompts afin d'améliorer l'alignement :

const prompts = [
  'Write a function to calculate factorial',
  'Create a Python function that calculates factorial with error handling for negative inputs',
  'Implement a factorial calculator in Python with: input validation, error handling, and docstring',
]

// Compare alignment scores to find the best prompt
for (const prompt of prompts) {
  const result = await scorer.run(createTestRun(prompt, response))
  console.log(`Prompt alignment: ${result.score}`)
}

Évaluation d'un système multi-Agent

Comparez différents Agents ou modèles :

const agents = [agent1, agent2, agent3];
const testPrompts = [...]; // Array of test prompts

for (const agent of agents) {
  let totalScore = 0;
  for (const prompt of testPrompts) {
    const response = await agent.run(prompt);
    const evaluation = await scorer.run({ input: prompt, output: response });
    totalScore += evaluation.score;
  }
  console.log(`${agent.name} average alignment: ${totalScore / testPrompts.length}`);
}

Exemples

Configuration de base

import { createPromptAlignmentScorerLLM } from '@mastra/evals'

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
})

// Evaluate a code generation task
const result = await scorer.run({
  input: [
    {
      role: 'user',
      content: 'Write a Python function to calculate factorial with error handling',
    },
  ],
  output: {
    role: 'assistant',
    text: `def factorial(n):
    if n < 0:
        raise ValueError("Factorial not defined for negative numbers")
    if n == 0:
        return 1
    return n * factorial(n-1)`,
  },
})
// Result: { score: 0.95, reason: "Excellent alignment - function addresses intent, includes error handling..." }

Exemples de configuration personnalisée

// Configure scale and evaluation mode
const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: {
    scale: 10, // Score from 0-10 instead of 0-1
    evaluationMode: 'both', // 'user', 'system', or 'both' (default)
  },
})

// User-only evaluation - focus on user satisfaction
const userScorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'user' },
})

// System-only evaluation - focus on compliance
const systemScorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'system' },
})

const result = await scorer.run(testRun)
// Result: { score: 8.5, reason: "Score: 8.5 out of 10 - Good alignment with both user intent and system guidelines..." }

Évaluation propre au format

// Evaluate bullet point formatting
const result = await scorer.run({
  input: [
    {
      role: 'user',
      content: 'List the benefits of TypeScript in bullet points',
    },
  ],
  output: {
    role: 'assistant',
    text: 'TypeScript provides static typing, better IDE support, and enhanced code reliability.',
  },
})
// Result: Lower appropriateness score due to format mismatch (paragraph vs bullet points)

Exemple d'excellent alignement

Dans cet exemple, la réponse traite entièrement le prompt de l'utilisateur et satisfait toutes les exigences.

src/example-excellent-prompt-alignment.ts

import { createPromptAlignmentScorerLLM } from '@mastra/evals/scorers/prebuilt'

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
})

const inputMessages = [
  {
    role: 'user',
    content:
      'Write a Python function to calculate factorial with error handling for negative numbers',
  },
]

const outputMessage = {
  text: `def factorial(n):
    """Calculate factorial of a number."""
    if n < 0:
        raise ValueError("Factorial not defined for negative numbers")
    if n == 0 or n == 1:
        return 1
    return n * factorial(n - 1)`,
}

const result = await scorer.run({
  input: inputMessages,
  output: outputMessage,
})

console.log(result)

Sortie avec un excellent alignement

La sortie obtient un score élevé, car elle répond parfaitement à l'intention et satisfait toutes les exigences. Elle utilise également le format approprié.

{
  score: 0.95,
  reason: 'The score is 0.95 because the response perfectly addresses the primary intent of creating a factorial function and fulfills all requirements including Python implementation, error handling for negative numbers, and proper documentation. The code format is appropriate and the implementation is complete.'
}

Exemple d'alignement partiel

Dans cet exemple, la réponse traite l'intention principale, mais omet certaines exigences ou présente des problèmes de format.

src/example-partial-prompt-alignment.ts

import { createPromptAlignmentScorerLLM } from '@mastra/evals/scorers/prebuilt'

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
})

const inputMessages = [
  {
    role: 'user',
    content: 'List the benefits of TypeScript in bullet points',
  },
]

const outputMessage = {
  text: 'TypeScript provides static typing, better IDE support, and enhanced code reliability through compile-time error checking.',
}

const result = await scorer.run({
  input: inputMessages,
  output: outputMessage,
})

console.log(result)

Sortie avec un alignement partiel

La sortie obtient un score plus faible : son contenu est exact, mais ne respecte pas le format demandé, à savoir une liste à puces.

{
  score: 0.75,
  reason: 'The score is 0.75 because the response addresses the intent of explaining TypeScript benefits and provides accurate information, but fails to use the requested bullet point format, resulting in lower appropriateness scoring.'
}

Exemple de mauvais alignement

Dans cet exemple, la réponse ne traite pas les exigences précises de l'utilisateur.

src/example-poor-prompt-alignment.ts

import { createPromptAlignmentScorerLLM } from '@mastra/evals/scorers/prebuilt'

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
})

const inputMessages = [
  {
    role: 'user',
    content:
      'Write a Python class with initialization, validation, error handling, and documentation',
  },
]

const outputMessage = {
  text: `class Example:
    def __init__(self, value):
        self.value = value`,
}

const result = await scorer.run({
  input: inputMessages,
  output: outputMessage,
})

console.log(result)

Sortie avec un mauvais alignement

La sortie obtient un score faible, car elle ne satisfait que partiellement les exigences : la validation, la gestion des erreurs et la documentation sont absentes.

{
  score: 0.35,
  reason: 'The score is 0.35 because while the response addresses the basic intent of creating a Python class with initialization, it fails to include validation, error handling, and documentation as specifically requested, resulting in incomplete requirement fulfillment.'
}

Exemples de modes d'évaluation

Mode utilisateur - Centré uniquement sur le prompt utilisateur

Évalue dans quelle mesure la réponse traite la demande de l'utilisateur, sans tenir compte des instructions système :

src/example-user-mode.ts

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'user' },
})

const result = await scorer.run({
  input: {
    inputMessages: [
      {
        role: 'user',
        content: 'Explain recursion with an example',
      },
    ],
    systemMessages: [
      {
        role: 'system',
        content: 'Always provide code examples in Python',
      },
    ],
  },
  output: {
    text: 'Recursion is when a function calls itself. For example: factorial(5) = 5 * factorial(4)',
  },
})
// Scores high for addressing user request, even without Python code

Mode système - Centré uniquement sur les directives système

Évalue la conformité aux directives comportementales et aux contraintes du système :

src/example-system-mode.ts

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'system' },
})

const result = await scorer.run({
  input: {
    systemMessages: [
      {
        role: 'system',
        content: 'You are a helpful assistant. Always be polite, concise, and provide examples.',
      },
    ],
    inputMessages: [
      {
        role: 'user',
        content: 'What is machine learning?',
      },
    ],
  },
  output: {
    text: 'Machine learning is a subset of AI where computers learn from data. For example, spam filters learn to identify unwanted emails by analyzing patterns in previously marked spam.',
  },
})
// Evaluates politeness, conciseness, and example provision

Mode combiné - Évaluation conjointe (par défaut)

Évalue à la fois le respect de l'intention de l'utilisateur et la conformité au système avec un scoring pondéré (70 % utilisateur, 30 % système) :

src/example-both-mode.ts

const scorer = createPromptAlignmentScorerLLM({
  model: 'openai/gpt-5.6-sol',
  options: { evaluationMode: 'both' }, // This is the default
})

const result = await scorer.run({
  input: {
    systemMessages: [
      {
        role: 'system',
        content: 'Always provide code examples when explaining programming concepts',
      },
    ],
    inputMessages: [
      {
        role: 'user',
        content: 'Explain how to reverse a string',
      },
    ],
  },
  output: {
    text: `To reverse a string, you can iterate through it backwards. Here's an example in Python:
    
    def reverse_string(s):
        return s[::-1]
    
    # Usage: reverse_string("hello") returns "olleh"`,
  },
})
// High score for both addressing the user's request AND following system guidelines

Comparaison avec les autres Scorers

Aspect	Alignement du prompt	Pertinence de la réponse	Fidélité
Objectif	Respect multidimensionnel du prompt	Pertinence entre requête et réponse	Ancrage dans le contexte
Évaluation	Intention, exigences, exhaustivité, format	Similarité sémantique avec la requête	Cohérence factuelle avec le contexte
Cas d'utilisation	Suivi général des prompts	Récupération d'informations	Systèmes RAG ou fondés sur le contexte
Dimensions	4 dimensions pondérées	Une dimension de pertinence	Une dimension de fidélité

Voir aussi

• Scorer de pertinence de la réponse : évalue la pertinence entre la requête et la réponse
• Scorer de fidélité : mesure l'ancrage dans le contexte
• Scorer de précision des appels de Tool : évalue la sélection des Tools
• Scorers personnalisés : créez vos propres métriques d'évaluation