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

# Hallucination scorer

`createHallucinationScorer()` 函數會將 LLM 的輸出與所提供的上下文比較，評估 LLM 產生的資料在事實上是否正確。此 scorer 透過識別上下文與輸出之間的直接矛盾，衡量幻覺程度。

## 參數

`createHallucinationScorer()` 函數接受單一 options 物件，包含以下屬性：

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

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

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

**options.context** (`string[]`): 用作幻覺偵測基準事實的靜態上下文字串。

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

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

## `.run()` 傳回值

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

**preprocessStepResult** (`object`): 包含已擷取陳述的物件：{ claims: string\[] }

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

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

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

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

**reason** (`string`): 分數及已識別矛盾的詳細解釋。

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

## 評分詳情

此 scorer 透過偵測矛盾及分析缺乏支持的陳述來評估幻覺。

### 評分流程

1. 分析事實內容：

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

2. 分析輸出中的幻覺：

   - 與上下文陳述比較
   - 將直接衝突標記為幻覺
   - 將缺乏支持的陳述識別為幻覺
   - 評估數值準確度
   - 考慮近似值的上下文

3. 計算幻覺分數：

   - 點算出現幻覺的陳述（矛盾及缺乏支持的陳述）
   - 除以陳述總數
   - 按已設定的範圍縮放

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

### 重要注意事項

- 上下文中沒有出現的陳述會被視為幻覺

- 除非有明確支持，否則主觀陳述會被視為幻覺

- 對上下文所載事實使用推測語句（「可能」、「也許」）是允許的

- 對上下文沒有提及的事實使用推測語句，會被視為幻覺

- 空白輸出的幻覺數目為零

- 數值評估會考慮：

  - 與量級相稱的精確度
  - 依據上下文作出的近似值
  - 明確的精確度指標

### 分數解讀

介乎 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 進行即時評分

將 scorer 附加至 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-HK/reference/evals/run-evals)。

如要將此 scorer 加入 Agent，請參閱 [Scorer 概覽](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)指南。

## 相關內容

- [Faithfulness Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/faithfulness)
- [Answer Relevancy Scorer](https://mastra.zisheng.pro/zh-HK/reference/evals/answer-relevancy)