三個月前，我在 Github 上開源的一個 RAG 練手項目，目前已經有了 327 個 star，總共解決了 22 個 issues。結合過去幾個月的項目實踐，我重新對項目做了輕量化重構，降低資源消耗與部署門檻。

項目地址：https://github.com/weiwill88/Local_Pdf_Chat_RAG

麻雀雖小，五臟俱全。總體來說，這是一個輕量級但組件完整的本地化 RAG 智能問答平臺。可以通過 Gradio Web UI 直觀體驗混合檢索、重排序、遞歸查詢及聯網搜索等高級 RAG 策略，更能從源碼層面學習和實踐 RAG 的完整流程與優化技巧。BTW，也支持 API 的調用方式.

這篇試圖說清楚，項目的各個核心組件構成，日志分段拆解含義，以及進階和擴展方向參考，歡迎感興趣的盆友基于此項目進行探索和貢獻。

以下，enjoy:

1、項目定位

在接觸如 Dify、RAGFlow 這類高度封裝的 RAG 框架之前，復現和二開這個項目，可以：

熟悉 RAG 核心組件：實際體驗文本加載、切分、向量化、向量存儲與檢索（本項目使用 FAISS）、LLM 集成等關鍵環節。

理解 RAG 基本流程：從底層腳本層面觀察數據如何在 RAG 系統中流轉和處理。

進行初步優化與測試：嘗試調整參數、替換模型、優化提示詞等，直觀感受不同策略對結果的影響。

掌握這些基礎后，能更有的放矢地使用高級 RAG 框架的 API 進行針對性調優或定制開發。

2、核心優化

這部分要介紹的項目輕量化改造，主要也是為了讓初學者盆友更好的抓住 RAG 的核心脈絡，避免過早陷入數據庫管理和配置的細節中。

當理解了核心流程后，再過渡到如 ChromaDB 或其他生產級向量數據庫，就能更好地理解這些數據庫所解決的問題和提供的價值。

2.1舊版依賴問題

在上一個版本的 issues 中，有挺多用戶反饋依賴安裝時間過久，幾個主要的“重量級”組件及其依賴項是導致安裝時間較長的主要原因：

torch 和 transformers

這兩個庫是 sentence-transformers 的核心依賴。sentence-transformers 用于生成文本嵌入（向量化）以及進行結果重排序（通過交叉編碼器）。torch 是一個龐大的深度學習框架，而 transformers 包含了許多預訓練模型和工具。這些是現代 NLP 和 RAG 系統的基石，因此體積較大。

onnxruntime

這是 chromadb 的一個依賴。chromadb 在內部可能使用 ONNX Runtime 來執行其默認的嵌入模型或其他優化計算，即使項目代碼中指定了使用 sentence-transformers 來生成嵌入。onnxruntime 本身是一個跨平臺的機器學習模型執行引擎，體積也不小。

Langchain

雖然原項目目前主要使用它的文本分割器 (RecursiveCharacterTextSplitter)，但完整安裝 langchain 會引入不少間接依賴。

2.2輕量化改造

針對 Langchain 的優化

項目主要使用了 langchain 的文本分割功能，考慮到 langchain 已經將許多組件模塊化，所以可以僅安裝文本分割器模塊，并相應修改代碼中的導入語句。

針對向量數據庫

ChromaDB 雖然功能較為全面，但在某些場景下，尤其是對于本地運行和初學者而言，其依賴和服務可能相對“重”一些，會涉及到更多的后臺進程和磁盤空間占用。

FAISS-CPU 是一個專注于高效向量相似性搜索的 C++庫，Python 綁定通常更為輕量，依賴更少，尤其是在 CPU 版本下，不需要額外的數據庫服務運行，直接在內存中進行索引和搜索。這使得項目更容易在普通個人電腦上快速啟動和運行。

注：針對嵌入和重排序模型 (sentence-transformers, torch, transformers)，這部分是 RAG 系統效果的核心，輕量化難度較大，且容易犧牲模型性能，所以暫時不做處理。

3、核心組件拆解

項目雖然經過了輕量化改造，但依然包含了構建一個完整 RAG 系統的所有核心組件。學習和理解下述組件的運作方式，對于入門 RAG 技術很重要。

