项目总览 - HKUDS/LightRAG

核心特性与功能

LightRAG 在 2024-2025 年间持续迭代，引入了多项关键功能增强，使其在企业级应用场景中具备更强的竞争力。

评估与追踪能力

项目集成了 RAGAS 评估框架和 Langfuse 追踪系统，为开发者提供了完整的 RAG 系统性能评估能力。RAGAS 支持上下文精度等关键指标计算，而 Langfuse 则提供了全链路追踪功能，帮助开发者定位检索与生成过程中的性能瓶颈。API 层面已更新为在返回查询结果的同时返回检索到的上下文，以支持上下文精度指标计算（README.md:76-77）。

Reranker 支持

Reranker 模型的集成显著提升了混合查询模式下的检索性能。当启用 Reranker 时，系统推荐将"mix mode"设置为默认查询模式，以充分发挥重排序能力。项目推荐使用 BAAI/bge-reranker-v2-m3 或 Jina 等主流 Reranker 模型（README.md:79-80，README.md:241-244）。

文档管理与知识图谱重建

系统支持文档删除功能，并在删除后自动触发知识图谱重建，确保查询性能始终处于最优状态。这一特性解决了动态文档管理场景下的数据一致性问题（README.md:80-81）。

多模态数据处理

通过 RAG-Anything 集成，LightRAG 现已支持全面的多模态数据处理能力，包括 PDF、图像、Office 文档、表格和公式等多种格式。这使得 LightRAG 能够应对更复杂的文档处理场景（README.md:81-82）。

引用功能

系统新增引用功能，支持源文档归因和增强的文档可追溯性，这对于需要严格引用来源的学术研究和企业应用尤为重要（README.md:83-84）。

系统架构与工作流程

LightRAG 采用双层级检索架构，将知识图谱推理与向量相似度检索相结合，实现了对局部细节和全局知识的双重覆盖。

架构总览

正在加载图表渲染器...

上图展示了 LightRAG 的核心架构，包含输入层、索引阶段、存储层、检索阶段和输出层五个主要组件。系统架构图可在项目 README 中找到可视化展示（README.md:44-50）。

索引流程详解

索引阶段是 LightRAG 的核心，决定了后续检索的质量。该阶段包含以下关键步骤：

文本分块：将输入文档按照 chunk_token_size（默认 1200 tokens）进行分割，块之间保持 chunk_overlap_token_size（默认 100 tokens）的重叠，确保上下文连续性（README.md:352-353）。
实体与关系提取：对每个文本块执行实体提取和关系提取，构建知识图谱的节点和边。系统支持通过 entity_extract_max_gleaning 参数控制提取循环次数（默认为 1），以提升提取质量（README.md:356-357）。
向量化存储：使用配置的 Embedding 模型（如 BAAI/bge-m3 或 text-embedding-3-large）将文本块转换为向量并存储（README.md:237-240）。

查询流程与检索模式

LightRAG 支持六种查询模式，每种模式适用于不同的场景需求（README.md:384-391）：

模式	说明	适用场景
local	聚焦于上下文相关信息	具体事实查询
global	利用全局知识	概括性、总结性问题
hybrid	结合 local 和 global 方法	需要兼顾细节与全局的问题
naive	基础搜索，不使用高级技术	简单关键词匹配
mix	整合知识图谱和向量检索	复杂查询（推荐与 Reranker 配合）
bypass	直接使用 LLM，不进行检索	通用对话场景

关键调用链

正在加载图表渲染器...

该时序图展示了 LightRAG 的两个核心流程：文档索引和查询处理。索引流程涉及文本分块、实体/关系提取和向量化存储；查询流程则根据选择的模式执行不同的检索策略，最终由 LLM 生成响应。完整的算法流程图可在项目文档中找到（README.md:95-105）。

技术栈与依赖

LightRAG 采用模块化设计，支持多种技术栈组合，为开发者提供了极大的灵活性。

LLM 模型支持

