Context precision scorer

createContextPrecisionScorer() 関数は、期待される出力の生成に対して、取得したコンテキストの各部分がどの程度関連し、適切な位置にあるかを評価するスコアラーを作成します。**Mean Average Precision（MAP）**を使用し、関連するコンテキストをシーケンスの早い位置に配置するシステムを高く評価します。

特に次のユースケースに役立ちます。

RAG システムの評価

次のような、RAG パイプラインで取得したコンテキストの評価に適しています。

• コンテキストの順序がモデルの性能に影響する
• 基本的な関連性だけでなく、検索品質を測定する必要がある
• 後方にある関連コンテキストより、前方にある関連コンテキストの価値が高い

コンテキストウィンドウの最適化

次の条件でコンテキスト選択を最適化する場合に使用します。

• 制限されたコンテキストウィンドウ
• トークン予算の制約
• 複数ステップの推論タスク

パラメーター

model:

MastraModelConfig

コンテキストの関連性を評価するために使用する言語モデル

options:

ContextPrecisionMetricOptions

スコアラーの設定オプション

context または contextExtractor のいずれかを指定する必要があります。両方を指定した場合は、contextExtractor が優先されます。

.run() の戻り値

score:

number

0から scale までの Mean Average Precision スコア（デフォルト：0〜1）

reason:

string

コンテキスト精度の評価について、人が読める形式で示した説明

スコアリングの詳細

Mean Average Precision（MAP）

Context Precision は、Mean Average Precision を使用して関連性と配置の両方を評価します。

1. コンテキストの評価：期待される出力の生成に対し、各コンテキスト部分を「関連あり」または「関連なし」に分類します
2. Precision の計算：位置 i にある関連コンテキストごとに、precision = relevant_items_so_far / (i + 1) として計算します
3. Average Precision：すべての precision 値を合計し、関連項目の総数で割ります
4. 最終スコア：倍率を掛け、小数点以下2桁に丸めます

スコアリング式

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

スコアの解釈

• 0.9〜1.0：非常に高い精度 — すべての関連コンテキストがシーケンスの前方にある
• 0.7〜0.8：高い精度 — ほとんどの関連コンテキストが適切に配置されている
• 0.4〜0.6：中程度の精度 — 関連コンテキストと無関係なコンテキストが混在している
• 0.1〜0.3：低い精度 — 関連コンテキストが少ないか、配置が不適切
• 0.0：関連コンテキストが見つからない

理由の分析

reason フィールドでは、次の内容を説明します。

• どのコンテキスト部分が関連あり／なしと判断されたか
• 配置が MAP の計算にどのように影響したか
• 評価で使用された具体的な関連性基準

最適化のヒント

結果を次の用途に使用できます。

• 検索の改善：ランキング前に無関係なコンテキストを除外する
• ランキングの最適化：関連コンテキストが前方に現れるようにする
• チャンクサイズの調整：コンテキストの詳細度と関連性の精度のバランスを取る
• Embedding の評価：検索を改善するため、異なる Embedding モデルをテストする

計算例

context：[relevant, irrelevant, relevant, irrelevant]

• 位置0：関連あり → Precision = 1/1 = 1.0
• 位置1：スキップ（関連なし）
• 位置2：関連あり → Precision = 2/3 = 0.67
• 位置3：スキップ（関連なし）

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

スコアラーの設定

コンテキストの動的抽出

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,
  },
})

大規模なコンテキストの評価

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
    ],
  },
})

例

さまざまなクエリに対する RAG システムのコンテキスト検索精度を評価します。

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)

runEvals の詳細は、runEvals リファレンスを参照してください。

このスコアラーを Agent に追加する方法については、スコアラーの概要ガイドを参照してください。

Context relevance との比較

用途に適したスコアラーを選択してください。

ユースケース	Context Relevance	Context Precision
RAG の評価	使用状況が重要な場合	ランキングが重要な場合
コンテキストの品質	段階的なレベル	二値の関連性
欠落の検出	✓ 不足を特定	✗ 評価しない
使用状況の追跡	✓ 使用率を追跡	✗ 考慮しない
位置への感度	✗ 位置に依存しない	✓ 前方への配置を高く評価

関連項目

• Answer Relevancy Scorer：回答が質問に対応しているかを評価します
• Faithfulness Scorer：回答がコンテキストにどの程度根拠を持つかを測定します
• カスタムスコアラー：独自の評価指標を作成します