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. 把文件切成文字区块。

1. 将区块转成 embeddings，写入向量储存。

1. 使用者提问时，以相似度找出几个区块。

1. 将区块交给 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 等来源取得文字、表格、图片与公式。

1. 切分 chunks：依固定长度、递回字元、向量语意或段落语意策略分割。

1. 抽取 entities 与 relationships：由 extraction LLM 读取每个 chunk，产生图谱节点与边。

1. 建立 embeddings：为 chunks、entities 与 relationships 建立向量。

1. 写入 storage：保存原始资料、图谱、向量与处理状态。

1. 查询与生成：先依 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 模式建立品质与成本基准线。

1. 选一小批代表性文件，确认 parser 与 chunking 不会破坏标题、表格及引用。

1. 用 local、global、hybrid、mix 建立离线评估矩阵。

1. 将 extraction、keyword、query 与 VLM 模型分开量测。

1. 确认 embedding model、维度与 storage schema 后，再导入正式资料。

1. 先以 REST API 整合应用程式；只有确定需要核心级客制化时，才直接采用 SDK。

1. 上线前补齐 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