LightRAG 跟普通 RAG 的分水岭就一句话:它把文档里的实体关系抽成一张图谱,查询时图谱和向量两条路一起召回。纯向量只记得"这段话跟问题像不像",图谱还记"这个实体跟那个实体是什么关系"。这篇记我装它、跑它的过程,重点讲这三条路各自查的是什么。

我先给判断。要不要上 LightRAG,看你的问题是不是跨文档、要靠关系推理的。法律、金融、供应链这种"谁持有谁、谁违约谁"的场景,图谱多记住的那层关系是真的值钱。纯事实问答、单文档检索,纯向量已经够。别为它折腾。

装包,四个 LLM 角色是前提

我在本机(macOS arm64,Python 3.13.12)装了 1 遍 lightrag-hku,挂清华镜像,20 秒装完,版本 1.5.7。装完先别急着写代码。LightRAG 跟别的 RAG 不一样,它要四个 LLM 角色一起干活:extract 做实体关系抽取,keyword 抽关键词,query 生成答案,vlm 处理图片。这四个角色都得有模型,一个都不能缺。

我打开源码核了 1 遍。默认的 gpt_4o_mini_complete 走 OpenAI,openai_embed 走 text-embedding-3-small,1536 维。官方 quickstart 用的就是这个。这意味着你要直接跑,得先有 OPENAI_API_KEY。我没有,所以换 mock 函数跑,把整条链路先验证通。没 key 就说没 key,这是诚实的选择。

两个坑,初始化存储和 embedding 返回值

我按直觉直接 LightRAG(...) 然后 ainsert,第一下就炸了。报错原文是 PipelineNotInitializedError: Pipeline namespace 'pipeline_status' not found。我翻报错尾巴,它自己给了答案:1.5.x 起要先调 await rag.initialize_storages()。这是个 API 变化,旧教程里没这一行。这条我踩了,记下来。

from lightrag import LightRAG, QueryParam
from lightrag.utils import EmbeddingFunc

rag = LightRAG(working_dir="./wd", llm_model_func=mock_llm,
               embedding_func=EmbeddingFunc(embedding_dim=8, max_token_size=500, func=mock_embed))
await rag.initialize_storages()   # 1.5.x 必须有这一行,否则 ainsert 报 PipelineNotInitializedError
await rag.ainsert("Alice 写 Go 服务。")

补上 initialize_storages 再跑,第二个坑来了。我的 mock embedding 返回的是 Python list,它直接抛 AttributeError: 'list' object has no attribute 'size'。源码里 utils.py 那行写死了 total_elements = result.size,它要的是 numpy 数组。改成 np.array(...) 才过。这条说明 embedding 函数的返回值类型是硬约束,别想当然返回 list。

实体抽取还有个格式要求,我一起记在这。默认 prompt 要的是 ` 分隔符格式,一行一个实体,先实体后关系,不是 JSON。我第一版 mock 返回 JSON,它警告Complete delimiter can not be found in extraction result`。改成下面这个形状才认:

entityAlicePersona backend engineer
relationAliceBobreports toAlice reports to Bob

双存储,文件里看得见

跑通之后,我打开 working_dir 数了 1 遍文件,双路检索这件事就摊开了。图谱存成 graph_chunk_entity_relation.graphml,310 字节;向量库存成三个 json,vdb_chunks.json 1168 字节、vdb_entities.json 46 字节、vdb_relationships.json 46 字节。图谱和向量是两套独立的存储,各存各的。

这几个文件名就是证据。text chunks 进向量库,实体进图谱也进向量库,关系进图谱也进向量库。所谓"双路",不是说一次检索跑两个算法,是它建索引的时候就建了两份,查询时各查各的、再合并。

五种查询模式,查的是不同东西

LightRAG 的查询有五个模式,这是它跟纯向量最实的分界。我逐个跑了 1 遍 naive、local、global、mix,把每个模式返回的 context 前 80 个字符抄了下来看差异。naive 模式走纯向量,返回的开头是 Document Chunks,就是把最像的原文段落捞出来,637 字符。mix 模式返回的开头是 Knowledge Graph Data,后面跟关系数据,735 字符。

r = await rag.aquery("谁在维护搜索服务?", param=QueryParam(mode="naive", only_need_context=True))

naive 根本不知道实体之间有边,它只能比相似度。local 模式捞具体实体和它直接相连的关系,global 模式捞跨越多个实体的关系链,mix 三样都合并。我的 mock LLM 抽的实体是固定的 Alice 和 Bob,所以 local 和 global 查到的是这两条,跟真实模型的抽取质量无关。但"各查各的存储"这个结构是真实跑出来的。别把我 mock 的实体当成 LightRAG 的真实抽取能力。

什么时候该上它

值不值得上,我给个分界。你的查询要回答"这两个实体怎么连上的""这件事影响了哪些下游",LightRAG 的 global 模式能捞关系链,纯向量做不到。你要是做知识库问答、单文档事实检索,naive 模式跟普通 RAG 一样,图谱那套对你没增益,还白多一份抽取成本。

还有个成本判断别忽略。实体关系抽取是每个 chunk 一次 LLM 调用,README 官方标的默认模型是 gpt-6-luna 这种 reasoning 模型,官方还专门建议把 reasoning effort 设成 low,不然抽取慢得肉疼。换句话说,图谱那一份索引是拿算力换来的。数据量小、关系简单的时候,这个账不划算。

一句话。LightRAG 多记住的是实体之间的边,不是更多的事实。你的问题靠关系推理,才值得为这些边付抽取的账。