给文档建知识图谱再问答的 RAG 框架（LightRAG）

把一批 PDF、Word、Markdown 丢进去提问，常见 RAG 方案的处理方式是按固定长度切块、算向量、检索相似片段，再把片段拼进提示词。文档里的实体关系、跨章节的因果链条，很难在这种做法里保留下来。LightRAG 选了另一条路：先抽实体和关系织成知识图谱，查询时图谱结构和向量检索同时用上。

LightRAG 是用 Python 写的检索增强生成框架，把文档切块、抽取实体与关系构建知识图谱，再按图谱和向量两条路径回答查询。

仓库托管在 HKUDS/LightRAG，MIT 许可证，主要语言 Python，目前 39939 star、5644 fork、293 个开放 Issue，最近一次提交在 2026-09-30。输入是一批文本文档，PDF、Word、Markdown 都行，图片表格公式这类多模态内容走 MinerU / Docling；输出是回答，以及回答背后的知识图谱与检索上下文。适合愿意先花时间配环境、给自己积累的资料建一套可追问知识库的团队。

第一次用它需要知道的事

• 运行环境是 Python 3.10（README 徽章标注的版本）。仓库同时提供 PyPI 包与 Docker 部署两条路径。
• 抽取实体和回答查询都要调用大模型。走云端 API 时文档内容会离开本机；不接云端就得自己起 Ollama。这两条路在 Issue 里都出过问题。
• 存储后端要提前定。仓库支持 PostgreSQL、MongoDB、OpenSearch 等一体化方案，图存储也有多个选项，选完再迁移成本不低。
• 配置体量不小。根目录的 env.example 约 91.6 KB，env.docker-compose-full 约 51.1 KB，config.ini.example 约 1.1 KB。
• Docker 镜像定义有三个：Dockerfile、Dockerfile.lite、Dockerfile.postgres；编排文件有 docker-compose.yml、docker-compose-full.yml、docker-compose.podman.yml，另有 k8s-deploy/ 下的 K8s 清单。是否需要管理员权限，仓库里没有说明。

最短上手路径

1. 装包。PyPI 上的包名是 lightrag-hku，命令为 pip install lightrag-hku。
2. 准备配置。以 env.example 为模板填模型接口和存储后端，或用 config.ini.example 走 ini 形式的配置。仓库节选没有列出必填字段的完整清单。
3. 启动服务。走 Docker 就用根目录的 docker-compose.yml，全量部署换 docker-compose-full.yml 并配套 env.docker-compose-full。
4. 打开界面。v1.5.7 起 WebUI 多了一个面向终端用户的入口 /workspace。
5. 验证。上传文档，等实体抽取与图谱构建跑完，再在界面里提问。仓库节选没有给出可直接复制的 Python 启动命令，这一步要看仓库内的 examples/ 与文档。

它实际上能做哪些事

文档解析与图谱构建

• 四种分块策略可选：Fix、Recursive、Vector、Paragraph，2026.05 引入，按文档形态挑一种。
• DOCX 有 Smart Heading 识别，v1.5.5 起内置解析器能看出章节结构，排版不规范的 Word 文档也能按节切块；图片、表格、公式则交给 MinerU / Docling 做多模态解析，这块能力来自 2026.05 合并进来的 RAG-Anything。
• 抽取环节有一条硬限制：实体目前只按名称完全匹配合并，同一对象的不同叫法会在图谱里留下多个节点。

查询与检索

• Reranker 从 2025.08 起支持并成为默认查询模式，混合查询的排序靠它兜底；引用功能从 2025.03 起提供，回答可以带来源标注。
• API 在返回答案的同时返回检索到的上下文，方便算 context precision；评估可接 RAGAS，链路追踪可接 Langfuse，2025.11 起支持。
• 图优先摄取在 v1.5.7rc2 引入，先把知识图谱建起来，向量索引延后做。

存储与运维

