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

# ハルシネーションスコアラー

`createHallucinationScorer()` 関数は、LLM の出力を提供されたコンテキストと比較し、生成された情報が事実として正しいかを評価します。このスコアラーは、コンテキストと出力の直接的な矛盾を特定してハルシネーションを測定します。

## パラメーター

`createHallucinationScorer()` 関数は、次のプロパティを持つ単一の options オブジェクトを受け取ります。

**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/ja/reference/evals/mastra-scorer)を参照）。ただし、戻り値には以下に示す LLM 固有のフィールドが含まれます。

## `.run()` の戻り値

**runId** (`string`): 実行 ID（任意）。

**preprocessStepResult** (`object`): 抽出された主張を持つオブジェクト：{ claims: string\[] }

**preprocessPrompt** (`string`): preprocess ステップで LLM に送信されたプロンプト（任意）。

**analyzeStepResult** (`object`): 判定を持つオブジェクト：{ verdicts: Array<{ statement: string, verdict: 'yes' | 'no', reason: string }> }

**analyzePrompt** (`string`): analyze ステップで LLM に送信されたプロンプト（任意）。

**score** (`number`): ハルシネーションスコア（0 から scale まで、デフォルトは 0〜1）。

**reason** (`string`): スコアと特定された矛盾の詳細な説明。

**generateReasonPrompt** (`string`): generateReason ステップで LLM に送信されたプロンプト（任意）。

## スコアリングの詳細

スコアラーは、矛盾の検出と裏付けのない主張の分析によってハルシネーションを評価します。

### スコアリング手順

1. 事実に関する内容を分析します。

   - コンテキストから記述を抽出する
   - 数値と日付を特定する
   - 記述間の関係を対応付ける

2. 出力のハルシネーションを分析します。

   - コンテキストの記述と比較する
   - 直接的な矛盾をハルシネーションと判定する
   - 裏付けのない主張をハルシネーションとして特定する
   - 数値の正確性を評価する
   - 近似表現のコンテキストを考慮する

3. ハルシネーションスコアを計算します。

   - ハルシネーションと判定された記述（矛盾および裏付けのない主張）を数える
   - 記述の総数で割る
   - 設定した範囲にスケーリングする

最終スコア：`(hallucinated_statements / total_statements) * scale`

### 重要な考慮事項

- コンテキストにない主張はハルシネーションとして扱われる

- 主観的な主張は、明示的な裏付けがない限りハルシネーションと判定される

- コンテキストに含まれる事実に対する推測表現（「〜かもしれない」「おそらく」）は許容される

- コンテキストにない事実に対する推測表現はハルシネーションとして扱われる

- 空の出力ではハルシネーションは 0 件となる

- 数値の評価では次の点が考慮される

  - スケールに応じた精度
  - コンテキストに沿った近似
  - 明示的な精度表現

### スコアの解釈

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/ja/reference/evals/run-evals)を参照してください。

このスコアラーを Agent に追加する方法は、[スコアラーの概要](https://mastra.zisheng.pro/ja/docs/evals/overview)ガイドを参照してください。

## 関連項目

- [忠実性スコアラー](https://mastra.zisheng.pro/ja/reference/evals/faithfulness)
- [回答関連性スコアラー](https://mastra.zisheng.pro/ja/reference/evals/answer-relevancy)