RAG 管道故障模式：生產環境除錯現場指南

RAG 管道會靜默地失敗。與當機的服務或拋出的例外不同，損壞的 RAG 管道仍然會回傳答案。只不過是錯誤的答案、不完整的答案，或者被不應該到達 LLM 的資訊所污染的答案。系統看起來運作正常，實際上卻在輸出無用的結果。

本指南編錄了我們在生產 RAG 系統中反覆看到的故障模式。每個條目遵循相同的結構：您觀察到什麼、為什麼會發生以及如何修復。請收藏本頁。當凌晨 2 點您的檢索管道回傳無意義的結果而您無法弄清原因時，您會需要它。

故障模式 1：檢索未命中（相關文件存在但未被檢索）

症狀： LLM 說「我沒有關於這個的資訊」或虛構一個答案，即使正確的文件在您的向量儲存中。使用者報告系統「不知道」您明知已經索引的內容。

根本原因： 查詢 embedding 和文件區塊 embedding 在向量空間中不夠接近，儘管它們在語義上是相關的。這發生在以下情況：

• 查詢使用的術語與來源文件不同（使用者詢問「解僱員工」，文件使用「非自願終止」）
• embedding 模型未在您的領域詞彙上訓練
• 區塊太大，用不相關的上下文稀釋了 embedding
• 區塊太小，遺失了與查詢匹配所需的語義含義

修復方法：

• 新增混合搜尋層（BM25 關鍵字搜尋與向量相似度並行）以擷取術語不匹配
• 在上線前用真實使用者查詢測試檢索——不僅僅是您自己編寫的查詢
• 嘗試不同的區塊大小：256-512 個 token 對大多數文件類型來說是一個合理的起點
• 如果您的內容使用專業詞彙，考慮使用領域適配的 embedding 模型
• 新增查詢擴展或重寫，在 embedding 之前重新表述使用者查詢

故障模式 2：檢索到錯誤的上下文（不相關的文件獲得高分）

症狀： LLM 給出自信但不正確的答案，引用了錯誤文件、錯誤章節或完全不同主題的資訊。檢索到的區塊看起來合理但與實際問題無關。

根本原因： 向量相似度不等於相關性。兩個段落可以在語義上相似（相同領域、相同詞彙），但一個對另一個並不相關。常見觸發因素：

• 範本文字（頁首、頁尾、免責聲明）獲得高相似度分數，因為它們到處出現
• 來自不同時間段或版本的文件未被區分
• 缺少中繼資料過濾器，因此搜尋考慮整個語料庫而不是相關子集

修復方法：

• 新增中繼資料過濾（日期、文件類型、部門、版本），使檢索在相似度排序之前縮小搜尋空間
• 在擷取過程中去除範本文字——在分塊之前移除頁首、頁尾和重複的免責聲明
• 在初始檢索之後實施重排序步驟，使用 cross-encoder 模型比原始餘弦相似度更準確地評分查詢-文件相關性
• 新增相關性閾值——如果區塊的相似度分數低於經過測試的最低值，則不要將其傳遞給 LLM

故障模式 3：過時的上下文（文件已過期）

症狀： LLM 基於舊資訊給出答案——上季度的定價、被取代的政策、已棄用的 API 端點。使用者失去信任，因為他們知道資訊已更改但系統仍給出舊答案。

根本原因： 向量儲存包含已被更新或取代的文件的 embedding，而索引管道不偵測或處理更新。這是生產中最常見的 RAG 故障，因為大多數團隊建構了初始索引管道，但從未建構更新管道。

修復方法：

• 在中繼資料中實施帶時間戳記的文件版本控制，以便可以按新近度過濾
• 建構增量重新索引管道，偵測更改的文件並僅重新 embed 更新的區塊
• 為每個區塊新增「上次索引」時間戳記，並在上下文中將其呈現給 LLM，以便它可以提醒可能過時的資訊
• 安排定期的完整重新索引作為安全網，即使您有增量更新
• 請參閱我們關於 embedding 漂移和過時向量 的深入分析以瞭解偵測策略

故障模式 4：區塊邊界損壞（答案跨區塊分裂）

症狀： LLM 給出感覺不完整的部分答案，或者因為相關內容被分裂在區塊邊界而組合了兩個不相關部分的資訊。使用者描述答案「接近但缺少關鍵細節」。

根本原因： 固定大小分塊在任意字元或 token 計數處分割文件，忽略語義邊界。一個關鍵段落被一分為二。前半部分落在一個區塊中，後半部分在另一個區塊中。檢索找到一半但找不到另一半。

修復方法：

• 使用尊重段落、節和標題邊界的語義分塊
• 新增區塊重疊（區塊大小的 10-20%），使邊界內容出現在相鄰的區塊中
• 對於結構化文件（法律合約、技術規格），按節層級而不是按大小分塊
• 在每個區塊中包含父節標題，以便 LLM 即使對於節中間的區塊也有結構上下文
• 請參閱我們關於糟糕的區塊如何毒害 RAG 答案的文章以取得詳細分析

故障模式 5：上下文視窗溢位（檢索到太多上下文）

症狀： LLM 忽略一些檢索到的文件，給出僅引用第一個或最後一個區塊的答案（首因/近因偏差），或產生過於籠統的回應，不涉及上下文中的具體細節。

根本原因： 檢索步驟回傳太多區塊，超出了 LLM 的有效上下文利用能力。即使是擁有超過 128K 上下文視窗的模型，在上下文嘈雜或過多時也會表現出效能下降。當模型被埋在十頁鬆散相關的文字中時，它無法區分信號和雜訊。

修復方法：