• 一体化存储可选 PostgreSQL（2025.01 起）、MongoDB（2025.02 起）、OpenSearch（2026.03 起，覆盖 LightRAG 的四类存储）。
• PGTableGraphStorage 在 v1.5.6 引入，用 PostgreSQL 原生表做图存储，不再依赖 Apache AGE；v1.5.7rc2 配套给了把图从 Apache AGE 迁到 PostgreSQL 表的离线工具。删除文档会触发知识图谱自动重建，2025.08 起支持；EXTRACT、QUERY、KEYWORDS、VLM 四个角色可以各配一套模型，2026.05 起支持；2026.03 起还带部署向导，embedding、reranking 与存储后端能在 Docker 里本地起。

参数速查

代码分两块：lightrag/ 是 Python 主包，lightrag_webui/ 是 TypeScript 前端。日常会改到的取值集中在这几处：

• 分块策略：Fix、Recursive、Vector、Paragraph
• LLM 角色：EXTRACT、QUERY、KEYWORDS、VLM
• 配置模板：config.ini.example、env.example、env.docker-compose-full
• 镜像与编排：Dockerfile、Dockerfile.lite、Dockerfile.postgres，docker-compose.yml、docker-compose-full.yml、docker-compose.podman.yml
• 服务化：lightrag.service.example、docker-entrypoint.sh、Makefile、k8s-deploy/

环境变量的逐项名称与默认值都写在 env.example 里，仓库节选没有展开，这里不逐个列出。

输出与结果位置

• WebUI：部署完成后访问 /workspace，这是 v1.5.7 起新增的终端用户入口。
• API：问答接口在返回答案的同时返回检索到的上下文，调用方可以直接拿去做后续处理。
• 知识图谱与向量索引：落在你选定的存储后端里，本地部署时就在对应的容器或数据卷中。
• 评估与追踪：RAGAS 出评估数据，Langfuse 收链路信息。
• 论文复现脚本放在 reproduce/ 目录，模型提示词模板放在 prompts/。

实际使用中的坑

下面几条来自仓库 Issue 列表，是真实用户踩过的。

• 同名实体不会自动合并。LightRAG 目前只按名称完全匹配合并实体（含 caption），同一对象的不同写法会分裂成多个节点，直接影响图谱质量。这条是 Feature Request，状态为待解决。
• 批量推文件时 WebUI 卡住，界面不动但后端还在处理。这条已解决。
• 用 Ollama 跑 llama3.2:1b Q8 这类小模型，索引慢到难以接受，实体抽取环节尤其明显。这条已解决。
• 搭配 gpt-4o-mini 时出现不工作的情况，用 Ollama 模型时抽不出实体和关系。这两条都已解决。

替代方案一览

如果只是要把个人文件放进本机做语义检索，不打算碰知识图谱，LightRAG 这条链路偏重：要选存储后端、要跑实体抽取、要调大模型，配置文件以 KB 计。以本地索引为主的方案部署更轻。反过来，需要跨文档推理、需要答案带来源标注的场景，纯向量索引覆盖不了，图谱路径才是它的价值所在。调研阶段先翻一遍 Awesome-GraphRAG 那份清单，比直接上手装环境快。

别踩的合规线

LightRAG 处理的是你自己提供的文档，处理过程中内容会发给所选的大模型服务。上传之前先确认你有权处理这些材料：受版权保护的出版物、含个人信息的客户资料、涉密的企业文档，都不该直接投进第三方 API。改用本地 Ollama 或自建的 embedding、reranking 服务能减少外发，代价是要有对应算力和运维能力。

抓取网页再入库的用法同样要守住边界。只处理你拥有、已获授权或明确公开许可的内容，不要绕过网站的访问限制，也不要用它批量采集他人平台的数据。误用可能带来版权纠纷、个人信息保护方面的责任，以及账号被平台封禁的风险。这类工具只适合用在自己的资产或已获授权的目标上。

什么时候值得用它

• 你手上有一批自己的文档，问题需要跨文档、跨章节才能答上来，单条片段检索经常漏掉关键联系。
• 你能接受先花时间选存储后端、配模型角色，换来后续文档增量入库和按需删改。
• 你需要答案带来源标注，或者需要把检索上下文交给 RAGAS、Langfuse 这类工具做评估与追踪。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。