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

# 關鍵字覆蓋率評分器

`createKeywordCoverageScorer()` 函式會評估 LLM 輸出涵蓋輸入中重要關鍵字的程度。它會分析關鍵字是否出現以及相符情形，同時忽略常用字詞與停用詞。

## 參數

`createKeywordCoverageScorer()` 函式不接受任何選項。

此函式會傳回 MastraScorer 類別的執行個體。如需 `.run()` 方法及其輸入／輸出的詳細資訊，請參閱 [MastraScorer 參考文件](https://mastra.zisheng.pro/zh-TW/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
}
```

## 評分詳情

此評分器會比對關鍵字，並具備以下功能，以評估關鍵字覆蓋率：

- 過濾常用字詞與停用詞（例如「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**：回應不包含任何關鍵字。

### 特殊情況

此評分器會處理數種特殊情況：

- 輸入／輸出為空：若兩者皆空，傳回 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/zh-TW/reference/evals/run-evals)。

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

## 相關資源

- [完整度評分器](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/reference/evals/answer-relevancy)
- [文字差異評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/textual-difference)