3.1文檔加載與解析：

使用 pdfminer.six 從 PDF 文件中提取文本內容，理解如何從不同格式的非結構化數據源中提取原始文本，這是 RAG 流程的第一步。熟悉不同的解析庫及其優缺點，能為后續處理多種數據源打下基礎。

3.2文本切分：

使用 langchain_text_splitters (如 RecursiveCharacterTextSplitter) 將長文本分割成小的數據塊 (chunks)。理解文本切分對于 RAG 的重要性。合適的切分策略能確保每個數據塊既包含足夠的上下文，又不超過后續處理（如向量化模型輸入長度、LLM 上下文窗口）的限制。學習不同的切分方法（如按字符數、按句子、遞歸等）及其適用場景。

3.3文本向量化 ：

使用 sentence-transformers 庫加載預訓練的句向量模型（如 moka-ai/m3e-base），將文本塊轉換為高維向量。這是 RAG 的核心之一。理解文本向量化的概念，即如何將語義信息編碼為計算機可以理解和比較的數字表示。

熟悉不同的向量化模型及其特點（如多語言支持、特定領域優化、向量維度等），并了解如何選擇合適的模型。

3.4向量存儲與索引 ：

使用 faiss-cpu 構建向量索引 (IndexFlatL2)，并在內存中存儲和管理這些向量及其與原始文本塊的關聯（通過我們自己維護的 faiss_contents_map, faiss_metadatas_map, faiss_id_order_for_index）。

理解向量數據庫/搜索引擎的基本原理，即如何高效地存儲大量向量，并根據查詢向量快速找到最相似的 K 個向量。通過 FAISS，可以直觀感受到索引構建、相似度計算（如 L2 距離）的過程。學習不同的索引策略對檢索效率和精度的影響。

3.5檢索：

語義檢索：用戶問題向量化后，在 FAISS 索引中執行 search 操作，獲取最相似的文本塊。

關鍵詞檢索：使用 rank_bm25 實現 BM25 算法，根據關鍵詞匹配度進行檢索。

混合檢索：結合語義檢索和 BM25 的結果，進行加權合并。

理解不同的檢索策略。語義檢索關注意義的相似性，關鍵詞檢索關注字面匹配。混合檢索則試圖結合兩者優點，提高召回率和相關性。學習如何評估和調整不同檢索策略的權重。

3.6上下文重排序：

使用 sentence-transformers 加載交叉編碼器 (CrossEncoder) 模型，對初步檢索到的上下文片段進行重新打分和排序，選出與問題最相關的片段。

理解在初步檢索后，如何進一步優化上下文的相關性。交叉編碼器通常比雙編碼器（用于向量化的模型）在相關性判斷上更精確，但計算量也更大，因此常用于對少量候選結果的精排。

3.7提示工程與大語言模型交互 ：

構建合適的提示 (Prompt)，將用戶問題和檢索到的相關上下文整合后，提交給大語言模型 (LLM)。通過 requests 與本地 Ollama 服務或云端 SiliconFlow API 進行交互，獲取 LLM 生成的答案。

遞歸檢索：利用 LLM 分析當前結果，判斷是否需要生成新的查詢以進行更深入的探索。

理解 LLM 在 RAG 中的核心作用——基于提供的上下文生成答案。學習如何設計有效的提示詞，以引導 LLM 更好地利用檢索到的信息。體驗與不同 LLM（本地/云端）集成的過程。遞歸檢索則展示了更高級的 RAG 模式，即如何讓 LLM 參與到信息檢索的迭代優化中。

3.8用戶界面：

使用 Gradio 構建交互式的 Web 界面。雖然不是 RAG 核心算法的一部分，但一個好的界面能極大地方便用戶與 RAG 系統交互、測試和調試。學習 Gradio 這類工具可以快速搭建原型。

4、運行日志拆解

下文會清晰地追蹤 RAG 系統處理問題的每一步，各位仔細閱讀下，有助于更好理解各組件的功能和協同方式。

4.1應用啟動與用戶界面初始化 (Gradio)

