> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dify-guide/knowledge-base/dify-docs-testing-and-quality-improvement.md).

# テストと精度改善

Difyのナレッジベース画面の左メニューに「検索テスト」があり、質問を入力すると実際に検索されるチャンクと「スコア（SCORE）」が表示されます。スコアは関連性の高さを示し、デジタルヒューマン向けの推奨値は0.7以上です。

ナレッジベース（RAG）の回答品質は、ユーザー体験を決定づける最重要要素です。本ドキュメントでは、最新のRAG評価トレンド（自動評価・合成データ活用）を取り入れ、**テストの自動化・効率化**と**実務的な精度改善サイクル**を体系化します。

## 1. テスト戦略：評価の3本柱

RAGの評価は\*\*「データセット」「メトリクス（指標）」「評価手法」\*\*の3要素で構成されます。

### テストデータセットの構築

テストには「質問」と「正解（回答および参照すべき根拠）」のペアが必要です。

**実際のログ（Real Data）**: 実際の問い合わせログやFAQから抽出。

**合成データ（Synthetic Data）**: 手動作成はコストがかかるため、LLMを活用してドキュメントから「想定Q\&Aペア」を自動生成する手法を取り入れます（例: RAGAS, LlamaIndex等の機能活用）。これにより、網羅的なテストケースを短時間で作成可能です。

### 評価の分離

問題の切り分けを容易にするため、プロセスを分離して評価します。

**Retrieval（検索）評価**: 質問に対して、適切なドキュメント（チャンク）が上位に取得できているか。

**Generation（生成）評価**: 取得したドキュメントに基づき、正しく回答できているか。

## 2. 評価指標

主観的な「良さそう」ではなく、定量的な指標を用います。

### 検索精度の指標

**Hit Rate (Recall)**: 正解ドキュメントがTopKに含まれている割合。

**MRR (Mean Reciprocal Rank)**: 正解ドキュメントが何番目に表示されたかの順位スコア。

### 生成品質の指標（LLMによる自動評価）

人間による評価に加え、LLMを審査員（LLM-as-a-Judge）として用いる以下の指標が標準的です。

* **Faithfulness（忠実性）**: 回答が参照ドキュメントの内容に基づいているか（ハルシネーションの検知）。
* **Answer Relevance（回答関連性）**: ユーザーの質問に対して的確に答えているか。
* **Context Precision（コンテキスト精度）**: 検索された情報のなかに、回答に不要なノイズがどれだけ少ないか。

## 3. テストシナリオとケース分類

多様な質問タイプをカバーするテストセットを用意します。

| カテゴリ       | 内容               | テスト目的                        |
| ---------- | ---------------- | ---------------------------- |
| **事実・仕様**  | 製品スペック、手順、価格     | 正確な情報検索と抽出                   |
| **推論・要約**  | 「AとBの違いは？」       | 複数チャンクの統合・比較能力               |
| **否定・対象外** | 「〜できますか？」（答えはNo） | 「できない」と正しく回答できるか（ハルシネーション抑制） |
| **条件分岐**   | 「プランAの場合の料金は？」   | 類似情報から特定条件を選び出す能力            |
| **ノイズ耐性**  | 関係ない前提情報を混ぜた質問   | 検索意図の理解とノイズ除去                |

## 4. 精度改善のアプローチ

設定変更の前に、まずは「データの質」を高めることが最優先です（Data-Centric AIアプローチ）。

### データ品質と構造化（最重要）

* **ドキュメント粒度**: 1つのチャンクに複数のトピックを混ぜない。見出し（Markdownヘッダ）で明確に構造化する。
* **メタデータ付与**: カテゴリ、製品名、日付などをメタデータとして付与し、検索時にフィルタリング（Pre-filtering）できるようにする。
* **Q\&A形式の追加**: 複雑なドキュメントの場合、FAQ形式のセクションを追加することで、検索ヒット率が大幅に向上する。

### 検索パイプラインの最適化

* **ハイブリッド検索**: 「キーワード検索（BM25）」と「ベクトル検索（Embedding）」を組み合わせる。
  * キーワード: 型番、専門用語、固有名詞に強い。
  * ベクトル: 意味、文脈、表現揺れに強い。
* **Re-rankingの導入**:

  検索で見つけた上位（例: 50件）候補に対し、高精度なリランカーモデル（Cross-Encoder等）で並び替えを行い、最終的なTopK（例: 5件）をLLMに渡す。これにより精度が劇的に向上する場合が多い。