• 將 top-k 檢索減少到 3-5 個區塊而不是 10-20 個
• 新增重排序步驟，僅將排名最高的結果傳遞給 LLM
• 實施上下文壓縮——在傳遞給模型之前，對檢索到的區塊進行摘要或擷取關鍵句子
• 使用您的特定文件類型，在不同上下文長度下測試模型的實際效能
• 考慮您是否需要所有區塊還是只需要最相關的那一個

故障模式 6：透過上下文洩露 PII

症狀： LLM 的回應包含不應該向當前使用者展示的文件中的個人姓名、電子郵件地址、電話號碼或其他個人身分資訊。合規團隊提交事件報告。

根本原因： 包含 PII 的文件在未經編輯的情況下被索引，檢索管道沒有存取控制層。LLM 忠實地包含上下文中的任何內容，包括它不應該看到的敏感資料。

修復方法：

• 在文件解析和分塊/embedding 之間新增 PII 編輯作為管道階段
• 實施文件級和區塊級存取控制，使檢索尊重使用者權限
• 稽核您的向量儲存以查找 PII 暴露——在儲存的區塊文字中搜尋模式（電子郵件、電話號碼、SSN）
• 請參閱我們關於 RAG 上下文視窗中的 PII 洩露 的指南以取得全面的預防框架

故障模式 7：儘管上下文正確仍產生幻覺

症狀： 檢索到了正確的文件並存在於上下文中，但 LLM 仍然產生不正確的資訊。它可能綜合了不在任何檢索區塊中的事實，或誤解上下文並得出錯誤的結論。

根本原因： LLM 將其參數知識（預訓練資料）與提供的上下文混合，其參數知識佔了上風。這在具有強先驗的更大、更強模型中更為常見。當上下文與模型的訓練資料相矛盾時也會發生——模型「信任自己」勝過信任上下文。

修復方法：

• 在系統提示中新增明確指令：「僅根據提供的上下文回答。如果上下文不包含答案，請說明。」
• 使用更小的、經過微調的模型，這些模型被訓練為忠實於上下文而不是依賴參數知識
• 實施引用要求——強制模型引用其參考的特定區塊
• 新增驗證步驟，檢查答案是否基於檢索到的上下文
• 如果這是一個持續存在的問題，考慮針對上下文忠實度進行微調

故障模式 8：Embedding 模型不匹配

症狀： 儘管分塊良好且文件充足，所有查詢的檢索品質始終很差。相關文件的得分低於預期。切換到不同的 embedding 模型後結果發生了顯著變化。

根本原因： embedding 模型是根據基準測試分數而不是領域適配性選擇的。通用 embedding 模型在專業內容（醫學、法律、金融）上可能表現不佳，因為它們未在該詞彙上訓練。此外，對索引和查詢使用不同的 embedding 模型會產生無意義的相似度分數。

修復方法：

• 始終對索引和查詢使用相同的 embedding 模型——這是不可協商的
• 在做出選擇之前，用您的實際文件和實際查詢測試多個 embedding 模型
• 對專業內容考慮使用特定領域或微調的 embedding 模型
• 執行檢索評估：對於 50-100 個已知的查詢-文件對，衡量正確文件是否出現在 top-k 結果中

診斷檢查表

當您的 RAG 管道產生糟糕的結果時，按順序完成此檢查表：

1. 文件是否在儲存中？ 檢查來源文件是否確實已被索引。擷取失敗比您想像的更常見。
2. 區塊是否可檢索？ 用來源文件中的確切文字直接查詢向量儲存。如果精確匹配都失敗了，您的 embedding 管道已損壞。
3. 對於真實查詢是否檢索到了正確的區塊？ 用實際使用者查詢測試，而不是您編寫的合成查詢。
4. 區塊的內容是否正確？ 閱讀區塊的原始文字。它是完整的嗎？它是否損壞？它是否包含回答問題所需的資訊？
5. 上下文是否到達了 LLM？ 記錄傳送給模型的完整提示，包括所有檢索到的上下文。確認沒有內容被截斷或丟棄。
6. LLM 是否在使用上下文？ 如果上下文正確但答案錯誤，問題出在產生步驟，而不是檢索。

建構可觀測的 RAG 管道

這些故障模式中的大多數共享一個共同的促成因素：缺乏可觀測性。當您的 RAG 管道是一系列不可見的函式呼叫——文件解析、分塊、embedding、檢索、上下文組裝、產生——診斷故障需要追溯幾個月前在截止日期壓力下編寫的程式碼。

Ertas Data Suite 採用了不同的方法。RAG 管道的每個階段都是畫布上可見的節點——用於索引的 File Import、Parser、PII Redactor、RAG Chunker、Embedding、Vector Store Writer；用於檢索的 API Endpoint、Query Embedder、Vector Search、Context Assembler、API Response。每個節點記錄其輸入和輸出。當檢索品質下降時，您可以檢查每個階段的確切輸出，而無需向深埋的 Python 函式新增列印陳述式。

管道不是隱藏在 LangChain 抽象或 LlamaIndex 回呼中。它是可見的、可稽核的和可除錯的——這正是當生產 RAG 在凌晨 2 點崩潰時您所需要的。

令人不安的真相

RAG 管道不是「設定後就忘記」的基礎設施。它們是活的系統，隨著文件變化、使用者查詢演變和 embedding 模型漂移而退化。每個在生產中部署 RAG 的團隊最終都會遇到本目錄中的大多數故障模式。快速恢復的團隊和花數週除錯的團隊之間的區別在於可觀測性：您能看到管道每個階段在做什麼，還是在猜測？

建構您的 RAG 管道，使您能夠看到其內部。未來的您會感謝現在的自己。