LightRAG：把知識圖譜與向量檢索整合進 RAG 的實作指南

LightRAG：把知識圖譜與向量檢索整合進 RAG 的實作指南

如果你的 RAG 系統只依賴向量相似度，面對「跨文件比較」、「找出多個實體之間的關係」或「先理解整體主題，再回到具體細節」這類問題時，常常會遇到檢索上下文碎片化的問題。LightRAG 提供另一條路：在同一套工作流中，同時維護知識圖譜與向量索引，讓檢索可以在局部實體、全域關係與原始文字區塊之間切換。

本文以 LightRAG 官方 repository 與文件為依據，拆解它的架構、查詢模式、文件處理流程，以及如何用最小可行設定部署一個可用的 RAG 服務。重點不是把「知識圖譜」當成口號，而是理解哪些資料會被抽取、哪些元件會消耗模型呼叫，以及何時應該選擇 REST API 而不是直接嵌入 SDK。

先講結論：LightRAG 解決的是哪一層問題？

LightRAG 是一個以 Python 撰寫的 knowledge-graph RAG framework，專案採 MIT License，並提供 lightrag-hku 套件與 lightrag-server 指令。它不是一個新的 LLM，也不是單純的向量資料庫；它處在「文件進入系統後，如何建立可檢索表示，以及如何組合上下文給 LLM」這一層。

傳統 chunk-based RAG 通常是：

1. 把文件切成文字區塊。
2. 將區塊轉成 embeddings，寫入向量儲存。
3. 使用者提問時，以相似度找出幾個區塊。
4. 將區塊交給 LLM 生成答案。

LightRAG 保留這條路徑，同時在索引階段從文字中抽取 entity 與 relation，建立知識圖譜，再對文字區塊、實體與關係建立可檢索表示。因此，查詢時不必永遠只回答「最像問題的幾段文字」，也可以沿著實體關係或跨文件主題尋找上下文。

這個設計特別適合內規、研究論文、法律文件、財務文件、產品手冊等需要跨段落或跨文件理解的場景。不過，知識圖譜並不會自動消除資料品質問題；抽取結果仍取決於文件解析品質、chunking 策略、LLM 能力與提示設計。

核心架構：雙層索引，而不是只加一個 Graph

LightRAG 的關鍵是雙層檢索：

• 向量層：保留文字 chunks，並儲存文字、entities、relationships 的向量表示，負責語意相似度召回。
• 圖譜層：以實體作為節點、以關係作為邊，保存跨文字區塊的結構化連結。
• KV 與文件狀態層：保存原始文件、chunk 結果、LLM response cache、抽取結果與文件處理狀態。

這個分層也反映在儲存設定上。LightRAG 需要四種 storage：

• KV_STORAGE：LLM 快取、文件與抽取結果等鍵值資料。
• VECTOR_STORAGE：文字區塊、實體與關係的向量資料。
• GRAPH_STORAGE：知識圖譜。
• DOC_STATUS_STORAGE：文件清單與處理狀態。

預設儲存適合開發與評估：資料保存在本機持久化檔案與記憶體資料庫中。正式環境則可依需求選擇 PostgreSQL、MongoDB、OpenSearch、Milvus、Qdrant、Neo4j 或 Memgraph 等後端。這是重要的工程邊界：能在本機跑起來，不代表預設 storage 已經適合多人同時寫入或大規模部署。

五種查詢模式，對應五種問題形狀

LightRAG 提供五種 query mode。理解它們，比盲目把所有查詢都切到最複雜的模式更重要。

naive：傳統向量 RAG 基準線

naive 不使用知識圖譜，只從原始文字 chunks 做向量檢索。它適合拿來建立基準線，也適合問題本身只需要一段明確內容的情況。

local：回答特定實體與細節

local 會聚焦在候選 entities 及其直接關聯的屬性與上下文。像是「某產品的 timeout 設定是什麼？」、「合約中的甲方是誰？」這種局部問題，通常可先從 local 開始。

global：回答主題與跨文件關係

global 著重較大範圍的主題、關係鏈與跨文件推理。例如「這批研究論文共同指出哪些風險？」、「公司政策在不同版本之間如何演變？」這類問題，比單純相似度召回更需要整體脈絡。

hybrid：合併 local 與 global

hybrid 同時利用局部實體與全域關係，適合問題同時包含「某個具體對象」以及「它與整體主題的關係」。它通常是實際產品中很有用的折衷選項。

mix：再加上傳統 chunks

