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

LightRAG 入门指南手把手教你用图增强 RAG 系统一、LightRAG 是什么二、核心原理解析2.1 双层索引架构2.2 实体与关系抽取2.3 四种检索模式三、快速安装与配置3.1 安装3.2 使用 OpenAI API 配置国际版3.3 国内用户推荐方案四、完整使用教程4.1 文档插入4.2 四种模式查询对比4.3 异步查询生产环境推荐五、进阶技巧5.1 批量文档插入5.2 增量更新索引5.3 可视化知识图谱5.4 调整实体抽取粒度六、LightRAG vs 传统 RAG vs GraphRAG七、总结与推荐场景推荐使用 LightRAG 的场景暂时不适合的场景资源汇总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 提供了四种查询模式适合不同类型的问题模式检索策略适合问题类型naive纯向量相似度检索简单事实查找local以实体为中心的局部图谱检索特定人物/概念的详细信息global全图关系主题检索跨实体的宏观主题分析hybrid向量 局部 全局融合复杂推理、综合分析推荐简单理解问某个人做了什么 →local效果好问整篇文档的核心主题是什么 →global更合适不确定用哪个用hybrid准没错三、快速安装与配置3.1 安装pipinstalllightrag-hku安装完成后核心依赖会自动拉取包括图数据库客户端和 Embedding 工具。3.2 使用 OpenAI API 配置国际版importosfromlightragimportLightRAG,QueryParamfromlightrag.llmimportgpt_4o_mini_complete# 设置工作目录索引和图谱数据都存在这里WORKING_DIR./my_rag_projectos.makedirs(WORKING_DIR,exist_okTrue)# 设置 OpenAI API Keyos.environ[OPENAI_API_KEY]your-api-key-here# 初始化 LightRAGragLightRAG(working_dirWORKING_DIR,llm_model_funcgpt_4o_mini_complete# 也可以换成 gpt_4o_complete)3.3 国内用户推荐方案如果你在国内直接用 OpenAI API 可能不方便有两条路可以走方案 A使用 Ollama 本地模型完全免费不需要联网先安装 Ollama 并拉取模型ollama pull qwen2.5:7b ollama pull nomic-embed-text然后配置 LightRAGfromlightragimportLightRAG,QueryParamfromlightrag.llmimportollama_model_complete,ollama_embeddingfromlightrag.utilsimportEmbeddingFunc WORKING_DIR./my_rag_projectragLightRAG(working_dirWORKING_DIR,llm_model_funcollama_model_complete,llm_model_nameqwen2.5:7b,# 使用本地 Qwen 模型llm_model_kwargs{host:http://localhost:11434,# Ollama 默认地址options:{num_ctx:32768},},embedding_funcEmbeddingFunc(embedding_dim768,max_token_size8192,funclambdatexts:ollama_embedding(texts,embed_modelnomic-embed-text,hosthttp://localhost:11434),),)方案 B使用 DeepSeek API低成本云端方案DeepSeek 兼容 OpenAI 的 API 格式配置非常简单importosfromlightragimportLightRAG,QueryParamfromlightrag.llmimportopenai_complete_if_cache,openai_embeddingfromlightrag.utilsimportEmbeddingFunc os.environ[DEEPSEEK_API_KEY]your-deepseek-keyasyncdefdeepseek_complete(prompt,system_promptNone,history_messages[],**kwargs):returnawaitopenai_complete_if_cache(deepseek-chat,prompt,system_promptsystem_prompt,history_messageshistory_messages,api_keyos.environ[DEEPSEEK_API_KEY],base_urlhttps://api.deepseek.com/v1,**kwargs,)ragLightRAG(working_dirWORKING_DIR,llm_model_funcdeepseek_complete,embedding_funcEmbeddingFunc(embedding_dim1536,max_token_size8192,funclambdatexts:openai_embedding(texts,modeltext-embedding-3-small,api_keyos.environ[OPENAI_API_KEY],),),)注意DeepSeek 目前没有官方的 Embedding 接口建议 Embedding 部分使用nomic-embed-textOllama或text-embedding-3-smallOpenAI。两者混用完全没问题。四、完整使用教程下面用《双城记》A Tale of Two Cities作为示例文本带你走完完整流程。这也是 LightRAG 官方 demo 使用的数据集非常适合展示图谱的关系理解能力。4.1 文档插入withopen(./book.txt,r,encodingutf-8)asf:contentf.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?”故事的主要主题是什么questionWhat are the main themes of the story?# Naive 模式 —— 纯向量检索print(*50)print([Naive 模式])print(rag.query(question,paramQueryParam(modenaive)))# Local 模式 —— 实体中心检索print(*50)print([Local 模式])print(rag.query(question,paramQueryParam(modelocal)))# Global 模式 —— 全局关系检索print(*50)print([Global 模式])print(rag.query(question,paramQueryParam(modeglobal)))# Hybrid 模式 —— 混合检索推荐print(*50)print([Hybrid 模式])print(rag.query(question,paramQueryParam(modehybrid)))实际输出对比简化版模式回答特点示例输出摘要naive引用了几段原文但缺乏整体分析“The story mentions resurrection, sacrifice, and the French Revolution…”local集中在具体人物的主题体现上“Sydney Carton’s arc represents self-sacrifice. Lucie Manette symbolizes…”global从关系网络中提炼宏观主题“The overarching themes are: 1) Resurrection and redemption… 2) The cycle of violence…”hybrid结合局部细节与全局脉络最为完整综合了以上所有角度给出了有逻辑层次的分析可以明显看出对于主题分析这类需要全局理解的问题global和hybrid的回答质量远超naive。4.3 异步查询生产环境推荐importasyncioasyncdefmain():resultawaitrag.aquery(Describe the relationship between Sydney Carton and Charles Darnay.,paramQueryParam(modehybrid))print(result)asyncio.run(main())五、进阶技巧5.1 批量文档插入importos docs[]forfilenameinos.listdir(./documents):iffilename.endswith(.txt):withopen(f./documents/{filename},r,encodingutf-8)asf:docs.append(f.read())# 批量插入内部会并发处理rag.insert(docs)5.2 增量更新索引LightRAG 天然支持增量更新——直接 insert 新文档即可已有的图谱不会被覆盖新的实体和关系会被合并进去# 插入新文档自动合并到现有知识图谱withopen(./new_document.txt,r,encodingutf-8)asf:rag.insert(f.read())5.3 可视化知识图谱LightRAG 会把知识图谱存为标准的.graphml格式可以用多种工具可视化方法 A使用 Gephi免费桌面软件直接打开graph_chunk_entity_relation.graphml文件即可看到实体关系网络图。方法 B使用 Python networkximportnetworkxasnximportmatplotlib.pyplotasplt Gnx.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_labelsTrue,node_size50,font_size6)plt.savefig(knowledge_graph.png,dpi150)plt.show()方法 C接入 Neo4j生产级图数据库ragLightRAG(working_dirWORKING_DIR,llm_model_funcgpt_4o_mini_complete,graph_storageNeo4JStorage,addon_params{neo4j_url:bolt://localhost:7687,neo4j_auth:(neo4j,your_password),})5.4 调整实体抽取粒度ragLightRAG(working_dirWORKING_DIR,llm_model_funcgpt_4o_mini_complete,addon_params{entity_types:[organization,person,location,concept,event],})作者提示对于专业领域文档如法律、医疗建议自定义entity_types加入领域专属实体类型如legal_term、disease能显著提升图谱质量。六、LightRAG vs 传统 RAG vs GraphRAG维度传统 RAGGraphRAG微软LightRAG检索方式向量相似度图谱社区遍历向量 图谱融合全局理解能力弱强强局部细节检索强中强索引构建速度快很慢较快推理/查询速度快慢快API 调用成本低高中部署复杂度低高低本地模型支持支持有限原生支持适用场景FAQ、片段检索超大规模复杂知识库通用场景强烈推荐结论如果你是个人开发者或中小团队LightRAG 是目前性价比最高的图增强 RAG 方案。GraphRAG 更适合有充足预算和算力的大型企业知识库项目。七、总结与推荐场景推荐使用 LightRAG 的场景法律文书分析合同条款之间的引用关系、义务主体的关联梳理医疗文献研究疾病-症状-药物之间的关系图谱构建技术文档问答API 文档、架构文档中跨模块的概念关联小说/剧本分析人物关系、情节脉络、主题提炼企业知识库员工手册、流程文档、历史决策记录的智能检索研究论文助手多篇论文的观点对比与关联分析暂时不适合的场景实时数据图谱构建有一定延迟不适合需要秒级更新的实时信息流结构化数据库查询如果你的数据本来就是表格形式Text-to-SQL 方案更合适超大规模文档库亿级此量级建议考虑专业的图数据库 企业级 RAG 架构资源汇总GitHub 项目主页https://github.com/HKUDS/LightRAG官方论文arXivLightRAG: Simple and Fast Retrieval-Augmented Generation官方示例代码https://github.com/HKUDS/LightRAG/tree/main/examplesLightRAG 代表了 RAG 技术演进的一个重要方向——从找段落到懂关系从碎片化匹配到结构化理解。如果你在做任何涉及复杂知识关联的 AI 应用强烈建议把 LightRAG 纳入你的技术选型清单。动手跑一遍你会发现图增强的力量。 博客主页https://xiaoy.blog.csdn.net 本文由呆呆敲代码的小Y原创 学习专栏推荐Unity系统学习专栏 游戏制作专栏推荐游戏制作Unity实战100例专栏推荐Unity 实战100例 教程 欢迎点赞 收藏 ⭐留言 如有错误敬请指正 未来很长值得我们全力奔赴更美好的生活✨------------------❤️分割线❤️-------------------------资料白嫖技术互助学习路线指引点击解锁知识定位人群定位 Unity系统学习专栏入门级本专栏从Unity入门开始学习快速达到Unity的入门水平 Unity实战类项目进阶级计划制作Unity的 100个实战案例助你进入Unity世界争取做最全的Unity原创博客大全。❤️ 游戏制作专栏难度偏高分享学习一些Unity成品的游戏Demo和其他语言的小游戏 游戏爱好者万人社区互助/吹水数万人游戏爱好者社区聊天互助白嫖奖品 Unity100个实用技能Unity查漏补缺针对一些Unity中经常用到的一些小知识和技能进行学习介绍核心目的就是让我们能够快速学习Unity的知识以达到查漏补缺