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

# 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桁に丸めます

### スコアリング式

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

### スコアの解釈

- **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**

## スコアラーの設定

### コンテキストの動的抽出

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

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

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

## 例

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

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

`runEvals` の詳細は、[runEvals リファレンス](https://mastra.zisheng.pro/ja/reference/evals/run-evals)を参照してください。

このスコアラーを Agent に追加する方法については、[スコアラーの概要](https://mastra.zisheng.pro/ja/docs/evals/overview)ガイドを参照してください。

## Context relevance との比較

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

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

## 関連項目

- [Answer Relevancy Scorer](https://mastra.zisheng.pro/ja/reference/evals/answer-relevancy)：回答が質問に対応しているかを評価します
- [Faithfulness Scorer](https://mastra.zisheng.pro/ja/reference/evals/faithfulness)：回答がコンテキストにどの程度根拠を持つかを測定します
- [カスタムスコアラー](https://mastra.zisheng.pro/ja/docs/evals/custom-scorers)：独自の評価指標を作成します