mix 將 local、global 與 naive 的結果合併，官方 README 將它列為預設模式。它的上下文通常最完整，但完整不等於永遠最好：上下文變長會增加模型輸入成本，也可能讓答案更容易被低相關內容干擾。建議用真實問題集比較答案正確性、延遲與 token 成本，而不是只看模式名稱。

文件進入系統後，真正發生了什麼？

LightRAG 的品質上限，很大一部分在 indexing 之前就決定了。文件處理大致可拆成以下階段：

1. 解析文件：從 PDF、Word、Markdown 等來源取得文字、表格、圖片與公式。
2. 切分 chunks：依固定長度、遞迴字元、向量語意或段落語意策略分割。
3. 抽取 entities 與 relationships：由 extraction LLM 讀取每個 chunk，產生圖譜節點與邊。
4. 建立 embeddings：為 chunks、entities 與 relationships 建立向量。
5. 寫入 storage：保存原始資料、圖譜、向量與處理狀態。
6. 查詢與生成：先依 query mode 召回上下文，再交由 query LLM 生成答案。

這裡有一個容易被忽略的成本：entity-relation extraction 會在大量 chunks 上重複呼叫 LLM。因此，官方建議把 extraction model 與 query model 分開配置。前者需要速度與成本效率，後者則需要更強的長上下文整理能力；keyword 步驟也應使用低延遲模型。若文件包含圖片、表格或公式，則再配置 VLM 讓多模態內容能參與索引與查詢。

Chunking 不只是切長度

LightRAG 支援四種 chunking 策略：固定長度 F、遞迴字元 R、向量語意 V，以及段落語意 P。其中 P 會盡量讓 chunk 邊界對齊標題、段落與表格，對操作手冊或論文這類結構明顯的文件特別有用。

實務上，應先確認文件類型，再選擇策略：

• 結構規則、段落清楚的文件：優先測試 P。
• 短句或格式混亂的純文字：可先以 R 建立簡單基準。
• 需要依語意切分的長文：比較 V 與 P 的召回品質。
• 參考文獻很多的論文：注意 reference 區塊可能抽出大量低價值 entity，造成索引緩慢或 timeout；P 策略可搭配丟棄 reference 的設定。

最小部署路徑：先用 Server，再決定是否嵌入 SDK

官方 README 明確建議整合到其他專案時優先使用 LightRAG Server 提供的 REST API；SDK 比較適合嵌入式應用、研究與評估。這個建議很合理，因為 Server 已經處理 API、Web UI、文件上傳、查詢與部署設定，能降低應用程式直接耦合核心內部 API 的風險。

依官方安裝方式，最小流程如下：

# 安裝 uv 後，以 tool 方式安裝 API 版 LightRAG
uv tool install "lightrag-hku[api]"

# 準備環境設定檔，填入 LLM、embedding 與 storage 設定
cp env.example .env

# 確認安全設定後啟動服務
lightrag-server

也可以從 source checkout 使用 Docker Compose：

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env
# 編輯 .env 後再啟動
docker compose up

暴露到網路前，先處理 authentication

官方設定特別提醒：Server 預設綁定 0.0.0.0，如果沒有設定 LIGHTRAG_API_KEY，或沒有用 AUTH_ACCOUNTS 搭配 TOKEN_SECRET 啟用驗證，端點可能對外公開。正式部署至少要做到以下幾點：

