LightRAG：用知识图谱让 RAG 兼顾局部细节与全局主题
香港大学开源的 Python RAG 框架，用知识图谱组织文档，同时提供 Python 与 CLI 接口，为私有文档搭建可查询知识库，MIT 许可，GitHub 星标逾四万。
检索增强生成的老问题不是「找不到资料」，而是找到了却拼不成一个完整的答案。传统 RAG 把文档切成平铺的文本块，用向量相似度召回若干片段丢给大模型——问一个具体事实够用，问「这批文档里反复出现的几个概念之间是什么关系」就开始露馅：片段彼此割裂，模型只能看到局部，看不到全局。
LightRAG 的切入点就在这里：先把文档索引成一张知识图谱，再在查询时同时走「局部」和「全局」两条检索路径。这个思路来自香港大学的数据智能实验室，代码在 HKUDS/LightRAG，论文挂在 arXiv:2410.05779。仓库 2024 年 10 月创建，至今星标 40190、fork 5704，MIT 许可，主语言 Python。
一张图看懂它凭什么「兼顾」
README 里给出的两张流程图（索引流程图、检索与查询流程图）揭示了核心机制：LightRAG 不是「存向量 + 检索向量」，而是把文档拆解成实体与关系，落进图结构里。索引阶段，LLM 从每个文本块中抽取实体和关系，形成节点与边；查询阶段，系统同时利用图谱的低层（局部）邻域和高层（全局）主题来构造上下文。
这个双层设计是它区别于普通向量 RAG 的关键：
- 局部层：围绕具体实体展开，回答「某个东西是什么、和谁有关」这类细节问题。
- 全局层：从图谱的整体结构里提炼主题与跨文档关联，回答「这些材料整体在讲什么、几条线索怎么交汇」。
- 混合查询：README 的更新日志里明确写到，2025 年 8 月加入 Reranker 后，混合查询成为默认查询模式，用于提升混合型问题的表现。
换句话说，LightRAG 想解决的是「碎片化答案抓不住复杂相互依赖」这个痛点——这正是论文摘要里点名的现有 RAG 局限。
架构拆解：四类存储 + 多层角色
把 README 的功能描述归纳起来，LightRAG 的运行结构可以分成几层：
| 层 | 组成 | 职责 |
|---|---|---|
| 文档接入层 | MinerU / Docling 服务、RAG-Anything 集成、Smart Heading | 解析 PDF、图片、Office 文档、表格、公式等多模态内容，识别标题结构 |
| 文本处理层 | 四种分块策略：Fix、Recursive、Vector、Paragraph | 把长文档切成适合抽取的文本块 |
| 图谱构建层 | EXTRACT 角色的 LLM、实体/关系抽取 | 从文本块中抽取实体与关系，写入知识图谱 |
| 存储层 | 四类存储后端：图存储、向量存储、KV 存储、文档状态存储 | 分别承载图结构、向量检索、键值缓存与文档状态；支持 Neo4J、MongoDB、PostgreSQL、OpenSearch 等一体化方案 |
| 查询层 | QUERY / KEYWORDS 角色的 LLM、Reranker | 走局部/全局/混合检索，重排后生成答案，并返回检索到的上下文 |
| 服务与观测层 | lightrag-server、WebUI、RAGAS 评测、Langfuse 追踪 | 对外提供 API 与可视化界面，支持评测与链路追踪 |
几个值得单独说的设计点：
角色化 LLM 配置。2026 年 5 月的更新引入了 4 个独立角色：EXTRACT、QUERY、KEYWORDS、VLM，每个角色可以配不同的 LLM。这意味着抽取实体这种重活可以用便宜/本地的模型，查询生成用更强的模型，视觉理解单独走 VLM——成本和质量的分配被拆开了。
四类存储可插拔。README 提到 OpenSearch 作为统一存储后端，覆盖全部四类存储；此前也支持 MongoDB、PostgreSQL 作为一体化方案，以及 Neo4J 作为图数据库。这种「四类存储各司其职、又能被单一后端统一承载」的结构，是它从 demo 走向工程化的关键。
文档删除与图谱重建。2025 年 8 月加入的文档删除功能会触发知识图谱自动重建，避免删了文档但图谱里残留孤立节点，拖累查询质量。
引用与可追溯。2025 年 3 月加入引用功能，配合查询返回检索上下文，让答案能回溯到源文档——这也是 RAGAS 评测里 context precision 指标能算起来的前提。
怎么跑起来
README 提供了三条安装路径，最省事的是把服务端当工具装：
bash### Install LightRAG Server as tool using uv (recommended) uv tool install "lightrag-hku[api]" # Setup env file # Run make env-base or copy env.example to .env before starting the server. cp env.example .env # Update the .env with your LLM and embedding configurations # Launch the server lightrag-server
也可以从源码构建，走 make dev 一键拉起开发环境（会装测试工具链、完整离线依赖栈并构建前端）：
bashgit clone https://github.com/HKUDS/LightRAG.git cd LightRAG make dev source .venv/bin/activate make env-base # Or: cp env.example .env and update it manually lightrag-server
或者用 Docker Compose：
bashgit clone https://github.com/HKUDS/LightRAG.git cd LightRAG cp env.example .env # Update the .env with your LLM and embedding configurations docker compose up
README 里有一条安全提醒必须原样转述：服务端默认绑定 0.0.0.0，在暴露到网络之前，要么在 .env 里配置 LIGHTRAG_API_KEY，要么用 AUTH_ACCOUNTS 配合 TOKEN_SECRET，要么只绑 127.0.0.1 本地访问；否则所有端点都是公开的。另外 Ollama 兼容的 /api/* 路由默认不鉴权，需要设 WHITELIST_PATHS=/health 才会要求认证。
启动后配套的是 WebUI，可以插入文档、发起查询、可视化知识图谱。对私有文档搭知识库这个场景，这条链路基本是完整的：装服务端 → 配 LLM 和 embedding → 灌文档 → 网页里查。
和同主题项目比，它站在哪
同主题的开源项目里，定位差异其实很清楚：
| 项目 | 语言 | 核心定位 | 与 LightRAG 的差异 |
|---|---|---|---|
| LightRAG | Python | 文档 → 知识图谱 → 双层检索的 RAG 框架 | 面向「私有文档问答」，图谱是检索的中间结构，不是最终产品 |
| Understand-Anything | TypeScript | 把代码转成可交互图谱，供浏览、搜索、提问 | 输入是代码库，输出是给人看的图谱；LightRAG 输入是文档，输出是答案 |
| MiroFish | Python | 多智能体群体智能引擎，用图谱组织信息做推演 | 目标是预测/模拟，图谱服务于多视角推演，不是文档检索 |
| codebase-memory-mcp | C | 代码库索引为持久图谱，给 agent 省 token | 面向 agent 的代码记忆，偏 MCP 服务；LightRAG 是完整 RAG 系统 |
| logseq | Clojure | 隐私优先的双向链接笔记平台 | 人工构建知识网络；LightRAG 由 LLM 自动抽取图谱 |
| Trilium | TypeScript | 个人知识库，层级 + 双向链接 | 同样是人工整理型工具，不涉及检索增强生成 |
一句话概括：Understand-Anything 和 codebase-memory-mcp 把图谱当终点（给人看、给 agent 查），MiroFish 把图谱当推演的底座，logseq/Trilium 靠人手连图谱，而 LightRAG 把图谱当RAG 的中间层——自动抽取、自动检索、自动生成答案。它更接近「一个能回答问题的知识库引擎」，而不是「一个知识管理工具」。
谁该用它
如果你手上有一批私有文档（技术资料、内部规章、研究材料），想让团队用自然语言提问，且问题不局限于「某段话在哪」，而是涉及跨文档的概念关联与整体脉络——LightRAG 的双层检索就是为这类问题设计的。它提供 Python 接口和 CLI，也提供带 WebUI 的服务端，可以从脚本一路用到部署。
代价也要说清楚：它依赖 LLM 做实体抽取，索引阶段有模型调用成本；图谱质量直接取决于抽取质量，README 里专门提到针对 Qwen3-30B-A3B 这类开源模型优化过抽取准确率，说明这不是开箱即完美的事。多模态解析要接 MinerU / Docling，存储要选后端，配置面不小。
但方向是明确的：RAG 不该只会在文本块里捞相似片段。把文档先组织成一张图，再在图上分局部和全局两条路走，这是 LightRAG 给出的答案。