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

# 幻覺評分器

`createHallucinationScorer()` 函式會比較 LLM 輸出與所提供的上下文，以評估 LLM 產生的資訊是否符合事實。此評分器透過找出上下文與輸出之間的直接矛盾來衡量幻覺程度。

## 參數

`createHallucinationScorer()` 函式接受包含下列屬性的單一選項物件：

**model** (`LanguageModel`): 用於評估幻覺的模型設定。

**options** (`Options`): 設定選項。

**options.scale** (`number`): 最高分數值。

**options.context** (`string[]`): 用作標準答案以偵測幻覺的靜態上下文字串。

**options.getContext** (`(params: GetContextParams) => string[] | Promise<string[]>`): 在執行階段動態解析上下文的掛鉤。其優先順序高於靜態上下文，適合上下文（例如 Tool 結果）只能在評分器執行時取得的即時評分。

此函式會傳回 MastraScorer 類別的執行個體。`.run()` 方法接受與其他評分器相同的輸入（請參閱 [MastraScorer 參考文件](https://mastra.zisheng.pro/zh-TW/reference/evals/mastra-scorer)），但傳回值會包含下方所述的 LLM 專用欄位。

## `.run()` 傳回值

**runId** (`string`): 執行 ID（選填）。

**preprocessStepResult** (`object`): 包含所擷取主張的物件：{ claims: string\[] }

**preprocessPrompt** (`string`): 在預處理步驟傳送給 LLM 的提示詞（選填）。

**analyzeStepResult** (`object`): 包含判定的物件：{ verdicts: Array<{ statement: string, verdict: 'yes' | 'no', reason: string }> }

**analyzePrompt** (`string`): 在分析步驟傳送給 LLM 的提示詞（選填）。

**score** (`number`): 幻覺分數（0 到 scale，預設為 0-1）。

**reason** (`string`): 分數與所發現矛盾的詳細說明。

**generateReasonPrompt** (`string`): 在 generateReason 步驟傳送給 LLM 的提示詞（選填）。

## 評分詳情

此評分器會偵測矛盾並分析缺乏支援的主張，以評估幻覺程度。

### 評分流程

1. 分析事實內容：

   - 從上下文擷取陳述
   - 識別數值與日期
   - 建立陳述之間的關係

2. 分析輸出中的幻覺：

   - 與上下文陳述進行比較
   - 將直接衝突標記為幻覺
   - 將缺乏支援的主張識別為幻覺
   - 評估數值正確性
   - 考量上下文中的近似說法

3. 計算幻覺分數：

   - 計算含有幻覺的陳述數量（矛盾及缺乏支援的主張）
   - 除以陳述總數
   - 依設定範圍縮放

最終分數：`(hallucinated_statements / total_statements) * scale`

### 重要考量

- 上下文中未出現的主張會視為幻覺

- 除非上下文明確支援，否則主觀主張會視為幻覺

- 對上下文中已有的事實使用推測語氣（"might"、"possibly"）是允許的

- 對上下文中沒有的事實使用推測語氣，仍會視為幻覺

- 空白輸出的幻覺數為零

- 數值評估會考量：

  - 符合數值尺度的精確度
  - 依上下文判斷的近似值
  - 明確的精確度指標

### 分數解讀

幻覺分數介於 0 到 1：

- **0.0**：沒有幻覺，所有主張都與上下文相符。
- **0.3 到 0.4**：幻覺程度低，存在少量矛盾。
- **0.5 到 0.6**：幻覺程度不一，存在數項矛盾。
- **0.7 到 0.8**：幻覺程度高，存在許多矛盾。
- **0.9 到 1.0**：完全是幻覺，大多數或所有主張都與上下文矛盾。

此分數代表幻覺程度；分數越低，表示與所提供上下文的事實一致性越高。

## 範例

### 靜態上下文

已有可供比較的標準答案時，請使用靜態上下文：

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

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: [
      'The first iPhone was announced on January 9, 2007.',
      'It was released on June 29, 2007.',
      'Steve Jobs introduced it at Macworld.',
    ],
  },
})
```

### 使用 `getContext` 的動態上下文

若即時評分情境中的上下文來自 Tool 結果，請使用 `getContext`：

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

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    getContext: ({ run, step }) => {
      // Extract tool results as context
      const toolResults = extractToolResults(run.output)
      return toolResults.map(t => JSON.stringify({ tool: t.toolName, result: t.result }))
    },
  },
})
```

### 使用 Agent 進行即時評分

將評分器附加至 Agent，以進行即時評估：

```typescript
import { Agent } from '@mastra/core/agent'
import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt'
import { extractToolResults } from '@mastra/evals/scorers'

const hallucinationScorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    getContext: ({ run }) => {
      const toolResults = extractToolResults(run.output)
      return toolResults.map(t => JSON.stringify({ tool: t.toolName, result: t.result }))
    },
  },
})

const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful assistant.',
  evals: {
    scorers: [hallucinationScorer],
  },
})
```

### 使用 `runEvals` 進行批次評估

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

const scorer = createHallucinationScorer({
  model: 'openai/gpt-5.6-sol',
  options: {
    context: ['Known fact 1', 'Known fact 2'],
  },
})

const result = await runEvals({
  data: [{ input: 'Tell me about topic A' }, { input: 'Tell me about topic B' }],
  scorers: [scorer],
  target: myAgent,
  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)指南。

## 相關資源

- [忠實度評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/faithfulness)
- [答案相關性評分器](https://mastra.zisheng.pro/zh-TW/reference/evals/answer-relevancy)