• 本機開發時綁定 127.0.0.1，不必要時不要暴露所有介面。
• 對外服務前設定 API key 或帳號驗證。
• 確認 Ollama-compatible /api/* 路由的白名單策略，不要只驗證 Web UI。
• 將 .env 放進 secret management，不要提交到 Git。
• 以 reverse proxy、TLS、網路 ACL 與 rate limit 補上應用層之外的防護。

直接使用 Python SDK：適合研究與客製化流程

若你需要嵌入自己的 ingestion pipeline，官方範例使用 LightRAG 與 QueryParam：

import asyncio
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed

WORKING_DIR = "./rag_storage"

async def main():
    rag = LightRAG(
        working_dir=WORKING_DIR,
        embedding_func=openai_embed,
        llm_model_func=gpt_4o_mini_complete,
    )
    await rag.initialize_storages()

    await rag.ainsert("這是一段要建立索引的文件內容。")

    answer = await rag.aquery(
        "文件的主要主題是什麼？",
        param=QueryParam(mode="mix"),
    )
    print(answer)
    await rag.finalize_storages()

asyncio.run(main())

這段程式展示的是 API 形狀，不是完整的 production 設定。實際使用時仍要配置模型憑證、embedding、timeout、並行度與 storage backend；也應使用 try/finally 確保發生例外時仍會呼叫 finalize_storages()。如果只想把 RAG 能力接到現有 Web service，REST API 通常會比直接管理 SDK lifecycle 更容易維護。

成本、延遲與一致性：部署前必須做的三個決策

1. 把索引成本與查詢成本分開量測

索引階段會反覆做 parsing、chunking、entity-relation extraction 與 embedding；查詢階段則有 keyword、召回、rerank 與 final generation。兩者的瓶頸不同，不能只用單次問答延遲評估系統。

LightRAG 提供 MAX_ASYNC_LLM、EXTRACT_ASYNC_LLM、MAX_PARALLEL_INSERT、EMBEDDING_FUNC_MAX_ASYNC 與 EMBEDDING_BATCH_NUM 等設定來調整並行度。提高並行度可能縮短索引時間，但也會增加 API 限流、記憶體與儲存後端壓力。應從小批量文件開始，逐步提高並行度，並記錄失敗重試與實際 token 成本。

2. Embedding model 不是隨時可替換的設定

官方文件提醒，embedding model 必須在 indexing 前決定，查詢時也要使用相同模型。若更換模型，通常必須重新計算 chunks、entities 與 relationships 的 embeddings；某些後端還需要重新建立向量欄位維度。換句話說，embedding model 應被視為資料 schema 的一部分，而不是部署時隨手可改的環境變數。

3. Rerank 是品質與延遲的交換

Rerank 能改善召回內容的排序，但官方也指出它通常會帶來額外延遲。若產品對即時性敏感，可先以離線評估確認 rerank 的實際收益，再決定是否啟用；如果文件集合大、查詢又複雜，將 rerank model 放在本地或專用服務上，也能降低外部 API 往返的影響。

LightRAG 的限制：什麼情況不該直接採用？

LightRAG 很適合拿來建立圖譜輔助的 RAG，但不代表每個問答系統都需要它。

• 問題只對應一小段明確文字：傳統向量 RAG 可能更簡單、便宜、容易除錯。
• 文件品質很差：OCR、表格解析或標題層級錯誤時，圖譜會把錯誤結構化，反而增加排查成本。
• 沒有評估集：沒有可重複的問題與期望答案，就很難知道 naive、hybrid 與 mix 是否真的改善品質。
• 只想快速嵌入一個小功能：先用 Server 或現有 RAG 元件驗證需求，再決定是否承擔圖譜索引與 storage 維護成本。
• 要求強一致的即時資料：文件更新、刪除與抽取是非同步且有成本的流程，必須設計文件狀態、重試、刪除與重新索引策略。

另外，官方 README 的 benchmark 表格是專案自己報告的評估結果，包含不同資料領域與 RAG 基線；讀者在採用前仍應使用自己的語料、語言、模型與查詢集重新驗證，不應直接把表格百分比當成所有場景的保證。

建議的導入順序

如果要把 LightRAG 放進實際 AI 應用，我會採用以下順序：

1. 先用 naive 模式建立品質與成本基準線。
2. 選一小批代表性文件，確認 parser 與 chunking 不會破壞標題、表格及引用。
3. 用 local、global、hybrid、mix 建立離線評估矩陣。
4. 將 extraction、keyword、query 與 VLM 模型分開量測。
5. 確認 embedding model、維度與 storage schema 後，再導入正式資料。
6. 先以 REST API 整合應用程式；只有確定需要核心級客製化時，才直接採用 SDK。
7. 上線前補齊 authentication、TLS、備份、刪除與重新索引流程。

結語

LightRAG 的價值不只在於「把 Graph 加進 RAG」，而在於它把不同檢索尺度放進同一個可配置的工程流程：naive 處理文字相似度，local 對應實體細節，global 處理跨文件關係，hybrid 與 mix 則在完整度與成本之間取捨。對需要跨文件理解、結構化關係與多模態文件處理的團隊而言，它是一個值得實驗的開源框架。

但正確的導入方式不是直接把所有文件丟進 mix。先建立基準線、確認 parsing 與 chunking、量測索引成本，再選擇 query mode 與 storage backend，才能知道知識圖譜真正帶來的是答案品質，還是只是額外的系統複雜度。

延伸閱讀與來源

• LightRAG GitHub Repository
• LightRAG README：查詢模式、設定與安裝
• LightRAG API Server 文件
• File Processing Pipeline 文件
• Programing With Core 文件
• 論文：LightRAG: Simple and Fast Retrieval-Augmented Generation