ghcr.io/hkuds/lightrag:v1.5.5

🚀 LightRAG：简单快速的检索增强生成（Retrieval-Augmented Generation）

🎉 最新动态

• [2026.07]🎯[新功能]：新增Word文档的Smart Heading识别功能。
• [2026.05]🎯[新功能]：将RagAnything合并至LightRAG🎉。通过MinerU / Docling服务实现多模态内容解析与提取。
• [2026.05]🎯[新功能]：引入四种可选文本分块策略：Fix、Recursive、Vector和Paragraph。
• [2026.05]🎯[新功能]：支持特定角色LLM配置，4种 distinct 角色：EXTRACT、QUERY、KEYWORDS和VLM，具备独立LLM设置。
• [2026.03]🎯[新功能]：集成OpenSearch作为统一存储后端，全面支持LightRAG的所有四种存储类型。
• [2026.03]🎯[新功能]：引入设置向导。支持通过Docker本地部署嵌入（embedding）、重排序（reranking）和存储后端。
• [2025.11]🎯[新功能]：集成RAGAS用于评估和Langfuse用于追踪。更新API以在返回查询结果时附带检索上下文，支持上下文精确率指标。
• [2025.10]🎯[可扩展性增强]：消除了处理瓶颈，以高效支持大规模数据集。
• [2025.09]🎯[新功能]：提升开源LLM（如Qwen3-30B-A3B）的知识图谱提取准确性。
• [2025.08]🎯[新功能]：现已支持重排序器（Reranker），显著提升混合查询性能（设为默认查询模式）。
• [2025.08]🎯[新功能]：新增文档删除功能，自动重新生成知识图谱（KG）以确保最佳查询性能。
• [2025.06]🎯[新版本发布]：团队已发布https://github.com/HKUDS/RAG-Anything——**一体化多模态RAG**系统，支持无缝处理文本、图像、表格和公式。
• [2025.06]🎯[新功能]：LightRAG现在通过https://github.com/HKUDS/RAG-Anything集成支持全面的多模态数据处理，实现跨多种格式（包括PDF、图像、Office文档、表格和公式）的无缝文档解析和RAG能力。详情请参阅新的https://github.com/HKUDS/LightRAG/?tab=readme-ov-file#multimodal-document-processing-rag-anything-integration。
• [2025.03]🎯[新功能]：LightRAG现已支持引用功能，实现适当的来源归因和增强的文档可追溯性。
• [2025.02]🎯[新功能]：现在可将MongoDB用作一体化存储解决方案，实现统一数据管理。
• [2025.02]🎯[新版本发布]：团队已发布https://github.com/HKUDS/VideoRAG——用于理解超长上下文视频的RAG系统。
• [2025.01]🎯[新版本发布]：团队已发布https://github.com/HKUDS/MiniRAG，通过小型模型简化RAG实现。
• [2025.01]🎯现在可将PostgreSQL用作一体化存储解决方案进行数据管理。
• [2024.11]🎯[新资源]：LightRAG综合指南现已在LearnOpenCV上线——探索深入教程和最佳实践。非常感谢博客作者的杰出贡献！
• [2024.11]🎯[新功能]：推出LightRAG WebUI——通过直观的基于Web的仪表板插入、查询和可视化LightRAG知识的界面。
• [2024.11]🎯[新功能]：现在可https://github.com/HKUDS/LightRAG?tab=readme-ov-file#using-neo4j-for-storage——支持图数据库。
• [2024.10]🎯[新功能]：添加了LightRAG介绍视频链接——LightRAG功能演示。感谢作者的杰出贡献！
• [2024.10]🎯[新渠道]：我们已创建***频道!💬 欢迎加入社区进行分享、讨论和协作！ 🎉🎉

算法流程图

图1：LightRAG索引流程图 - 图片说明：来源
图2：LightRAG检索与查询流程图 - 图片说明：来源

安装

[!NOTE] 你也可以根据偏好使用pip，但推荐使用uv以获得更好的性能和更可靠的依赖管理。

[!NOTE] 📦 离线部署：对于离线或隔离环境，请参阅离线部署指南，了解预安装所有依赖项和缓存文件的说明。

安装LightRAG服务器

• 从PyPI安装

