# https://github.com/HKUDS/LightRAG 项目说明书
生成时间：2026-05-30 18:04:43 UTC
## 目录
- [LightRAG 简介](#page-introduction)
- [快速开始](#page-quick-start)
- [安装指南](#page-installation)
- [系统架构](#page-architecture)
- [存储后端](#page-storage-backends)
- [文本分块策略](#page-text-chunking)
- [知识图谱提取](#page-knowledge-graph)
- [多模态文档处理](#page-multimodal)
- [API服务器与WebUI](#page-api-server)
- [核心库编程](#page-programming-core)
## LightRAG 简介
### 相关页面
相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture), [安装指南](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [lightrag/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/__init__.py)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
- [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
# LightRAG 简介
LightRAG 是由香港大学（HKU）开发的新一代检索增强生成（Retrieval-Augmented Generation，RAG）框架，旨在解决传统 RAG 系统在处理复杂查询时的局限性。通过将**知识图谱**与**向量检索**深度融合，LightRAG 能够实现高效且全面的信息检索与答案生成。
## 核心特性
LightRAG 在传统 RAG 基础上进行了多项创新优化，主要特性包括：
| 特性 | 说明 |
|------|------|
| **双层检索架构** | 同时支持实体级（局部）和关系级（全局）检索 |
| **知识图谱集成** | 自动从文档中提取实体和关系构建知识图谱 |
| **多查询模式** | 支持 naive、local、global、hybrid、mix、bypass 六种模式 |
| **多模态支持** | 支持 PDF、Office 文档、图片、表格、公式等格式处理 |
| **灵活存储后端** | 支持 Neo4j、MongoDB、PostgreSQL、OpenSearch 等多种存储 |
| **交互式 WebUI** | 提供知识图谱可视化、文档管理和查询界面 |
| **完整 API 服务** | 提供 RESTful API 和 Ollama 兼容接口 |
| **引用溯源** | 支持返回检索结果来源，实现答案可追溯性 |
> 资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 系统架构
LightRAG 采用分层架构设计，主要包含以下核心组件：
```mermaid
graph TB
subgraph "表示层"
WebUI[Web 用户界面]
API[RESTful API]
Ollama[Ollama 兼容接口]
end
subgraph "业务逻辑层"
QueryEngine[查询引擎]
IndexEngine[索引引擎]
KGExtractor[知识图谱提取器]
end
subgraph "存储层"
VectorDB[向量数据库]
KGStore[(知识图谱存储)]
KVStore[KV 存储]
DocStatus[(文档状态存储)]
end
subgraph "模型层"
LLM[大语言模型]
Embedding[Embedding 模型]
Reranker[重排序模型]
end
WebUI --> QueryEngine
API --> QueryEngine
Ollama --> QueryEngine
QueryEngine --> LLM
QueryEngine --> Embedding
QueryEngine --> Reranker
IndexEngine --> KGExtractor
IndexEngine --> VectorDB
IndexEngine --> KGStore
IndexEngine --> KVStore
IndexEngine --> DocStatus
```
### 架构说明
| 层级 | 功能 | 主要组件 |
|------|------|----------|
| **表示层** | 提供用户交互接口 | WebUI（React）、API 服务（FastAPI）、Ollama 兼容接口 |
| **业务逻辑层** | 处理检索和生成逻辑 | 查询引擎、索引引擎、图谱提取器 |
| **存储层** | 数据持久化存储 | 向量库、图数据库、键值存储、文档状态存储 |
| **模型层** | AI 模型调用 | LLM（大语言模型）、Embedding（嵌入模型）、Reranker（重排模型） |
> 资料来源：[lightrag/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/__init__.py)
## 工作流程
### 索引流程
文档进入系统后，LightRAG 通过以下步骤进行处理：
```mermaid
graph LR
A[文档输入] --> B[文档分块]
B --> C[Embedding 向量化]
C --> D[向量存储]
B --> E[实体识别]
E --> F[关系抽取]
F --> G[知识图谱构建]
D --> H[索引完成]
G --> H
```
1. **文档分块**：将输入文档切分为适合处理的文本块
2. **向量化**：使用 Embedding 模型将文本块转换为向量表示
3. **向量存储**：将向量存入向量数据库支持语义检索
4. **实体识别**：从文本块中识别实体
5. **关系抽取**：抽取实体之间的关系
6. **图谱构建**：将实体和关系存储到知识图谱
> 资料来源：[lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
### 查询流程
LightRAG 提供多种查询模式以适应不同场景：
```mermaid
graph TD
Q[用户查询] --> M{查询模式}
M -->|naive| V1[向量检索]
M -->|local| V2[向量检索] --> E1[实体匹配]
M -->|global| KG1[图谱全局检索]
M -->|hybrid| V3[向量检索] & KG2[图谱检索]
M -->|mix| V4[向量检索] & KG3[图谱检索] & R1[重排序]
M -->|bypass| LLM1[直接 LLM 处理]
V1 --> R1
V2 --> R1
E1 --> R1
KG1 --> R1
V3 --> R1
KG2 --> R1
V4 --> R1
KG3 --> R1
R1 --> ANS[生成答案]
```
> 资料来源：[lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## 查询模式详解
LightRAG 支持六种查询模式，每种模式适用于不同类型的查询场景：
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **naive** | 仅使用向量检索，类似于传统 RAG | 简单事实性查询 |
| **local** | 向量检索 + 实体匹配，关注局部上下文 | 实体属性、关系查询 |
| **global** | 仅使用知识图谱全局检索 | 需要全局上下文的问题 |
| **hybrid** | 结合向量检索和图谱检索 | 平衡局部与全局信息 |
| **mix** | 混合检索 + 重排序（默认模式） | 复杂混合查询，性能最优 |
| **bypass** | 跳过检索，直接使用 LLM | 通用知识回答，无需检索 |
> 资料来源：[lightrag_webui/src/api/lightrag.ts:7](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts#L7)
### 查询参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | string | 必需 | 查询文本 |
| `mode` | QueryMode | 必需 | 查询模式 |
| `only_need_context` | boolean | false | 仅返回检索上下文 |
| `only_need_prompt` | boolean | false | 仅返回生成提示词 |
| `response_type` | string | - | 响应格式（如 "Multiple Paragraphs"） |
| `stream` | boolean | false | 启用流式输出 |
| `top_k` | number | - | 检索返回数量（实体模式为实体数，全局模式为关系数） |
| `chunk_top_k` | number | - | 重排序后保留的文本块数 |
| `max_entity_tokens` | number | - | 实体上下文最大 token 数 |
| `max_relation_tokens` | number | - | 关系上下文最大 token 数 |
| `max_total_tokens` | number | - | 整个查询上下文最大 token 数 |
> 资料来源：[lightrag_webui/src/api/lightrag.ts:8-35](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts#L8-L35)
## 存储后端支持
LightRAG 支持多种存储后端，可根据需求灵活选择：
### 向量存储
| 存储类型 | 说明 | 特点 |
|----------|------|------|
| **Neo4j** | 图数据库，支持完整存储 | 成熟稳定，适合图数据 |
| **MongoDB** | 文档数据库 | 灵活 schema，适合快速迭代 |
| **PostgreSQL** | 关系数据库 + pgvector | 一站式解决方案 |
| **OpenSearch** | 分布式搜索平台 | 支持全文和向量混合搜索 |
| **Milvus** | 专用向量数据库 | 高性能向量检索 |
| **Chroma** | 轻量级向量库 | 适合开发和测试 |
| **Qdrant** | 向量相似度搜索引擎 | 高性能，支持过滤 |
| **Weaviate** | 混合搜索引擎 | 原生支持多模态 |
### 知识图谱存储
| 存储类型 | 说明 |
|----------|------|
| **Neo4j** | 原生图数据库，支持 Cypher 查询 |
| **MongoDB** | 文档存储，通过聚合实现图查询 |
| **PostgreSQL** | 关系表存储，适合复杂关联查询 |
| **OpenSearch** | 统一存储，支持全文 + 图结构 |
> 资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 多模态文档处理
LightRAG v1.5.0 起支持完整的多模态文档处理能力，已将 [RAG-Anything](https://github.com/HKUDS/RAG-Anything) 的功能合并到主仓库中。
### 支持的文档格式
| 格式类型 | MIME 类型 | 文件扩展名 |
|----------|-----------|------------|
| **PDF** | application/pdf | .pdf |
| **Word** | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| **PowerPoint** | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| **Excel** | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| 代码类型 | 文件扩展名 |
|----------|------------|
| **编程语言** | .sql, .bat, .sh, .c, .h, .cpp, .hpp, .py, .java, .js, .ts, .swift, .go, .rb, .php |
| **样式表** | .css, .scss, .less |
| **其他** | .json, .xml, .yaml, .yml, .toml, .ini, .cfg, .conf, .log, .md, .txt, .env |
> 资料来源：[lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
### 多模态处理流程
```mermaid
graph TD
subgraph "解析阶段"
PDF[PDF 文档] --> MinerU[MinerU 解析]
DOC[Office 文档] --> Docling[Docling 解析]
IMG[图片/表格] --> OCR[OCR 识别]
end
subgraph "内容提取"
MinerU --> Text[文本块]
MinerU --> Table[表格内容]
MinerU --> Formula[公式内容]
MinerU --> Image[图片内容]
Docling --> Text
OCR --> Image
end
subgraph "索引阶段"
Text --> Embed[Embedding 向量化]
Image --> VLM[视觉语言模型处理]
Table --> Embed
Formula --> Embed
Embed --> VectorDB[向量数据库]
Text --> KGExtract[知识图谱提取]
KGExtract --> KGStore[图谱存储]
end
```
多模态解析依赖外部服务（ MinerU 或 Docling），需在配置中指定相应服务端点。
## 安装与部署
### 环境要求
| 组件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| **Python** | 3.10+ | 3.11+ |
| **LLM** | 32B 参数，上下文 ≥ 32KB | 更大参数，更长上下文 |
| **Embedding** | 支持的模型 | BAAI/bge 系列 |
| **Reranker** | 可选 | BAAI/bge-reranker-v2-m3 |
> 资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### 安装方式
#### 方式一：Docker 部署（推荐）
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env # 编辑配置
docker compose up
```
#### 方式二：从源码安装
```bash
cd LightRAG
uv sync # 创建虚拟环境并安装依赖
source .venv/bin/activate # 激活虚拟环境
```
#### 方式三：pip 安装
```bash
uv pip install lightrag-hku
# 或
pip install lightrag-hku
```
#### 方式四：离线部署
对于内网环境或离线部署场景，需预先下载所有依赖和模型文件，具体步骤请参考 [OfflineDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/OfflineDeployment.md)。
### 交互式配置向导
LightRAG 提供交互式配置向导简化部署：
| 命令 | 说明 |
|------|------|
| `make env-base` | 配置 LLM、Embedding、Reranker |
| `make env-storage` | 配置存储后端和数据库服务 |
| `make env-server` | 配置服务器端口、认证和 SSL |
| `make env-base-rewrite` | 强制重新生成基础服务配置 |
| `make env-storage-rewrite` | 强制重新生成存储服务配置 |
| `make env-security-check` | 安全审计当前 .env 配置 |
> 资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 配置说明
### 环境变量配置
核心配置项说明：
| 配置项 | 说明 | 必填 |
|--------|------|------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | 是（使用 OpenAI 时） |
| `LITELLM_HOST` | LiteLLM 代理地址 | 否 |
| `EMBEDDING_PROVIDER` | Embedding 服务提供商 | 是 |
| `EMBEDDING_API_KEY` | Embedding API 密钥 | 否 |
| `RERANKER_PROVIDER` | Reranker 服务提供商 | 否 |
| `VECTOR_DB` | 向量数据库类型 | 是 |
| `GRAPH_DB` | 图数据库类型 | 是 |
| `MONGO_URI` | MongoDB 连接地址 | 否 |
| `NEO4J_URI` | Neo4j 连接地址 | 否 |
| `POSTGRES_CONN_INFO` | PostgreSQL 连接信息 | 否 |
| `OPENSEARCH_HOST` | OpenSearch 集群地址 | 否 |
### 运行时路径配置
LightRAG 支持通过反向代理部署，路径前缀可在运行时动态配置：
| 配置项 | 说明 |
|--------|------|
| `LIGHTRAG_API_PREFIX` | API 路径前缀 |
| `LIGHTRAG_WEBUI_PATH` | WebUI 路径前缀 |
配置通过服务器注入到前端，无需重新构建：
```html
```
> 资料来源：[lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
## 常见问题与解决方案
### 文档区分问题
**问题**：同名文档如何区分？
LightRAG 使用内部 `document_id` 标识文档，文件名仅用于显示。建议在上传时使用唯一文件名或在上传后记录返回的 `document_id`。
**参考**：[Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
### 反向代理部署问题
**问题**：在子路径下部署时资源无法加载。
**原因**：应用曾使用绝对路径，某些资源路径未正确处理子路径前缀。
**解决方案**：配置 `LIGHTRAG_WEBUI_PATH` 和 `LIGHTRAG_API_PREFIX`，确保服务器正确注入路径前缀。
**参考**：[Issue #2755](https://github.com/HKUDS/LightRAG/issues/2755)
### 源文件溯源问题
**问题**：查询结果能否返回来源文件？
LightRAG 支持引用功能（v2025.03+），可在查询时启用返回检索上下文，以便追踪信息来源。但目前文件名信息需要通过文档上传接口记录。
**参考**：[Issue #323](https://github.com/HKUDS/LightRAG/issues/323)
### 多模态支持问题
**问题**：如何添加多模态支持？
LightRAG 已将 RAG-Anything 功能合并。对于 PDF、Office 文档、图片等，需要配置外部解析服务（MinerU 或 Docling）。
**参考**：[Issue #2642](https://github.com/HKUDS/LightRAG/issues/2642)
## 相关资源
| 资源 | 链接 |
|------|------|
| GitHub 仓库 | https://github.com/HKUDS/LightRAG |
| 官方文档 | [docs/](https://github.com/HKUDS/LightRAG/tree/main/docs) |
| 视频演示 | [YouTube](https://www.youtube.com/watch?v=g21royNJ4fw) |
| RAG-Anything | https://github.com/HKUDS/RAG-Anything |
| VideoRAG | https://github.com/HKUDS/VideoRAG |
| Discord 社区 | https://discord.gg/yF2MmDJyGJ |
## 参考阅读
- [编程指南](./ProgramingWithCore.md) - Core API 完整参考
- [高级功能](./AdvancedFeatures.md) - Token 追踪、数据导出、评估工具
- [交互式配置](./InteractiveSetup.md) - 配置向导详细说明
- [Docker 部署](./DockerDeployment.md) - 容器化部署指南
- [离线部署](./OfflineDeployment.md) - 内网环境部署指南
- [LightRAG Server](./LightRAG-API-Server.md) - API 服务器使用指南
- [LightRAG 3D 可视化](./lightrag/tools/lightrag_visualizer/README.md) - 知识图谱 3D 可视化工具
---
## 快速开始
### 相关页面
相关主题：[LightRAG 简介](#page-introduction), [安装指南](#page-installation), [核心库编程](#page-programming-core)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [examples/lightrag_openai_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_openai_demo.py)
- [examples/lightrag_openai_compatible_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_openai_compatible_demo.py)
- [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)
- [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
- [docs/ProgramingWithCore.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ProgramingWithCore.md)
- [docs/DockerDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/DockerDeployment.md)
# 快速开始
本文档为 LightRAG 新用户提供从环境准备到首次运行的完整指南，涵盖多种部署方式的核心配置流程。
## 前置要求
### 系统环境
LightRAG 支持在以下环境中运行：
| 组件 | 要求 |
|------|------|
| Python 版本 | >= 3.10 |
| 操作系统 | Linux、macOS、Windows |
| 内存 | 推荐 16GB 及以上 |
| 磁盘空间 | 根据文档规模，建议预留足够存储空间 |
### 技术栈依赖
LightRAG 对大语言模型的能力要求比传统 RAG 系统更高，因为它需要 LLM 执行实体关系抽取任务。合理的 Embedding 和 Reranker 模型配置对提升查询性能至关重要。资料来源：[README.md:1-50]()
**LLM 选择建议：**
| 场景 | 推荐配置 |
|------|----------|
| 参数规模 | 建议使用至少 320 亿参数的 LLM |
| 上下文长度 | 至少 32KB，建议 64KB |
| 索引阶段 | 不建议使用推理模型 |
| 查询阶段 | 建议使用比索引阶段更强的模型 |
**Embedding 模型建议：**
| 模型名称 | 说明 |
|----------|------|
| `BAAI/bge-m3` | 多语言 Embedding 模型 |
| `text-embedding-3-large` | OpenAI 提供的高性能模型 |
> ⚠️ **重要提示**：Embedding 模型必须在文档索引前确定，查询阶段必须使用相同的模型。对于某些存储方案（如 PostgreSQL），向量维度在首次创建表时定义，更换 Embedding 模型需要删除现有向量表并让 LightRAG 重新创建。
**Reranker 模型建议：**
启用 Reranker 模型可显著提升检索性能。推荐使用主流 Reranker 模型，如 `BAAI/bge-reranker-v2-m3`。启用 Reranker 后，建议将"混合模式"设为默认查询模式。资料来源：[README.md:1-50]()
## 安装方式
LightRAG 提供多种安装方式，用户可根据实际需求选择。
### 方式一：从源码安装（推荐）
```bash
cd LightRAG
# 使用 uv 进行包管理，自动创建 .venv/ 虚拟环境
uv sync
source .venv/bin/activate # Linux/macOS
# Windows: .venv\Scripts\activate
# 或者使用 pip 安装
# pip install -e .
```
### 方式二：从 PyPI 安装
```bash
uv pip install lightrag-hku
# 或
pip install lightrag-hku
```
### 方式三：开发环境快速启动
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 使用 make 工具快速初始化开发环境
make dev
source .venv/bin/activate
```
`make dev` 会安装测试工具链、完整的离线堆栈（API、存储后端、提供商集成）以及前端构建工具。资料来源：[README.md:1-50]()
## 环境配置
### 使用交互式配置向导
LightRAG 提供了交互式配置向导，可自动生成 `.env` 配置文件和 `docker-compose.final.yml`。资料来源：[docs/InteractiveSetup.md:1-100]()
```bash
# 基础配置：LLM、Embedding、Reranker
make env-base
# 可选：存储后端和数据库服务
make env-storage
# 可选：服务器端口、认证和 SSL
make env-server
# 强制重新生成向导管理的 compose 服务
make env-base-rewrite
make env-storage-rewrite
# 可选：审计当前 .env 的安全风险
make env-security-check
```
配置向导的详细说明请参阅 [docs/InteractiveSetup.md](./InteractiveSetup.md)。
### 手动配置环境变量
1. 复制示例配置文件：
```bash
cp env.example .env
```
2. 编辑 `.env` 文件，配置以下核心参数：
| 参数 | 说明 | 示例 |
|------|------|------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-...` |
| `OPENAI_EMBEDDING_MODEL` | Embedding 模型名称 | `text-embedding-3-large` |
| `LLM_MODEL` | LLM 模型名称 | `gpt-4o` |
| `RERANKER_MODEL` | Reranker 模型（可选） | `BAAI/bge-reranker-v2-m3` |
完整的环境变量说明请参考 [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)。
## LightRAG Server 快速启动
LightRAG Server 提供 Web UI 和 API 支持，包含知识图谱可视化、文档索引和查询界面。
### 安装 Server
```bash
# 使用 uv 安装（推荐）
uv tool install "lightrag-hku[api]"
# 使用 pip 安装
# python -m venv .venv
# source .venv/bin/activate
# pip install "lightrag-hku[api]"
```
### 构建前端
```bash
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
```
### 启动服务
```bash
# 配置环境变量
export OPENAI_API_KEY="sk-...your_openai_key..."
# 启动服务器
lightrag-server
```
服务启动后，访问 `http://localhost:5678` 即可使用 Web UI。资料来源：[README.md:1-50]()
## LightRAG Core 快速启动
对于希望将 LightRAG 集成到现有项目中的开发者，可以使用 Core API。资料来源：[docs/ProgramingWithCore.md:1-100]()
### 基础使用示例
以下示例演示如何使用 LightRAG Core 进行文档索引和查询：
```python
import os
from lightrag import LightRAG, QueryParam
# 配置 API 密钥
os.environ["OPENAI_API_KEY"] = "sk-..."
# 初始化 LightRAG 实例
rag = LightRAG(
working_dir="./lightrag_storage",
llm_model_name="gpt-4o",
embedding_model_name="text-embedding-3-large"
)
# 索引文档
with open("your_document.txt", "r", encoding="utf-8") as f:
rag.insert(f.read())
# 查询文档
result = rag.query(
"你的查询问题",
param=QueryParam(mode="hybrid")
)
print(result)
```
### 查询模式
LightRAG 支持多种查询模式，适用于不同的应用场景：资料来源：[docs/ProgramingWithCore.md:1-100]()
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `naive` | 纯向量检索 | 简单问答 |
| `local` | 基于实体定位的局部知识图谱检索 | 实体相关查询 |
| `global` | 全局知识图谱检索 | 需要全局信息的查询 |
| `hybrid` | 结合向量和知识图谱的混合检索 | 平衡性能和准确性 |
| `mix` | 混合模式增强版 | 复杂混合查询（默认推荐） |
| `bypass` | 跳过检索，直接使用 LLM | 无需检索的场景 |
### 完整示例代码
详细的核心 API 参考（包括初始化参数、LLM/Embedding 提供商配置、Reranker 注入、插入操作、实体/关系管理、删除/合并等）请参阅 [docs/ProgramingWithCore.md](./docs/ProgramingWithCore.md)。资料来源：[examples/lightrag_openai_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_openai_demo.py)
## Docker 部署
### 快速部署
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env # 编辑 .env 配置 LLM 和 Embedding
docker compose up
```
> 💡 历史版本的 Docker 镜像可在 [LightRAG Docker Images](https://github.com/HKUDS/LightRAG/pkgs/container/lightrag) 获取。官方 GHCR 镜像使用 Sigstore Cosign 通过 GitHub OIDC 进行签名。验证命令请参阅 [docs/DockerDeployment.md](./docs/DockerDeployment.md#verify-official-ghcr-images-with-cosign)。资料来源：[README.md:1-50]()
### Docker 部署架构
```mermaid
graph TD
A[用户请求] --> B[LightRAG Server]
B --> C{查询类型}
C -->|文档检索| D[Vector Store]
C -->|知识图谱| E[Graph Store]
C -->|混合查询| F[Combined Results]
D --> G[Embedding Service]
E --> H[LLM Service]
F --> H
G --> I[Document Storage]
```
## 离线部署
对于离线或气隙环境，请参阅 [docs/OfflineDeployment.md](./docs/OfflineDeployment.md)，了解如何预安装所有依赖项和缓存文件。资料来源：[README.md:1-50]()
## 常见问题
### 1. 如何区分同名但内容不同的文档？
社区中有用户提问关于同名文档区分的问题。LightRAG 使用文档 ID 来追踪文档，而非文件名。如需区分同名文档，建议在上传时添加元数据或使用唯一标识符。资料来源：[github.com/HKUDS/LightRAG/issues/3158]()
### 2. 反向代理子路径问题
在某些反向代理配置下，LightRAG 可能无法正常工作。这是因为应用使用了绝对路径来加载资源（CSS、JS、图片等）。如遇到此问题，请检查反向代理配置或使用子路径适配配置。资料来源：[github.com/HKUDS/LightRAG/issues/2755]()
### 3. 更换 Embedding 模型后无法查询
这是已知限制。更换 Embedding 模型后，需要删除现有的向量相关表，让 LightRAG 使用新的向量维度重新创建表。资料来源：[README.md:1-50]()
## 快速验证
部署完成后，可使用以下方式验证安装：
1. **访问 Web UI**：打开浏览器访问 `http://localhost:5678`
2. **上传测试文档**：上传示例文档
3. **执行查询**：尝试提问验证检索效果
示例测试代码：
```python
import os
import requests
# 使用示例文档测试
url = "https://www.gutenberg.org/cache/epub/24022/pg24022.txt"
os.system(f"curl -o christmas_carol.txt {url}")
# 通过 API 上传和查询
# 参考 examples/ 目录下的完整示例
```
## 下一步
| 文档 | 说明 |
|------|------|
| [docs/ProgramingWithCore.md](./docs/ProgramingWithCore.md) | Core API 完整参考 |
| [docs/AdvancedFeatures.md](./docs/AdvancedFeatures.md) | 高级功能（多模态、追踪等） |
| [docs/InteractiveSetup.md](./docs/InteractiveSetup.md) | 交互式配置向导详解 |
| [docs/LightRAG-API-Server.md](./docs/LightRAG-API-Server.md) | API Server 详细文档 |
| [docs/DockerDeployment.md](./docs/DockerDeployment.md) | Docker 部署指南 |
---
## 安装指南
### 相关页面
相关主题：[快速开始](#page-quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [pyproject.toml](https://github.com/HKUDS/LightRAG/blob/main/pyproject.toml)
- [Dockerfile](https://github.com/HKUDS/LightRAG/blob/main/Dockerfile)
- [Dockerfile.postgres](https://github.com/HKUDS/LightRAG/blob/main/Dockerfile.postgres)
- [docker-compose.yml](https://github.com/HKUDS/LightRAG/blob/main/docker-compose.yml)
- [docs/OfflineDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/OfflineDeployment.md)
- [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
- [Makefile](https://github.com/HKUDS/LightRAG/blob/main/Makefile)
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
# 安装指南
本文档提供 LightRAG 的完整安装指南，涵盖从源码安装、Docker 部署、交互式配置向导到离线环境部署的多种安装方式。LightRAG 是一个基于知识图谱增强的检索增强生成（RAG）框架，支持多模态文档处理能力。资料来源：[README.md:1-100]()
## 前提条件
在开始安装 LightRAG 之前，请确保满足以下系统要求：
### 硬件要求
| 组件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 内存 | 8 GB RAM | 16 GB RAM 或更高 |
| 磁盘空间 | 10 GB | 50 GB 或更高（取决于数据量） |
| CPU | 多核处理器 | 多核处理器 |
### 软件依赖
| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Python | 3.10 - 3.12 | 推荐使用 Python 3.11 |
| uv | 最新版本 | 高性能 Python 包管理器（推荐） |
| Docker | 24.0+ | 仅 Docker 部署需要 |
| Docker Compose | 2.0+ | 仅 Docker 部署需要 |
### LLM 和嵌入模型要求
LightRAG 对大语言模型（LLM）的能力要求比传统 RAG 系统更高，因为它需要 LLM 执行实体关系抽取任务。资料来源：[README.md:50-80]()
- **LLM 选择建议**：
- 推荐使用至少 320 亿参数的 LLM
- 上下文长度至少 32KB，推荐 128KB 或更高
- **Embedding 模型**：配置适当的嵌入模型对查询性能至关重要
- **Reranker 模型**：启用 Reranker 模型可显著提升混合查询性能，推荐使用 `BAAI/bge-reranker-v2-m3` 或 Jina 等服务商提供的模型
## 安装方式概览
LightRAG 提供三种主要的安装方式：
```mermaid
graph TD
A[开始安装] --> B{选择安装方式}
B --> C[源码安装
LightRAG Core]
B --> D[PyPI 安装
lightrag-hku]
B --> E[Docker 部署
docker-compose]
C --> C1[uv sync 或 pip install]
D --> D1[uv tool install 或 pip install]
E --> E1[make env-* 配置向导]
E --> E2[docker compose up]
style C fill:#e1f5fe
style D fill:#e8f5e8
style E fill:#fff3e0
```
## 方式一：安装 LightRAG Core（源码安装）
源码安装允许开发者深入研究框架源码并进行定制化开发。资料来源：[README.md:25-45]()
### 使用 uv 安装（推荐）
`uv` 是一个高性能的 Python 包管理器，推荐用于 LightRAG 项目。资料来源：[README.md:20-30]()
```bash
# 克隆仓库
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 使用 uv 同步依赖并创建虚拟环境
uv sync
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
# 或在 Windows 上: .venv\Scripts\activate
# 验证安装
python -c "import lightrag; print(lightrag.__version__)"
```
### 使用 pip 安装
如果不习惯使用 `uv`，也可以使用传统的 `pip` 进行安装：
```bash
cd LightRAG
pip install -e .
```
### 从 PyPI 安装预发布版本
```bash
# 使用 uv
uv pip install lightrag-hku
# 或使用 pip
pip install lightrag-hku
```
## 方式二：Docker 部署（推荐生产环境）
Docker 部署提供完整的环境隔离和简化的依赖管理，适合生产环境和快速原型开发。资料来源：[docker-compose.yml:1-50]()
### 前置准备
1. 确保已安装 Docker 24.0+ 和 Docker Compose 2.0+
2. 获取必要的 API 密钥（OpenAI API Key 或其他 LLM 提供商密钥）
### 快速启动
```bash
# 克隆仓库
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 复制环境配置文件
cp env.example .env
# 编辑 .env 文件，配置 LLM 和嵌入设置
vim .env
# 启动所有服务
docker compose up
```
### Docker 镜像说明
LightRAG 的官方 Docker 镜像托管在 GitHub Container Registry (GHCR) 上。历史版本的镜像可以在 [LightRAG Docker Images](https://github.com/HKUDS/LightRAG/pkgs/container/lightrag) 页面找到。资料来源：[README.md:100-110]()
官方 GHCR 镜像使用 Sigstore Cosign 通过 GitHub OIDC 进行签名验证。详情请参阅 [Docker 部署文档](./DockerDeployment.md#验证官方-ghcr镜像)。
## 方式三：使用交互式配置向导
LightRAG 提供了交互式配置向导来简化环境配置过程，无需手动编辑 `.env` 文件。资料来源：[docs/InteractiveSetup.md:1-50]()
### Makefile 目标说明
| 目标 | 说明 | 必需 |
|------|------|------|
| `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 文件的安全风险 | 否 |
资料来源：[README.md:115-130]()
### 配置流程
```mermaid
graph LR
A[make env-base] --> B[LLM 配置]
A --> C[Embedding 配置]
A --> D[Reranker 配置]
E[make env-storage] --> F[选择存储后端]
F --> G[(Neo4j)]
F --> H[(PostgreSQL)]
F --> I[(MongoDB)]
F --> J[(OpenSearch)]
K[make env-server] --> L[服务器配置]
L --> M[端口设置]
L --> N[认证配置]
L --> O[SSL 配置]
P[make env-security-check] --> Q[安全审计]
```
### 详细配置步骤
**第一步：基础环境配置**
```bash
make env-base
```
此命令会引导您配置：
- LLM 提供商（OpenAI、Azure、Gemini、Ollama 等）
- Embedding 模型配置
- Reranker 模型配置
**第二步：存储后端配置（可选）**
```bash
make env-storage
```
支持的存储后端包括：
- **Neo4j**：图数据库，用于存储知识图谱
- **PostgreSQL**：支持 pgvector 扩展的向量存储
- **MongoDB**：文档数据库和向量存储
- **OpenSearch**：统一存储后端，支持所有四种存储类型
**第三步：服务器配置（可选）**
```bash
make env-server
```
配置内容包括：
- Web UI 和 API 端口
- 认证设置
- SSL/TLS 配置
**第四步：安全审计**
```bash
make env-security-check
```
此命令会检查当前 `.env` 文件的安全风险。建议在部署前运行此检查。
## 方式四：离线部署
对于离线或气隙环境，LightRAG 提供了完整的离线部署指南。资料来源：[docs/OfflineDeployment.md:1-100]()
### 离线环境准备
1. 在有网络的环境下准备所有依赖和缓存文件
2. 打包模型文件和配置
3. 在离线环境中解压并安装
详细步骤请参阅 [离线部署指南](./OfflineDeployment.md)。
## 安装 LightRAG Server
LightRAG Server 提供 Web UI 和 API 支持，包含知识图谱可视化、文档索引、查询等功能。资料来源：[README.md:75-95]()
### 使用 uv 安装（推荐）
```bash
# 安装包含 API 功能的 LightRAG Server
uv tool install "lightrag-hku[api]"
# 构建前端资源
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
# 复制并编辑环境配置
cp env.example .env
vim .env
# 启动服务器
lightrag-server
```
### 使用 pip 安装
```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 安装带 API 功能的 LightRAG
pip install "lightrag-hku[api]"
# 构建前端
cd lightrag_webui
npm install
npm run build
cd ..
# 启动服务器
lightrag-server
```
### LightRAG Server 功能特性
| 功能 | 说明 |
|------|------|
| Web UI | 文档索引、知识图谱探索、RAG 查询界面 |
| API | RESTful API 接口 |
| Ollama 兼容接口 | 模拟 LightRAG 为 Ollama 聊天模型 |
| 知识图谱可视化 | 支持多种重力布局、节点查询、子图过滤 |
| 多模态支持 | 支持 PDF、Office 文档、图片、表格和公式处理 |
## 开发环境快速启动
推荐使用 `make dev` 命令快速初始化开发环境：资料来源：[docs/InteractiveSetup.md:20-40]()
```bash
# 克隆仓库
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# 初始化开发环境（安装测试工具链、离线栈和前端）
make dev
# 激活虚拟环境
source .venv/bin/activate
# 运行示例代码
cd examples
python example.py
```
`make dev` 会安装完整的测试工具链、离线存储后端、提供商集成和前端构建。
## 快速开始示例
安装完成后，可以使用以下代码快速测试 LightRAG：资料来源：[README.md:85-100]()
```bash
# 设置 OpenAI API 密钥
export OPENAI_API_KEY="sk-...your_openai_key..."
# 下载示例文档
curl https://...
# 运行示例查询
python examples/quick_start.py
```
### 验证安装
```python
from lightrag import LightRAG, QueryParam
# 初始化 LightRAG 实例
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="gpt-4",
embedding_model="text-embedding-3-large"
)
# 插入文档
with open("your_document.txt", "r") as f:
rag.insert(f.read())
# 查询
result = rag.query(
"你的查询问题",
param=QueryParam(mode="hybrid")
)
print(result)
```
## 安装问题排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 依赖安装失败 | Python 版本不兼容 | 确保使用 Python 3.10-3.12 |
| uv 找不到命令 | uv 未安装 | 运行 `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Docker 服务启动失败 | 端口冲突 | 检查并释放冲突端口 |
| API 连接失败 | .env 配置错误 | 验证 API 密钥和环境变量 |
| 前端构建失败 | Node.js 版本过低 | 升级到最新稳定版本 |
### 获取帮助
如果在安装过程中遇到问题：
1. 查看 [GitHub Issues](https://github.com/HKUDS/LightRAG/issues) 是否已有解决方案
2. 搜索 [GitHub Discussions](https://github.com/HKUDS/LightRAG/discussions) 获取社区支持
3. 加入 [Discord 社区](https://discord.gg/yF2MmDJyGJ) 获取实时帮助
## 下一步
安装完成后，建议阅读以下文档：
- [编程指南](./ProgramingWithCore.md) - 了解如何使用 LightRAG Core API
- [高级功能](./AdvancedFeatures.md) - 多模态文档处理、令牌追踪、评估工具
- [LightRAG API Server](./LightRAG-API-Server.md) - 完整的 API 参考文档
- [交互式配置](./InteractiveSetup.md) - 详细配置向导说明
## 参见
- [官方文档首页](../README.md)
- [编程指南](./ProgramingWithCore.md)
- [高级功能](./AdvancedFeatures.md)
- [Docker 部署](./DockerDeployment.md)
- [离线部署](./OfflineDeployment.md)
---
## 系统架构
### 相关页面
相关主题：[LightRAG 简介](#page-introduction), [存储后端](#page-storage-backends), [文本分块策略](#page-text-chunking), [知识图谱提取](#page-knowledge-graph)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
- [lightrag/operate.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py)
- [lightrag/base.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py)
- [lightrag/pipeline.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/pipeline.py)
- [lightrag/kg/factory.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/factory.py)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
- [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
# 系统架构
LightRAG 是一个基于知识图谱增强的检索增强生成（RAG）框架，其系统架构采用分层设计，核心层负责文档索引与知识图谱构建，API 服务层提供统一的 REST 接口，WebUI 层提供可视化交互界面。本文详细介绍 LightRAG 的整体架构设计、各组件职责以及数据流向。
## 整体架构概述
LightRAG 采用四层架构设计，从下至上依次为存储层、核心引擎层、API 服务层和前端交互层。存储层支持多种后端数据库，包括向量数据库、图数据库、KV 存储和文档状态存储；核心引擎层负责文本分块、实体关系抽取、向量化和检索查询；API 服务层基于 FastAPI 提供标准化接口；前端交互层提供 WebUI 和可视化工具。
```mermaid
graph TB
subgraph 存储层["存储层 Storage Layer"]
VDB["向量数据库
Vector DB"]
GDB["图数据库
Graph DB"]
KV["KV 存储
Key-Value Store"]
DOC["文档状态存储
DocStatus Store"]
end
subgraph 核心引擎层["核心引擎层 Core Engine"]
CHUNK["文本分块
Text Chunking"]
KG["知识图谱构建
KG Extraction"]
EMBED["向量化
Embedding"]
RETRIEVE["检索引擎
Retrieval"]
QUERY["查询处理
Query Processing"]
end
subgraph API服务层["API 服务层 API Service"]
REST["REST API
FastAPI"]
WS["WebSocket
实时通信"]
AUTH["认证授权
Authentication"]
end
subgraph 前端交互层["前端交互层 Frontend"]
WEBUI["WebUI
React"]
VIEWER["3D 可视化
Graph Viewer"]
DOCS["文档管理
Document Mgmt"]
end
USER([用户]) --> WEBUI
USER --> REST
USER --> VIEWER
WEBUI --> API服务层
REST --> 核心引擎层
CHUNK --> VDB
KG --> GDB
EMBED --> VDB
RETRIEVE --> VDB
RETRIEVE --> GDB
QUERY --> KG
核心引擎层 --> 存储层
```
资料来源：[README.md](./README.md)
## 核心组件详解
### LightRAG Core 核心引擎
LightRAG Core 是框架的核心引擎，封装在 `lightrag/lightrag.py` 文件中。它负责管理整个 RAG 生命周期的所有关键操作，包括文档插入、知识图谱查询、向量检索和结果生成。
核心引擎支持六种查询模式，每种模式针对不同的检索场景进行优化：
| 查询模式 | 说明 | 适用场景 |
|---------|------|---------|
| `naive` | 纯向量检索，直接使用 LLM 生成回答 | 简单问答 |
| `local` | 基于实体邻居检索，获取局部子图信息 | 细节查询 |
| `global` | 基于关系遍历检索，获取全局图结构信息 | 聚合分析 |
| `hybrid` | 结合 local 和 global 模式 | 平衡检索 |
| `mix` | 混合模式，融合向量和图谱检索（**默认模式**） | 通用场景 |
| `bypass` | 跳过 RAG 流程，直接使用 LLM | 无需检索 |
资料来源：[lightrag_webui/src/api/lightrag.ts:7](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
### 存储层架构
LightRAG 的存储层采用抽象工厂模式设计，通过 `lightrag/kg/factory.py` 中的工厂类创建不同存储后端的实现实例。这种设计使得系统可以灵活切换底层存储技术，同时保持上层接口的一致性。
```mermaid
classDiagram
class StorageFactory {
+create_vector_storage()
+create_graph_storage()
+create_kv_storage()
+create_doc_status_storage()
}
class VectorStorage {
<>
+upsert()
+query()
+delete()
}
class GraphStorage {
<>
+upsert_nodes()
+upsert_edges()
+query_nodes()
+query_edges()
}
class KVStorage {
<>
+get()
+set()
+delete()
}
StorageFactory ..> VectorStorage : creates
StorageFactory ..> GraphStorage : creates
StorageFactory ..> KVStorage : creates
```
支持的存储后端包括：
| 存储类型 | 支持的后端 | 配置项 |
|---------|-----------|--------|
| 向量存储 | OpenSearch, PostgreSQL (pgvector), MongoDB Atlas, Milvus, Qdrant, Chroma | `VECTOR_DB_TYPE` |
| 图存储 | OpenSearch, Neo4j, NetworkX (内存) | `GRAPH_DB_TYPE` |
| KV 存储 | OpenSearch, PostgreSQL, MongoDB | `KV_DB_TYPE` |
| 文档状态 | OpenSearch, PostgreSQL, MongoDB | `DOC_STATUS_STORE_TYPE` |
资料来源：[lightrag/kg/factory.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/factory.py)
### 文档处理管道
文档处理管道（Pipeline）是 LightRAG 处理上传文档的核心流程，定义在 `lightrag/pipeline.py` 文件中。管道支持多种文档格式的处理，包括纯文本、PDF、Office 文档等。
```mermaid
flowchart LR
A[上传文档] --> B{格式检测}
B -->|PDF| C[PDF 解析]
B -->|DOCX| D[Word 解析]
B -->|PPTX| E[PPT 解析]
B -->|XLSX| F[Excel 解析]
B -->|TXT/MD| G[文本提取]
C --> H[多模态处理
RAG-Anything]
D --> H
E --> H
F --> H
G --> H
H --> I[文本分块
Chunking]
I --> J[实体抽取
Entity Extraction]
J --> K[关系抽取
Relation Extraction]
K --> L[向量化
Embedding]
L --> M[存储索引
Storage Indexing]
M --> N[文档状态更新
DocStatus]
```
管道支持的分块策略包括 `Recursive`、`Token`、`Fixed`、`RecursiveCharacterTextSplitter`、`Character` 等，可通过配置 `CHUNKING strategy` 参数选择合适的分块方式。
资料来源：[lightrag/pipeline.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/pipeline.py)
## API 服务架构
LightRAG Server 基于 FastAPI 构建，提供完整的 RESTful API 接口。API 架构采用分层设计，将路由处理、数据验证和业务逻辑分离。
### API 端点概览
| 功能模块 | 主要端点 | 说明 |
|---------|---------|------|
| 文档管理 | `POST /documents`, `GET /documents`, `DELETE /documents/{doc_id}` | 文档上传、查询、删除 |
| 知识检索 | `POST /query` | RAG 查询接口 |
| 知识图谱 | `GET /kg/{entity_id}`, `GET /kg/relations` | 图谱节点和关系查询 |
| 管道状态 | `GET /pipeline/status`, `POST /pipeline/cancel` | 异步处理状态管理 |
| 用户认证 | `POST /auth/login`, `GET /auth/status` | JWT 认证支持 |
资料来源：[lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
### 查询请求参数
```typescript
interface QueryRequest {
query: string // 查询文本
mode: QueryMode // 查询模式
only_need_context?: boolean // 仅返回上下文
only_need_prompt?: boolean // 仅返回提示词
response_type?: string // 响应格式
stream?: boolean // 流式输出
top_k?: number // Top-K 检索数
chunk_top_k?: number // Rerank 后保留数
max_entity_tokens?: number // 实体上下文最大 token 数
max_relation_tokens?: number // 关系上下文最大 token 数
max_total_tokens?: number // 总 token 预算
}
```
### 反向代理支持
LightRAG Server 支持在反向代理（如 Nginx）后以子路径方式部署。系统通过 `LIGHTRAG_API_PREFIX` 和 `LIGHTRAG_WEBUI_PATH` 环境变量配置运行时路径前缀。前端资源通过 HTML 中的占位符注入配置，确保所有资源引用使用相对路径。
```typescript
// 运行时配置注入点
window.__LIGHTRAG_CONFIG__ = {
apiPrefix: "/lightrag/api", // API 路径前缀
webuiPrefix: "/lightrag/" // WebUI 路径前缀
}
```
资料来源：[lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
## 前端架构
### WebUI 组件
LightRAG WebUI 是基于 React 构建的单页应用，使用 Tailwind CSS 进行样式设计，提供直观的可视化交互界面。
```mermaid
graph LR
subgraph WebUI["WebUI 架构"]
A[文档管理页面] --> B[上传组件]
A --> C[文档列表组件]
A --> D[状态监控组件]
E[知识图谱页面] --> F[图谱可视化]
E --> G[节点查询]
E --> H[子图过滤]
I[查询页面] --> J[查询输入]
I --> K[结果展示]
I --> L[引用溯源]
M[设置页面] --> N[模型配置]
M --> O[存储配置]
end
```
### 支持的文件格式
| 文件类型 | MIME 类型 | 扩展名 |
|---------|----------|--------|
| 纯文本 | `text/plain` | `.txt`, `.md` |
| 代码文件 | `text/x-python`, `text/x-java` 等 | `.py`, `.java`, `.js` 等 |
| PDF | `application/pdf` | `.pdf` |
| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `.docx` |
| PowerPoint | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | `.pptx` |
| Excel | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx` |
资料来源：[lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
### 3D 图谱可视化
LightRAG 提供独立的 3D 图谱可视化工具 `lightrag-viewer`，基于 ModernGL 渲染引擎和 imgui_bundle 构建。
| 功能特性 | 说明 |
|---------|------|
| 布局算法 | Spring、Circular、Shell、Random |
| 交互控制 | WASD + QE 键位移动，右键拖拽视角 |
| 社区检测 | 自动检测并可视化图谱社区结构 |
| 标签显示 | 可配置的节点标签显示 |
资料来源：[lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
## 检索与查询流程
### 混合检索流程（Mix Mode）
Mix 模式是 LightRAG 的默认查询模式，结合了向量检索和知识图谱检索的优势：
```mermaid
flowchart TD
A[用户查询] --> B[查询改写]
B --> C[关键词提取]
B --> D[向量编码]
C --> E[实体识别]
D --> F[向量相似度检索]
E --> G[知识图谱遍历]
F --> H[候选上下文]
G --> H
H --> I[Rerank 重排]
I --> J[Token 预算分配]
J --> K[上下文组装]
K --> L[Prompt 生成]
L --> M[LLM 生成回答]
M --> N[返回结果]
```
### Token 预算控制
LightRAG 实现了统一的 token 预算控制系统，确保检索结果不超过 LLM 的上下文窗口限制：
| 参数 | 说明 |
|-----|------|
| `max_entity_tokens` | 实体上下文最大 token 数 |
| `max_relation_tokens` | 关系上下文最大 token 数 |
| `max_total_tokens` | 总 token 预算（含系统提示词） |
系统采用动态分配策略，根据各部分的重要性自动调整各部分的内容量。
## 数据模型
### 文档状态模型
```typescript
type DocStatus =
| "pending" // 待处理
| "processing" // 处理中
| "completed" // 已完成
| "failed" // 处理失败
interface DocStatusResponse {
id: string
content_length?: number
file_path: string
status: DocStatus
chunk_count?: number
entity_count?: number
error_msg?: string
created_at: string
updated_at: string
}
```
### 知识图谱数据模型
LightRAG 知识图谱采用实体-关系双层结构：
| 元素类型 | 字段 | 说明 |
|---------|------|------|
| 实体 | `entity_name` | 实体名称 |
| 实体 | `entity_type` | 实体类型（如人物、地点、概念等） |
| 实体 | `description` | 实体描述 |
| 实体 | `source_id` | 来源文档 ID |
| 关系 | `src_id` | 源实体 ID |
| 关系 | `tgt_id` | 目标实体 ID |
| 关系 | `relation_type` | 关系类型 |
| 关系 | `weight` | 权重分数 |
实体类型支持中文同义词映射，例如「人物」映射为 `person`，「组织」映射为 `organization`，「概念」映射为 `concept` 等。
资料来源：[lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts)
## 部署架构
### Docker 部署
LightRAG 支持 Docker Compose 一键部署，所有服务通过容器化运行：
```yaml
# docker-compose 结构
services:
lightrag-server # API 服务
openwebui # 可选：WebUI 前端
storage-backend # 存储后端服务
```
### 交互式配置向导
v1.4.11 版本引入交互式配置向导，通过 Makefile 目标简化部署配置：
| 命令 | 用途 |
|-----|------|
| `make env-base` | 配置 LLM、Embedding、Reranker |
| `make env-storage` | 配置存储后端 |
| `make env-server` | 配置服务器端口、认证、SSL |
| `make env-security-check` | 安全审计 |
资料来源：[README.md](./README.md)
## 多模态扩展
v1.5.0 版本集成了 RAG-Anything 的多模态处理能力，支持以下内容类型的处理：
| 内容类型 | 处理方式 |
|---------|---------|
| 图像 | OCR 识别 + 图像描述生成 |
| 表格 | 表格结构解析 + 单元格内容提取 |
| 公式 | LaTeX 转换 + 数学关系识别 |
| PDF | 页面布局分析 + 文本流提取 |
多模态处理依赖外部解析服务（ MinerU 或 Docling），解析后的内容通过标准管道进行索引。
## 常见问题与注意事项
### 文档标识问题
社区反馈（Issue #3158、#323）指出系统目前通过内部 `doc_id` 管理文档，而非文件名。如果需要追踪文档来源，建议在上传时添加自定义元数据。
### 嵌入模型兼容性
嵌入模型必须在文档索引和查询阶段保持一致。某些存储后端（如 PostgreSQL）在创建向量表时需要指定维度，因此更换嵌入模型可能需要重建索引。
### LLM 选型建议
| 阶段 | 推荐配置 |
|-----|---------|
| 索引阶段 | 32B+ 参数模型，上下文 ≥32KB，避免使用推理模型 |
| 查询阶段 | 使用比索引阶段更强的模型以获得更好的查询效果 |
## 相关文档
- [快速开始指南](./README.md)
- [编程接口文档](./docs/ProgramingWithCore.md)
- [API 服务文档](./docs/LightRAG-API-Server.md)
- [高级特性文档](./docs/AdvancedFeatures.md)
- [交互式配置向导](./docs/InteractiveSetup.md)
- [离线部署指南](./docs/OfflineDeployment.md)
---
## 存储后端
### 相关页面
相关主题：[系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/kg/postgres_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py)
- [lightrag/kg/mongo_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py)
- [lightrag/kg/neo4j_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py)
- [lightrag/kg/opensearch_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py)
- [lightrag/kg/redis_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/redis_impl.py)
- [lightrag/kg/milvus_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/milvus_impl.py)
- [docs/MilvusConfigurationGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/MilvusConfigurationGuide.md)
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
# 存储后端
LightRAG 是一个支持多种存储后端的检索增强生成框架，其设计目标是为 KV 存储、向量存储、知识图谱存储和文档状态跟踪提供统一的存储抽象层。通过模块化的存储接口设计，LightRAG 允许用户根据自身基础设施和性能需求选择最合适的存储解决方案。
## 概述
LightRAG 的存储系统采用插件化架构，每种存储类型（KV、向量、图谱、文档状态）都有独立的接口定义和多种实现。版本 v1.4.11 引入了 OpenSearch 作为统一存储后端，可以同时支持所有四种存储类型，简化了部署复杂度。资料来源：[README.md:1-50]()
```mermaid
graph TD
A[LightRAG 存储层] --> B[KV 存储]
A --> C[向量存储]
A --> D[知识图谱存储]
A --> E[文档状态存储]
B --> B1[Redis]
B --> B2[PostgreSQL]
C --> C1[PostgreSQL/pgvector]
C --> C2[Milvus]
C --> C3[MongoDB Atlas]
C --> C4[OpenSearch]
D --> D1[Neo4j]
D --> D2[MongoDB]
D --> D3[OpenSearch]
E --> E1[PostgreSQL]
E --> E2[MongoDB]
E --> E3[OpenSearch]
```
## 支持的存储后端
### 存储后端对比
| 存储后端 | KV 存储 | 向量存储 | 图谱存储 | 文档状态 | 部署难度 | 推荐场景 |
|---------|---------|---------|---------|---------|---------|---------|
| PostgreSQL | ✅ | ✅ | ❌ | ✅ | 低 | 中小规模，单一数据库 |
| MongoDB | ✅ | ✅ | ✅ | ✅ | 低 | 需要灵活文档模型 |
| Neo4j | ❌ | ❌ | ✅ | ❌ | 中 | 复杂图关系分析 |
| OpenSearch | ✅ | ✅ | ✅ | ✅ | 中 | 大规模统一部署 |
| Redis | ✅ | ❌ | ❌ | ❌ | 低 | 高性能缓存场景 |
| Milvus | ❌ | ✅ | ❌ | ❌ | 中 | 超大规模向量检索 |
资料来源：[README.md:1-30]()
## PostgreSQL 存储
PostgreSQL 是 LightRAG 最常用的存储后端之一，通过 pgvector 扩展提供向量存储能力，同时支持 KV 存储和文档状态存储。
### 核心特性
PostgreSQL 实现位于 `lightrag/kg/postgres_impl.py`，提供以下功能：
- **向量相似度检索**：支持余弦相似度和欧氏距离计算
- **事务支持**：完整的事务语义保证数据一致性
- **批量操作优化**：v1.4.12 版本将批量插入性能优化至每批 200 条记录
- **条件向量禁用**：可通过 `POSTGRES_ENABLE_VECTOR` 选项选择性禁用 pgvector 扩展
资料来源：[lightrag/kg/postgres_impl.py:1-100]()
### 配置参数
```bash
# .env 配置示例
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=lightrag
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag
POSTGRES_ENABLE_VECTOR=true
```
| 参数 | 说明 | 默认值 |
|-----|------|-------|
| `POSTGRES_HOST` | 数据库主机地址 | localhost |
| `POSTGRES_PORT` | 数据库端口 | 5432 |
| `POSTGRES_USER` | 数据库用户名 | - |
| `POSTGRES_PASSWORD` | 数据库密码 | - |
| `POSTGRES_DATABASE` | 数据库名称 | lightrag |
| `POSTGRES_ENABLE_VECTOR` | 启用 pgvector 扩展 | true |
### 性能优化
v1.4.13 版本引入了协作式让出机制（cooperative yielding），防止事件循环阻塞，提升高并发场景下的性能表现。资料来源：[README.md:1-20]()
## MongoDB 存储
MongoDB 提供灵活的文档模型，特别适合需要存储多种类型元数据和复杂文档结构的场景。
### 核心特性
MongoDB 实现位于 `lightrag/kg/mongo_impl.py`，支持以下存储类型：
- **文档存储**：原生 JSON 文档支持
- **向量搜索**：通过 Atlas Search 或聚合管道实现向量检索
- **图谱存储**：使用集合存储实体和关系
- **Atlas Local Docker**：v1.4.14 支持通过 Docker 本地部署 MongoDB 向量存储
资料来源：[lightrag/kg/mongo_impl.py:1-100]()
### Atlas Local Docker 配置
```bash
# 启动 MongoDB Atlas Local
docker run -d \
--name mongodb-atlas-local \
-p 27017:27017 \
-e MONGODB_URI="mongodb://localhost:27017" \
mongodb/atlas-local
```
MongoDB Atlas Local 支持完整的向量搜索功能，无需云服务订阅即可获得高性能向量检索能力。资料来源：[README.md:1-30]()
## Neo4j 存储
Neo4j 是专为图数据设计的数据库，在知识图谱存储方面具有原生优势。
### 核心特性
Neo4j 实现位于 `lightrag/kg/neo4j_impl.py`，提供：
- **Cypher 查询语言**：强大的图查询能力
- **原生图遍历**：高效的节点和关系查询
- **图算法支持**：内置中心性、路径查找等图算法
```mermaid
graph LR
A[实体节点] -->|关系| B[实体节点]
A -->|关系| C[实体节点]
B -->|关系| D[实体节点]
C -->|关系| D
```
### 适用场景
Neo4j 特别适合需要深度图关系分析的应用，例如：
- 复杂实体关系网络分析
- 知识图谱可视化
- 社交网络分析
资料来源：[lightrag/kg/neo4j_impl.py:1-80]()
## OpenSearch 存储
OpenSearch 是 LightRAG v1.4.11 引入的统一存储后端，能够同时满足所有四种存储需求。
### 核心特性
OpenSearch 实现位于 `lightrag/kg/opensearch_impl.py`，主要特性包括：
- **统一存储架构**：单一 OpenSearch 集群支持 KV、向量、图谱和文档状态
- **PIT 搜索**：Point-in-Time 搜索支持一致性读取
- **向量化插件**：内置 k-NN 插件支持向量检索
资料来源：[README.md:1-40]()
### 版本兼容性注意事项
v1.4.16 版本对 OpenSearch < 3.3.0 引入了破坏性变更：使用版本感知的排序平局决胜机制进行 PIT 搜索。升级前需确保 OpenSearch 版本满足要求。资料来源：[README.md:1-30]()
### 配置示例
```bash
# .env 配置示例
OPENSEARCH_HOST=localhost
OPENSEARCH_PORT=9200
OPENSEARCH_USER=admin
OPENSEARCH_PASSWORD=your_password
OPENSEARCH_INDEX_PREFIX=lightrag
```
## Redis 存储
Redis 主要用于 KV 存储，提供极低延迟的键值读写能力。
### 核心特性
Redis 实现位于 `lightrag/kg/redis_impl.py`，适用于：
- 缓存层实现
- 临时数据存储
- 会话状态管理
- 高性能 KV 访问场景
```mermaid
graph TD
A[请求] --> B[Redis Cache]
B -->|命中| C[返回结果]
B -->|未命中| D[主存储]
D --> E[更新缓存]
D --> C
```
### 限制
Redis 不支持向量存储和图谱存储，通常作为其他存储的缓存层配合使用。资料来源：[lightrag/kg/redis_impl.py:1-60]()
## Milvus 存储
Milvus 是专门为向量检索设计的数据库，在超大规模向量场景下表现优异。
### 核心特性
Milvus 实现位于 `lightrag/kg/milvus_impl.py`，支持：
- **分布式架构**：水平扩展能力强
- **多种索引类型**：IVF、HNSW、DiskANN 等
- **混合检索**：支持标量过滤与向量检索结合
资料来源：[docs/MilvusConfigurationGuide.md:1-50]()
### 索引类型选择
| 索引类型 | 适用场景 | 召回率 | 延迟 |
|---------|---------|-------|------|
| FLAT | 小规模数据集 | 100% | 中等 |
| IVF_FLAT | 中等规模 | 高 | 低到中 |
| HNSW | 追求低延迟 | 高 | 低 |
| DiskANN | 超大规模 | 高 | 低 |
资料来源：[docs/MilvusConfigurationGuide.md:1-100]()
### 配置参数
```bash
# .env 配置示例
MILVUS_HOST=localhost
MILVUS_PORT=19530
MILVUS_COLLECTION=lightrag_vectors
MILVUS_INDEX_TYPE=HNSW
MILVUS_METRIC_TYPE=COSINE
```
| 参数 | 说明 | 可选值 |
|-----|------|--------|
| `MILVUS_HOST` | Milvus 服务器地址 | - |
| `MILVUS_PORT` | Milvus 服务器端口 | - |
| `MILVUS_INDEX_TYPE` | 索引类型 | FLAT, IVF_FLAT, HNSW, DiskANN |
| `MILVUS_METRIC_TYPE` | 距离度量方式 | COSINE, L2, IP |
## 向量维度与嵌入模型
### 重要约束
**警告**：向量维度必须在首次创建向量表时确定，且必须与使用的嵌入模型输出维度匹配。更换嵌入模型（如从 `bge-m3` 切换到 `text-embedding-3-large`）需要删除现有向量表并重新创建。资料来源：[README.md:1-50]()
### 维度对应关系
| 嵌入模型 | 输出维度 | 推荐存储后端 |
|---------|---------|-------------|
| BAAI/bge-m3 | 1024 | PostgreSQL, Milvus, OpenSearch |
| text-embedding-3-large | 3072 | PostgreSQL, Milvus, OpenSearch |
| text-embedding-3-small | 1536 | PostgreSQL, Milvus, OpenSearch |
| voyageai | 可配置 | PostgreSQL, Milvus |
资料来源：[README.md:1-50]()
## 交互式配置向导
LightRAG 提供了交互式配置向导简化存储后端配置：
```bash
# 基础环境配置（LLM、嵌入模型、重排序模型）
make env-base
# 存储后端配置
make env-storage
# 服务器配置（端口、认证、SSL）
make env-server
# 安全审计
make env-security-check
```
配置向导会更新 `.env` 文件，必要时生成 `docker-compose.final.yml`。使用 `*-rewrite` 目标可强制重新生成向导管理的配置块。资料来源：[README.md:1-60]()
## 迁移与切换
### 跨存储后端迁移
不同存储后端之间迁移需要导出数据后导入：
1. **导出当前数据**：使用 LightRAG Core API 导出知识图谱数据
2. **清理目标存储**：确保目标存储为空或已配置
3. **导入数据**：使用 `ainsert_custom_kg` 批量导入
v1.4.14 优化了大批量导入场景的图操作性能。资料来源：[README.md:1-30]()
### 切换嵌入模型流程
当需要更换嵌入模型时：
1. 停止所有 LightRAG 服务
2. 删除现有向量相关表/集合
3. 更新 `.env` 中的嵌入模型配置
4. 重新索引所有文档
## 常见问题
### 文档去重问题
用户反馈：同名不同内容的文档难以区分。LightRAG 支持内容哈希去重机制，上传时会检测内容重复。v1.4.10 增强了文档去重跟踪功能。资料来源：[README.md:1-30]()
### 反向代理兼容性问题
使用子路径部署时，部分资源使用绝对路径可能导致加载失败。确保 WebUI 构建时正确配置了运行时路径前缀。资料来源：[lightrag_webui/src/lib/runtimeConfig.ts:1-40]()
## 相关文档
- [快速开始指南](./README.md)
- [交互式配置向导](./docs/InteractiveSetup.md)
- [Milvus 配置指南](./docs/MilvusConfigurationGuide.md)
- [Docker 部署指南](./docs/DockerDeployment.md)
- [离线部署指南](./docs/OfflineDeployment.md)
- [使用 Core 编程](./docs/ProgramingWithCore.md)
- [高级功能](./docs/AdvancedFeatures.md)
## 参见
- [LightRAG Server](./LightRAG-API-Server.md) - 完整 API 服务器文档
- [评估与部署](./docs/Evaluation.md) - 存储性能评估方法
---
## 文本分块策略
### 相关页面
相关主题：[系统架构](#page-architecture), [知识图谱提取](#page-knowledge-graph), [多模态文档处理](#page-multimodal)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/chunker/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/__init__.py)
- [lightrag/chunker/recursive_character.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/recursive_character.py)
- [lightrag/chunker/semantic_vector.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/semantic_vector.py)
- [lightrag/chunker/paragraph_semantic.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/paragraph_semantic.py)
- [lightrag/chunker/token_size.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/token_size.py)
- [docs/ParagraphSemanticChunking.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ParagraphSemanticChunking.md)
- [docs/AsymmetricEmbedding.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AsymmetricEmbedding.md)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
# 文本分块策略
## 概述
文本分块（Text Chunking）是 LightRAG 系统中文档处理的核心环节之一。原始文档被切分成较小的文本块后，系统会对每个块进行向量化处理，并建立与知识图谱的关联关系。合理的分块策略直接影响检索质量和查询准确性。
LightRAG 支持多种分块策略，开发者可根据文档类型和业务需求选择合适的方案。分块策略在文档索引阶段生效，通过 `chunking_strategy` 参数指定。资料来源：[lightrag/chunker/__init__.py:1-50]()
## 分块策略类型
LightRAG 提供了以下几种内置分块策略，每种策略适用于不同的场景：
| 策略名称 | 描述 | 适用场景 |
|---------|------|---------|
| `TokenSize` | 基于 token 数量的固定大小分块 | 通用场景，默认策略 |
| `Recursive` | 递归分块，优先保持语义完整性 | 代码、格式化文档 |
| `SemanticVector` | 基于语义向量相似度的智能分块 | 长文本、学术论文 |
| `Paragraph` | 基于段落语义边界的分块 | 自然语言文档 |
| `RecursiveCharacter` | 基于字符的递归分块 | 纯文本处理 |
资料来源：[lightrag/chunker/__init__.py:10-30]()
### TokenSize 分块策略
`TokenSize` 是最基础的分块策略，按照预设的 token 数量将文本切分成固定大小的块。这种方式简单高效，适合大多数通用场景。
**核心参数：**
| 参数名 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| `chunk_token_size` | int | 256 | 每个文本块的 token 数量上限 |
| `overlap_token_size` | int | 50 | 块之间的重叠 token 数量 |
```python
# 示例配置
from lightrag import LightRAG, ChunkingStrategy
rag = LightRAG(
chunking_strategy=ChunkingStrategy(
name="TokenSize",
chunk_token_size=512,
overlap_token_size=100
)
)
```
资料来源：[lightrag/chunker/token_size.py:1-40]()
### Recursive 分块策略
`Recursive` 分块策略采用递归方式按层次切分文本，优先保持语义单元的完整性。它会尝试按段落、句子、单词的顺序逐步切分，直到每个块符合大小要求。
**工作原理：**
1. 首先尝试按最大分隔符（如换行符）切分
2. 如果切分后的块过大，则使用次级分隔符继续切分
3. 重复此过程直到所有块符合大小限制
```mermaid
graph TD
A[原始文本] --> B{文本是否超过限制?}
B -->|是| C[按一级分隔符切分]
C --> D{子块是否超过限制?}
D -->|是| E[按二级分隔符切分]
D -->|否| F[保留子块]
E --> G{子块是否超过限制?}
G -->|是| H[按三级分隔符切分]
G -->|否| I[保留子块]
H --> J[...]
F --> K[输出文本块]
I --> K
J --> K
```
资料来源：[lightrag/chunker/recursive_character.py:1-60]()
### SemanticVector 分块策略
`SemanticVector` 分块策略利用语义向量相似度来识别文档中的主题边界。当相邻段落之间的语义相似度低于阈值时，系统将其视为新的主题起点，从而实现智能分块。
**适用场景：**
- 长篇学术论文
- 技术文档
- 包含多个主题的新闻文章
**优势：**
- 自动识别主题边界
- 保持语义连贯性
- 减少无关上下文干扰
资料来源：[lightrag/chunker/semantic_vector.py:1-80]()
### Paragraph 分块策略
`Paragraph` 分块策略基于段落语义边界进行切分，保留完整的段落内容。这种策略特别适合处理自然语言文档，能够保持段落的语义完整性。
**特点：**
- 以段落为基本单位
- 保留段落间的自然分隔
- 适用于叙事性、说明性文档
资料来源：[lightrag/chunker/paragraph_semantic.py:1-50]()
## 配置选项
### 全局分块配置
在初始化 LightRAG 实例时，可以通过 `chunking_strategy` 参数指定分块策略：
```python
from lightrag import LightRAG, ChunkingStrategy
# 使用 TokenSize 策略（默认）
rag = LightRAG(
chunking_strategy=ChunkingStrategy(name="TokenSize")
)
# 使用 Recursive 策略
rag = LightRAG(
chunking_strategy=ChunkingStrategy(name="Recursive")
)
# 使用 Paragraph 策略
rag = LightRAG(
chunking_strategy=ChunkingStrategy(name="Paragraph")
)
```
### API 配置参数
通过 API 接口上传文档时，可在请求中指定分块策略：
| 参数 | 类型 | 说明 |
|-----|------|------|
| `chunking_strategy` | string | 分块策略名称 |
| `chunk_token_size` | int | 每个块的 token 上限 |
| `overlap_token_size` | int | 块间重叠 token 数 |
资料来源：[lightrag_webui/src/api/lightrag.ts:1-100]()
## 文件类型与分块处理
LightRAG 根据文件类型自动应用适当的处理流程。系统支持以下文件类型的分块处理：
| 文件类型 | MIME 类型 | 分块支持 |
|---------|-----------|---------|
| 纯文本 | `text/plain` | ✅ 完全支持 |
| Markdown | `text/markdown` | ✅ 完全支持 |
| Python | `.py` | ✅ 完全支持 |
| JavaScript | `.js`, `.ts` | ✅ 完全支持 |
| HTML | `text/html` | ✅ 完全支持 |
| PDF | `application/pdf` | ✅ 通过多模态管道 |
| Word | `.docx` | ✅ 通过多模态管道 |
| Excel | `.xlsx` | ✅ 通过多模态管道 |
| PPT | `.pptx` | ✅ 通过多模态管道 |
资料来源：[lightrag_webui/src/lib/constants.ts:1-50]()
## 分块策略与检索质量
### 块大小对检索的影响
| 块大小 | 优势 | 劣势 |
|-------|------|------|
| 过小 (< 100 tokens) | 检索精确度高 | 可能丢失上下文信息 |
| 中等 (200-500 tokens) | 平衡精确度与上下文 | 需要更多检索步骤 |
| 过大 (> 1000 tokens) | 保留完整上下文 | 引入噪声，降低精确度 |
### 选择策略的建议
**代码类文档：**
- 推荐使用 `Recursive` 策略
- 保留代码块、函数边界的完整性
- 适当增大块大小以保持代码逻辑
**自然语言文档：**
- 推荐使用 `Paragraph` 或 `SemanticVector` 策略
- 保持段落语义完整
- 自动识别主题边界
**结构化数据：**
- 推荐使用 `TokenSize` 策略
- 固定大小便于批量处理
- 通过重叠 token 保持连续性
## 常见问题与解决方案
### 问题一：同名文档区分
**问题描述：** 上传多个同名但内容不同的文档时，无法区分来源。
**解决方案：** LightRAG 通过文档 ID 追踪文档来源，而非文件名。查询时可通过 `file_path` 字段获取源文件信息。
```python
# 查询时获取源文件信息
result = await rag.aquery(
query="查找关于合同的信息",
only_need_context=True # 仅返回检索上下文
)
# 返回结果中包含 file_path 字段
```
> 相关讨论：GitHub Issue #3158 讨论了同名文档区分问题
资料来源：[lightrag_webui/src/api/lightrag.ts:50-80]()
### 问题二：分块破坏语义完整性
**问题描述：** 固定大小分块可能将一句话或公式切分到不同块中。
**解决方案：**
1. 使用 `Recursive` 策略优先保持语义边界
2. 增大 `overlap_token_size` 参数增加块间重叠
3. 对于公式和表格，考虑使用多模态管道处理
### 问题三：PDF 文件分块失败
**问题描述：** 受密码保护的 PDF 文件无法正常解析。
**解决方案：**
- 确保 PDF 文件未设置打开密码
- v1.4.12 版本已修复权限限制类 PDF 的处理问题
## 分块与知识图谱的关系
文档经过分块后，每个文本块会被：
1. **向量化** - 使用嵌入模型生成向量表示
2. **实体抽取** - 从块中提取实体和关系
3. **存储** - 分别存入向量库和图数据库
```mermaid
graph LR
A[原始文档] --> B[分块处理]
B --> C[文本块 1]
B --> D[文本块 2]
B --> E[文本块 N]
C --> F[向量嵌入]
D --> G[向量嵌入]
E --> H[向量嵌入]
C --> I[实体抽取]
D --> J[实体抽取]
E --> K[实体抽取]
F --> L[(向量数据库)]
G --> L
H --> L
I --> M[(图数据库)]
J --> M
K --> M
```
分块策略直接影响实体抽取的质量。较大的块可能包含更多上下文，但也会增加抽取难度；较小的块则可能丢失实体间的关系信息。
## 进阶配置
### 自定义分块参数
```python
from lightrag import LightRAG, ChunkingStrategy
# 自定义 TokenSize 分块
custom_chunking = ChunkingStrategy(
name="TokenSize",
chunk_token_size=1024, # 增大块大小
overlap_token_size=200 # 增加重叠
)
rag = LightRAG(chunking_strategy=custom_chunking)
```
### 异步批量处理
对于大规模文档集，LightRAG 支持异步批量插入：
```python
# 批量插入文档
await rag.ainsert_many(
documents=document_list,
chunking_strategy=ChunkingStrategy(name="Recursive")
)
```
## 相关文档
- [段落语义分块详解](./ParagraphSemanticChunking.md) - 深入了解 Paragraph 策略原理
- [非对称嵌入](./AsymmetricEmbedding.md) - 了解查询与文档嵌入的差异
- [核心编程指南](./ProgramingWithCore.md) - 完整的 API 使用说明
- [高级特性](./AdvancedFeatures.md) - 多模态处理和评估功能
## 参考资料
- LightRAG 官方仓库：https://github.com/HKUDS/LightRAG
- 分块策略源码：[lightrag/chunker/](https://github.com/HKUDS/LightRAG/tree/main/lightrag/chunker)
---
## 知识图谱提取
### 相关页面
相关主题：[系统架构](#page-architecture), [文本分块策略](#page-text-chunking), [存储后端](#page-storage-backends)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/utils_graph.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/utils_graph.py) - 知识图谱工具函数
- [lightrag/prompt.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/prompt.py) - 实体关系提取提示词
- [lightrag/llm_roles.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm_roles.py) - LLM角色配置
- [docs/Algorithm.md](https://github.com/HKUDS/LightRAG/blob/main/docs/Algorithm.md) - 算法与提取流程
- [examples/insert_custom_kg.py](https://github.com/HKUDS/LightRAG/blob/main/examples/insert_custom_kg.py) - 自定义知识图谱插入示例
- [examples/graph_visual_with_html.py](https://github.com/HKUDS/LightRAG/blob/main/examples/graph_visual_with_html.py) - HTML可视化示例
- [examples/graph_visual_with_neo4j.py](https://github.com/HKUDS/LightRAG/blob/main/examples/graph_visual_with_neo4j.py) - Neo4j可视化示例
- [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md) - 3D图谱查看器
- [lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts) - 图谱节点颜色配置
# 知识图谱提取
本文档详细介绍了 LightRAG 中知识图谱提取（Knowledge Graph Extraction）功能的设计原理、提取流程、配置选项以及使用方式。知识图谱提取是 LightRAG 区别于传统 RAG 系统的核心能力之一，通过大语言模型从文档中自动识别实体与关系，构建结构化的知识网络，从而支持更精准的语义检索与问答。
## 概述
### 什么是知识图谱提取
知识图谱提取是指使用大语言模型（LLM）从非结构化文档中自动识别和抽取**实体（Entity）**与**关系（Relation）**，并将抽取结果存储为图结构数据的过程。与传统的向量检索仅关注文本片段的相似性不同，知识图谱能够捕捉实体之间的语义关联，形成"实体-关系-实体"的三元组结构。
在 LightRAG 中，文档经过分块处理后，每个文本块会经过 LLM 分析，识别出其中的实体节点及其属性、关系边及其类型。随后，这些节点和边被持久化到图数据库中，支持后续的局部检索（Local Search）和全局检索（Global Search）操作。
### 为什么需要知识图谱提取
传统的 RAG 系统在处理复杂查询时存在明显局限：当用户问题涉及多个实体之间的关系推理时，纯向量检索难以有效捕捉跨文档的关联信息。LightRAG 通过知识图谱提取解决了这一问题：
- **结构化语义表示**：将文本中的隐含关系显式化为图结构，便于精确查询
- **多跳推理支持**：支持多跳查询，如"某实体的邻居的邻居"
- **可解释性增强**：检索结果可以追溯到具体的实体和关系路径
- **检索精度提升**：结合向量检索和图检索，显著提高混合查询的准确率
资料来源：[README.md:1-50](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 系统架构
### 整体数据流
```mermaid
graph TD
A[文档输入] --> B[文本分块]
B --> C{多模态处理}
C -->|启用| D[RAG-Anything解析]
C -->|禁用| E[纯文本块]
D --> F[文本块+图片+表格]
E --> G[实体关系提取]
F --> G
G --> H[实体节点]
G --> I[关系边]
H --> J[图数据库存储]
I --> J
H --> K[向量数据库存储]
K --> J
J --> L[局部检索]
J --> M[全局检索]
L --> N[查询结果聚合]
M --> N
N --> O[LLM生成答案]
```
### 实体关系提取组件
知识图谱提取的核心组件位于 `lightrag/` 目录下，主要包括：
| 组件 | 文件路径 | 功能描述 |
|------|----------|----------|
| 实体关系提取 | `prompt.py` | 定义 LLM 提取实体和关系的提示词模板 |
| 图谱工具函数 | `utils_graph.py` | 提供图谱构建、查询、合并等底层操作 |
| LLM 角色配置 | `llm_roles.py` | 配置提取任务使用的 LLM 模型和参数 |
| 自定义插入 | `insert_custom_kg.py` | 支持批量导入外部知识图谱数据 |
资料来源：[lightrag/prompt.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/prompt.py)、[lightrag/utils_graph.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/utils_graph.py)
## 提取流程详解
### 文本分块策略
文档在进入实体提取之前需要先进行分块处理。LightRAG 支持多种分块策略，可通过配置参数 `chunk_token_size` 和 `chunk_method` 进行调整：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `chunk_token_size` | 每个文本块的 token 数量上限 | 1200 |
| `chunk_method` | 分块方法：`Recursive`, `Sentence`, `Paragraph` 等 | `Recursive` |
| `chunk_overlap` | 相邻块之间的重叠 token 数 | 100 |
分块策略的选择直接影响实体提取的质量：较小的块有助于提取细粒度实体，但可能丢失上下文信息；较大的块则相反。建议根据文档类型和领域特点进行调优。
资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md) - 分块配置说明
### 实体识别与提取
每个文本块被发送给 LLM 进行实体提取。LightRAG 使用精心设计的提示词模板，引导模型识别以下信息：
**实体节点属性：**
- `entity_name`：实体名称（唯一标识）
- `entity_type`：实体类型（如：人物、地点、概念、事件等）
- `entity_description`：实体的简要描述
**关系边属性：**
- `src_entity`：源实体名称
- `tgt_entity`：目标实体名称
- `relation`：关系类型（如：属于、工作于、创建于等）
- `weight`：关系强度权重（1-10）
- `relation_description`：关系的详细描述
```mermaid
graph LR
A[文本块] --> B[LLM实体提取]
B --> C[实体节点列表]
B --> D[关系边列表]
C --> E[去重合并]
D --> E
E --> F[知识图谱存储]
```
### 实体类型映射
LightRAG 支持多语言实体类型识别，并提供自动类型映射功能。系统定义了标准的实体类型及其同义词：
| 标准类型 | 中文同义词 | 英文同义词 |
|----------|-----------|-----------|
| `person` | 人物、人类、人 | person, people, human |
| `concept` | 概念、对象、类别 | concept, object, type, model |
| `artifact` | 人工制品、技术、产品 | artifact, technology, product |
| `location` | 地点、地理、位置 | location, geography, geo |
| `organization` | 组织、机构、公司 | org, company, organization |
| `event` | 事件、活动 | event, activity |
| `method` | 方法、过程 | method, process |
| `naturalobject` | 自然对象、物质 | natural, phenomena, substance |
| `data` | 数据、数值 | data, figure, value |
| `content` | 内容、作品 | content, book, video |
资料来源：[lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts)
## 配置与使用
### LLM 模型配置
实体提取对 LLM 的能力要求较高，LightRAG 提供了角色级别的 LLM 配置，可以为提取任务单独指定模型：
| 角色 | 说明 | 推荐配置 |
|------|------|----------|
| `EXTRACT` | 实体关系提取 | 32B+ 参数模型，32K+ 上下文 |
| `QUERY` | 查询理解和答案生成 | 同上或更强 |
| `KEYWORDS` | 关键词提取 | 中等规模模型 |
| `VLM` | 多模态视觉理解 | 支持视觉的模型 |
**配置示例（.env）：**
```bash
# EXTRACT 角色 LLM 配置
LIGHTRAG_LLM_MODEL=your-extract-model
LIGHTRAG_LLM_BASE_URL=https://api.example.com/v1
# 向量化和重排序模型配置
LIGHTRAG_EMBED_MODEL=bge-m3
LIGHTRAG_EMBED_DIM=1024
LIGHTRAG_RERANK_MODEL=bge-reranker-v2-m3
```
> **注意**：建议在索引阶段使用至少 32B 参数的模型，查询阶段可使用更强或专门的推理模型。提取阶段不建议使用推理模型（如 o1、DeepSeek-R1 等），因为它们可能过度思考导致提取结果不稳定。
资料来源：[README.md - LLM选择指南](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### 自定义知识图谱插入
对于已有结构化知识的场景，LightRAG 支持通过 `insert_custom_kg` 功能批量导入外部知识图谱：
```python
from lightrag import LightRAG, QueryParam
# 初始化 LightRAG 实例
rag = LightRAG(
working_dir="./lightrag_storage",
llm_model="gpt-4o",
embedding_model="text-embedding-3-large"
)
# 定义要插入的知识图谱数据
entities = [
{"entity_name": "LightRAG", "entity_type": "concept", "description": "轻量级RAG框架"},
{"entity_name": "HKUDS", "entity_type": "organization", "description": "香港大学数据科学研究组"}
]
relations = [
{"src_entity": "LightRAG", "tgt_entity": "HKUDS", "relation": "由开发", "weight": 10}
]
# 插入自定义知识图谱
rag.insert_custom_kg(entities, relations)
```
该功能已针对大规模导入进行了性能优化，支持批量图操作以提高效率。
资料来源：[examples/insert_custom_kg.py](https://github.com/HKUDS/LightRAG/blob/main/examples/insert_custom_kg.py)
### 知识图谱存储后端
LightRAG 支持多种图数据库作为知识图谱的存储后端：
| 存储类型 | 支持状态 | 特点 |
|----------|---------|------|
| **Neo4j** | 生产可用 | 功能完整，支持 Cypher 查询 |
| **MongoDB** | 生产可用 | 一体化存储，支持向量存储 |
| **PostgreSQL** | 生产可用 | 关系型+向量扩展（pgvector） |
| **OpenSearch** | 生产可用 | 全量存储支持（KV+Vector+Graph+DocStatus） |
| **Dgraph** | 历史支持 | 已弃用 |
选择存储后端时需考虑：部署复杂度、社区支持、扩展性需求等因素。MongoDB 和 OpenSearch 提供了一体化存储方案，可减少系统复杂度。
资料来源：[README.md - v1.4.11 发布说明](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 知识图谱可视化
### WebUI 可视化
LightRAG Server 提供了交互式知识图谱可视化界面，支持：
- 多种重力布局算法
- 节点类型筛选和查询
- 子图过滤和导出
- 节点/边的属性查看
界面中不同类型的实体节点以不同颜色区分，便于直观理解知识图谱的结构。
资料来源：[README.md - LightRAG Server](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### 3D 图谱查看器
LightRAG 提供了独立的 3D 图谱可视化工具：
```bash
pip install lightrag-hku[tools]
lightrag-viewer
```
**功能特性：**
- 高性能 3D 渲染（基于 ModernGL）
- 多种布局算法：Spring、Circular、Shell、Random
- 社区检测和可视化
- 键盘+鼠标交互控制
**控制方式：**
| 操作 | 说明 |
|------|------|
| W/S/A/D | 相机前后左右移动 |
| Q/E | 相机上下移动 |
| 鼠标右键拖拽 | 调整视角 |
| 左键点击 | 选中节点 |
资料来源：[lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
### 自定义可视化集成
LightRAG 支持导出图数据用于第三方可视化工具：
**Neo4j 导出示例：**
```python
import json
# 获取图谱数据
graph_data = rag.get_graph_data()
# 导出为 Neo4j 兼容格式
with open("graph_for_neo4j.json", "w", encoding="utf-8") as f:
json.dump(graph_data, f, ensure_ascii=False, indent=2)
```
示例文件：`examples/graph_visual_with_neo4j.py` 提供了完整的 Neo4j 可视化集成代码。
资料来源：[examples/graph_visual_with_neo4j.py](https://github.com/HKUDS/LightRAG/blob/main/examples/graph_visual_with_neo4j.py)、[examples/graph_visual_with_html.py](https://github.com/HKUDS/LightRAG/blob/main/examples/graph_visual_with_html.py)
## 查询模式与提取的配合
### 局部检索（Local Search）
当查询涉及特定实体时，局部检索首先定位该实体节点，然后沿着关系边探索其邻居节点：
```mermaid
graph TD
A[用户查询] --> B[关键词提取]
B --> C[定位目标实体]
C --> D[探索一层邻居]
D --> E[探索二层邻居]
E --> F[收集关联文本块]
F --> G[返回上下文]
```
### 全局检索（Global Search）
当查询需要跨领域综合分析时，全局检索使用社区检测算法（如 Leiden）将知识图谱划分为多个社区，每个社区代表一个语义聚类：
```mermaid
graph TD
A[用户查询] --> B[关键词提取]
B --> C[社区检测]
C --> D[选择相关社区]
D --> E[收集社区内实体]
E --> F[聚合社区描述]
F --> G[返回综合上下文]
```
### 混合模式（Mix Mode）
v1.4.9 引入的混合模式结合了局部和全局检索的优势，通过重排序（Reranker）机制动态调整检索结果的优先级：
```mermaid
graph TD
A[用户查询] --> B[局部检索]
A --> C[全局检索]
A --> D[向量检索]
B --> E[结果合并]
C --> E
D --> E
E --> F[Reranker重排]
F --> G[Top-K 结果]
G --> H[LLM生成答案]
```
启用重排序后，建议将默认查询模式设置为 `mix`，以获得最佳检索效果。
资料来源：[README.md - v1.4.9 发布说明](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 常见问题与故障排除
### 实体提取质量不佳
**症状**：检索结果不准确，实体遗漏或错误关联。
**排查步骤**：
1. 检查 LLM 模型配置是否正确加载
2. 确认 `chunk_token_size` 是否适合文档长度（过小的块可能丢失上下文）
3. 查看 `lightrag/prompt.py` 中的提示词是否与领域匹配
4. 考虑定制提示词模板以适应特定领域术语
**解决方案**：自定义 `prompt.py` 中的提取提示词，针对特定领域优化实体类型和关系描述。
资料来源：[lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md) - 提示词优化建议
### 文档区分问题
**症状**：同名文档的内容被混淆。
**背景**：这是社区中反馈较多的问题（参见 Issue #3158）。当前系统通过 `file_path` 字段区分文档，但由于存储设计限制，同名文件可能覆盖或混淆。
**建议方案**：
1. 确保上传文件时使用唯一命名（包括相对路径信息）
2. 利用文档上传 API 时指定唯一的 `file_key`
3. 关注后续版本更新，社区正在讨论改进方案
资料来源：[Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158) - 文档区分问题讨论
### 知识图谱更新与删除
v1.4.10 引入了文档删除功能，删除文档时会自动触发相关知识图谱的重新生成，确保索引一致性：
```python
# 删除文档并自动更新知识图谱
rag.delete_document(document_id)
```
> **注意**：删除操作会触发完整的知识图谱重建，对于大型知识库可能需要较长时间。
资料来源：[README.md - v1.4.10 发布说明](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### 大规模导入性能优化
对于需要导入海量知识图谱数据的场景，`insert_custom_kg` 函数已进行批量操作优化：
- 启用批量图操作以减少数据库往返
- 支持增量导入避免重复处理
- 建议分批提交（每批 1000-5000 条边）
资料来源：[README.md - v1.4.14 性能优化说明](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 性能考量
### 模型选择建议
| 场景 | 推荐模型 | 参数规模 | 上下文长度 |
|------|---------|----------|-----------|
| 开源模型提取 | Qwen3-30B-A3B | 30B | 32K+ |
| 开源模型提取 | DeepSeek-V3 | 236B | 128K |
| GPT 系列 | GPT-4o | - | 128K |
| Claude 系列 | Claude-3.5-Sonnet | - | 200K |
v1.4.9 版本增强了开源模型的实体提取准确性，特别针对 Qwen3-30B-A3B 进行了优化。
### Token 预算控制
LightRAG 提供了统一的 Token 预算控制系统，防止单次查询消耗过多上下文：
| 参数 | 说明 | 用途 |
|------|------|------|
| `max_entity_tokens` | 实体上下文最大 Token 数 | 控制实体数量 |
| `max_relation_tokens` | 关系上下文最大 Token 数 | 控制关系数量 |
| `max_total_tokens` | 总 Token 预算 | 全局上限 |
资料来源：[lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts) - QueryRequest 类型定义
## 相关文档
- [LightRAG 核心编程指南](./ProgramingWithCore.md) - Core API 完整参考
- [高级功能](./AdvancedFeatures.md) - Token 追踪、导出、Langfuse 集成
- [多模态文档处理](./AdvancedFeatures.md#multimodal) - 图片、表格、公式解析
- [交互式部署向导](./InteractiveSetup.md) - 一键部署配置
- [算法详解](./Algorithm.md) - 检索和查询算法原理
## 参考资料
- LightRAG 官方仓库：https://github.com/HKUDS/LightRAG
- RAG-Anything 多模态扩展：https://github.com/HKUDS/RAG-Anything
- VideoRAG 视频理解：https://github.com/HKUDS/VideoRAG
---
## 多模态文档处理
### 相关页面
相关主题：[文本分块策略](#page-text-chunking), [API服务器与WebUI](#page-api-server), [核心库编程](#page-programming-core)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
- [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
- [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
# 多模态文档处理
## 概述
LightRAG 从 v1.5.0 版本开始全面支持多模态文档处理，能够充分利用文档中的图像、表格和公式来回答查询。所有 RagAnything 的多模态处理能力已合并到 LightRAG 中，用户可以在不依赖外部系统的情况下完成复杂的文档解析和检索任务。
多模态处理功能允许 LightRAG 不仅索引文本内容，还能理解并检索嵌入在文档中的视觉元素（如图片、图表）和结构化数据（如表格、公式）。这对于处理技术文档、学术论文、商业报告等包含丰富多媒体内容的文件尤为重要。
资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 支持的文档格式
LightRAG 多模态处理支持多种常见的文档格式，具体支持的文件类型如下：
### 文本类文档
| 文件类型 | MIME 类型 | 说明 |
|---------|----------|------|
| Markdown | - | 轻量级标记语言文档 |
| PDF | application/pdf | 便携式文档格式 |
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word 文档 (.docx) |
| PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | Microsoft PowerPoint 文档 (.pptx) |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | Microsoft Excel 文档 (.xlsx) |
### 代码类文档
LightRAG 支持以下代码文件格式的纯文本处理：
| 文件类型 | 扩展名 |
|---------|-------|
| SQL 脚本 | .sql |
| Shell 脚本 | .sh |
| Python | .py |
| Java | .java |
| JavaScript | .js |
| TypeScript | .ts |
| C/C++ | .c, .cpp, .h, .hpp |
| Go | .go |
| Ruby | .rb |
| PHP | .php |
| CSS/SCSS | .css, .scss, .less |
资料来源：[lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
## 处理架构
### 整体架构流程
```mermaid
graph TD
A[用户上传文档] --> B{文件类型检测}
B -->|PDF/Office| C[外部解析服务]
B -->|纯文本| D[直接文本提取]
C -->|MinerU| E[MinerU 解析引擎]
C -->|Docling| F[Docling 解析引擎]
E --> G[结构化内容提取]
F --> G
G --> H[文本块分块]
G --> I[图像提取]
G --> J[表格提取]
G --> K[公式提取]
H --> L[Embedding 向量化]
I --> M[图像描述生成]
J --> N[表格结构化]
K --> O[公式 LaTeX 转换]
L --> P[向量数据库存储]
M --> Q[多模态上下文索引]
N --> Q
O --> Q
P --> R[知识图谱构建]
Q --> R
```
### 解析服务集成
LightRAG 通过外部解析服务实现多模态文档处理，主要支持两种解析引擎：
| 解析引擎 | 特点 | 适用场景 |
|---------|------|---------|
| **MinerU** | 高精度 PDF 解析，支持复杂布局 | 技术文档、学术论文 |
| **Docling** | 统一的文档解析接口，支持多种格式 | 综合性文档处理 |
解析服务需要独立部署，LightRAG 通过 API 接口与这些服务通信。用户可以在配置中指定使用的解析服务及其连接参数。
资料来源：[docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
## 多模态索引流程
### VLM 角色配置
LightRAG 支持角色特定的 LLM 配置，其中 VLM（视觉语言模型）角色专门用于处理多模态内容的理解和描述生成。
```python
# VLM 角色配置示例
role_llm_config = {
"VLM": {
"binding": "openai", # VLM 提供商
"model": "gpt-4o", # 视觉语言模型
"api_key": "your-api-key",
"timeout": 120,
"max_async": 10
}
}
```
### 多模态上下文索引
多模态处理的核心是将提取的图像、表格、公式等非文本元素转换为可检索的上下文。处理流程如下：
1. **图像处理**：提取文档中的图片，使用 VLM 生成图像描述（alt-text），将描述文本与原始图像关联存储
2. **表格处理**：保留表格的行列结构信息，支持按单元格内容检索
3. **公式处理**：将数学公式转换为 LaTeX 格式，便于在检索时重建原始公式
资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 查询模式与多模态支持
### 查询模式类型
LightRAG 提供多种查询模式，多模态内容可以在所有模式下被检索和使用：
| 模式 | 描述 | 多模态支持 |
|-----|------|-----------|
| `naive` | 纯向量检索 | ✅ 支持 |
| `local` | 基于实体邻居的检索 | ✅ 支持 |
| `global` | 基于关系网络的检索 | ✅ 支持 |
| `hybrid` | 本地+全局混合检索 | ✅ 支持 |
| `mix` | 混合模式（含重排序） | ✅ 推荐 |
| `bypass` | 仅使用 LLM | ✅ 支持 |
查询请求示例：
```typescript
const queryRequest: QueryRequest = {
query: "文档中关于某图表的说明是什么？",
mode: 'mix', // 推荐使用 mix 模式
top_k: 5, // 检索结果数量
chunk_top_k: 10, // 重排序后保留数量
response_type: "Multiple Paragraphs",
stream: true
};
```
资料来源：[lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## 配置说明
### 环境变量配置
启用多模态处理需要在 `.env` 文件中进行以下配置：
```bash
# VLM 处理开关
VLM_PROCESS_ENABLE=true
# VLM 提供商配置
VLM_BINDING=openai
VLM_MODEL=gpt-4o
VLM_API_KEY=your-api-key
VLM_HOST=https://api.openai.com/v1
# 解析服务配置（可选）
PARSER_SERVICE=mineru # 或 docling
PARSER_SERVICE_URL=http://localhost:8080
```
### 交互式设置向导
对于不熟悉手动配置的用户，LightRAG 提供了交互式设置向导来简化配置过程：
```bash
# 基础环境配置
make env-base
# 存储后端配置
make env-storage
# 服务器配置
make env-server
```
运行设置向导后，系统会引导用户完成 LLM、Embedding、重排序模型以及存储后端的配置。
资料来源：[docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
## WebUI 使用指南
### 文件上传
通过 LightRAG WebUI 上传文档时，系统会自动识别文件类型并调用相应的解析器：
1. 访问 LightRAG Server 的 WebUI 界面
2. 点击上传按钮或拖拽文件到上传区域
3. 选择要上传的文档（支持多选）
4. 系统自动进行多模态内容提取
### 文档管理
上传后的文档可以在 WebUI 中进行管理：
```typescript
interface DocStatusResponse {
id: string; // 文档唯一标识
file_name: string; // 文件名
file_path: string; // 文件路径
status: DocStatus; // 处理状态
total_chunks: number; // 分块数量
error_msg?: string; // 错误信息
}
```
支持按状态筛选文档列表，便于跟踪处理进度和排查问题。
资料来源：[lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## 常见问题与解决方案
### 文档名称区分问题
社区反馈（[Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)）：如何区分名称相同但内容不同的文档？
**解决方案**：LightRAG 使用文档的唯一标识符（UUID）来区分文档，文件名仅作为显示用途。如果需要按文件名追踪文档，建议在上传时添加额外元数据或使用文件路径中的目录结构来区分。
### 多模态支持集成方式
社区反馈（[Issue #2642](https://github.com/HKUDS/LightRAG/issues/2642)）：如何向 LightRAG 添加多模态支持？
**说明**：从 v1.5.0 开始，RagAnything 的所有核心功能已合并到 LightRAG 中。用户无需额外集成，直接通过配置 VLM 即可启用多模态处理能力。
### 解析服务部署
| 问题 | 解决方案 |
|-----|---------|
| 解析服务连接失败 | 检查服务 URL 和网络连通性 |
| PDF 解析结果不完整 | 确认 PDF 未加密或有读取权限 |
| 图片内容未提取 | 确认 VLM 模型配置正确且可用 |
## 评估与测试
### 使用示例文档进行测试
LightRAG 提供了用于评估的示例文档集，位于 `lightrag/evaluation/sample_documents/` 目录：
| 文档 | 内容 |
|-----|------|
| 01_lightrag_overview.md | LightRAG 框架概述 |
| 02_rag_architecture.md | RAG 系统组件 |
| 03_lightrag_improvements.md | LightRAG 改进对比 |
| 04_supported_databases.md | 支持的向量数据库 |
| 05_evaluation_and_deployment.md | 评估与部署 |
评估步骤：
```bash
# 1. 将示例文档索引到 LightRAG
# 2. 运行评估脚本
python lightrag/evaluation/eval_rag_quality.py
# 3. 预期结果：每个问题的 RAGAS 分数约 91-100%
```
资料来源：[lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
## 性能优化建议
### 并行处理配置
```bash
# 最大并行插入数
MAX_PARALLEL_INSERT=32
# 异步操作配置
MAX_ASYNC=128
# Embedding 批处理数量
EMBEDDING_BATCH_NUM=100
```
### 存储后端选择
对于大规模多模态文档处理，推荐使用支持全部四种存储类型的统一后端：
| 存储类型 | 说明 | 推荐后端 |
|---------|------|---------|
| KV 存储 | 键值对存储 | PostgreSQL, MongoDB, OpenSearch |
| 向量存储 | Embedding 存储 | PostgreSQL (pgvector), Milvus, Qdrant |
| 图存储 | 知识图谱关系 | Neo4j, OpenSearch |
| 文档状态 | 处理状态跟踪 | PostgreSQL, MongoDB |
资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## 相关文档
- [高级功能指南](./AdvancedFeatures.md) - 包含多模态配置的详细说明
- [交互式设置向导](./InteractiveSetup.md) - 使用向导完成环境配置
- [编程接口参考](./ProgramingWithCore.md) - Core API 的完整使用说明
- [离线部署指南](./OfflineDeployment.md) - 无法访问外网环境下的部署方法
- [LightRAG Server](./LightRAG-API-Server.md) - 服务器部署与 API 使用
---
## API服务器与WebUI
### 相关页面
相关主题：[安装指南](#page-installation), [核心库编程](#page-programming-core)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/api/lightrag_server.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/lightrag_server.py)
- [lightrag/api/routers/document_routes.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/routers/document_routes.py)
- [lightrag/api/routers/query_routes.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/routers/query_routes.py)
- [lightrag/api/routers/graph_routes.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/routers/graph_routes.py)
- [lightrag_webui/src/App.tsx](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/App.tsx)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/src/lib/pathPrefix.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/pathPrefix.ts)
- [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
- [docs/FrontendBuildGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/FrontendBuildGuide.md)
# API服务器与WebUI
LightRAG 提供了一套完整的 API 服务器和 Web 用户界面，用于文档索引、知识图谱可视化和 RAG 查询。本页详细介绍这两个核心组件的架构、功能和使用方法。
## 系统概述
LightRAG 采用前后端分离的架构设计：
```mermaid
graph TB
subgraph 前端层["前端层 (WebUI)"]
UI[React Web界面]
API_CLIENT[API客户端]
end
subgraph 后端层["后端层 (API Server)"]
FASTAPI[FastAPI服务器]
subgraph 路由层["路由模块"]
DOC_ROUTE[文档路由]
QUERY_ROUTE[查询路由]
GRAPH_ROUTE[图谱路由]
end
subgraph 服务层["核心服务"]
CORE[LightRAG Core]
PIPELINE[文档处理管道]
AUTH[认证服务]
end
end
subgraph 存储层["存储层"]
VECTOR_DB[向量数据库]
GRAPH_DB[图数据库]
KV_STORE[KV存储]
DOC_STATUS[文档状态存储]
end
UI --> API_CLIENT
API_CLIENT -->|HTTP/REST| FASTAPI
FASTAPI --> DOC_ROUTE
FASTAPI --> QUERY_ROUTE
FASTAPI --> GRAPH_ROUTE
DOC_ROUTE --> PIPELINE
QUERY_ROUTE --> CORE
GRAPH_ROUTE --> CORE
CORE --> 存储层
PIPELINE --> 存储层
```
资料来源：[lightrag_webui/src/api/lightrag.ts:1-100]()
## API服务器架构
### 服务器主程序
LightRAG API 服务器基于 FastAPI 框架构建，提供 RESTful API 接口。服务器主程序位于 `lightrag/api/lightrag_server.py`，负责：
- 初始化 FastAPI 应用实例
- 注册所有路由模块
- 配置中间件（认证、CORS 等）
- 提供 Ollama 兼容接口
```mermaid
graph LR
A[客户端请求] --> B[FastAPI路由]
B --> C{认证检查}
C -->|已认证| D[业务逻辑]
C -->|未认证| E[返回401错误]
D --> F[LightRAG Core]
F --> G[存储后端]
```
资料来源：[lightrag/api/lightrag_server.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/lightrag_server.py)
### 路由模块结构
API 服务器包含以下主要路由模块：
| 路由模块 | 文件路径 | 功能描述 |
|---------|---------|---------|
| 文档路由 | `lightrag/api/routers/document_routes.py` | 文档上传、删除、状态查询 |
| 查询路由 | `lightrag/api/routers/query_routes.py` | RAG 查询、上下文检索 |
| 图谱路由 | `lightrag/api/routers/graph_routes.py` | 知识图谱查询与操作 |
资料来源：[lightrag/api/routers/](https://github.com/HKUDS/LightRAG/tree/main/lightrag/api/routers)
### 查询请求参数
LightRAG 支持多种查询模式，通过 `QueryRequest` 类型定义请求参数：
| 参数名 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| `query` | string | 必填 | 查询文本 |
| `mode` | QueryMode | 必填 | 查询模式 |
| `only_need_context` | boolean | false | 仅返回检索上下文 |
| `only_need_prompt` | boolean | false | 仅返回生成的提示词 |
| `response_type` | string | - | 响应格式（如"Multiple Paragraphs"） |
| `stream` | boolean | false | 启用流式输出 |
| `top_k` | number | - | 实体/关系数量 |
| `chunk_top_k` | number | - | 重排后保留的文本块数量 |
| `max_entity_tokens` | number | - | 实体上下文最大token数 |
| `max_relation_tokens` | number | - | 关系上下文最大token数 |
| `max_total_tokens` | number | - | 整体查询上下文最大token数 |
资料来源：[lightrag_webui/src/api/lightrag.ts:18-50]()
### 查询模式
LightRAG 支持以下查询模式：
| 模式 | 值 | 说明 |
|-----|---|------|
| Naive | `naive` | 纯向量检索，直接使用 LLM 生成答案 |
| Local | `local` | 基于实体的局部检索，适合具体实体相关查询 |
| Global | `global` | 基于关系网络的全局检索，适合聚合分析 |
| Hybrid | `hybrid` | 结合局部和全局检索 |
| Mix | `mix` | 混合模式，结合重排器使用（默认推荐） |
| Bypass | `bypass` | 跳过知识图谱，直接使用原始检索 |
资料来源：[lightrag_webui/src/api/lightrag.ts:10-11]()
## WebUI 前端架构
### 技术栈
LightRAG WebUI 基于以下技术栈构建：
- **框架**：React 19 + TypeScript
- **路由**：React Router DOM v7
- **样式**：Tailwind CSS + Typography 插件
- **构建工具**：Vite
- **图可视化**：Sigma.js
- **状态管理**：Zustand
- **Markdown渲染**：react-markdown + remark-gfm
资料来源：[lightrag_webui/package.json](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/package.json)
### 运行时配置
WebUI 采用运行时配置机制，支持反向代理部署。配置通过 FastAPI 服务器在 HTML 响应时注入：
```mermaid
sequenceDiagram
participant Browser as 浏览器
participant FastAPI as FastAPI服务器
participant WebUI as WebUI构建产物
Browser->>FastAPI: 请求 /webui/index.html
FastAPI->>FastAPI: 注入 __LIGHTRAG_CONFIG__
FastAPI-->>Browser: 返回包含配置的HTML
Browser->>WebUI: 加载JS bundle
WebUI->>Browser: 读取 window.__LIGHTRAG_CONFIG__
Browser->>FastAPI: 使用配置的prefix发起API请求
```
资料来源：[lightrag_webui/src/lib/runtimeConfig.ts:1-40]()
### 路径前缀处理
WebUI 支持通过反向代理挂载到子路径。路径前缀规范化逻辑如下：
```typescript
// 空值/undefined/"/" → 回退到 "/webui"
function normalizeWebuiPrefix(value: string | undefined | null, fallback = '/webui'): string
```
资料来源：[lightrag_webui/src/lib/pathPrefix.ts:1-30]()
### 支持的文件类型
WebUI 和 API 服务器支持以下文档格式：
| MIME类型 | 扩展名 | 说明 |
|---------|-------|------|
| `application/pdf` | `.pdf` | PDF文档 |
| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `.docx` | Word文档 |
| `application/vnd.openxmlformats-officedocument.presentationml.presentation` | `.pptx` | PowerPoint演示文稿 |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx` | Excel表格 |
| `text/plain` | `.txt` | 纯文本 |
| `text/markdown` | `.md` | Markdown文档 |
| `text/html` | `.html` | HTML文档 |
| 代码文件 | `.py`, `.js`, `.ts`, `.java`, `.go`, `.cpp` 等 | 源代码文件 |
资料来源：[lightrag_webui/src/lib/constants.ts:1-60]()
## 认证与安全
### 认证状态管理
LightRAG API 支持两种认证模式：
| 认证模式 | 值 | 说明 |
|---------|---|------|
| 已启用 | `enabled` | 需要API密钥访问 |
| 已禁用 | `disabled` | 完全开放访问 |
认证状态响应包含以下字段：
```typescript
interface AuthStatusResponse {
auth_configured: boolean
access_token?: string
token_type?: string
auth_mode?: 'enabled' | 'disabled'
message?: string
core_version?: string
api_version?: string
webui_title?: string
webui_description?: string
}
```
资料来源：[lightrag_webui/src/api/lightrag.ts:120-135]()
### 令牌管理
前端实现自动令牌刷新机制，防止多请求同时触发令牌刷新：
```typescript
let isRefreshingGuestToken = false;
let refreshTokenPromise: Promise | null = null;
```
资料来源：[lightrag_webui/src/api/lightrag.ts:160-170]()
## 文档处理管道
### 文档状态追踪
文档上传后进入异步处理管道，状态流转如下：
```mermaid
stateDiagram-v2
[*] --> 上传中
上传中 --> 处理中: 上传完成
处理中 --> 索引中: 开始索引
索引中 --> 完成: 索引完成
处理中 --> 失败: 处理错误
索引中 --> 失败: 索引错误
失败 --> [*]
完成 --> [*]
```
### 文档状态响应
```typescript
interface DocStatusResponse {
doc_id: string
content_length?: number
file_path: string
file_name?: string
file_type?: string
status: DocStatus
created_at: string
updated_at: string
total_chunks?: number
chunks_count?: number
error_msg?: string
metadata?: Record
}
```
资料来源：[lightrag_webui/src/api/lightrag.ts:70-90]()
## 部署配置
### 环境变量配置
LightRAG 支持交互式配置向导生成 `.env` 文件：
```bash
# 基础配置（必需）
make env-base # LLM、嵌入、重排模型配置
# 存储配置（可选）
make env-storage # 存储后端和数据库服务
# 服务器配置（可选）
make env-server # 服务器端口、认证、SSL
# 安全审计
make env-security-check # 检查当前.env的安全风险
```
资料来源：[README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Docker 部署
使用 Docker Compose 部署完整服务：
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env # 编辑.env配置
docker compose up
```
官方镜像支持 Cosign 签名验证：
```bash
cosign verify \
--certificate-identity-regexp="https://github.com/HKUDS/LightRAG" \
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
ghcr.io/hkuds/lightrag:latest
```
资料来源：[docs/DockerDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/DockerDeployment.md)
### 反向代理配置注意事项
⚠️ **已知问题**：在反向代理子路径部署时，应用对资源使用绝对路径，可能导致资源加载失败。
社区反馈：[Issue #2755](https://github.com/HKUDS/LightRAG/issues/2755)
解决方案是确保正确配置 `LIGHTRAG_API_PREFIX` 和 `LIGHTRAG_WEBUI_PATH` 环境变量。
## 常见问题
### 如何区分同名但内容不同的文档？
社区讨论：[Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
当前实现中，文档通过 `doc_id` 标识，文件名不作为唯一标识。建议在上传时使用包含内容哈希或时间戳的自定义文件名。
### 如何获取查询使用的源文件？
社区讨论：[Issue #323](https://github.com/HKUDS/LightRAG/issues/323)
当前版本已支持引用功能，查询结果可返回检索到的上下文片段。详细配置请参考 [AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)。
### 多模态支持
v1.5.0 版本已集成 RAG-Anything 的多模态处理能力，支持：
- PDF 文档中的图片、表格、公式提取
- Office 文档处理
- 图文混合索引
详细配置见 [AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)。
## 另请参阅
- [LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md) - API服务器详细文档
- [FrontendBuildGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/FrontendBuildGuide.md) - 前端构建指南
- [InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md) - 交互式配置向导
- [AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md) - 高级功能配置
- [ProgramingWithCore.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ProgramingWithCore.md) - Core API编程指南
- [DockerDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/DockerDeployment.md) - Docker部署指南
---
## 核心库编程
### 相关页面
相关主题：[快速开始](#page-quick-start), [API服务器与WebUI](#page-api-server), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
- [lightrag/types.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/types.py)
- [lightrag/llm/openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/openai.py)
- [lightrag/llm/ollama.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/ollama.py)
- [lightrag/llm/azure_openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/azure_openai.py)
- [lightrag/llm/gemini.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/gemini.py)
- [lightrag/llm/huggingface.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/huggingface.py)
- [lightrag/rerank.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/rerank.py)
- [docs/ProgramingWithCore.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ProgramingWithCore.md)
- [docs/RoleSpecificLLMConfiguration.md](https://github.com/HKUDS/LightRAG/blob/main/docs/RoleSpecificLLMConfiguration.md)
- [examples/lightrag_ollama_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_ollama_demo.py)
- [examples/lightrag_gemini_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_gemini_demo.py)
- [examples/lightrag_azure_openai_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_azure_openai_demo.py)
# 核心库编程
## 概述
LightRAG Core 是整个系统的核心引擎，提供了完整的检索增强生成（RAG）功能。与 LightRAG Server 不同，Core 库专注于为开发者提供嵌入式的编程接口，适用于需要将 RAG 功能直接集成到 Python 应用中的场景。
**适用场景**：
- 将 LightRAG 嵌入到现有的 Python 应用中
- 研究人员需要进行 RAG 相关的实验和评估
- 需要对文档处理流程进行细粒度控制的场景
**不适用场景**：
- 生产环境部署（建议使用 REST API）
- 需要 Web UI 和知识图谱可视化的场景
- 不熟悉 Python 编程的用户
资料来源：[docs/ProgramingWithCore.md:1-15](https://github.com/HKUDS/LightRAG/blob/main/docs/ProgramingWithCore.md)
---
## 核心组件架构
LightRAG Core 的架构由以下几个核心组件构成：
```mermaid
graph TD
A[LightRAG Core] --> B[文本向量化模块]
A --> C[知识图谱模块]
A --> D[检索模块]
A --> E[生成模块]
B --> B1[Embedding Provider]
B --> B2[Vector Storage]
C --> C1[实体抽取]
C --> C2[关系抽取]
C --> C3[Graph Storage]
D --> D1[Reranker]
D --> D2[混合检索]
E --> E1[LLM Provider]
E --> E2[答案生成]
```
| 组件 | 功能 | 可配置性 |
|------|------|----------|
| Embedding Provider | 文本向量化 | 支持多种 provider |
| Vector Storage | 向量存储 | 可切换后端 |
| Graph Storage | 知识图谱存储 | 支持多种图数据库 |
| LLM Provider | 大语言模型调用 | 支持多种 LLM |
| Reranker | 检索结果重排序 | 可选配置 |
---
## 初始化与配置
### 基本初始化
使用 LightRAG Core 的第一步是创建 `LightRAG` 实例并配置相关参数：
```python
from lightrag import LightRAG, QueryParam
# 基础初始化
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small"
)
```
资料来源：[examples/lightrag_ollama_demo.py:1-20](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_ollama_demo.py)
### 初始化参数详解
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `working_dir` | str | 是 | - | 工作目录，用于存储数据 |
| `llm_model` | str | 是 | - | LLM 模型名称 |
| `llm_model_name` | str | 否 | `llm_model` | LLM 模型完整名称 |
| `embedding_model` | str | 是 | - | Embedding 模型名称 |
| `embedding_dim` | int | 否 | 根据模型自动推断 | 向量维度 |
| `max_token_limit` | int | 否 | 8192 | 最大 token 限制 |
| `kv_storage` | str | 否 | "JsonKVStorage" | KV 存储类型 |
| `graph_storage` | str | 否 | "NetworkXStorage" | 图存储类型 |
| `vector_storage` | str | 否 | "NanoVectorDBStorage" | 向量存储类型 |
| `doc_status_storage` | str | 否 | "JsonDocStatusStorage" | 文档状态存储类型 |
| `chunk_token_size` | int | 否 | 1200 | 文本块 token 大小 |
| `chunk_overlap_token_size` | int | 否 | 100 | 文本块重叠 token 大小 |
| `llm_model_max_async` | int | 否 | 32 | 最大异步调用数 |
| `extension_model` | str | 否 | None | 扩展模型路径 |
资料来源：[lightrag/lightrag.py:100-200](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
### LLM 与 Embedding Provider 配置
LightRAG 支持多种 LLM 和 Embedding provider，通过环境变量或初始化参数进行配置：
#### OpenAI 配置
```python
import os
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["OPENAI_BASE_URL"] = "https://api.openai.com/v1"
rag = LightRAG(
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small",
# OpenAI 特定配置
llm_model_max_async=32,
)
```
资料来源：[lightrag/llm/openai.py:1-50](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/openai.py)
#### Ollama 配置
```python
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="qwen2.5:7b-instruct",
llm_base_url="http://localhost:11434",
embedding_model="bge-m3:latest",
embedding_base_url="http://localhost:11434",
)
```
资料来源：[examples/lightrag_ollama_demo.py:10-30](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_ollama_demo.py)
#### Azure OpenAI 配置
```python
import os
os.environ["AZURE_OPENAI_API_KEY"] = "your-azure-api-key"
os.environ["AZURE_OPENAI_ENDPOINT"] = "https://your-resource.openai.azure.com"
os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"] = "your-deployment-name"
os.environ["AZURE_OPENAI_API_VERSION"] = "2024-06-01"
rag = LightRAG(
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small",
)
```
资料来源：[examples/lightrag_azure_openai_demo.py:1-30](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_azure_openai_demo.py)
#### Gemini 配置
```python
import os
os.environ["GEMINI_API_KEY"] = "your-gemini-api-key"
rag = LightRAG(
llm_model="gemini-2.0-flash",
embedding_model="text-embedding-3-small",
)
```
资料来源：[examples/lightrag_gemini_demo.py:1-25](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_gemini_demo.py)
#### HuggingFace 配置
```python
rag = LightRAG(
llm_model="Qwen/Qwen2.5-7B-Instruct",
embedding_model="BAAI/bge-m3",
hf_token="your-hf-token",
)
```
资料来源：[lightrag/llm/huggingface.py:1-50](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/huggingface.py)
---
## 角色特定 LLM 配置
LightRAG 支持为不同任务角色配置独立的 LLM 模型，这一功能允许用户根据任务特点选择最合适的模型。
### 支持的角色
| 角色 | 说明 | 推荐模型规模 |
|------|------|-------------|
| `EXTRACT` | 实体和关系抽取 | ≥30B 参数 |
| `QUERY` | 查询理解和重写 | ≥30B 参数 |
| `KEYWORDS` | 关键词提取 | 较小模型即可 |
| `VLM` | 多模态内容处理 | 支持视觉的模型 |
资料来源：[docs/RoleSpecificLLMConfiguration.md:1-30](https://github.com/HKUDS/LightRAG/blob/main/docs/RoleSpecificLLMConfiguration.md)
### 配置示例
```python
from lightrag import LightRAG, QueryParam
rag = LightRAG(
# 默认 LLM 配置
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small",
# 角色特定 LLM 配置
llm_model_config={
"EXTRACT": {
"model": "gpt-4o", # 抽取任务使用更强大的模型
"temperature": 0.3,
},
"QUERY": {
"model": "gpt-4o-mini",
"temperature": 0.5,
},
"KEYWORDS": {
"model": "gpt-4o-mini",
"temperature": 0.0,
},
}
)
```
资料来源：[docs/RoleSpecificLLMConfiguration.md:30-60](https://github.com/HKUDS/LightRAG/blob/main/docs/RoleSpecificLLMConfiguration.md)
---
## 查询模式与参数
### 查询模式
LightRAG 支持六种查询模式，通过 `QueryParam` 的 `mode` 参数指定：
```python
from lightrag.types import QueryMode
```
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `naive` | 仅使用向量检索 | 简单查询 |
| `local` | 基于实体邻居检索 | 实体相关查询 |
| `global` | 基于关系遍历检索 | 聚合类查询 |
| `hybrid` | 结合 local 和 global | 复杂查询 |
| `mix` | 混合模式 + Reranker | **默认推荐模式** |
| `bypass` | 直接使用 LLM | 旁路模式 |
```python
result = rag.query(
"What is the relationship between entity A and entity B?",
param=QueryParam(mode="mix")
)
```
资料来源：[lightrag/types.py:1-30](https://github.com/HKUDS/LightRAG/blob/main/lightrag/types.py)
### QueryParam 完整参数
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `mode` | QueryMode | `"mix"` | 查询模式 |
| `only_need_context` | bool | `False` | 仅返回检索上下文 |
| `only_need_prompt` | bool | `False` | 仅返回生成提示 |
| `response_type` | str | `"Multiple Paragraphs"` | 响应格式 |
| `stream` | bool | `False` | 是否流式输出 |
| `top_k` | int | 动态计算 | 检索数量 |
| `chunk_top_k` | int | 动态计算 | 重排后保留数量 |
| `max_entity_tokens` | int | 3000 | 实体上下文最大 token |
| `max_relation_tokens` | int | 3000 | 关系上下文最大 token |
| `max_total_tokens` | int | None | 总 token 预算上限 |
| `history` | List[Message] | [] | 对话历史 |
```python
param = QueryParam(
mode="hybrid",
only_need_context=False,
response_type="Bullet Points",
top_k=10,
chunk_top_k=5,
max_entity_tokens=2000,
max_relation_tokens=2000,
max_total_tokens=8000,
)
```
资料来源：[lightrag/types.py:30-100](https://github.com/HKUDS/LightRAG/blob/main/lightrag/types.py)
---
## Reranker 配置
Reranker 可以显著提升混合查询的性能，是可选但推荐的功能：
```python
from lightrag import LightRAG, QueryParam
from lightrag.rerank import Reranker
# 使用默认 reranker
rag = LightRAG(
reranker=Reranker(),
# 或指定模型
# reranker=Reranker("BAAI/bge-reranker-v2-m3"),
)
# 查询时会自动使用 reranker
result = rag.query("your question", param=QueryParam(mode="mix"))
```
资料来源：[lightrag/rerank.py:1-80](https://github.com/HKUDS/LightRAG/blob/main/lightrag/rerank.py)
| 配置项 | 说明 |
|--------|------|
| 无参数 | 使用默认模型 `BAAI/bge-reranker-v2-m3` |
| 指定模型名 | 使用 HuggingFace 模型 |
| `None` | 禁用 reranker |
---
## 文档操作
### 插入文档
```python
# 插入单个文档
result = rag.insert("This is a document about LightRAG framework...")
# 批量插入
results = rag.batch_insert([
"Document 1 content...",
"Document 2 content...",
"Document 3 content...",
])
```
### 自定义知识图谱插入
```python
# 插入自定义实体和关系
await rag.ainsert_custom_kg(
[
{
"tokens": 100,
"content": "ENTITY:Alice TYPE:person",
"level": 1,
},
{
"tokens": 100,
"content": "ENTITY:Bob TYPE:person",
"level": 1,
},
{
"tokens": 100,
"content": "RELATION:Alice-KNOWS-Bob",
"level": 2,
},
]
)
```
### 删除文档
文档删除支持两种模式：
| 删除模式 | 说明 | 行为 |
|----------|------|------|
| `soft` | 软删除 | 仅标记，保留 KG |
| `hard` | 硬删除 | 完全删除，自动重建 KG |
```python
# 软删除
result = rag.delete("doc_id_123", mode="soft")
# 硬删除
result = rag.delete("doc_id_123", mode="hard")
```
### 文档去重
LightRAG 支持基于内容哈希的文档去重：
```python
result = rag.ainsert(
"Document content...",
hash=None, # 自动计算哈希
# 或指定哈希
# hash="custom_hash_value",
)
```
> **注意**：相同内容的文档会被识别为重复文档，系统会根据哈希值进行去重处理。
资料来源：[lightrag/lightrag.py:500-600](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
---
## 实体与关系管理
### 获取实体列表
```python
# 获取所有实体
entities = rag.get_entities(
entity_name=None, # None 表示获取所有实体
start_offset=0,
max_count=100,
)
# 获取特定类型的实体
entities = rag.get_entities(
entity_name=None,
entity_type="person", # 过滤类型
)
```
### 获取关系列表
```python
# 获取所有关系
relations = rag.get_relations(
rel_name=None,
start_offset=0,
max_count=100,
)
```
### 获取实体详情
```python
# 获取特定实体的详细信息
entity_info = rag.get_entity(
entity_name="Alice",
entity_type="person",
)
```
### 知识图谱导出
```python
# 导出知识图谱数据
kg_data = rag.export_kg()
# 返回格式
# {
# "nodes": [...],
# "edges": [...],
# "source": "lightrag"
# }
```
---
## 存储后端配置
LightRAG 支持多种存储后端配置：
### 向量存储
```python
rag = LightRAG(
vector_storage="NanoVectorDBStorage", # 默认
# 或使用其他后端
# vector_storage="PGVectorStorage",
# vector_storage="ChromaStorage",
# vector_storage="MongoVectorStorage",
)
```
### 图存储
```python
rag = LightRAG(
graph_storage="NetworkXStorage", # 默认
# 或使用 Neo4j
# graph_storage="Neo4JStorage",
)
```
### KV 存储
```python
rag = LightRAG(
kv_storage="JsonKVStorage", # 默认
# 或使用其他后端
# kv_storage="PGKVStorage",
# kv_storage="MongoKVStorage",
)
```
---
## 异步操作
LightRAG Core 提供完整的异步 API：
```python
import asyncio
from lightrag import LightRAG
async def main():
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small",
)
# 异步插入
await rag.ainsert("Document content...")
# 异步查询
result = await rag.aquery(
"Your question?",
param=QueryParam(mode="hybrid")
)
# 异步批量插入
await rag.abatch_insert([
"Doc 1...",
"Doc 2...",
])
asyncio.run(main())
```
| 方法 | 异步版本 | 说明 |
|------|----------|------|
| `insert()` | `ainsert()` | 插入文档 |
| `batch_insert()` | `abatch_insert()` | 批量插入 |
| `query()` | `aquery()` | 查询 |
| `delete()` | `adelete()` | 删除文档 |
---
## 完整使用示例
### 基础使用流程
```python
from lightrag import LightRAG, QueryParam
# 1. 初始化
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="gpt-4o-mini",
embedding_model="text-embedding-3-small",
)
# 2. 插入文档
rag.insert("""
LightRAG is a lightweight RAG framework.
It supports multiple retrieval modes including local, global, and hybrid.
LightRAG uses knowledge graphs to enhance retrieval quality.
""")
# 3. 查询
result = rag.query(
"What retrieval modes does LightRAG support?",
param=QueryParam(mode="hybrid", response_type="Single Paragraph")
)
print(result)
# 4. 关闭
rag.finalize()
```
### 多模态查询示例
```python
from lightrag import LightRAG, QueryParam
rag = LightRAG(
working_dir="./lightrag_data",
llm_model="gpt-4o",
embedding_model="text-embedding-3-small",
)
# 查询图片相关内容
result = rag.query(
"Describe the content of the uploaded image",
param=QueryParam(mode="naive", only_need_context=False)
)
```
---
## 常见问题与注意事项
### 1. 模型选择建议
| 阶段 | 推荐模型 | 说明 |
|------|----------|------|
| 索引阶段 | ≥30B 参数 | 实体关系抽取需要较强的模型能力 |
| 查询阶段 | 更强能力模型 | 推荐比索引阶段更强的模型 |
| Embedding | BAAI/bge-m3, text-embedding-3-large | 高性能多语言模型 |
### 2. Token 限制
```python
# 调整 chunk 大小
rag = LightRAG(
chunk_token_size=1200, # 默认
chunk_overlap_token_size=100, # 默认
)
```
### 3. 并发控制
```python
# 调整最大异步调用数
rag = LightRAG(
llm_model_max_async=32, # 默认 32
)
```
### 4. 文档标识
> **社区问题**：用户反馈无法区分同名文档的不同内容版本。
>
> 当前系统中，文档通过内部 `doc_id` 进行标识，不直接存储原始文件名。如需区分同名文档，建议在文档内容中添加版本信息或元数据。
>
> 相关讨论：[GitHub Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
### 5. 存储后端切换
切换存储后端时需要注意：
- 不同后端的向量维度可能不同
- 更换 Embedding 模型可能需要重建索引
- 部分后端（如 PostgreSQL）需要在首次创建时确定向量维度
---
## 高级功能
### Token 使用追踪
```python
# 获取 token 使用统计
token_usage = rag.get_token_usage()
print(token_usage)
```
### LLM 缓存管理
```python
# 清理 LLM 缓存
rag.clear_llm_cache()
```
### Langfuse 集成
```python
# 启用 Langfuse 追踪
rag = LightRAG(
# ... 其他配置
langfuse_public_key="your-public-key",
langfuse_secret_key="your-secret-key",
langfuse_host="https://cloud.langfuse.com",
)
```
### RAGAS 评估
```python
# 运行 RAG 质量评估
from lightrag.evaluation import evaluate_rag_quality
results = evaluate_rag_quality(
rag=rag,
questions=["question1", "question2"],
ground_truths=[["answer1"], ["answer2"]]
)
```
详细说明请参阅 [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)。
---
## See Also
- [LightRAG Server 配置](./LightRAG-API-Server.md) - Web UI 和 REST API 部署
- [交互式设置向导](./InteractiveSetup.md) - 配置文件生成工具
- [高级功能](./AdvancedFeatures.md) - Token 追踪、Langfuse、RAGAS
- [角色特定 LLM 配置](./RoleSpecificLLMConfiguration.md) - 多角色 LLM 配置
- [离线部署指南](./OfflineDeployment.md) - 离线环境部署
---
---
## Doramagic 踩坑日志
项目：HKUDS/LightRAG
摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?。
## 1. 安装坑 · 来源证据：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9aea67d79c4b46508c4267093ebb19da | https://github.com/HKUDS/LightRAG/issues/2642 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[Question]: How to distinguish documents with same name but different content?
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question]: How to distinguish documents with same name but different content?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6c7ed97673d041ef92d4ff54a3718289 | https://github.com/HKUDS/LightRAG/issues/3158 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 失败模式：installation: v1.4.10
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.4.10
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.10
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.10. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_dceb1b266203b7a89767ff26a0852383 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.10 | v1.4.10
## 4. 配置坑 · 失败模式：configuration: [Bug]: Not working on reverse proxy - sub path
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Bug]: Not working on reverse proxy - sub path
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]: Not working on reverse proxy - sub path
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Not working on reverse proxy - sub path. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_13dbaaeb506c72cc5b9ecd91cdabc2a2 | https://github.com/HKUDS/LightRAG/issues/2755 | [Bug]: Not working on reverse proxy - sub path
## 5. 配置坑 · 失败模式：configuration: v1.4.11
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.4.11
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.11
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_eda26a0bfd194234d2eb2fa02f9bdae9 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11 | v1.4.11
## 6. 配置坑 · 失败模式：configuration: v1.4.11rc2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.4.11rc2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.11rc2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11rc2. Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_0ff3ca856c8031ac2b0c56ec5eb253ab | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11rc2 | v1.4.11rc2
## 7. 配置坑 · 失败模式：configuration: v1.4.12
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.4.12
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.12
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.12. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_ded21b8d88cae5cd73ae76e6ec499f47 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.12 | v1.4.12
## 8. 配置坑 · 失败模式：configuration: v1.4.13
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.4.13
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.13
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.13. Context: Observed when using node
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_9e994731fd7834839bbe18111ec634c6 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.13 | v1.4.13
## 9. 配置坑 · 失败模式：configuration: v1.4.14
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.4.14
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.14
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.14. Context: Observed when using python, docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_a1044f275fce0a09fbf5f7ff15ce5406 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.14 | v1.4.14
## 10. 配置坑 · 失败模式：configuration: v1.5.0rc3
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.5.0rc3
- 对用户的影响：Upgrade or migration may change expected behavior: v1.5.0rc3
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.5.0rc3. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_f612aafe1cfe8a3c51740b6487bd93a7 | https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0rc3 | v1.5.0rc3
## 11. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:866513204 | https://github.com/HKUDS/LightRAG | README/documentation is current enough for a first validation pass.
## 12. 维护坑 · 失败模式：migration: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify)...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- 对用户的影响：Developers may hit a documented source-backed failure mode: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_dfedf4f77da9bdcac28253497ad6ce68 | https://github.com/HKUDS/LightRAG/issues/2642 | Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
## 13. 维护坑 · 失败模式：migration: v1.4.16
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.4.16
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.16
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.16. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_e1bc29ea5c00bb483634fa73149ec8cf | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.16 | v1.4.16
## 14. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | last_activity_observed missing
## 15. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:866513204 | https://github.com/HKUDS/LightRAG | no_demo; severity=medium
## 16. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:866513204 | https://github.com/HKUDS/LightRAG | no_demo; severity=medium
## 17. 安全/权限坑 · 来源证据：[Bug]: Not working on reverse proxy - sub path
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Not working on reverse proxy - sub path
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_969a894078ba4625956be8aafdd77a49 | https://github.com/HKUDS/LightRAG/issues/2755 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 18. 能力坑 · 失败模式：capability: [Question]: How to distinguish documents with same name but different content?
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [Question]: How to distinguish documents with same name but different content?
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Question]: How to distinguish documents with same name but different content?
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Question]: How to distinguish documents with same name but different content?. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_7de313ae4505d08ac41ea7819dc560ae | https://github.com/HKUDS/LightRAG/issues/3158 | [Question]: How to distinguish documents with same name but different content?
## 19. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | issue_or_pr_quality=unknown
## 20. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG | release_recency=unknown
## 21. 维护坑 · 失败模式：maintenance: v1.4.15
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.4.15
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.15
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.15. Context: Observed when using docker
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_71ec5d7890568d905bed167788b6732f | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.15 | v1.4.15
## 22. 维护坑 · 失败模式：maintenance: v1.4.9.11
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.4.9.11
- 对用户的影响：Upgrade or migration may change expected behavior: v1.4.9.11
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v1.4.9.11. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_f875fc1d48e0d9cf17d2b49dd7fa0cf4 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.9.11 | v1.4.9.11