トラブルシューティング
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利用枠・クレジット残高の確認。
最終更新