(venv) PS D:\Projects\Ongoing\開源項目\local_pdf+Chat_rag> python rag_demo_pro.py
Gradio version: 5.29.0
D:\Projects\Ongoing\開源項目\local_pdf+Chat_rag\rag_demo_pro.py:1703: UserWarning: You have not specified a value for the `type` parameter. Defaulting to the 'tuples' format for chatbot messages, but this is deprecated and will be removed in a future version of Gradio. Please set type='messages' instead, which uses openai-style dictionaries with 'role' and 'content' keys.
  chatbot = gr.Chatbot(
INFO:httpx:HTTP Request: GET https://api.gradio.app/pkg-version "HTTP/1.1 200 OK"
* Running on local URL:  http://0.0.0.0:17995
INFO:httpx:HTTP Request: GET http://localhost:17995/gradio_api/startup-events "HTTP/1.1 200 OK"
INFO:httpx:HTTP Request: HEAD http://localhost:17995/ "HTTP/1.1 200 OK"
* To create a public link, set `share=True` in `launch()`.

python rag_demo_pro.py: 這是啟動整個 RAG 應用的主命令。radio version: 5.29.0: 顯示了 Gradio 庫版本，它負責構建用戶交互界面。

UserWarning... chatbot = gr.Chatbot(...): Gradio 提示其聊天機器人組件參數 type 的未來變更。INFO:httpx:HTTP Request...: Gradio 啟動過程中的網絡請求，如檢查版本等。

Running on local URL: http://0.0.0.0:17995 : Gradio 服務成功啟動，用戶可通過此地址訪問 Web UI。

4.2數據初始化/清理

INFO:root:成功清理歷史FAISS數據和BM25索引

在處理新文檔前或應用啟動時，系統會清理舊的 FAISS 向量索引和 BM25 關鍵詞索引，確保基于當前文檔進行問答，避免數據混淆。

涉及組件：FAISS 索引管理、BM25 索引管理。

4.3文檔處理、向量化與 FAISS 索引構建

Batches: 100%|████████████████████████████████████████████████████████████| 1/1 [00:02<00:00,  2.71s/it]
INFO:root:FAISS索引構建完成，共索引 9 個文本塊

此階段包括了從 PDF 提取文本、將文本切分成小塊（chunks）、然后使用 sentence-transformers 模型（如 moka-ai/m3e-base）將這些文本塊批量轉換為向量。Batches: 100%...: 顯示文本塊向量化的進度。

INFO:root:FAISS 索引構建完成...: 表明所有文本塊的向量已成功存入 FAISS (IndexFlatL2) 索引。此處示例中，PDF 被處理成了 9 個文本塊。

涉及組件：pdfminer.six (PDF 解析)、langchain_text_splitters (文本切分)、sentence-transformers (向量化)、faiss-cpu (向量索引)。

4.4BM25 關鍵詞索引構建

Building prefix dict from the default dictionary ...
DEBUG:jieba:Building prefix dict from the default dictionary ...
Loading model from cache C:\Users\10440\AppData\Local\Temp\jieba.cache
DEBUG:jieba:Loading model from cache C:\Users\10440\AppData\Local\Temp\jieba.cache
Loading model cost 6.168 seconds.
DEBUG:jieba:Loading model cost 6.168 seconds.
Prefix dict has been built successfully.
DEBUG:jieba:Prefix dict has been built successfully.
INFO:root:BM25索引更新完成，共索引 9 個文檔

系統為相同的文本塊構建 BM25 關鍵詞索引，以支持后續的混合檢索。Building prefix dict...: jieba 分詞庫正在初始化并加載詞典，這是處理中文文本進行 BM25 計算的前提。

INFO:root:BM25 索引更新完成...: 表明針對這 9 個文本塊的 BM25 索引已創建。

涉及組件：rank_bm25 庫、jieba 分詞庫。

4.5用戶提問與遞歸檢索啟動 (第一輪)

INFO:root:遞歸檢索迭代 1/3，當前查詢: 發動機冒藍煙的故障原因分析

用戶通過 Gradio 界面輸入問題“發動機冒藍煙的故障原因分析”。系統啟動遞歸檢索流程，配置的最大迭代次數為 3，這是第一輪的開始。

涉及組件：Gradio UI、遞歸檢索控制邏輯。

4.6聯網搜索（可選，第一輪）

INFO:root:網絡搜索返回 5 條結果，這些結果不會被添加到FAISS索引中。

如果啟用了聯網搜索，系統會使用 SerpAPI 根據當前查詢從互聯網獲取實時信息。這些結果作為臨時上下文，當前版本不存入 FAISS。

涉及組件：SerpAPI 集成、requests 庫。

4.7查詢向量化 (第一輪)

Batches: 100%|████████████████████████████████████████████████████████████| 1/1 [00:00<00:00,  3.53it/s]

用戶的查詢（或其變體）被送入 sentence-transformers 模型轉換為查詢向量，用于在 FAISS 中進行語義相似度搜索。

涉及組件：sentence-transformers 模型。

4.8檢索結果重排序(第一輪)

Some weights of DistilBertForSequenceClassification were not initialized from the model checkpoint at sentence-transformers/distiluse-base-multilingual-cased-v2 and are newly initialized: ['classifier.bias', 'classifier.weight', 'pre_classifier.bias', 'pre_classifier.weight']
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
INFO:sentence_transformers.cross_encoder.CrossEncoder:Use pytorch device: cpu
INFO:root:交叉編碼器加載成功
Batches: 100%|████████████████████████████████████████████████████████████| 1/1 [00:07<00:00,  7.42s/it]

初步通過 FAISS 和 BM25 檢索到的候選文本塊，會由交叉編碼器 (CrossEncoder) 進行更精確的相關性打分和重排序。

Some weights...: Hugging Face Transformers 庫關于交叉編碼器底層模型部分權重新初始化的提示。INFO:...Use pytorch device: cpu: 交叉編碼器在 CPU 上運行。Batches: 100%...7.42s/it: 顯示重排序過程及其耗時。

涉及組件：sentence-transformers (CrossEncoder 模型)。

4.9LLM 交互：判斷是否需要遞歸查詢及生成新查詢 (第一輪后)

INFO:root:使用SiliconFlow API分析是否需要進一步查詢
INFO:root:生成新查詢: 新查詢(如果需要):
1. 渦輪增壓器故障是否會引起發動機冒藍煙？
2. 曲軸箱通風系統（PCV閥）故障如何導致燒機油？
3. 氣門油封老化與冒藍煙的具體關聯是什么？
4. 使用錯誤粘度的機油的燒機油風險有哪些？

系統將第一輪檢索的上下文及原始問題提交給大語言模型 (LLM，此處為 SiliconFlow API)。LLM 分析后判斷需要進一步探索，并生成了一系列更具體的新查詢點，以指導下一輪檢索。

涉及組件：LLM (SiliconFlow API/Ollama)、提示工程。

4.10遞歸檢索 (第二輪)

INFO:root:遞歸檢索迭代 2/3，當前查詢: 新查詢(如果需要):
1. 渦輪增壓器故障是否會引起發動機冒藍煙？
2. 曲軸箱通風系統（PCV閥）故障如何導致燒機油？
3. 氣門油封老化與冒藍煙的具體關聯是什么？
4. 使用錯誤粘度的機油的燒機油風險有哪些？
INFO:root:網絡搜索返回 5 條結果，這些結果不會被添加到FAISS索引中。
Batches: 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 15.57it/s] 
Batches: 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:06<00:00,  6.47s/it]

