Dify 常見錯誤排除：從模型設定到知識庫失效
模型接不上、文件上傳沒反應、機器人不讀知識庫、回答開始亂編。這篇按症狀分類，每一種給出判斷順序與最可能的原因。
🚀 想直接開始?60 秒部署你的 Dify
AI 應用開發平台 — No-Code 建構你的 AI。月付 NT$1,599 起,
Dify 出問題的時候，症狀常常長得很像——都是「它沒有照我想的做」。但原因可能在完全不同的層。
這篇按症狀分類，每一種給一條判斷路徑。先分辨是哪一層的問題，再動手，比亂調參數快得多。
30 秒總覽
| 症狀 | 最可能的原因 | 先看哪裡 |
|---|---|---|
| 模型接不上 | Key 有問題或額度用完 | 供應商後台 |
| 文件上傳沒反應 | 解析失敗或資源不足 | 文件格式與大小 |
| 不讀知識庫 | 沒把知識庫接到應用 | 應用的上下文設定 |
| 回答亂編 | 撈不到正確段落 | 回答的引用來源 |
| 突然變慢 | 資源或知識庫規模 | 是單人慢還是多人慢 |
一、模型設定相關
填了 API Key 但顯示未設定
最常見的是複製時夾帶了前後空白或換行。重新貼一次，確認沒有多餘字元。
其次是這把 Key 沒有對應模型的權限。有些供應商的 Key 是分權限的，能呼叫 A 模型不代表能呼叫 B。
設定成功但呼叫失敗
依序確認三件事：
- 額度——去供應商後台看餘額與用量，用完了是最常見的原因
- 模型名稱——供應商下架或改名舊模型時，設定會失效
- 速率限制——短時間大量呼叫可能被限流
判斷方法很簡單：直接在供應商的平台上測同一把 Key。那邊能用、這邊不能，問題在設定；兩邊都不能，問題在 Key 本身。
二、知識庫相關
文件上傳後一直在處理中
解析與建立索引是整個流程最重的一步，大型 PDF 特別吃資源。
- 掃描版 PDF——解析成功率低，建議先轉成文字
- 檔案很大——拆成幾個小檔案再上傳
- 經常發生——可能是規格不夠，看資源邊界那篇判斷
機器人完全不引用知識庫
先確認你把知識庫接到應用了。建好知識庫不等於應用會用它，要在應用的上下文設定裡加進去。
這是最常見的漏掉，而且症狀很誤導——看起來像是檢索壞了，其實是根本沒接。
撈到的段落不相關
這是檢索的問題，不是模型的問題。可調的地方在知識庫教學有完整說明，優先順序是：
- 換成混合檢索（尤其內容有專有名詞時）
- 檢查分段是不是把答案切斷了
- 降低或關閉分數閾值
三、回答品質相關
它在編造答案
先看引用來源，分兩種情況處理：
| 引用來源 | 問題在 | 怎麼修 |
|---|---|---|
| 撈到的段落不相關 | 檢索 | 調檢索模式或分段 |
| 撈對了但答案不對 | Prompt | 明確要求「只根據提供的資料回答」 |
| 什麼都沒撈到 | 閾值或文件 | 降低閾值，或確認文件真的有寫 |
回答的內容是舊的
來源文件改了但沒重新上傳。知識庫不會自動同步，這是最容易累積的維護債——尤其是價格和政策這類會變的內容。
換了模型之後品質下降
正常。同一段 Prompt 在不同模型上的表現差異比多數人預期的大，換模型之後 Prompt 通常要重調。
四、效能相關
先分辨是哪一種慢
這個判斷能省掉大量無效嘗試：
- 只有你一個人用也慢——多半是模型的回應時間，加資源沒用
- 多人同時用才慢——並發吃滿，這才是資源問題
- 知識庫變大後才慢——檢索負擔上升，先考慮拆分知識庫
費用突然變高
三個常見原因：Top-K 設太大（每次送給模型的內容變多）、對話輪數變長、或用了 Agent 而它一直重試。
什麼時候該重建實例
誠實講：大多數問題不需要重建。上面的症狀幾乎都能在設定層面解決。
真的需要重建的情況很少，而且重建會清掉你的應用與知識庫設定。動手之前先確認你已經排除了設定層的原因——不然重建之後同樣的問題會再出現一次。
自架與託管的排查差異
同樣的症狀，兩種部署方式要查的地方不一樣：
| 症狀 | 自架先查 | 託管先查 |
|---|---|---|
| 整個服務打不開 | 容器有沒有全部起來 | 控制台的實例狀態 |
| 上傳一直失敗 | Worker 容器的記憶體 | 檔案大小與格式 |
| 升級後壞了 | 版本更新紀錄的破壞性變更 | 回報給服務方 |
| 資料不見了 | 資料庫容器與磁碟掛載 | 確認是不是刪錯知識庫 |
自架的排查範圍大很多——多容器架構代表任何一個容器出問題都會表現成「Dify 怪怪的」。這也是成本拆解那篇說的隱藏成本：不是架設的那幾小時，是往後每次出事的排查時間。
怎麼減少出事
一、變更一次只改一項
同時換模型、調 Top-K、改 Prompt，效果變差時你不知道是哪一個造成的。這是最常見的除錯陷阱。
二、留一組固定的測試問題
準備十個真實問過的問題，每次調整後跑一遍。沒有基準就沒有「變好了」這回事——憑感覺判斷通常是錯的。
三、文件更新要有流程
價格改了、政策改了，同時要重傳知識庫。把這件事綁進既有流程，不要靠記憶。
常見問題
Q：怎麼知道問題在 Dify 還是在模型供應商？
直接在供應商平台上用同一把 Key 測一次。那邊正常就是這邊的設定問題，那邊也不正常就是 Key 或額度。
Q：可以看到詳細的錯誤訊息嗎？
應用的日誌會記錄每次對話的執行細節，包含撈到哪些段落、送出什麼、模型回什麼。排查任何回答品質問題都從這裡開始。
Q：升級版本之後東西壞了？
先看官方的版本更新紀錄，確認是不是有破壞性變更。託管版本的升級由平台處理，自架的話升級前務必備份。
Q：知識庫刪掉的文件還會被引用嗎？
刪除文件後索引會一併移除。如果還是引用得到，確認是不是同一份內容也存在於別的知識庫裡。
回報問題前先準備的資訊
要找人幫忙看的時候，帶著這幾項會快很多：
- 完整的錯誤訊息，不是「就是不能用」
- 是一直這樣還是偶爾這樣
- 最近改過什麼（換模型、傳新文件、升級版本）
- 應用日誌裡那次失敗的紀錄
第三項最常被忽略，但它通常直接指向答案。「昨天還好好的」後面幾乎都跟著一個被忘記的變更。
資料來源與延伸連結
- Dify 官方文件
- Dify 版本更新紀錄——升級後出問題先查這裡
- Dify 原始碼與 Issue 追蹤
