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，得出分數。

評分公式

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

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 評估

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 擷取的完整度：

src/example-context-recall.ts

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 參考文件。

如要將此 scorer 加至 Agent，請參閱 Scorer 概覽指南。

與 context precision 比較

按需要選擇合適的 scorer：

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

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

相關內容

• Context Precision Scorer：評估擷取所得的 context 是否相關及排序恰當
• Context Relevance Scorer：評估 context 的使用情況和質素
• Faithfulness Scorer：衡量答案是否以 context 為依據
• 自訂 Scorer：建立你自己的評估指標