### チャンク戦略の調整

* **固定長チャンク vs 意味的チャンク**: 単なる文字数区切りではなく、段落やセクション単位での区切りを検討。
* **Parent Document Retriever**: 検索は「小さなチャンク」で行い、LLMにはその周囲を含む「大きなコンテキスト」を渡す手法。

## 5. 運用サイクル

一度作って終わりではなく、継続的な改善ループを構築します。

1. **モニタリング**: 実際のユーザーログから「低評価回答」や「回答拒否」を抽出する。
2. **ログ分析**: 検索失敗（ドキュメントがない、キーワード不一致）か？ 生成失敗（ドキュメントはあるが答えられなかった）か？
3. **データセット追加**: 失敗ケースをテストデータセットに追加する。
4. **改善実施**: ドキュメントを修正またはパイプラインを調整する。
5. **自動テスト実行**: 修正により他の質問が壊れていないか確認してからデプロイ。

### 推奨ツール・スタック例

* **評価フレームワーク**: RAGAS, DeepEval, TruLens
* **ログ管理**: LangSmith, Weights & Biases, MLflow

## 6. 定期メンテナンス項目

* **情報の鮮度管理**: 古いドキュメントをアーカイブまたは更新する。
* **テストセットの更新**: 新機能や新サービスに合わせてテストケースを追加する。
* **A/Bテスト**: プロンプト変更や検索ロジック変更時は、一部ユーザーまたは内部環境で比較検証をおこなう。

### テストシナリオの作成

**テスト方法**

![](/files/uGSz9UUnorIOHfKDzA68)

**検索プレビュー**

1. ナレッジベースの詳細画面を開く
2. 「検索テスト」タブをクリック
3. テストクエリを入力
4. 検索結果を確認

**アプリからのテスト**

1. ナレッジベースを接続したアプリを開く
2. デバッグモードでテスト
3. 検索されたチャンクを確認

**テストケースの種類**

体系的なテストを実施するため、以下のカテゴリごとにテストケースを準備します。

| カテゴリ          | 説明                    | テスト例                                  |
| ------------- | --------------------- | ------------------------------------- |
| **基本的な質問**    | 明確かつ直接的な質問。FAQに該当する内容 | 「住所は？」「営業時間は？」「価格はいくらですか？」「場所を教えて」    |
| **複雑な質問**     | 比較・条件付き・多段階の情報が必要な質問  | 「AとBの違いは？」「〜の場合、どうすればいい？」「手順を教えて」     |
| **表記揺れ・言い換え** | 同じ内容を異なる表現で質問         | 「返品/リターン/返したい」「キャンセル/取消/中止」「料金/価格/値段」 |
| **曖昧な質問**     | 情報が不足した抽象的な質問         | 「それについて教えて」「どうすればいい？」「他には？」           |
| **複数意図の質問**   | 1つの質問に複数の質問が含まれる      | 「価格と営業時間と場所を教えて」「申込方法と必要書類は？」         |
| **文脈依存の質問**   | 前の会話を踏まえた質問           | 「それはいつですか？」「もっと詳しく」「他のオプションは？」        |
| **範囲外の質問**    | ナレッジベースに含まれない内容       | 未登録の製品・サービス、個人情報、時事ネタ                 |
| **エッジケース**    | 極端に長い/短い、特殊文字、誤字を含む質問 | 「あ」「すみまんせん」非常に長い質問文                   |

**テストケースの例**

実際のテスト実施時に使用できる、テストケースのテンプレートです。

**評価基準** ○: 期待通りの結果 △: 関連情報は取得できたが不完全 ×: 期待する結果が得られない スコア: 検索結果の関連性スコア（0.0〜1.0）

