LightRAG 入门指南：手把手教你用图增强 RAG 系统

LightRAG 入门指南：手把手教你用图增强 RAG 系统

你有没有遇到过这样的问题：明明把文档喂给了 RAG 系统，但问一个需要"全局理解"的问题，比如"这份合同的整体风险点在哪里"，得到的回答却是东一块西一块，像是从文档里随机摘出来的句子拼凑的？

这就是传统 RAG 的核心痛点——它本质上是"碎片化检索"，靠的是向量相似度匹配，擅长找局部相关段落，却对文档的整体结构和实体关系一无所知。

LightRAG就是为了解决这个问题而生的。它把知识图谱（Knowledge Graph）引入 RAG 架构，让系统不仅能"找段落"，还能"理关系"、“懂全局”。

一、LightRAG 是什么？

LightRAG是香港大学于 2024 年发布的一个开源 RAG 框架，核心思想是将知识图谱与向量检索结合，构建一套双层索引的检索增强生成系统。

项目一经发布便迅速走红，截至 2025 年初 GitHub Star 数已突破10,000+，是目前图增强 RAG 领域最受关注的开源项目之一。

GitHub 地址：https://github.com/HKUDS/LightRAG

你可能听说过微软的GraphRAG，同样是图+RAG 的思路，但两者定位差异明显：

• GraphRAG功能强大，但构建索引耗时极长（几百页文档可能要跑几十分钟），API 调用成本高，部署复杂。
• LightRAG更轻量，索引速度更快，架构更简洁，个人开发者和小团队可以直接上手，同时也支持本地模型，对国内用户更友好。

作者提示：LightRAG 的 “Light” 不是说功能弱，而是说它在保留图谱理解能力的前提下，把工程复杂度降到了最低。

二、核心原理解析

在动手之前，花 5 分钟理解 LightRAG 的工作原理，会让你在后续使用中少走很多弯路。

2.1 双层索引架构

LightRAG 在文档插入时，会同时构建两种索引：

原始文档 │ ├──► [LLM 抽取] ──► 实体（Entity）+ 关系（Relation）──► 图索引（Graph Index） │ └──► [Embedding] ──► 语义向量 ──► 向量索引（Vector Index）

• 向量索引：和传统 RAG 一样，把文本切块后做 Embedding，用于语义相似度检索。
• 图索引：由 LLM 从文本中抽取实体（人、地点、概念、组织等）和它们之间的关系，构建成一张知识图谱，存储在本地图数据库中。

2.2 实体与关系抽取

这是 LightRAG 的核心步骤，也是它比传统 RAG "聪明"的关键。

举个例子，对于这段文本：

“查尔斯·达内是一位法国贵族，他后来放弃了头衔，与露西·曼内特结婚。”

LightRAG 会抽取出：

• 实体：查尔斯·达内（人物）、法国贵族（身份）、露西·曼内特（人物）
• 关系：查尔斯·达内 --[放弃]–> 贵族头衔；查尔斯·达内 --[结婚于]–> 露西·曼内特

这些关系最终构成图谱，让系统在检索时能够沿着关系链条进行推理，而不只是找"语义相似的片段"。

2.3 四种检索模式

LightRAG 提供了四种查询模式，适合不同类型的问题：

简单理解：

• 问"某个人做了什么" →local效果好
• 问"整篇文档的核心主题是什么" →global更合适
• 不确定用哪个？用hybrid准没错

三、快速安装与配置

3.1 安装

pipinstalllightrag-hku

安装完成后，核心依赖会自动拉取，包括图数据库客户端和 Embedding 工具。

3.2 使用 OpenAI API 配置（国际版）

importosfromlightragimportLightRAG,QueryParamfromlightrag.llmimportgpt_4o_mini_complete# 设置工作目录（索引和图谱数据都存在这里）WORKING_DIR="./my_rag_project"os.makedirs(WORKING_DIR,exist_ok=True)# 设置 OpenAI API Keyos.environ["OPENAI_API_KEY"]="your-api-key-here"# 初始化 LightRAGrag=LightRAG(working_dir=WORKING_DIR,llm_model_func=gpt_4o_mini_complete# 也可以换成 gpt_4o_complete)

3.3 国内用户推荐方案

如果你在国内，直接用 OpenAI API 可能不方便，有两条路可以走：

方案 A：使用 Ollama 本地模型（完全免费，不需要联网）