系統進入第二輪遞歸檢索，使用 LLM 生成的新查詢。重復進行聯網搜索、查詢向量化、混合檢索（隱含）、重排序等步驟。

涉及組件：同第一輪的檢索、向量化、重排序組件。

4.11LLM 交互：再次判斷與生成新查詢 (第二輪后)

INFO:root:使用SiliconFlow API分析是否需要進一步查詢
INFO:root:生成新查詢: 新查詢:  
1. 活塞環磨損或斷裂如何導致發動機冒藍煙？
2. 氣門油封老化與燒機油的因果關系及檢測方法
3. 氣缸壁劃傷是否會引起過量機油進入燃燒室？
4. 高粘度與低粘度機油選擇錯誤對燒藍煙現象的具體影響差異
5. 廢氣再循環系統(EGR)故障是否可能間接引發燒機油問題？


理由：
- **角度擴展**：現有信息聚焦于PCV閥、渦輪增壓器和基礎油品問題（如低粘度），但未覆蓋活塞環/氣門油封等機械磨損核心因素。需補充機械結構失效的關聯分析。
- **技術細化**：針對已知的“粘度過低”提示，需明確不同粘度機油的適用場景與異常消耗閾值（如高溫剪切性能）。
- **系統關聯性**：EGR系統雖不直接涉及潤滑回路，但其堵塞可能導致異常燃燒壓力變化間接加劇竄油現象。