| No. | カテゴリ | 優先度 | テストクエリ             | 期待される結果（検索されるべき情報）  | 結果 | スコア  | 備考        |
| --- | ---- | --- | ------------------ | ------------------- | -- | ---- | --------- |
| 001 | 基本   | 高   | 営業時間を教えて           | 店舗営業時間（平日・土日）       | ○  | 0.92 | 正確に検索     |
| 002 | 基本   | 高   | 価格はいくらですか？         | 料金プラン一覧             | △  | 0.68 | 関連情報も含む   |
| 003 | 表記揺れ | 高   | 返品はできますか？          | 返品・交換ポリシー           | ○  | 0.88 |           |
| 004 | 表記揺れ | 高   | リターンしたいです          | 返品・交換ポリシー           | ○  | 0.85 | 同義語で検索可   |
| 005 | 複雑   | 中   | AプランとBプランの違いは？     | プラン比較表、各プラン詳細       | ○  | 0.79 | 複数チャンク    |
| 006 | 複雑   | 中   | 学生の場合、割引はありますか？    | 学割情報、申込条件           | ○  | 0.82 |           |
| 007 | 複数意図 | 中   | 営業時間と場所とアクセス方法を教えて | 店舗情報（営業時間・住所・アクセス）  | △  | 0.71 | 一部情報のみ    |
| 008 | 曖昧   | 低   | それについて教えて          | （文脈依存のため判定不可）       | ×  | 0.42 | 文脈情報必要    |
| 009 | 範囲外  | 中   | 天気を教えて             | 該当情報なし（適切に「わかりません」） | ○  | -    | 範囲外を正しく判定 |
| 010 | 範囲外  | 中   | 〇〇社の製品について         | 該当情報なし（適切に「わかりません」） | ○  | -    | 競合情報は非対応  |
| 011 | エッジ  | 低   | えいぎょうじかん           | 店舗営業時間              | △  | 0.61 | ひらがなで検索低下 |
| 012 | エッジ  | 低   | あ                  | （不明瞭なため判定不可）        | ×  | 0.38 | 情報不足      |

### ドキュメントの改善

| 問題              | 対策               |
| --------------- | ---------------- |
| **情報が見つからない**   | ドキュメントを追加する      |
| **関連情報がヒットしない** | 想定される質問キーワードを含める |
| **情報が古い**       | ドキュメントを更新する      |

### チャンク設定の調整

![](/files/LImPVzwEkW57QvfZTwLd)

| 問題            | 対策          |
| ------------- | ----------- |
| **情報が途中で切れる** | チャンクサイズを大きく |
| **ノイズが多い**    | チャンクサイズを小さく |
| **文脈が失われる**   | オーバーラップを増やす |

### 検索設定の調整

!\[test\_improvement\_01\_search\_result.png]\(.gitbook/assets/test\_improvement\_01\_search\_result 1.png)

| 問題               | 対策                   |
| ---------------- | -------------------- |
| **結果が少なすぎる**     | TopKを増やす、スコア閾値を下げる   |
| **無関係な結果が多い**    | Rerankを有効化、スコア閾値を上げる |
| **キーワードがヒットしない** | Hybrid Searchに変更     |

## 7.その他の実務的な改善施策

### A/Bテストによる比較評価

複数の設定パターンを比較して、最適な設定を見つけます。

| 比較項目    | パターンA         | パターンB                  | 評価指標       |
| ------- | ------------- | ---------------------- | ---------- |
| チャンクサイズ | 512トークン       | 1024トークン               | 適合率、再現率    |
| 検索方法    | Vector Search | Hybrid Search + Rerank | 検索精度、レイテンシ |
| TopK    | 3             | 5                      | 回答品質、コスト   |

### 情報の構造化とドキュメント設計

RAGの精度を高めるには、テストや設定調整の前に、**登録する情報の構造化**が最も重要です。

### ドキュメント粒度の最適化

| 原則               | 説明                          | 例                                                       |
| ---------------- | --------------------------- | ------------------------------------------------------- |
| **1ドキュメント1トピック** | 1つのドキュメントには1つの明確なトピックのみを含める | <p>○ 「返品ポリシー」専用ドキュメント<br>× 「全ポリシー」に返品・配送・キャンセルを詰め込む</p> |
| **適切なサイズ**       | 長すぎず短すぎない（目安: 500〜2000文字）   | <p>○ 1つの製品説明で1ドキュメント<br>× 全製品カタログで1ドキュメント</p>           |
| **自己完結性**        | そのドキュメントだけで質問に答えられる         | <p>○ 必要な前提情報も含める<br>× 「詳細は別ページ参照」が多い</p>                |

### 見出し構造の最適化

見出しはRAGの検索精度に大きく影響します。

**良い見出しの例:**

* ✅ 「営業時間について」「店舗の営業時間」
* ✅ 「返品・交換の手順」「返品方法」
* ✅ 「料金プランの比較」「各プランの違い」

**避けるべき見出し:**

