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

# 摘要評分器

`createSummarizationScorer()` 函式會建立一個從兩個面向評估摘要的評分器：摘要中的每項主張是否都有來源文字支援，以及摘要是否保留來源陳述的資訊。最終分數取兩者中較低的分數，因此摘要無法僅靠忠實但空泛，或詳盡但錯誤而通過評估。

摘要是 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 濃縮文字時，可使用此評分器：

- 文件與逐字稿摘要
- 客服討論串與電子郵件摘要
- 將長篇輸入壓縮為簡短輸出的任何步驟

## 參數

**model** (`MastraModelConfig`): 用於判定主張與覆蓋率問題的語言模型

**options** (`SummarizationMetricOptions`): 評分器的設定選項

**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` 所占比例。

## 評分詳情

### 雙面向評估

此評分器會執行三步驟 pipeline：

1. **來源判定**：擷取摘要提出的主張並對照來源檢查，同時從來源產生封閉式問題。每個問題都會設計成可由來源以「是」回答。
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**：摘要沒有產生可供判定的內容，或無法支援任何主張。未回答任何問題的摘要也會得到此分數

### 解讀兩個面向

兩個面向都會在執行結果中留下判定結果：一致性判定結果位於 preprocess 步驟，覆蓋率判定結果則位於 analyze 步驟。每筆判定結果都包含所屬的主張或問題及其理由。一致性分數低與覆蓋率分數低的意義不同：

- 一致性分數低但覆蓋率高，表示摘要捏造或扭曲細節
- 覆蓋率分數低但一致性高，表示摘要正確，但遺漏過多內容

reason 欄位會指出是哪個面向產生此分數。

### 分數未納入的因素

長度不影響分數。逐字重複來源的摘要會支援每項主張並回答每個問題，因此得分為 1。若壓縮程度是測試項目之一，請自行加入長度檢查。

### 成本

每次評估會呼叫模型三次。`maxQuestions` 會限制覆蓋率部分的工作量，否則工作量會隨來源長度增加。若文件很長，十個問題無法代表其內容，請提高此值。

## 評分器設定

### 摘要此次執行的輸入

```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-TW/reference/evals/run-evals)。

如需將此評分器新增至 Agent，請參閱[評分器概觀](https://mastra.zisheng.pro/zh-TW/docs/evals/overview)指南。

## 與 faithfulness 比較

| 使用情境         | 摘要評分         | Faithfulness          |
| ------------ | ------------ | --------------------- |
| **衡量內容**     | 同時衡量支援程度與覆蓋率 | 僅衡量支援程度               |
| **判定依據**     | 正在濃縮的來源文字    | 擷取的 context 或 Tool 結果 |
| **能否找出遺漏**   | 能            | 不能                    |
| **是否需要完整來源** | 是            | 否，只要有 context 即可      |

若要判斷答案是否以擷取的 context 為根據，請使用 `faithfulness`。若輸出是用來替代較長的文字，請使用 `summarization`。

## 相關資源

- [Faithfulness 評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/faithfulness)：衡量答案是否以 context 為根據
- [完整度評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/completeness)：不使用模型，比較元素覆蓋率
- [內容相似度評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/content-similarity)：不使用模型，比較文字相似度
- [自訂評分器](https://mastra.zisheng.pro/zh-TW/docs/evals/custom-scorers)：建立自己的評估指標