> 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/operations/dify-docs-troubleshooting.md).

# トラブルシューティング

## 1. トラブルシューティングの基本フロー

問題が発生した際は、以下のステップで対応を行ってください。

1. **再現確認**: 発生条件、頻度、影響範囲を整理する。
2. **ログ・トレース確認**: Difyの「ログ」および「トレース」機能で、どのノードで時間がかかっているか、エラーが出ているかを確認する。
3. **切り分け**: 原因がLLM、ナレッジ（RAG）、外部ツール、ネットワーク、設定のどこにあるかを特定する。
4. **処置**: 設定変更、修正、またはロールバックを実施する。
5. **検証**: テスト環境で動作確認後、本番環境で同条件の再試験を行う。
6. **恒久対策**: 監視アラートの追加、ナレッジの整備、手順化を行う。

## 2. よくある問題と解決策

### ケース1：応答が生成されない

**症状**: 無限ローディング、エラーメッセージ表示、タイムアウト

| 原因             | 対処・確認項目                                                |
| -------------- | ------------------------------------------------------ |
| **公開設定の不備**    | アプリが公開状態になっているか、APIキーや許可ドメインの設定を確認してください。              |
| **ワークフローのエラー** | デバッグ画面で実行し、失敗しているノードを特定します。入力/出力変数の受け渡しミスがないか確認してください。 |
| **設定/認証エラー**   | APIエンドポイント、環境変数、シークレットキー（API Key）が正しいか再確認してください。       |
| **外部ツールの停止**   | 連携している外部ツール側で障害やタイムアウトが発生していないか、curl等で疎通確認を行ってください。    |

### ケース2：応答品質が低い

**症状**: 的外れな回答、情報不足、幻覚（ハルシネーション）

| 原因          | 対処・確認項目                                                     |
| ----------- | ----------------------------------------------------------- |
| **プロンプト不備** | System Promptでの役割定義、制約条件、出力形式の指定を具体化してください。                 |
| **ナレッジ不足**  | 参照すべき情報がナレッジベースに含まれているか、検索ヒットしやすい表現か確認し、ドキュメントを追加・更新してください。 |
| **モデル選定**   | より高性能なモデルへの変更や、Temperature（温度）パラメータの調整を検討してください。            |

### ケース3：応答が遅い

**症状**: 回答生成に時間がかかる、タイムアウト頻発

| 原因           | 対処・確認項目                                        |
| ------------ | ---------------------------------------------- |
| **入力過多**     | System Promptを簡潔にし、不要なコンテキストを削減してください。         |
| **ナレッジ取得過多** | ナレッジ検索設定の「Top K」（取得チャンク数）を減らすか、要約ノードを導入してください。 |
| **ツール遅延**    | 外部APIの応答速度を確認し、タイムアウト値の延長やキャッシュ利用を検討してください。    |

### ケース4：機能不全（検索・ツール）

**症状**: 検索結果0件、ツールエラー

| 原因            | 対処・確認項目                                                               |
| ------------- | --------------------------------------------------------------------- |
| **インデックス未反映** | ナレッジベースの同期状況を確認し、再取り込みを行ってください。                                       |
| **検索スコア低**    | 「Score Threshold」（類似度しきい値）を下げて調整するか、ドキュメントのセグメント設定（チャンクサイズ）を見直してください。 |
| **ツール認証エラー**  | APIキーの期限切れ、権限スコープ不足、リクエストパラメータの型不一致を確認してください。                         |

## 3. デジタルヒューマン固有の問題

音声合成やアバターを介する場合の特有の問題への対処です。

### 応答が不自然・読み上げにくい

* **プロンプト調整**: System Promptで「話し言葉で」「句読点を適切に」「一文を短く」といった指示を追加してください。
* **禁止ワード設定**: 読み上げソフトが誤読しやすい記号や表現を禁止します。

### 回答が長すぎる

* **トークン制限**: モデル設定の`max_tokens`を適切な長さに制限してください。
* **指示による制御**: プロンプトで「結論から述べる」「〇〇文字以内で」と制約を設けてください。

### 知ったかぶり（幻覚）の防止

* **制約プロンプト**: 「ナレッジベースに情報がない場合は『分かりません』と答えること」を明記してください。
* **アノテーション活用**: よくある質問（FAQ）には、Difyの「アノテーション（Annotation Reply）」機能や固定ルールを使用し、回答を固定化・安定化させてください。

  **プロンプト調整**

  ```markdown
  ## 制約条件
  ・ナレッジベースに情報がない場合は、正直に「その情報は持ち合わせていません」と回答してください。
  ・推測や作り話はしないでください。
  ```

## 4. 運用・保守体制

### 緊急度の定義と連絡先

| 緊急度   | 定義                  | 対応                  |
| ----- | ------------------- | ------------------- |
| **高** | サービス停止、全ユーザー影響、情報漏洩 | 直ちに開発担当およびプロバイダーへ連絡 |
| **中** | 一部機能不全、性能劣化         | 当日中に調査開始、回避策の検討     |
| **低** | 軽微な表示崩れ、再現性低        | 次回メンテナンス時に対応        |

### 定期チェック・予防策（推奨）

* **エラー率監視**: エラー率がしきい値（例: 5%）を超えた場合のアラート設定。
* **応答時間監視**: 平均応答時間が基準（例: 5秒）を超過していないか確認。
* **ナレッジメンテナンス**: 定期的なドキュメントの更新とインデックス再同期。
* **クォータ管理**: モデルプロバイダーやツールのAPI利用枠・クレジット残高の確認。