トラブルシューティング
dify-docs-troubleshooting
1. トラブルシューティングの基本フロー
問題が発生した際は、以下のステップで対応を行ってください。
- 再現確認: 発生条件、頻度、影響範囲を整理する。
- ログ・トレース確認: Difyの「ログ」および「トレース」機能で、どのノードで時間がかかっているか、エラーが出ているかを確認する。
- 切り分け: 原因がLLM、ナレッジ（RAG）、外部ツール、ネットワーク、設定のどこにあるかを特定する。
- 処置: 設定変更、修正、またはロールバックを実施する。
- 検証: テスト環境で動作確認後、本番環境で同条件の再試験を行う。
- 恒久対策: 監視アラートの追加、ナレッジの整備、手順化を行う。
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）」機能や固定ルールを使用し、回答を固定化・安定化させてください。
プロンプト調整
## 制約条件
・ナレッジベースに情報がない場合は、正直に「その情報は持ち合わせていません」と回答してください。
・推測や作り話はしないでください。4. 運用・保守体制
緊急度の定義と連絡先
緊急度 | 定義 | 対応 |
高 | サービス停止、全ユーザー影響、情報漏洩 | 直ちに開発担当およびプロバイダーへ連絡 |
中 | 一部機能不全、性能劣化 | 当日中に調査開始、回避策の検討 |
低 | 軽微な表示崩れ、再現性低 | 次回メンテナンス時に対応 |
定期チェック・予防策（推奨）
- エラー率監視: エラー率がしきい値（例: 5%）を超えた場合のアラート設定。
- 応答時間監視: 平均応答時間が基準（例: 5秒）を超過していないか確認。
- ナレッジメンテナンス: 定期的なドキュメントの更新とインデックス再同期。
- クォータ管理: モデルプロバイダーやツールのAPI利用枠・クレジット残高の確認。
お役に立ちましたか？
😞
😐
🤩
最終更新日 February 20, 2026