系统支持多种 LLM 后端，包括但不限于：

OpenAI：GPT-4o-mini（推荐用于索引阶段）、GPT-4o（推荐用于查询阶段）
Ollama：支持本地部署的开源模型
Gemini：Google 的大语言模型
vLLM：高性能推理引擎
OpenAI 兼容接口：支持各类兼容 OpenAI API 的服务

项目建议在索引阶段使用成本较低的模型（如 GPT-4o-mini），而在查询阶段使用能力更强的模型以获得更好的结果（README.md:233-237）。

Embedding 模型配置

Embedding 模型的选择对 RAG 系统性能至关重要。项目推荐使用主流多语言 Embedding 模型，如 BAAI/bge-m3 和 text-embedding-3-large。需要注意的是，Embedding 模型必须在文档索引前确定，且在查询阶段必须使用相同模型。对于某些存储方案（如 PostgreSQL），向量维度在表创建时定义，因此更换 Embedding 模型时需要删除现有向量相关表并重新创建（README.md:237-240）。

存储后端支持

LightRAG 支持多种存储后端，满足不同规模和场景的需求（README.md:341-351）：

存储类型	支持后端	默认选择
KV 存储	JsonKVStorage、PGKVStorage、RedisKVStorage、MongoKVStorage、OpenSearchKVStorage	JsonKVStorage
向量存储	NanoVectorDBStorage、PGVectorStorage、MilvusVectorDBStorage、ChromaVectorDBStorage、FaissVectorDBStorage、MongoVectorDBStorage、QdrantVectorDBStorage、OpenSearchVectorDBStorage	NanoVectorDBStorage
图存储	NetworkXStorage、Neo4JStorage、PGGraphStorage、AGEStorage、OpenSearchGraphStorage	NetworkXStorage
文档状态存储	JsonDocStatusStorage、PGDocStatusStorage、MongoDocStatusStorage、OpenSearchDocStatusStorage	JsonDocStatusStorage

核心配置参数

LightRAG 提供了丰富的初始化参数，允许开发者精细控制系统行为（README.md:341-374）：

分块配置：chunk_token_size（默认 1200）、chunk_overlap_token_size（默认 100）
并发控制：embedding_batch_num（默认 32）、embedding_func_max_async（默认 16）、llm_model_max_async（默认 4）
缓存配置：enable_llm_cache（默认 True）、enable_llm_cache_for_entity_extract（默认 True）
摘要配置：summary_context_size（默认 10000）、summary_max_tokens（默认 500）
向量检索阈值：cosine_better_than_threshold（默认 0.2）

安装与快速开始

LightRAG 提供了多种安装方式，支持从 PyPI 安装或从源码构建。

安装方式

项目推荐使用 uv 进行包管理，以获得更快的依赖解析和安装速度（README.md:107-114）：

bash
1# 安装 uv（Unix/macOS）
2curl -LsSf https://astral.sh/uv/install.sh | sh
3
4# 安装 LightRAG Server
5uv tool install "lightrag-hku[api]"
6
7# 或使用 pip 安装
8pip install lightrag-hku

对于离线或隔离环境，项目提供了离线部署指南，支持预安装所有依赖和缓存文件。

LightRAG Server 快速启动

LightRAG Server 提供 Web UI 和 API 支持，方便文档索引、知识图谱探索和 RAG 查询（README.md:116-126）：

bash
1# 安装 Server
2uv tool install "lightrag-hku[api]"
3
4# 启动服务
5lightrag-server

Server 还提供 Ollama 兼容接口，允许 Open WebUI 等 AI 聊天机器人轻松访问 LightRAG。

核心库快速入门

对于需要将 LightRAG 集成到项目中的开发者，推荐使用 REST API。核心库主要用于嵌入式应用或研究评估场景（README.md:250-270）：