### 使用uv安装LightRAG Server作为工具（推荐）
uv tool install "lightrag-hku[api]"

### 或者使用pip
# python -m venv .venv
# source .venv/bin/activate # Windows系统：.venv\Scripts\activate
# pip install "lightrag-hku[api]"

# 设置环境文件
# 通过从GitHub仓库根目录下载或从本地源码检出中复制获取env.example文件
cp env.example .env # 更新.env文件中的LLM和嵌入配置
# 启动服务器。默认绑定所有网络接口（0.0.0.0）。
# 安全提示：在网络上暴露服务前，需在.env中配置认证
# （LIGHTRAG_API_KEY，或AUTH_ACCOUNTS与TOKEN_SECRET组合），或绑定到
# 127.0.0.1仅本地访问；未配置认证时所有端点均为公开。
# 注意：为确保客户端兼容性，Ollama兼容的/api/*路由默认保持开放；
# 设置WHITELIST_PATHS=/health可要求对这些路由也进行认证。
lightrag-server

• 从源码安装

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# 引导开发环境（推荐）
make dev
source .venv/bin/activate # 激活虚拟环境（Linux/macOS）
# Windows系统：.venv\Scripts\activate

# make dev会安装测试工具链以及完整的离线栈
# （API、存储后端和提供程序集成），然后构建前端。
# 启动服务器前运行make env-base或复制env.example到.env。

# 使用uv的等效手动步骤
# 注意：uv sync会在.venv/中自动创建虚拟环境
uv sync --extra test --extra offline
source .venv/bin/activate # 激活虚拟环境（Linux/macOS）
# Windows系统：.venv\Scripts\activate

### 或者使用pip与虚拟环境
# python -m venv .venv
# source .venv/bin/activate # Windows系统：.venv\Scripts\activate
# pip install -e ".[test,offline]"

# 构建前端产物
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

# 设置环境文件
make env-base # 或：cp env.example .env并手动更新
# 启动API-WebUI服务器
lightrag-server

• 使用Docker Compose启动LightRAG服务器

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env # 更新.env文件中的LLM和嵌入配置
# 修改.env中的LLM和嵌入设置
docker compose up

使用设置工具创建 .env 文件

无需手动编辑 env.example，可使用交互式设置向导生成已配置的 .env 文件，必要时还会生成 docker-compose.final.yml：

make env-base # 必需的第一步：LLM、嵌入模型、重排序器
make env-storage # 可选：存储后端和数据库服务
make env-server # 可选：服务器端口、身份验证和 SSL
make env-base-rewrite # 可选：强制重新生成向导管理的 compose 服务
make env-storage-rewrite # 可选：强制重新生成向导管理的 compose 服务
make env-security-check # 可选：审计当前 .env 文件的安全风险

有关每个目标的完整说明，请参见 docs/InteractiveSetup.md。

嵌入模型

选择嵌入模型时，需关注其多语言支持能力。由于LightRAG的检索质量对嵌入模型的依赖有限，建议选择低维度且快速的模型。任何主流、最新的嵌入模型均可良好工作；对于本地部署，BAAI/bge-m3是一个可靠选择。强烈建议将嵌入模型部署在本地以获得最佳性能。

[!IMPORTANT] 嵌入模型必须在文档索引前确定，且查询阶段必须使用相同的模型。一旦选定，嵌入模型通常无法更改。如果更改，需要重新嵌入所有文本块、实体和关系。LightRAG目前未提供重新嵌入工具。某些存储后端（如PostgreSQL）在首次创建表时需要定义向量维度，因此更改嵌入模型需要删除向量相关表，以便LightRAG重新创建它们。

解决实体关系抽取过程中的LLM超时问题

实体关系抽取过程中的LLM超时通常由以下三种原因之一导致。请先确定原因，再应用相应的解决方法（这些参数可以组合使用）：

