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

# Context recall scorer

`createContextRecallScorer()` 函式會建立一個 scorer，評估擷取所得的 context 對標準參考答案中陳述的涵蓋程度。它會檢查標準答案中有多少比例的陳述可歸因於擷取所得的 context，從而衡量擷取的完整度。

此 scorer 需要標準參考答案，因此適合用於 CI 或測試環境中的已標註資料集。如果執行時未提供 `groundTruth`，scorer 會傳回 0 分，而不會拋出錯誤。

## RAG 擷取評估

適合在以下 RAG pipeline 中評估擷取的完整度：

- 你需要驗證 retriever 有否擷取所有必要資訊
- 你有包含已知正確答案的已標註資料集
- 你想找出 retriever 傳回內容的迴歸問題

## 以資料集為本的測試

對整理過的測試集執行評估時使用：

- 使用標準答案標註問題的 CI pipeline
- 對擷取策略進行 A/B 測試
- 對 embedding 模型的涵蓋度進行基準測試

## 參數

**model** (`MastraModelConfig`): 用於評估陳述歸因的語言模型

**options** (`ContextRecallMetricOptions`): scorer 的設定選項

必須提供 `context` 或 `contextExtractor` 其中之一。如兩者皆有提供，只有當執行輸入和輸出採用 Agent 格式（`MastraDBMessage[]`）時才會使用 `contextExtractor`；否則 scorer 會改用 `context`。

## `.run()` 傳回值

**score** (`number`): 介乎 0 與 scale 之間的召回率分數（預設為 0 至 1），代表 context 所涵蓋的標準答案陳述比例

**reason** (`string`): 關於哪些標準答案陳述可在 context 中找到、哪些找不到的易讀說明

## 評分詳情

### 陳述歸因

Context Recall 先使用 LLM 進行兩步評估，再以確定性方式計算分數：

1. **擷取陳述**：將標準答案拆分為不可再分的陳述
2. **歸因檢查**：逐項核對擷取 context 是否支持每項陳述

然後，將可歸因陳述數量除以陳述總數，再乘以 scale，得出分數。

### 評分公式

```text
Context Recall = attributed_claims / total_claims × scale

Where:
- attributed_claims = number of ground-truth claims supported by the context
- total_claims = total number of claims extracted from the ground truth
- Attribution is binary: a claim is either supported (yes) or not (no)
```

### 分數解讀

以下範圍假設使用預設 `scale` 值 1。如使用自訂 scale，請相應地乘算。

- **0.9-1.0**：極佳的召回率，context 幾乎涵蓋所有標準答案陳述
- **0.7-0.8**：良好的召回率。大部分陳述都有涵蓋，只有少量缺漏
- **0.4-0.6**：中等的召回率，context 遺漏大量資訊
- **0.1-0.3**：較差的召回率，大部分標準答案陳述都無法在 context 中找到
- **0.0**：沒有召回，context 中沒有任何標準答案陳述

### 原因分析

reason 欄位會說明：

- 可在 context 中找到哪些標準答案陳述
- 遺漏了哪些陳述，以及存在哪些資訊缺漏
- 哪些具體 context 片段支持可歸因的陳述

### 最佳化分析

使用結果來：

- **改善擷取**：識別 retriever 遺漏了哪些類型的資訊
- **調整 chunk 大小**：確保 chunk 包含足夠細節，能涵蓋標準答案陳述
- **評估 embedding**：測試不同的 embedding 模型，以改善資訊涵蓋度
- **擴充知識庫**：加入涵蓋經常遺漏陳述的文件

### 計算範例

標準答案：「Einstein was born in 1879. He developed relativity. He won the Nobel Prize.」

擷取所得陳述：3 項

- 「Einstein was born in 1879」→ 可歸因（context 提及出生日期）
- 「Einstein developed relativity」→ 可歸因（context 涵蓋相對論）
- 「Einstein won the Nobel Prize」→ 不可歸因（context 未提及諾貝爾獎）

召回率 = 2/3 = 0.67

## Scorer 設定

### 動態擷取 context

```typescript
const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      const query = input?.inputMessages?.[0]?.content || ''
      const searchResults = vectorDB.search(query, { limit: 10 })
      return searchResults.map(result => result.content)
    },
    scale: 1,
  },
})
```

### 靜態 context 評估

```typescript
const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'Document 1: Einstein was born on 14 March 1879 in Ulm, Germany.',
      'Document 2: Einstein published the theory of special relativity in 1905.',
      'Document 3: Einstein moved to the United States in 1933.',
    ],
  },
})
```

## 範例

根據已標註資料集評估 RAG 擷取的完整度：

```typescript
import { runEvals } from '@mastra/core/evals'
import { createContextRecallScorer } from '@mastra/evals/scorers/prebuilt'
import { myAgent } from './agent'

const scorer = createContextRecallScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    contextExtractor: (input, output) => {
      // Extract context from tool invocation results in the agent output
      return output
        .filter(msg => msg?.role === 'assistant')
        .flatMap(msg => msg?.content?.toolInvocations ?? [])
        .filter((tool: any) => tool.state === 'result')
        .map((tool: any) => JSON.stringify(tool.result))
    },
  },
})

const result = await runEvals({
  data: [
    {
      input: 'What are the health benefits of green tea?',
      groundTruth:
        'Green tea contains antioxidants that reduce inflammation, L-theanine that improves focus, and catechins that boost metabolism.',
    },
    {
      input: 'How does photosynthesis work?',
      groundTruth:
        'Photosynthesis converts sunlight into chemical energy using chlorophyll in chloroplasts, producing glucose and oxygen from carbon dioxide and water.',
    },
  ],
  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/zh-HK/reference/evals/run-evals)。

如要將此 scorer 加至 Agent，請參閱 [Scorer 概覽](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)指南。

## 與 context precision 比較

按需要選擇合適的 scorer：

| 使用情境         | Context Recall | Context Precision |
| ------------ | -------------- | ----------------- |
| **衡量內容**     | 標準答案的涵蓋度       | 擷取所得 chunk 的相關性   |
| **方向**       | 標準答案 → context | Context → 標準答案    |
| **對位置敏感**    | 否              | 是（獎勵較前位置）         |
| **需要標準答案**   | 是              | 是                 |
| **可發現的失敗模式** | 遺漏資訊           | 不相關的雜訊            |

兩者配合使用，可全面了解擷取質素：precision 可找出 context 中的無關內容，recall 則可找出缺漏。

## 相關內容

- [Context Precision Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/context-precision)：評估擷取所得的 context 是否相關及排序恰當
- [Context Relevance Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/context-relevance)：評估 context 的使用情況和質素
- [Faithfulness Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/faithfulness)：衡量答案是否以 context 為依據
- [自訂 Scorer](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)：建立你自己的評估指標