bash
1# 进入项目目录
2cd LightRAG
3
4# 设置 OpenAI API Key
5export OPENAI_API_KEY="sk-...your_openai_key..."
6
7# 下载示例文档
8curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt
9
10# 运行示例代码
11python examples/lightrag_openai_demo.py

核心模块职责边界

LightRAG 的核心实现包含四个主要模块，每个模块具有明确的职责边界。

存储管理模块

职责：管理文档、文本块、向量、知识图谱和文档处理状态的持久化存储。

不负责：不处理业务逻辑，仅提供数据存取接口。

关键 API：

kv_storage：文档和文本块存储
vector_storage：向量存储
graph_storage：图数据存储
doc_status_storage：文档处理状态跟踪

关键数据结构：

文档对象：包含原始文本、元数据和处理状态
向量对象：包含 embedding 向量和关联的文本块 ID
图节点/边：包含实体、关系及其属性

索引处理模块

职责：执行文档分块、实体提取、关系提取和向量化处理。

不负责：不处理查询请求，仅负责数据预处理和索引构建。

关键 API：

insert(document)：插入单个文档
insert_batch(documents)：批量插入文档

关键调用链：

文本分块 → 2. 实体提取（调用 LLM）→ 3. 关系提取（调用 LLM）→ 4. 向量化（调用 Embedding 模型）→ 5. 存储持久化

错误处理：

LLM 调用失败时支持重试机制
实体提取失败时记录错误并继续处理其他文本块
支持增量索引，避免重复处理

查询处理模块

职责：根据查询模式执行检索策略，整合检索结果并生成最终响应。

不负责：不负责文档索引和存储管理。

关键 API：

query(question, mode)：执行查询并返回响应
QueryParam：查询参数配置对象

关键数据结构：

QueryParam.mode：查询模式
QueryParam.response_type：响应类型
QueryParam.top_k：检索结果数量
QueryParam.rerank：是否启用重排序

关键调用链：

查询向量化 → 2. 根据模式执行检索 → 3. 可选 Rerank → 4. LLM 生成响应

LLM 集成模块

职责：管理与 LLM 和 Embedding 模型的交互，包括缓存和并发控制。

不负责：不处理具体的检索逻辑。

关键 API：

llm_model_func：LLM 生成函数
embedding_func：Embedding 生成函数

关键配置：

llm_model_max_async：最大并发 LLM 请求数
embedding_batch_num：Embedding 批处理大小
enable_llm_cache：是否启用 LLM 响应缓存

错误处理与边界条件：

超过并发限制时请求排队等待
API 调用失败时支持指数退避重试
缓存命中时直接返回，不调用模型

适用场景

LightRAG 适用于多种企业级和科研场景：

企业知识库：结合知识图谱和向量检索，支持复杂的企业内部知识查询
学术研究：支持 RAGAS 评估和 Langfuse 追踪，便于算法研究和性能分析
多模态文档处理：通过 RAG-Anything 集成，支持 PDF、图像、表格等多种格式
动态文档管理：支持文档删除和知识图谱自动重建，适用于内容频繁更新的场景
私有化部署：支持 Ollama 等本地模型，满足数据隐私要求

报告阅读路线图

正在加载图表渲染器...

上图展示了本技术分析报告的推荐阅读顺序。建议首先完成当前的项目总览，了解 LightRAG 的核心概念和整体架构；然后深入系统架构和数据流分析章节，理解内部实现机制；最后参考 API 设计、部署指南和性能评估章节，进行实际开发和部署。

项目核心能力量化

基于源码分析，LightRAG 的核心能力可量化如下：

支持的查询模式：6 种
支持的存储后端类型：4 类（KV、向量、图、文档状态）
支持的向量数据库：8 种
支持的图数据库：5 种（NetworkX、Neo4J、PostgreSQL AGE、OpenSearch 等）
支持的 KV 存储：5 种
核心初始化参数：25+ 个
Python 版本要求：3.10+
安装方式：PyPI 包（lightrag-hku）
示例代码文件：10+ 个（位于 examples/ 目录）