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

# 关键词覆盖率 Scorer

`createKeywordCoverageScorer()` 函数用于评估 LLM 输出对输入中重要关键词的覆盖程度。它会分析关键词是否出现以及是否匹配，同时忽略常用词和停用词。

## 参数

`createKeywordCoverageScorer()` 函数不接受任何选项。

此函数返回 MastraScorer 类的实例。有关 `.run()` 方法及其输入/输出的详情，请参阅 [MastraScorer 参考](https://mastra.zisheng.pro/reference/evals/mastra-scorer)。

## `.run()` 返回值

**runId** (`string`): 运行 ID（可选）。

**preprocessStepResult** (`object`): 包含所提取关键词的对象：{ referenceKeywords: Set\<string>, responseKeywords: Set\<string> }

**analyzeStepResult** (`object`): 包含关键词覆盖情况的对象：{ totalKeywords: number, matchedKeywords: number }

**score** (`number`): 表示关键词匹配比例的覆盖分数（0-1）。

`.run()` 返回以下结构的结果：

```typescript
{
  runId: string,
  extractStepResult: {
    referenceKeywords: Set<string>,
    responseKeywords: Set<string>
  },
  analyzeStepResult: {
    totalKeywords: number,
    matchedKeywords: number
  },
  score: number
}
```

## 评分详情

该 Scorer 通过匹配关键词来评估关键词覆盖情况，并具备以下特性：

- 过滤常用词和停用词（例如 "the"、"a"、"and"）
- 不区分大小写匹配
- 处理词形变化
- 对技术术语和复合词进行特殊处理

### 评分流程

1. 处理输入和输出中的关键词：

   - 过滤常用词和停用词
   - 统一大小写和词形
   - 处理特殊术语和复合词

2. 计算关键词覆盖率：

   - 匹配文本之间的关键词
   - 统计成功匹配的数量
   - 计算覆盖率

最终分数：`(matched_keywords / total_keywords) * scale`

### 分数解读

覆盖分数介于 0 和 1 之间：

- **1.0**：完全覆盖，所有关键词均已出现。
- **0.7 到 0.9**：覆盖率高，包含大多数关键词。
- **0.4 到 0.6**：部分覆盖，出现了一些关键词。
- **0.1 到 0.3**：覆盖率低，仅匹配到少量关键词。
- **0.0**：响应不包含任何关键词。

### 特殊情况

该 Scorer 会处理以下特殊情况：

- 输入/输出为空：如果两者均为空，则返回 1.0；如果只有一个为空，则返回 0.0
- 单个单词：作为单个关键词处理
- 技术术语：保留复合技术术语（例如 "React.js"、"machine learning"）
- 大小写差异："JavaScript" 可与 "javascript" 匹配
- 常用词：评分时忽略，以聚焦有用的关键词

## 示例

评估输入查询与 Agent 响应之间的关键词覆盖情况：

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

const scorer = createKeywordCoverageScorer()

const result = await runEvals({
  data: [
    {
      input: 'JavaScript frameworks like React and Vue',
    },
    {
      input: 'TypeScript offers interfaces, generics, and type inference',
    },
    {
      input:
        'Machine learning models require data preprocessing, feature engineering, and hyperparameter tuning',
    },
  ],
  scorers: [scorer],
  target: myAgent,
  onItemComplete: ({ scorerResults }) => {
    console.log({
      score: scorerResults[scorer.id].score,
    })
  },
})

console.log(result.scores)
```

有关 `runEvals` 的更多详情，请参阅 [runEvals 参考](https://mastra.zisheng.pro/reference/evals/run-evals)。

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

## 相关内容

- [Completeness Scorer](https://mastra.zisheng.pro/reference/evals/completeness)
- [Content Similarity Scorer](https://mastra.zisheng.pro/reference/evals/content-similarity)
- [Answer Relevancy Scorer](https://mastra.zisheng.pro/reference/evals/answer-relevancy)
- [Textual Difference Scorer](https://mastra.zisheng.pro/reference/evals/textual-difference)