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

# Summarization scorer

`createSummarizationScorer()` 函數會建立一個 scorer，從兩個維度評估摘要：當中的每項陳述是否都獲來源文字支持，以及摘要是否保留來源所述的資料。最終分數取兩者中較低者，因此摘要不能單靠忠於來源但內容空泛，或內容全面但不正確而通過評估。

摘要是 Agent 最後一則包含文字的訊息，而來源文字預設為執行輸入中的第一則用戶訊息。如果要摘要的文字位於其他地方（例如 Tool 結果），請傳入 `source` 或 `sourceExtractor`。

## 使用範例

根據摘要所濃縮的文件為摘要評分。

```typescript
import { createSummarizationScorer } from '@mastra/evals/scorers/prebuilt'

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

const result = await scorer.run({
  input: {
    inputMessages: [{ id: '1', role: 'user', content: sourceDocument }],
  },
  output: [{ id: '2', role: 'assistant', content: summary }],
})

console.log(result.score)
console.log(result.reason)
```

## 摘要評估

當 Agent 濃縮文字時，可使用此 scorer：

- 文件及謄本摘要
- 支援對話串及電郵摘要
- 任何將長篇輸入壓縮成簡短輸出的步驟

## 參數

**model** (`MastraModelConfig`): 用於判斷陳述及覆蓋範圍問題的語言模型

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

**options.source** (`string`): 用作摘要評判依據的文字。預設為執行輸入中的用戶訊息

**options.sourceExtractor** (`(input, output) => string`): 從執行輸入及輸出衍生來源文字的函數。其優先級高於 source

**options.maxQuestions** (`number`): 從來源擬定的覆蓋範圍問題數目上限（預設：10）

**options.scale** (`number`): 乘以最終分數的縮放系數（預設：1）

## `.run()` 傳回值

**score** (`number`): 介乎 0 至 scale 的摘要分數（預設為 0-1），取一致性分數與覆蓋範圍分數中較低者

**reason** (`string`): 易於理解的解釋，列明產生該分數的維度，以及相關的陳述或問題。文字中會顯示兩個維度的分數

**preprocessStepResult** (`object`): 一致性判定結果及從來源擬定的問題

**preprocessStepResult.alignment** (`{ claim: string; supported: boolean; reason: string }[]`): 摘要中每項陳述各有一個判定結果

**preprocessStepResult.questions** (`string[]`): 從來源文字擬定的覆蓋範圍問題

**analyzeStepResult** (`object`): 覆蓋範圍判定結果

**analyzeStepResult.coverage** (`{ question: string; answered: boolean; reason: string }[]`): 每條問題各有一個判定結果，並只根據摘要作答

各維度的分數會從這些判定結果推算，而不會儲存：一致性是 `alignment` 項目中 `supported: true` 所佔的比例，而覆蓋範圍則是 `questions` 中其 `coverage` 項目為 `answered: true` 的比例。

## 評分詳情

### 雙維度評估

此 scorer 會執行三步驟流程：

1. **來源判斷**：擷取摘要中的陳述並對照來源檢查，同時從來源擬定封閉式問題。每條問題都會以來源答案為「yes」的方式撰寫。
2. **覆蓋範圍**：只使用摘要回答每條問題。
3. **評分**：計算兩個比例，並以較低者作為分數。

覆蓋範圍步驟會以獨立的模型呼叫執行，而且絕不會接收來源文字。如果判斷模型能看到來源，就會根據來源而非摘要回答問題，因而掩蓋此維度旨在衡量的遺漏。

### 評分公式

```text
Alignment    = supported_claims / total_claims
Coverage     = answered_questions / total_questions
Summarization = min(Alignment, Coverage) × scale
```

如果摘要沒有產生任何陳述，或來源沒有產生任何問題，分數便是 0。

### 分數解讀

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

- **0.9-1.0**：出色的摘要，忠於來源並涵蓋其要點
- **0.7-0.8**：良好的摘要，只有少量遺漏或一項缺乏支持的細節
- **0.4-0.6**：一般的摘要，遺漏重要資料或偏離來源
- **0.1-0.3**：欠佳的摘要，來源的大部分內容都已遺失或被否定
- **0.0**：摘要沒有產生可供判斷的內容，或未能支持任何陳述。沒有回答任何問題的摘要亦會獲得此分數

### 解讀兩個維度

兩個維度的判定結果都會保留在執行結果中：一致性判定結果位於預處理步驟，覆蓋範圍判定結果則位於分析步驟。每個判定結果都會包含其所屬的陳述或問題，以及背後的原因。一致性分數低與覆蓋範圍分數低所代表的意思不同：

- 一致性分數低但覆蓋範圍高，表示摘要虛構或扭曲了細節
- 覆蓋範圍分數低但一致性高，表示摘要準確，但遺漏了太多內容

reason 欄位會列明哪個維度產生該分數。

### 分數沒有考慮的因素

長度不會影響分數。逐字重複來源的摘要會支持每項陳述並回答每條問題，因此得分為 1。如果壓縮程度是測試的一部分，請自行加入長度檢查。

### 成本

每次評估都會進行三次模型呼叫。`maxQuestions` 會限制覆蓋範圍部分的工作量；否則工作量會隨來源長度增加。對於無法以十條問題代表內容的長篇文件，請提高此值。

## Scorer 設定

### 摘要執行輸入

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

### 摘要來自其他位置的文件

```typescript
import { extractToolResults } from '@mastra/evals/scorers/utils'

const scorer = createSummarizationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    sourceExtractor: (input, output) => {
      return extractToolResults(output)
        .filter(({ toolName }) => toolName === 'fetchDocument')
        .map(({ result }) => String(result))
        .join('\n\n')
    },
    maxQuestions: 20,
  },
})
```

## 範例

根據一組文件評估摘要 Agent：

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

const scorer = createSummarizationScorer({
  model: 'openai/gpt-5.6-sol',
  options: { maxQuestions: 10 },
})

const result = await runEvals({
  target: summarizerAgent,
  scorers: [scorer],
  data: [
    {
      input:
        'The company was founded in 1995 by John Smith. It started with 10 employees and grew to 500 by 2020. The company is based in Seattle.',
    },
  ],
  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)指南。

## 與 faithfulness 比較

| 使用情境         | Summarization | Faithfulness    |
| ------------ | ------------- | --------------- |
| **衡量內容**     | 同時衡量支持程度及覆蓋範圍 | 只衡量支持程度         |
| **評判依據**     | 被濃縮的來源文字      | 擷取的上下文或 Tool 結果 |
| **能否偵測遺漏**   | 可以            | 不可以             |
| **是否需要完整來源** | 需要            | 不需要，只有上下文亦足夠    |

如果問題在於答案是否以擷取的上下文為依據，請使用 `faithfulness`。如果輸出旨在代替較長的文字，請使用 `summarization`。

## 相關內容

- [Faithfulness Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/faithfulness)：衡量答案以相關上下文為依據的程度
- [Completeness Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/completeness)：在不使用模型的情況下比較元素覆蓋範圍
- [Content Similarity Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/content-similarity)：在不使用模型的情況下比較文字相似度
- [Custom Scorer](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)：建立你自己的評估指標