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

# 幻觉 Scorer

`createHallucinationScorer()` 函数通过将 LLM 输出与所提供的上下文进行比较，评估其生成的信息在事实层面是否正确。该 Scorer 通过识别上下文与输出之间的直接矛盾来衡量 Hallucination。

## 参数

`createHallucinationScorer()` 函数接受一个 options 对象，其中包含以下属性：

**model** (`LanguageModel`): 用于评估 Hallucination 的模型配置。

**options** (`Options`): Scorer 的配置选项。

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

**options.context** (`string[]`): 用于作为 Hallucination 检测 ground truth 的静态上下文字符串。

**options.getContext** (`(params: GetContextParams) => string[] | Promise<string[]>`): 用于在运行时动态解析上下文的 hook。其优先级高于静态上下文，适合只在 Scorer 运行时才能取得上下文（例如 Tool 结果）的实时评分场景。

此函数返回 MastraScorer 类的实例。`.run()` 方法接受与其他 Scorer 相同的输入（参见 [MastraScorer 参考](https://mastra.zisheng.pro/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`): Hallucination 分数（0 到 scale，默认为 0-1）。

**reason** (`string`): 对分数和所识别矛盾的详细说明。

**generateReasonPrompt** (`string`): 在 generateReason 步骤中发送给 LLM 的 prompt（可选）。

## 评分详情

该 Scorer 通过检测矛盾并分析缺乏支持的声明来评估 Hallucination。

### 评分流程

1. 分析事实性内容：

   - 从上下文中提取陈述
   - 识别数值和日期
   - 梳理陈述之间的关系

2. 分析输出中的 Hallucination：

   - 与上下文陈述进行比较
   - 将直接冲突标记为 Hallucination
   - 将缺乏支持的声明识别为 Hallucination
   - 评估数值准确性
   - 考虑近似表达的上下文

3. 计算 Hallucination 分数：

   - 统计 Hallucination 陈述（矛盾和缺乏支持的声明）
   - 除以陈述总数
   - 缩放到配置的范围

最终分数： `(hallucinated_statements / total_statements) * scale`

### 重要注意事项

- 上下文中未出现的声明会被视为 Hallucination

- 除非得到明确支持，否则主观声明会被视为 Hallucination

- 允许对上下文中已有事实使用推测性语言（"might"、"possibly"）

- 对上下文中不存在的事实使用推测性语言会被视为 Hallucination

- 空输出的 Hallucination 数为零

- 数值评估会考虑：

  - 与数值量级相适应的精度
  - 符合上下文的近似值
  - 明确的精度指示

### 分数解读

Hallucination 分数介于 0 和 1 之间：

- **0.0**: 无 Hallucination，所有声明均与上下文一致。
- **0.3 to 0.4**: Hallucination 程度低，存在少量矛盾。
- **0.5 to 0.6**: Hallucination 程度中等，存在若干矛盾。
- **0.7 to 0.8**: Hallucination 程度高，存在大量矛盾。
- **0.9 to 1.0**: 完全 Hallucination，大多数或所有声明均与上下文矛盾。

该分数表示 Hallucination 的程度——分数越低，表示与所提供上下文的事实一致性越好

## 示例

### 静态上下文

当已有可供比较的已知 ground truth 时，请使用静态上下文：

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

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

## 相关内容

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