• 模型速度慢。 运行速度低于约50 tokens/秒的模型可能无法在请求超时前完成包含大量实体和关系的 chunk 处理。可以通过 *_LLM_TIMEOUT 增加超时时间——可以是全局的 LLM_TIMEOUT，也可以是抽取阶段特定的 EXTRACT_LLM_TIMEOUT。注意，实际执行超时时间是配置值的两倍，因此 EXTRACT_LLM_TIMEOUT=300 允许最长600秒。
• chunk 产生过多实体和关系。 例如，参考文献 chunk 可能会使模型生成大量记录，导致无法及时完成处理。通过 OPENAI_LLM_MAX_TOKENS 或 OPENAI_LLM_MAX_COMPLETION_TOKENS 限制输出长度（具体参数名称取决于 LLM 提供商——请参见 env.example）。一个有用的大小规则是 max_output_tokens

[!IMPORTANT] 对于集成到您的项目中，我们强烈建议使用 LightRAG Server 提供的 REST API。LightRAG SDK 主要用于嵌入式应用或学术研究与评估目的。

📚 文档与工具

参考文档（docs/）

标有 🇨🇳 的条目在同一文件夹中还提供中文翻译，文件名为 *-zh.md。

部署与设置

服务器与 API

文档处理

模型与存储

SDK 与开发

维护工具（lightrag/tools/）

面向存储的工具读取 .env 和环境变量的方式与服务器完全相同，因此请从项目根目录使用相同的配置运行它们。其中一些工具会就地重写存储——请查看链接的指南，了解是否需要先停止服务器（以及任何其他写入程序）；rebuild_vdb 需要停止服务器。

rebuild_vdb.py — lightrag-rebuild-vdb — README_REBUILD_VDB.md

删除并从权威源（图节点/边和 text_chunks KV 存储）重建所有向量存储。用于向量写入失败后的恢复路径，以及更改嵌入模型或维度之后。还提供只读一致性检查。

clean_llm_query_cache.py — lightrag-clean-llmqc — README_CLEAN_LLM_QUERY_CACHE.md

删除查询模式 LLM 缓存条目（mix:*、hybrid:*、local:*、global:*、naive:*），同时保留昂贵的提取缓存。

migrate_llm_cache.py —

python -m lightrag.tools.migrate_llm_cache

— README_MIGRATE_LLM_CACHE.md

在KV存储后端之间迁移默认模式缓存（提取、摘要、多模态分析），同时保持工作区隔离。

kg_integrity_repair.py —

python -m lightrag.tools.kg_integrity_repair [--apply]

— README_KG_INTEGRITY_REPAIR.md

审计整个图以查找full_entities/full_relations恢复锚点中缺失的贡献，报告无法恢复的孤立节点，并可选择修复锚点以便删除/重试操作能再次发现它们。

source_conflict_repair.py —

lightrag.tools.source_conflict_repair list

/

lightrag.tools.source_conflict_repair repair

— README_SOURCE_CONFLICT_REPAIR.md

列出声称具有相同规范源键的文档，并将操作员未选择的候选文档降级为重复项。它不会自行选择胜出者，也不会删除任何内容。

download_cache.py —

lightrag-download-cache [--spacy --spacy-install]

— OfflineDeployment.md

预下载离线部署所需的***en编码和固定的spaCy模型，以及docx的smart_heading引擎参数。

hash_password.py —

lightrag-hash-password [--username USER]

— LightRAG-API-Server.md

生成可直接粘贴到AUTH_ACCOUNTS中的bcrypt值。

check_initialization.py —

python -m lightrag.tools.check_initialization --demo

— ProgramingWithCore.md

SDK诊断：验证LightRAG实例是否完全初始化，可捕获常见的“忘记执行await rag.initialize_storages()”错误。

🔗 相关项目

生态系统与扩展

📸

RAG-Anything
多模态RAG

🎥

VideoRAG
超长上下文视频RAG

✨

MiniRAG
极简RAG

---

🤝 贡献

我们欢迎各种形式的贡献——错误修复、新功能、文档改进等。
提交拉取请求前，请阅读我们的Contributing Guide。

感谢所有贡献者的宝贵贡献。

📖 引用

@article{guo2024lightrag,
title={LightRAG: Simple and Fast Retrieval-Augmented Generation},
author={Zirui Guo and Lianghao Xia and Yanhua Yu and Tu Ao and Chao Huang},
year={2024},
eprint={2410.05779},
archivePrefix={arXiv},
primaryClass={cs.IR}
}

---

⭐
感谢您关注LightRAG！
⭐