第二輪檢索后，再次調用 LLM。LLM 進一步分析并生成了更細化、更深入的新查詢及理由，展示了其分析和引導能力。

涉及組件：LLM (SiliconFlow API/Ollama)、提示工程。

4.12遞歸檢索 (第三輪 - 最后一輪)

INFO:root:遞歸檢索迭代 3/3，當前查詢: 新查詢:
1. 活塞環磨損或斷裂如何導致發動機冒藍煙？
2. 氣門油封老化與燒機油的因果關系及檢測方法
3. 氣缸壁劃傷是否會引起過量機油進入燃燒室？
4. 高粘度與低粘度機油選擇錯誤對燒藍煙現象的具體影響差異
5. 廢氣再循環系統(EGR)故障是否可能間接引發燒機油問題？


理由：
- **角度擴展**：現有信息聚焦于PCV閥、渦輪增壓器和基礎油品問題（如低粘度），但未覆蓋活塞環/氣門油封等機械磨損核心因素。需補充機械結構失效的關聯分析。
- **技術細化**：針對已知的“粘度過低”提示，需明確不同粘度機油的適用場景與異常消耗閾值（如高溫剪切性能）。
- **系統關聯性**：EGR系統雖不直接涉及潤滑回路，但其堵塞可能導致異常燃燒壓力變化間接加劇竄油現象。
INFO:root:網絡搜索返回 5 條結果，這些結果不會被添加到FAISS索引中。
Batches: 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 11.48it/s] 
Batches: 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:04<00:00,  4.05s/it]

進入最后一輪遞歸檢索，重復之前輪次的步驟。在此輪結束后，系統會將所有收集到的、經過篩選的上下文信息，與原始問題一起，提交給 LLM 以生成最終答案（此部分日志未完全顯示）。

涉及組件：同前幾輪的檢索、向量化、重排序組件，以及最終的 LLM 答案生成。

5、進階與擴展方向

項目作為一個入門級的 RAG 實現，為后續的迭代和功能擴展提供了良好的基礎。以下是各位一些可以考慮的進階方向：

5.1更精細化的文本切分策略

當前的RecursiveCharacterTextSplitter是通用策略。可以研究并實現基于語義的切分（如使用模型判斷句子邊界或主題連貫性）、或針對特定文檔類型的結構化切分（如解析 Markdown 標題、表格等）。

5.2高級 FAISS 索引與管理

目前使用的是基礎的IndexFlatL2。可以嘗試更高級的 FAISS 索引類型，如IndexIVFPQ，以優化大規模數據下的檢索速度和內存占用。同時，研究如何更優雅地支持對 FAISS 中向量的刪除和更新（例如，使用IndexIDMap）。

5.3多元數據源接入

目前主要處理 PDF 和可選的網絡搜索。可以擴展支持導入其他格式的本地文檔（如.txt,.md,.docx），或者接入外部 API（如 Notion、Confluence 等知識庫）。

5.4查詢改寫與意圖識別：

在進行檢索前，使用 LLM 對用戶的原始查詢進行改寫（如糾錯、同義詞擴展、澄清模糊表述）或識別用戶真實意圖，可以提高檢索的精準度。

5.5上下文管理與壓縮

當檢索到的相關片段過多，超出 LLM 的上下文窗口限制時，需要有效的上下文壓縮策略（如篩選最重要片段、總結次要片段）來保證信息質量。

5.6更復雜的重排序模型/策略

除了當前的交叉編碼器和基于 LLM 打分，可以嘗試集成更先進的重排序模型，或實現多階段重排序策略。

5.7答案生成效果評估與追溯：

引入簡單的評估機制（如用戶反饋、答案與來源的相似度計算）和更清晰的答案來源追溯展示，幫助分析和改進系統表現。

6、寫在最后

Anyway，動手實踐的手搓方式來理解底層機制，是為后續深入學習和使用更高級框架的重要鋪墊。