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

# 摘要 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），取 Alignment 与 Coverage 分数中的较低值

**reason** (`string`): 易于理解的说明，指出决定最终分数的维度及其相关声明或问题。文本中会显示两个维度的分数

**preprocessStepResult** (`object`): Alignment 判定结果以及从源文本生成的问题

**preprocessStepResult.alignment** (`{ claim: string; supported: boolean; reason: string }[]`): 摘要中的每项声明对应一个判定结果

**preprocessStepResult.questions** (`string[]`): 从源文本生成的覆盖问题

**analyzeStepResult** (`object`): Coverage 判定结果

**analyzeStepResult.coverage** (`{ question: string; answered: boolean; reason: string }[]`): 每个问题对应一个仅根据摘要作出的判定结果

各维度分数根据这些判定结果计算，而非直接存储：Alignment 是 `alignment` 条目中 `supported: true` 所占的比例，Coverage 是 `questions` 中对应 `coverage` 条目为 `answered: true` 的比例。

## 评分详情

### 双维度评估

该 Scorer 运行一个三步 pipeline：

1. **源文本判断**：提取摘要中的声明并根据源文本进行检查，同时从源文本生成封闭式问题。每个问题都会被设计成源文本可回答 "yes"。
2. **Coverage**：仅根据摘要回答每个问题。
3. **评分**：计算两个比例，并取较低值作为分数。

Coverage 步骤作为单独的模型调用运行，并且绝不会接收源文本。如果 Judge 可以看到源文本，就会根据源文本而非摘要回答问题，从而掩盖该维度旨在衡量的遗漏。

### 评分公式

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

当摘要没有产生任何声明，或源文本没有产生任何问题时，分数为 0。

### 分数解读

以下范围假设使用默认 `scale` 1。使用自定义量表时，请按比例换算。

- **0.9-1.0**: 优秀的摘要，忠实于源文本并涵盖其要点
- **0.7-0.8**: 良好的摘要，仅有少量遗漏或一项缺乏支持的细节
- **0.4-0.6**: 一般的摘要，遗漏了重要信息或偏离源文本
- **0.1-0.3**: 较差的摘要，源文本的大部分信息已丢失或遭到曲解
- **0.0**: 摘要没有产生可供判断的内容，或未能支持任何声明。无法回答任何问题的摘要也会获得此分数

### 解读两个维度

两个维度都会在运行结果中留下判定结果：Alignment 判定结果位于预处理步骤，Coverage 判定结果位于分析步骤。每项判定结果都包含对应的声明或问题及其原因。Alignment 分数低与 Coverage 分数低的含义不同：

- Alignment 分数低但 Coverage 分数高，表示摘要虚构或歪曲了细节
- Coverage 分数低但 Alignment 分数高，表示摘要准确但遗漏过多

reason 字段会指出决定该分数的维度。

### 分数未涵盖的内容

长度不会影响分数。逐字重复源文本的摘要能够支持每项声明并回答每个问题，因此会得到 1 分。如果压缩程度是测试目标之一，请自行添加长度检查。

### 成本

每次评估会进行三次模型调用。`maxQuestions` 限制 Coverage 部分的工作量，否则工作量会随源文本长度增长。对于无法用十个问题充分呈现内容的长文档，请提高此值。

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

要将此 Scorer 添加到 Agent，请参阅 [Scorer 概述](https://mastra.zisheng.pro/docs/evals/overview)指南。

## 与 Faithfulness 的比较

| 使用场景          | Summarization | Faithfulness     |
| ------------- | ------------- | ---------------- |
| **衡量内容**      | 同时衡量支持度与覆盖度   | 仅衡量支持度           |
| **判断依据**      | 待浓缩的源文本       | 检索到的上下文或 Tool 结果 |
| **能否发现遗漏**    | 是             | No               |
| **是否需要完整源文本** | 是             | 否，仅上下文就足够        |

当需要判断答案是否以检索到的上下文为依据时，请使用 `faithfulness`。当输出旨在代替较长文本时，请使用 `summarization`。

## 相关内容

- [Faithfulness Scorer](https://mastra.zisheng.pro/reference/evals/faithfulness): 衡量答案是否以上下文为依据
- [Completeness Scorer](https://mastra.zisheng.pro/reference/evals/completeness): 无需模型即可比较元素覆盖情况
- [Content Similarity Scorer](https://mastra.zisheng.pro/reference/evals/content-similarity): 无需模型即可比较文本相似度
- [Custom Scorers](https://mastra.zisheng.pro/docs/evals/custom-scorers): 创建自己的评估指标