HKUDS/LightRAG · 上手攻略
- 仓库：HKUDS/LightRAG
- 链接：https://github.com/HKUDS/LightRAG
- 分类：ai
- 作者：Jay
- 更新：2026-07-06
是什么
LightRAG 是香港大学数据科学实验室（HKUDS）发布的轻量级知识图谱增强检索框架，发表在 EMNLP 2025。它采用双层（向量 + 知识图谱）架构，兼顾检索的全面性与语义深度，是 Microsoft GraphRAG 的高效替代方案。
核心思想：在索引阶段利用 LLM 从文档中提取实体和关系，构建知识图谱（KG），同时保留向量嵌入；查询时通过 local / global / hybrid / mix 四种模式灵活召回相关内容，解决传统 RAG 在跨文档推理、全局知识理解方面的缺陷。
关键数据：Stars 37,337（2026-07），周增约 +105，Python 3.10+，MIT 许可，持续活跃（2024-10 至今保持高频更新）。
解决什么问题
- 传统 RAG 的全局理解局限：向量 chunk 检索只能找到字面相似内容，无法回答"这个公司三年的战略趋势是什么"这类需要跨文档聚合的问题——LightRAG 的 KG 全局模式解决了这一点。
- GraphRAG 成本过高：GraphRAG 在索引和查询阶段都需要大量 LLM 调用（构建 Community Report）；LightRAG 通过直接提取实体-关系而非社区报告，大幅降低 LLM 调用次数和成本。
- 动态数据更新效率：增量数据只需走标准图索引生成局部图，再通过集合合并并入全局图，无需重建索引——这对知识库频繁更新的场景（客服、工单系统）至关重要。
- 多模态文档支持：2026.05 整合 RAG-Anything，支持 PDF、图片、表格、公式的跨模态实体提取和统一索引查询。
- 检索质量依赖 Embedding 模型：LightRAG 的 KG 层让检索质量对 Embedding 模型的依赖降低，可选择轻量快速的 embedding 模型（如 BGE-small）以节省成本。
快速安装
前置要求
- Python 3.10+
- 推荐使用 uv 包管理器（也可以用 pip）
# 安装 uv（Unix/macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
方式一：pip 安装（推荐尝鲜）
# 用 uv 安装（推荐）
uv tool install "lightrag-hku[api]"
# 用 pip 安装（备选）
pip install "lightrag-hku[api]"
方式二：从源码构建（完整功能）
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 推荐：用 make dev 一步搭建开发环境
make dev
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# 或手动
uv sync --extra test --extra offline
方式三：Docker Compose（本地一键环境，含 embedding + storage）
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 交互式向导生成 .env（配置 LLM / embedding / storage）
make env-base # 必填：选择 LLM 和 embedding
make env-storage # 可选：存储后端（Neo4j / PostgreSQL / MongoDB / OpenSearch）
make env-server # 可选：端口、认证、SSL
# 启动
docker compose up
# 访问 http://localhost:7860 （WebUI）
⚠️ 直接暴露到网络前，务必在
.env中配置LIGHTRAG_API_KEY或AUTH_ACCOUNTS认证。
离线/内网部署
参见官方离线部署文档：docs/OfflineDeployment.md
核心用法
Python API 用法
1. 初始化并索引文档
import asyncio
from lightrag import LightRAG, QueryParam
# 初始化（storage 默认为 Neo4j，可选 PostgreSQL / MongoDB / OpenSearch）
rag = LightRAG(
working_dir="./rag_storage",
# 如果用 Docker compose，llm_base_url 默认指向本地服务
llm_model_name="gpt-4o", # 或本地模型如 qwen3-30b-a3b
embedding_model_name="bge-large", # LightRAG 推荐轻量 embedding
)
# 插入文档（支持字符串或文件路径）
await rag.ainsert("你的知识库文本内容，可以是一段也可以是整篇文档。")
2. 四种查询模式
# local 模式：精准问答，具体实体/概念
result = await rag.aquery(
"苹果公司的 CEO 是谁？",
param=QueryParam(mode="local")
)
# global 模式：全局概览，跨文档聚合
result = await rag.aquery(
"过去三年公司的战略方向有什么变化？",
param=QueryParam(mode="global")
)
# hybrid 模式：local + global 合并
result = await rag.aquery(
"这个产品的竞争对手有哪些，各自优劣势是什么？",
param=QueryParam(mode="hybrid")
)
# mix 模式（默认）：Reranker 增强，自动混合
result = await rag.aquery(
"请帮我分析这份法律合同的要点",
param=QueryParam(mode="mix")
)
3. API Server（RESTful，附 WebUI）
启动服务后访问 http://localhost:7860 的 WebUI，或通过 API 调用：
# 插入文档
curl -X POST http://localhost:7860/insert \
-H "Content-Type: application/json" \
-d '{"text": "要索引的文档内容"}'
# 查询
curl -X POST http://localhost:7860/query \
-H "Content-Type: application/json" \
-d '{"query": "你的问题", "mode": "hybrid"}'
详细 API 文档参考：docs/LightRAG-API-Server.md
存储后端配置
LightRAG 支持多种存储后端（可组合）：
| 后端 | 用途 | 配置项 |
|---|---|---|
| Neo4j | 知识图谱存储 | NEO4J_* 环境变量 |
| PostgreSQL | 全功能关系存储 | POSTGRES_* 环境变量 |
| MongoDB | 全功能文档存储 | MONGODB_* 环境变量 |
| OpenSearch | 向量+全文统一存储 | OPENSEARCH_* 环境变量 |
| SQLite | 默认轻量本地存储 | 无需配置 |
LLM 角色配置（v2026.05+）
LightRAG 在不同阶段使用不同 LLM 角色，可以为每个角色配置独立模型以平衡性能与成本：
| 角色 | 用途 | 推荐模型 |
|---|---|---|
EXTRACT |
从文档中提取实体和关系 | 较强模型（如 GPT-4o） |
QUERY |
生成查询关键词 | 中等模型 |
KEYWORDS |
生成查询关键词（同上） | 中等模型 |
VLM |
多模态文档处理（PDF/图片） | 视觉模型 |
参考配置文档：docs/RoleSpecificLLMConfiguration.md
典型适用场景
- 法律/金融知识库：需要跨文档理解、聚合推理的场景（如法规对比、财务趋势分析）。
- 企业内部知识管理：将分散的文档、Wiki、邮件索引为统一 KG，支持"公司今年的研发重点是什么"这类宽泛查询。
- 客服机器人增强：local 模式精准匹配具体问题，global 模式处理"我们的退换货政策整体是怎样的"。
- 多模态文档问答：支持 PDF/图片/表格丰富的技术文档（手册、论文、报告）的 RAG 问答。
- 动态知识库：增量数据无需全量重建，频繁更新的知识库（如新闻、舆情监控）非常适合。
坑与注意
- LLM 成本仍不可忽视：虽然比 GraphRAG 便宜，但每个文档索引阶段都需要 LLM 提取实体关系，大规模语料（>10万文档）需估算好 token 成本；推荐使用本地开源模型（如 Qwen3-30B-A3B）以节省费用。
- Embedding 模型选择：LightRAG 官方推荐低维快速 embedding（如 BGE-small），但多模态场景下建议按需升级；与 LiteRAG 等方案不同，这里对 embedding 质量要求相对宽松。
- 存储后端选型：SQLite 适合本地开发和小规模数据；生产环境建议 PostgreSQL（分析能力强）或 OpenSearch（向量+全文统一）。Neo4j 在超大规模图上性能更优，但运维复杂度高。
- 配置 Wizard 安全性：Docker compose 的交互式配置向导生成的
.env可能包含明文密钥，不要将其直接 commit 到公开仓库。 - Python 3.10 严格：实测 3.9 及以下版本可能有依赖问题，建议使用 3.10–3.12 LTS 版本。
- 删除文档的 KG 重建：删除文档时会触发相关实体关系的 KG 重建（利用 LLM 缓存加速），但大规模删除仍可能耗时较长。
与同类对比
| 方案 | 核心架构 | 全局理解 | 增量更新 | 多模态 | 部署复杂度 | 开源/许可 |
|---|---|---|---|---|---|---|
| LightRAG | 双层（向量+KG） | ✅ 强 | ✅ 高效（集合合并） | ✅ RAG-Anything 集成 | 中等 | ✅ MIT |
| Microsoft GraphRAG | 全 KG + Community Report | ✅ 极强 | ❌ 需重建 | ❌ | 高（复杂 pipeline） | ✅ MIT |
| Naive RAG（向量检索） | 纯向量 | ❌ 弱 | ✅ 高效 | ❌ | 低 | — |
| HippoRAG | 知识图谱 + 记忆 | ✅ 中 | ⚠️ 一般 | ❌ | 中 | ✅ |
| RAPTOR（Recursive RAG） | 树形摘要 + 向量 | ✅ 中 | ⚠️ | ❌ | 中 | ✅ |
总结：LightRAG 在 GraphRAG 和 Naive RAG 之间找到了最佳平衡点——保留了 KG 的全局理解能力，同时通过跳过 Community Report 极大地降低了 LLM 成本和增量更新开销。2026 年持续迭代（多模态、多种存储后端、Reranker 集成），EMNLP 2025 论文背书，学术和工程双重验证。
一句话推荐结论
如果你需要 RAG 的全局推理能力（跨文档聚合、趋势分析）但又受不了 GraphRAG 的高成本和慢更新，LightRAG 是目前最优雅的解法——MIT 许可、EMNLP 2025 论文支撑、2026 年多模态和存储后端全面升级，配合 Langfuse Tracing 和 RAGAS 评测可构建完整的 RAG 质量保障体系。
来源：GitHub README (https://github.com/HKUDS/LightRAG)，arXiv:2410.05779，LightRAG 官方文档，LearnOpenCV 教程 (https://learnopencv.com/lightrag)