先安装 Ollama 并拉取模型：

ollama pull qwen2.5:7b ollama pull nomic-embed-text

然后配置 LightRAG：

fromlightragimportLightRAG,QueryParamfromlightrag.llmimportollama_model_complete,ollama_embeddingfromlightrag.utilsimportEmbeddingFunc WORKING_DIR="./my_rag_project"rag=LightRAG(working_dir=WORKING_DIR,llm_model_func=ollama_model_complete,llm_model_name="qwen2.5:7b",# 使用本地 Qwen 模型llm_model_kwargs={"host":"http://localhost:11434",# Ollama 默认地址"options":{"num_ctx":32768},},embedding_func=EmbeddingFunc(embedding_dim=768,max_token_size=8192,func=lambdatexts:ollama_embedding(texts,embed_model="nomic-embed-text",host="http://localhost:11434"),),)

方案 B：使用 DeepSeek API（低成本云端方案）

DeepSeek 兼容 OpenAI 的 API 格式，配置非常简单：

importosfromlightragimportLightRAG,QueryParamfromlightrag.llmimportopenai_complete_if_cache,openai_embeddingfromlightrag.utilsimportEmbeddingFunc os.environ["DEEPSEEK_API_KEY"]="your-deepseek-key"asyncdefdeepseek_complete(prompt,system_prompt=None,history_messages=[],**kwargs):returnawaitopenai_complete_if_cache("deepseek-chat",prompt,system_prompt=system_prompt,history_messages=history_messages,api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com/v1",**kwargs,)rag=LightRAG(working_dir=WORKING_DIR,llm_model_func=deepseek_complete,embedding_func=EmbeddingFunc(embedding_dim=1536,max_token_size=8192,func=lambdatexts:openai_embedding(texts,model="text-embedding-3-small",api_key=os.environ["OPENAI_API_KEY"],),),)

注意：DeepSeek 目前没有官方的 Embedding 接口，建议 Embedding 部分使用nomic-embed-text（Ollama）或text-embedding-3-small（OpenAI）。两者混用完全没问题。

四、完整使用教程

下面用《双城记》（A Tale of Two Cities）作为示例文本，带你走完完整流程。这也是 LightRAG 官方 demo 使用的数据集，非常适合展示图谱的关系理解能力。

4.1 文档插入

withopen("./book.txt","r",encoding="utf-8")asf:content=f.read()# 插入文档，LightRAG 会自动完成：# 1. 文本切块# 2. 实体/关系抽取（LLM 驱动）# 3. 构建向量索引和图索引rag.insert(content)print("文档插入完成！")

插入过程中，你会看到控制台输出 LLM 正在逐块处理文本，抽取实体和关系。对于一部完整的小说，这个过程可能需要几分钟（取决于模型速度和文档大小）。

工作目录下会生成以下文件：

my_rag_project/ ├── graph_chunk_entity_relation.graphml # 知识图谱文件 ├── kv_store_full_docs.json # 原始文档存储 ├── kv_store_text_chunks.json # 切块后的文本 ├── kv_store_llm_response_cache.json # LLM 响应缓存（节省 API 费用） └── vdb_entities.json # 向量索引

4.2 四种模式查询对比

我们用同一个问题来对比四种模式的差异：

问题：“What are the main themes of the story?”（故事的主要主题是什么？）

question="What are the main themes of the story?"# Naive 模式 —— 纯向量检索print("="*50)print("[Naive 模式]")print(rag.query(question,param=QueryParam(mode="naive")))# Local 模式 —— 实体中心检索print("="*50)print("[Local 模式]")print(rag.query(question,param=QueryParam(mode="local")))# Global 模式 —— 全局关系检索print("="*50)print("[Global 模式]")print(rag.query(question,param=QueryParam(mode="global")))# Hybrid 模式 —— 混合检索（推荐）print("="*50)print("[Hybrid 模式]")print(rag.query(question,param=QueryParam(mode="hybrid")))

实际输出对比（简化版）：

可以明显看出：对于"主题分析"这类需要全局理解的问题，global和hybrid的回答质量远超naive。

4.3 异步查询（生产环境推荐）

importasyncioasyncdefmain():result=awaitrag.aquery("Describe the relationship between Sydney Carton and Charles Darnay.",param=QueryParam(mode="hybrid"))print(result)asyncio.run(main())

五、进阶技巧

5.1 批量文档插入

importos docs=[]forfilenameinos.listdir("./documents"):iffilename.endswith(".txt"):withopen(f"./documents/{filename}","r",encoding="utf-8")asf:docs.append(f.read())# 批量插入（内部会并发处理）rag.insert(docs)

5.2 增量更新索引

LightRAG 天然支持增量更新——直接 insert 新文档即可，已有的图谱不会被覆盖，新的实体和关系会被合并进去：

# 插入新文档，自动合并到现有知识图谱withopen("./new_document.txt","r",encoding="utf-8")asf:rag.insert(f.read())

5.3 可视化知识图谱

LightRAG 会把知识图谱存为标准的.graphml格式，可以用多种工具可视化：

方法 A：使用 Gephi（免费桌面软件）
直接打开graph_chunk_entity_relation.graphml文件，即可看到实体关系网络图。

方法 B：使用 Python networkx

importnetworkxasnximportmatplotlib.pyplotasplt G=nx.read_graphml("./my_rag_project/graph_chunk_entity_relation.graphml")print(f"节点数（实体）:{G.number_of_nodes()}")print(f"边数（关系）:{G.number_of_edges()}")plt.figure(figsize=(12,8))nx.draw_spring(G,with_labels=True,node_size=50,font_size=6)plt.savefig("knowledge_graph.png",dpi=150)plt.show()

方法 C：接入 Neo4j（生产级图数据库）

rag=LightRAG(working_dir=WORKING_DIR,llm_model_func=gpt_4o_mini_complete,graph_storage="Neo4JStorage",addon_params={"neo4j_url":"bolt://localhost:7687","neo4j_auth":("neo4j","your_password"),})

5.4 调整实体抽取粒度

rag=LightRAG(working_dir=WORKING_DIR,llm_model_func=gpt_4o_mini_complete,addon_params={"entity_types":["organization","person","location","concept","event"],})

作者提示：对于专业领域文档（如法律、医疗），建议自定义entity_types，加入领域专属实体类型（如legal_term、disease），能显著提升图谱质量。

六、LightRAG vs 传统 RAG vs GraphRAG

结论：如果你是个人开发者或中小团队，LightRAG 是目前性价比最高的图增强 RAG 方案。GraphRAG 更适合有充足预算和算力的大型企业知识库项目。

七、总结与推荐场景

推荐使用 LightRAG 的场景

• 法律文书分析：合同条款之间的引用关系、义务主体的关联梳理
• 医疗文献研究：疾病-症状-药物之间的关系图谱构建
• 技术文档问答：API 文档、架构文档中跨模块的概念关联
• 小说/剧本分析：人物关系、情节脉络、主题提炼
• 企业知识库：员工手册、流程文档、历史决策记录的智能检索
• 研究论文助手：多篇论文的观点对比与关联分析

暂时不适合的场景

• 实时数据：图谱构建有一定延迟，不适合需要秒级更新的实时信息流
• 结构化数据库查询：如果你的数据本来就是表格形式，Text-to-SQL 方案更合适
• 超大规模文档库（亿级）：此量级建议考虑专业的图数据库 + 企业级 RAG 架构

资源汇总

• GitHub 项目主页：https://github.com/HKUDS/LightRAG
• 官方论文（arXiv）：LightRAG: Simple and Fast Retrieval-Augmented Generation
• 官方示例代码：https://github.com/HKUDS/LightRAG/tree/main/examples

LightRAG 代表了 RAG 技术演进的一个重要方向——从"找段落"到"懂关系"，从"碎片化匹配"到"结构化理解"。如果你在做任何涉及复杂知识关联的 AI 应用，强烈建议把 LightRAG 纳入你的技术选型清单。

动手跑一遍，你会发现图增强的力量。

• 🎬 博客主页：https://xiaoy.blog.csdn.net

• 🎥 本文由呆呆敲代码的小Y原创 🙉

• 🎄 学习专栏推荐：Unity系统学习专栏

• 🌲 游戏制作专栏推荐：游戏制作

• 🌲Unity实战100例专栏推荐：Unity 实战100例 教程

• 🏅 欢迎点赞 👍 收藏 ⭐留言 📝 如有错误敬请指正！

• 📆 未来很长，值得我们全力奔赴更美好的生活✨

• ------------------❤️分割线❤️-------------------------

资料白嫖，技术互助