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

## 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利用枠・クレジット残高の確認。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalhumans.jp/dify-guide/operations/dify-docs-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.