RAGLite：用 DuckDB 或 PostgreSQL 直接組裝 RAG 管線的 Python 工具箱
🥤 RAGLite is a Python toolkit for Retrieval-Augmented Generation (RAG) with DuckDB or PostgreSQL
秒懂
- 它是什麼？
- RAGLite 把檢索增強生成拆成可替換的零件：關鍵字與向量搜尋交給 DuckDB 或 PostgreSQL，LLM 交給 LiteLLM，重排序交給 rerankers。它不引入 PyTorch 與 LangChain，代價是部分功能要靠外部服務補齊。
- 適合誰用？
- RAGLite 適合已經有 DuckDB 或 PostgreSQL、想自己掌控檢索與生成流程、又不願被 LangChain 抽象層綁住的 Python 團隊。若你需要的是託管式檢索服務，或必須在完全離線且沒有預編譯 llama-cpp-python 二進位的環境跑本地模型，這個專案會讓你花時間在部署而不是在檢索品質上。
- 可以商用嗎？
- 可以，但有條件。MPL-2.0 是弱 copyleft 授權：可以用在商業與閉源軟體中，但如果你散布了對它本身檔案的修改，這些修改必須以同一授權公開。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 30 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解決的是 RAG 管線被框架綁死這件事
多數 RAG 框架把切塊、嵌入、檢索、重排序、生成全部包成自己的抽象層，一旦你想換掉其中一環，往往得連帶改動其他部分。RAGLite 的定位相反：README 把它描述為「a Python toolkit for Retrieval-Augmented Generation (RAG) with DuckDB or PostgreSQL」，每個環節都指向一個既有的獨立專案。LLM 走 LiteLLM，重排序走 rerankers，PDF 轉 Markdown 走 pdftext 與 pypdfium2，句分割走同團隊的 wtpsplit-lite，前端走 Chainlit。RAGLite 自己負責的是把這些零件串成資料流，以及幾個它自己實作的演算法。
目標讀者是已經在用 Python 寫資料管線、對向量資料庫有基本認識、並且願意自己讀原始碼的工程師。README 明確寫出「Only lightweight and permissive open source dependencies (e.g., no PyTorch or LangChain)」，這句話同時是賣點也是篩選條件：它假設你不介意自己處理模型部署，換來的是依賴樹小、升級時不會被上游框架的破壞性變更拖著走。
資料流：文件進來，多向量區塊出去，兩路檢索再融合
從 README 的章節順序可以看出管線的形狀：先設定 RAGLiteConfig，再插入文件，然後才做檢索生成。插入階段把文件轉成 Markdown，切分成句子，再切成語意區塊。這裡有兩個值得注意的機制。其一是 late chunking，先對整份文件做嵌入再切塊，讓每個區塊的向量保留上下文，而不是切完才各自嵌入。其二是 contextual chunk headings，為區塊補上標題脈絡。兩者都是為了同一個問題：區塊脫離原文後語意被截斷。
檢索階段是混合搜尋。DuckDB 走 FTS 加 VSS 擴充，PostgreSQL 走 tsvector 加 pgvector。兩路結果用 RRF 融合，README 引用的正是 Cormack 等人那篇 RRF 論文。融合之後交給 rerankers 重排，預設是 FlashRank，README 標注它支援多語言。最後一層是 adaptive retrieval，由 LLM 依查詢判斷要不要檢索、要檢索什麼。這個設計的意涵是：不是每個問題都會觸發向量搜尋，對於「你好」這類問候語可以省下一次檢索。
管線末端還有一個 query adapter，README 稱它為 closed-form linear query adapter，做法是解一個正交 Procrustes 問題。它的作用是線性變換查詢向量，讓檢索更貼合你的語料，而且有閉式解，不需要梯度下降。README 把它列為獨立步驟，表示要先計算再使用。
安裝與設定的實際形狀
最基本的安裝是 pip install raglite。前端、非 PDF 檔型、評估各自是額外的 extra：pip install raglite[chainlit]、pip install raglite[pandoc]、pip install raglite[ragas]。Mistral OCR 不在 extra 裡，README 要你直接 pip install mistralai。
設定從 RAGLiteConfig 開始。LLM 的識別字走 LiteLLM 的格式，本地模型則用 llama-cpp-python/<hugging_face_repo_id>/<filename>@<n_ctx> 這種形式，n_ctx 是選填的上下文長度。README 對本地模型給了一個明確提醒：建議安裝預編譯的 llama-cpp-python 二進位，並列出可選的變數 LLAMA_CPP_PYTHON_VERSION、PYTHON_VERSION、ACCELERATOR、PLATFORM。這裡有個容易被忽略的括號註記：「not every combination is available」，也就是這四個變數不是任意組合都有對應的 wheel。
資料庫端 README 提到可以在 neon.tech 幾次點擊就建好 PostgreSQL。DuckDB 則不需要外部服務。這個二選一不是純粹的部署偏好，它會連帶決定關鍵字搜尋的實作路徑。
為了不依賴 PyTorch，它把重量轉移到別的地方
README 把「no PyTorch or LangChain」放在 Features 的第一條，這是整個專案最鮮明的取捨。少了 PyTorch，安裝體積與冷啟動時間下降，在 macOS 上也不必處理 MPS 的相容問題。但代價出現在兩個地方。
第一，本地 LLM 的加速要靠 llama-cpp-python 的預編譯二進位，README 列出的 ACCELERATOR 包含 metal、cu121、cu122、cu123、cu124，PLATFORM 包含 macosx_11_0_arm64、linux_x86_64、win_amd64。這意味著你的平台與 Python 版本必須落在已發布的組合內，否則就得自己編譯，而自行編譯通常會把 PyTorch 的依賴問題以另一種形式帶回來。第二，嵌入模型同樣不能是 PyTorch 模型，這限制了你能選用的嵌入器範圍，README 並沒有列出完整的嵌入器清單，這部分需要看原始碼才能確認。
同樣的取捨也出現在文件處理。內建路徑是 pdftext 加 pypdfium2，只涵蓋 PDF。要處理 DOCX、PPTX、圖片，README 給的是兩條路：裝 pandoc 做通用轉換，或接 Mistral OCR 取得含自動圖片描述的高品質結果。兩者都是外部依賴，後者還是付費 API。如果你的語料以 Office 文件為主，RAGLite 的「輕量」優勢會被這些外部元件抵銷一部分。
DuckDB 與 PostgreSQL 不是同一條路
README 把 DuckDB 與 PostgreSQL 並列為選項，但兩者的檢索能力來源不同。DuckDB 靠 FTS 與 VSS 兩個擴充，PostgreSQL 靠原生的 tsvector 與 pgvector。關鍵字搜尋的評分方式、分詞行為、以及向量索引的建立與維護成本，在這兩套系統之間不會一致，RRF 融合後的排序結果自然也會有差異。
選擇的實際分界在於部署形態。DuckDB 是單檔、嵌入式，適合單機或批次處理，沒有連線管理與權限層。PostgreSQL 適合多個服務共用同一份索引，也適合需要線上更新與並發寫入的情境。README 只提到可以在 neon.tech 快速建立 PostgreSQL，沒有討論連線池、索引重建或遷移路徑。
這裡有一個 README 沒有回答的問題：從 DuckDB 換到 PostgreSQL 時，已嵌入的向量與 FTS 索引能不能直接搬過去。兩邊的向量格式與全文檢索結構不同，合理的推測是需要重新插入文件並重建索引，但材料中沒有確認這一點，導入前應該先在測試環境驗證。
MCP 伺服器與 Chainlit 前端：對外暴露的兩種方式
RAGLite 內建一個 Model Context Protocol 伺服器，README 說任何 MCP 客戶端都能連接，並以 Claude desktop 為例。這條路適合把檢索能力掛進既有的桌面 AI 工具，不需要自己寫介面。另一條路是 Chainlit 前端，README 描述為可自訂的 ChatGPT 式介面，並列出 web、Slack、Teams 三種部署目標，對應 Chainlit 自己的部署文件。
兩者的維護成本不同。MCP 伺服器是 RAGLite 的一部分，行為跟著套件版本走。Chainlit 前端是額外安裝的 extra，它的介面與部署細節由 Chainlit 決定，RAGLite 只負責接上。如果你只需要把檢索結果餵給既有的 LLM 工作流，MCP 那條路要維護的表面積小得多。
評估功能同樣是選配，透過 raglite[ragas] 安裝，README 說它能評估檢索與生成的表現。這對想調整切塊策略或 query adapter 的團隊有用，因為沒有量測就無法判斷改動是否有效。但 Ragas 是獨立專案，它的評估指標與資料集格式不在 RAGLite 的說明範圍內。
替代方案與真正的差異
最直接的對照是 LangChain。RAGLite 的 README 明確把它列為不採用的依賴，理由寫在「no PyTorch or LangChain」那一行。差異不只在依賴數量。LangChain 提供的是統一的抽象介面與大量整合，好處是換供應商時改動小，代價是抽象層本身會成為除錯對象，而且版本升級經常需要跟著調整。RAGLite 走的是相反路線：它把每個環節指向一個具體的獨立專案，你直接面對 LiteLLM、rerankers、pdftext 的 API 與版本，出問題時知道該去看哪一份文件。
另一個方向是 LlamaIndex，它同樣提供從文件載入到查詢引擎的完整鏈路，並且在索引結構上有更多預設選項。RAGLite 在這方面的差異在於它對切塊與檢索的處理更具體：late chunking、contextual chunk headings、以二元整數規劃求解的最佳句分割與語意切塊、以及閉式解的 query adapter。這些不是通用抽象，而是針對特定檢索品質問題的解法。
如果你的需求是快速接上十幾種資料來源並在幾小時內跑出雛形，LangChain 或 LlamaIndex 的整合廣度仍然有優勢。如果你已經知道自己要用哪個資料庫、哪個嵌入模型，並且想把管線的每一段都握在手裡，RAGLite 的零件化設計更貼近這種工作方式。
授權、維護與版本節奏
RAGLite 採用 MPL-2.0。這是一種檔案層級的 copyleft：你修改過的 RAGLite 原始檔案必須以相同授權釋出，但把它作為依賴放進你的專案、與你自己的程式碼連結，並不會讓你的專案整體被要求開源。相較 MIT 或 Apache-2.0，這個條件在「直接改套件原始碼」的情境下會產生義務。以上是授權條款的性質描述，不構成法律意見，實際情況請依條文與你的使用方式判斷。
版本節奏方面，可取得的發布紀錄顯示 v0.7.0 在 2025 年 3 月、v1.0.0 在 2025 年 6 月、v1.1.1 在 2026 年 5 月，最後一次推送時間為 2026 年 8 月。從 0.x 跨到 1.0 通常代表 API 進入穩定承諾，但 README 沒有提供遷移指南或棄用政策，從 0.7 升到 1.x 的破壞性變更需要自行比對。
升級成本的主要來源不是 RAGLite 本身，而是它依賴的那些專案。LiteLLM 的供應商介面、rerankers 的模型清單、pdftext 的解析行為、以及 DuckDB 的 FTS 與 VSS 擴充版本，任何一個變動都可能影響輸出。DuckDB 的擴充需要與資料庫版本匹配，這是嵌入式資料庫常見的升級摩擦點。
導入前建議先確認三件事：你的平台與 Python 版本是否落在 llama-cpp-python 已發布的預編譯組合內；語料是否只有 PDF，還是需要 pandoc 或 Mistral OCR；以及你打算用 DuckDB 還是 PostgreSQL，因為這會決定關鍵字搜尋走 FTS 還是 tsvector，而兩者的排序結果不會相同。
編輯結論
RAGLite 適合已經有 DuckDB 或 PostgreSQL、想自己掌控檢索與生成流程、又不願被 LangChain 抽象層綁住的 Python 團隊。若你需要的是託管式檢索服務，或必須在完全離線且沒有預編譯 llama-cpp-python 二進位的環境跑本地模型，這個專案會讓你花時間在部署而不是在檢索品質上。導入前先確認三件事：資料庫是 DuckDB 還是 PostgreSQL，因為兩者的關鍵字搜尋實作不同（FTS 對上 tsvector）；PDF 以外的檔案格式是否需要 pandoc 額外安裝；以及你是否接受 MPL-2.0 對檔案層級的 copyleft 要求。
社群筆記