* ❌ 「概要」「詳細」「その他」（内容が不明瞭）
* ❌ 「Q1」「項目1」（キーワードがない）
* ❌ 「注意事項」（何についての注意か不明）

### キーワードの戦略的配置

ユーザーが使いそうなキーワードを意図的に含めます。

| 対象           | 具体例                                                     |
| ------------ | ------------------------------------------------------- |
| **表記揺れ対応**   | <p>「返品・返却・リターン」を全て記載<br>「キャンセル・取消・中止」を併記</p>            |
| **質問表現を含める** | <p>「営業時間は何時から何時ですか？」という文を含める<br>「〜はできますか？」形式を意図的に使う</p> |
| **同義語・関連語**  | 「価格」「料金」「値段」「費用」を適切に使い分け                                |
| **略語と正式名称**  | <p>「FAQ（よくある質問）」両方記載<br>「AI（人工知能）」併記</p>                |

### Q\&A形式の活用

特にFAQは、Q\&A形式にすることで検索精度が大幅に向上します。

**例**

```
Q: 返品はできますか？
A: はい、商品到着後14日以内であれば返品可能です。未開封・未使用の商品に限ります。返品手順は...

Q: 返品の送料は誰が負担しますか？
A: 商品に不備がある場合は弊社負担、お客様都合の場合はお客様負担となります。
```

### メタデータの活用（該当する場合）

![](/files/kMLaexcCtT6UZJvI9R9K)

Difyではドキュメントにメタデータを付与できます。

* **カテゴリ**: 商品情報、サポート、料金など
* **対象者**: 一般ユーザー、法人、管理者など
* **更新日**: 情報の鮮度管理
* **優先度**: 重要な情報に高い優先度

### ユーザーフィードバックの収集

実際のユーザーからのフィードバックを体系的に収集します。

**収集方法**

* 👍👎 ボタンによる満足度評価
* フリーテキストでのコメント
* 「回答が役に立ちましたか？」アンケート
* 会話ログの定期レビュー

**フィードバックの収集例**

| 日付         | ユーザー質問 | 回答内容    | 評価 | 問題点      | 改善案        | ステータス |
| ---------- | ------ | ------- | -- | -------- | ---------- | ----- |
| 2025-01-10 | 返品方法は？ | 配送方法を回答 | 👎 | 質問意図を誤認識 | 返品ドキュメント強化 | 対応済   |
| 2025-01-11 | 学割ある？  | 該当情報なし  | 👎 | 口語表現に未対応 | 表記揺れ追加     | 対応中   |

### エラーパターンの特定と対策

頻出する問題をカテゴリ別に分析します。

| エラーパターン     | 原因              | 対策               | 優先度 |
| ----------- | --------------- | ---------------- | --- |
| **情報不足エラー** | 該当ドキュメントが存在しない  | ドキュメント追加         | 高   |
| **誤検索エラー**  | 類似キーワードで別情報がヒット | ドキュメント分離、メタデータ活用 | 高   |
| **部分情報エラー** | 情報が複数ドキュメントに分散  | TopK調整、ドキュメント統合  | 中   |
| **鮮度エラー**   | 古い情報が検索される      | ドキュメント更新、削除      | 中   |
| **曖昧性エラー**  | 質問が不明瞭          | プロンプト改善（確認質問）    | 低   |

### 定期メンテナンス計画

継続的な品質維持のためのスケジュールを設定します。

**推奨メンテナンススケジュール**

* **毎週**: フィードバックレビュー、エラーログ確認
* **毎月**: テストケース再実行、精度測定、問題ドキュメント更新
* **四半期**: 全体レビュー、A/Bテスト実施、大規模リファクタリング検討
* **随時**: 製品・サービス変更時の即座反映

### パフォーマンスモニタリング

RAGシステムの健全性を継続的に監視します。下記は一例です。

| 監視項目         | 目標値     | 警告値     | 対応               |
| ------------ | ------- | ------- | ---------------- |
| **平均レイテンシ**  | 2秒      | 3秒      | TopK削減、Rerank見直し |
| **トークン消費/日** | 予算内     | 予算の80%超 | TopK削減、チャンクサイズ調整 |
| **適合率**      | 80%     | 70%     | ドキュメント・設定見直し     |
| **ユーザー満足度**  | 4.0/5.0 | 3.5/5.0 | 全面的な改善プロジェクト     |