核心特性

LightRAG 在传统 RAG 基础上进行了多项创新优化，主要特性包括：

资料来源：README.md

系统架构

LightRAG 采用分层架构设计，主要包含以下核心组件：

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

架构说明

资料来源：lightrag/__init__.py

工作流程

索引流程

文档进入系统后，LightRAG 通过以下步骤进行处理：

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

查询流程

LightRAG 提供多种查询模式以适应不同场景：

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

查询模式详解

LightRAG 支持六种查询模式，每种模式适用于不同类型的查询场景：

资料来源：lightrag_webui/src/api/lightrag.ts:7

查询参数

资料来源：lightrag_webui/src/api/lightrag.ts:8-35

存储后端支持

LightRAG 支持多种存储后端，可根据需求灵活选择：

向量存储

知识图谱存储

资料来源：README.md

多模态文档处理

LightRAG v1.5.0 起支持完整的多模态文档处理能力，已将 RAG-Anything 的功能合并到主仓库中。

支持的文档格式

资料来源：lightrag_webui/src/lib/constants.ts

多模态处理流程

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），需在配置中指定相应服务端点。

安装与部署

环境要求

资料来源：README.md

安装方式

#### 方式一：Docker 部署（推荐）

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # 编辑配置
docker compose up

#### 方式二：从源码安装

cd LightRAG
uv sync                    # 创建虚拟环境并安装依赖
source .venv/bin/activate  # 激活虚拟环境

#### 方式三：pip 安装

uv pip install lightrag-hku
# 或
pip install lightrag-hku

#### 方式四：离线部署

对于内网环境或离线部署场景，需预先下载所有依赖和模型文件，具体步骤请参考 OfflineDeployment.md。

交互式配置向导

LightRAG 提供交互式配置向导简化部署：

资料来源：README.md

配置说明

环境变量配置

核心配置项说明：

运行时路径配置

LightRAG 支持通过反向代理部署，路径前缀可在运行时动态配置：

配置通过服务器注入到前端，无需重新构建：

<!-- 服务器注入配置 -->
<script>
  window.__LIGHTRAG_CONFIG__ = {
    apiPrefix: "/api",
    webuiPrefix: "/webui/"
  }
</script>

资料来源：lightrag_webui/src/lib/runtimeConfig.ts

常见问题与解决方案

文档区分问题

问题：同名文档如何区分？

LightRAG 使用内部 document_id 标识文档，文件名仅用于显示。建议在上传时使用唯一文件名或在上传后记录返回的 document_id。

参考：Issue #3158

反向代理部署问题

问题：在子路径下部署时资源无法加载。

原因：应用曾使用绝对路径，某些资源路径未正确处理子路径前缀。

解决方案：配置 LIGHTRAG_WEBUI_PATH 和 LIGHTRAG_API_PREFIX，确保服务器正确注入路径前缀。

参考：Issue #2755

源文件溯源问题

问题：查询结果能否返回来源文件？

LightRAG 支持引用功能（v2025.03+），可在查询时启用返回检索上下文，以便追踪信息来源。但目前文件名信息需要通过文档上传接口记录。

参考：Issue #323

多模态支持问题

问题：如何添加多模态支持？

LightRAG 已将 RAG-Anything 功能合并。对于 PDF、Office 文档、图片等，需要配置外部解析服务（MinerU 或 Docling）。

参考：Issue #2642

相关资源

参考阅读

• 编程指南 - Core API 完整参考
• 高级功能 - Token 追踪、数据导出、评估工具
• 交互式配置 - 配置向导详细说明
• Docker 部署 - 容器化部署指南
• 离线部署 - 内网环境部署指南
• LightRAG Server - API 服务器使用指南
• LightRAG 3D 可视化 - 知识图谱 3D 可视化工具

前置要求

系统环境

LightRAG 支持在以下环境中运行：

技术栈依赖

LightRAG 对大语言模型的能力要求比传统 RAG 系统更高，因为它需要 LLM 执行实体关系抽取任务。合理的 Embedding 和 Reranker 模型配置对提升查询性能至关重要。资料来源：README.md:1-50

LLM 选择建议：

Embedding 模型建议：

⚠️ 重要提示：Embedding 模型必须在文档索引前确定，查询阶段必须使用相同的模型。对于某些存储方案（如 PostgreSQL），向量维度在首次创建表时定义，更换 Embedding 模型需要删除现有向量表并让 LightRAG 重新创建。

Reranker 模型建议：

启用 Reranker 模型可显著提升检索性能。推荐使用主流 Reranker 模型，如 BAAI/bge-reranker-v2-m3。启用 Reranker 后，建议将"混合模式"设为默认查询模式。资料来源：README.md:1-50

安装方式

LightRAG 提供多种安装方式，用户可根据实际需求选择。

方式一：从源码安装（推荐）

cd LightRAG
# 使用 uv 进行包管理，自动创建 .venv/ 虚拟环境
uv sync
source .venv/bin/activate  # Linux/macOS
# Windows: .venv\Scripts\activate

# 或者使用 pip 安装
# pip install -e .

方式二：从 PyPI 安装

uv pip install lightrag-hku
# 或
pip install lightrag-hku

方式三：开发环境快速启动

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

# 基础配置：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。

手动配置环境变量

1. 复制示例配置文件：

cp env.example .env

1. 编辑 .env 文件，配置以下核心参数：

完整的环境变量说明请参考 env.example。

LightRAG Server 快速启动

LightRAG Server 提供 Web UI 和 API 支持，包含知识图谱可视化、文档索引和查询界面。

安装 Server

# 使用 uv 安装（推荐）
uv tool install "lightrag-hku[api]"

# 使用 pip 安装
# python -m venv .venv
# source .venv/bin/activate
# pip install "lightrag-hku[api]"

构建前端

cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

启动服务

# 配置环境变量
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 进行文档索引和查询：

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

完整示例代码

详细的核心 API 参考（包括初始化参数、LLM/Embedding 提供商配置、Reranker 注入、插入操作、实体/关系管理、删除/合并等）请参阅 docs/ProgramingWithCore.md。资料来源：examples/lightrag_openai_demo.py

Docker 部署

快速部署

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # 编辑 .env 配置 LLM 和 Embedding
docker compose up

💡 历史版本的 Docker 镜像可在 LightRAG Docker Images 获取。官方 GHCR 镜像使用 Sigstore Cosign 通过 GitHub OIDC 进行签名。验证命令请参阅 docs/DockerDeployment.md。资料来源：README.md:1-50

Docker 部署架构

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，了解如何预安装所有依赖项和缓存文件。资料来源：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. 执行查询：尝试提问验证检索效果

示例测试代码：

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/ 目录下的完整示例

下一步

前提条件

在开始安装 LightRAG 之前，请确保满足以下系统要求：

硬件要求

软件依赖

LLM 和嵌入模型要求

LightRAG 对大语言模型（LLM）的能力要求比传统 RAG 系统更高，因为它需要 LLM 执行实体关系抽取任务。资料来源：README.md:50-80

• LLM 选择建议：
• 推荐使用至少 320 亿参数的 LLM
• 上下文长度至少 32KB，推荐 128KB 或更高
• Embedding 模型：配置适当的嵌入模型对查询性能至关重要
• Reranker 模型：启用 Reranker 模型可显著提升混合查询性能，推荐使用 BAAI/bge-reranker-v2-m3 或 Jina 等服务商提供的模型

安装方式概览

LightRAG 提供三种主要的安装方式：

graph TD
    A[开始安装] --> B{选择安装方式}
    B --> C[源码安装<br/>LightRAG Core]
    B --> D[PyPI 安装<br/>lightrag-hku]
    B --> E[Docker 部署<br/>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

# 克隆仓库
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 进行安装：

cd LightRAG
pip install -e .

从 PyPI 安装预发布版本

# 使用 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 提供商密钥）

快速启动

# 克隆仓库
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 页面找到。资料来源：README.md:100-110

官方 GHCR 镜像使用 Sigstore Cosign 通过 GitHub OIDC 进行签名验证。详情请参阅 Docker 部署文档。

方式三：使用交互式配置向导

LightRAG 提供了交互式配置向导来简化环境配置过程，无需手动编辑 .env 文件。资料来源：docs/InteractiveSetup.md:1-50

Makefile 目标说明

资料来源：README.md:115-130

配置流程

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[安全审计]

详细配置步骤

第一步：基础环境配置

make env-base

此命令会引导您配置：

• LLM 提供商（OpenAI、Azure、Gemini、Ollama 等）
• Embedding 模型配置
• Reranker 模型配置

第二步：存储后端配置（可选）

make env-storage

支持的存储后端包括：

• Neo4j：图数据库，用于存储知识图谱
• PostgreSQL：支持 pgvector 扩展的向量存储
• MongoDB：文档数据库和向量存储
• OpenSearch：统一存储后端，支持所有四种存储类型

第三步：服务器配置（可选）

make env-server

配置内容包括：

• Web UI 和 API 端口
• 认证设置
• SSL/TLS 配置

第四步：安全审计

make env-security-check

此命令会检查当前 .env 文件的安全风险。建议在部署前运行此检查。

方式四：离线部署

对于离线或气隙环境，LightRAG 提供了完整的离线部署指南。资料来源：docs/OfflineDeployment.md:1-100

离线环境准备

1. 在有网络的环境下准备所有依赖和缓存文件
2. 打包模型文件和配置
3. 在离线环境中解压并安装

详细步骤请参阅 离线部署指南。

安装 LightRAG Server

LightRAG Server 提供 Web UI 和 API 支持，包含知识图谱可视化、文档索引、查询等功能。资料来源：README.md:75-95

使用 uv 安装（推荐）

# 安装包含 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 安装

# 创建虚拟环境
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 功能特性

开发环境快速启动

推荐使用 make dev 命令快速初始化开发环境：资料来源：docs/InteractiveSetup.md:20-40

# 克隆仓库
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

# 设置 OpenAI API 密钥
export OPENAI_API_KEY="sk-...your_openai_key..."

# 下载示例文档
curl https://...

# 运行示例查询
python examples/quick_start.py

验证安装

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)

安装问题排查

常见问题

获取帮助

如果在安装过程中遇到问题：

1. 查看 GitHub Issues 是否已有解决方案
2. 搜索 GitHub Discussions 获取社区支持
3. 加入 Discord 社区 获取实时帮助

下一步

安装完成后，建议阅读以下文档：

• 编程指南 - 了解如何使用 LightRAG Core API
• 高级功能 - 多模态文档处理、令牌追踪、评估工具
• LightRAG API Server - 完整的 API 参考文档
• 交互式配置 - 详细配置向导说明

参见

• 官方文档首页
• 编程指南
• 高级功能
• Docker 部署
• 离线部署

整体架构概述

LightRAG 采用四层架构设计，从下至上依次为存储层、核心引擎层、API 服务层和前端交互层。存储层支持多种后端数据库，包括向量数据库、图数据库、KV 存储和文档状态存储；核心引擎层负责文本分块、实体关系抽取、向量化和检索查询；API 服务层基于 FastAPI 提供标准化接口；前端交互层提供 WebUI 和可视化工具。

graph TB
    subgraph 存储层["存储层 Storage Layer"]
        VDB["向量数据库<br/>Vector DB"]
        GDB["图数据库<br/>Graph DB"]
        KV["KV 存储<br/>Key-Value Store"]
        DOC["文档状态存储<br/>DocStatus Store"]
    end
    
    subgraph 核心引擎层["核心引擎层 Core Engine"]
        CHUNK["文本分块<br/>Text Chunking"]
        KG["知识图谱构建<br/>KG Extraction"]
        EMBED["向量化<br/>Embedding"]
        RETRIEVE["检索引擎<br/>Retrieval"]
        QUERY["查询处理<br/>Query Processing"]
    end
    
    subgraph API服务层["API 服务层 API Service"]
        REST["REST API<br/>FastAPI"]
        WS["WebSocket<br/>实时通信"]
        AUTH["认证授权<br/>Authentication"]
    end
    
    subgraph 前端交互层["前端交互层 Frontend"]
        WEBUI["WebUI<br/>React"]
        VIEWER["3D 可视化<br/>Graph Viewer"]
        DOCS["文档管理<br/>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

核心组件详解

LightRAG Core 核心引擎

LightRAG Core 是框架的核心引擎，封装在 lightrag/lightrag.py 文件中。它负责管理整个 RAG 生命周期的所有关键操作，包括文档插入、知识图谱查询、向量检索和结果生成。

核心引擎支持六种查询模式，每种模式针对不同的检索场景进行优化：

资料来源：lightrag_webui/src/api/lightrag.ts:7

存储层架构

LightRAG 的存储层采用抽象工厂模式设计，通过 lightrag/kg/factory.py 中的工厂类创建不同存储后端的实现实例。这种设计使得系统可以灵活切换底层存储技术，同时保持上层接口的一致性。

classDiagram
    class StorageFactory {
        +create_vector_storage()
        +create_graph_storage()
        +create_kv_storage()
        +create_doc_status_storage()
    }
    
    class VectorStorage {
        <<interface>>
        +upsert()
        +query()
        +delete()
    }
    
    class GraphStorage {
        <<interface>>
        +upsert_nodes()
        +upsert_edges()
        +query_nodes()
        +query_edges()
    }
    
    class KVStorage {
        <<interface>>
        +get()
        +set()
        +delete()
    }
    
    StorageFactory ..> VectorStorage : creates
    StorageFactory ..> GraphStorage : creates
    StorageFactory ..> KVStorage : creates

支持的存储后端包括：

资料来源：lightrag/kg/factory.py

文档处理管道

文档处理管道（Pipeline）是 LightRAG 处理上传文档的核心流程，定义在 lightrag/pipeline.py 文件中。管道支持多种文档格式的处理，包括纯文本、PDF、Office 文档等。

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[多模态处理<br/>RAG-Anything]
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I[文本分块<br/>Chunking]
    I --> J[实体抽取<br/>Entity Extraction]
    J --> K[关系抽取<br/>Relation Extraction]
    K --> L[向量化<br/>Embedding]
    L --> M[存储索引<br/>Storage Indexing]
    
    M --> N[文档状态更新<br/>DocStatus]

管道支持的分块策略包括 Recursive、Token、Fixed、RecursiveCharacterTextSplitter、Character 等，可通过配置 CHUNKING strategy 参数选择合适的分块方式。

资料来源：lightrag/pipeline.py

API 服务架构

LightRAG Server 基于 FastAPI 构建，提供完整的 RESTful API 接口。API 架构采用分层设计，将路由处理、数据验证和业务逻辑分离。

API 端点概览

资料来源：lightrag_webui/src/api/lightrag.ts

查询请求参数

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 中的占位符注入配置，确保所有资源引用使用相对路径。

// 运行时配置注入点
window.__LIGHTRAG_CONFIG__ = {
  apiPrefix: "/lightrag/api",      // API 路径前缀
  webuiPrefix: "/lightrag/"        // WebUI 路径前缀
}

资料来源：lightrag_webui/src/lib/runtimeConfig.ts

前端架构

WebUI 组件

LightRAG WebUI 是基于 React 构建的单页应用，使用 Tailwind CSS 进行样式设计，提供直观的可视化交互界面。

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

支持的文件格式

资料来源：lightrag_webui/src/lib/constants.ts

3D 图谱可视化

LightRAG 提供独立的 3D 图谱可视化工具 lightrag-viewer，基于 ModernGL 渲染引擎和 imgui_bundle 构建。

资料来源：lightrag/tools/lightrag_visualizer/README.md

检索与查询流程

混合检索流程（Mix Mode）

Mix 模式是 LightRAG 的默认查询模式，结合了向量检索和知识图谱检索的优势：

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 的上下文窗口限制：

系统采用动态分配策略，根据各部分的重要性自动调整各部分的内容量。

数据模型

文档状态模型

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 知识图谱采用实体-关系双层结构：

实体类型支持中文同义词映射，例如「人物」映射为 person，「组织」映射为 organization，「概念」映射为 concept 等。

资料来源：lightrag_webui/src/utils/graphColor.ts

部署架构

Docker 部署

LightRAG 支持 Docker Compose 一键部署，所有服务通过容器化运行：

# docker-compose 结构
services:
  lightrag-server    # API 服务
  openwebui          # 可选：WebUI 前端
  storage-backend    # 存储后端服务

交互式配置向导

v1.4.11 版本引入交互式配置向导，通过 Makefile 目标简化部署配置：

资料来源：README.md

多模态扩展

v1.5.0 版本集成了 RAG-Anything 的多模态处理能力，支持以下内容类型的处理：

多模态处理依赖外部解析服务（ MinerU 或 Docling），解析后的内容通过标准管道进行索引。

常见问题与注意事项

文档标识问题

社区反馈（Issue #3158、#323）指出系统目前通过内部 doc_id 管理文档，而非文件名。如果需要追踪文档来源，建议在上传时添加自定义元数据。

嵌入模型兼容性

嵌入模型必须在文档索引和查询阶段保持一致。某些存储后端（如 PostgreSQL）在创建向量表时需要指定维度，因此更换嵌入模型可能需要重建索引。

LLM 选型建议

相关文档

• 快速开始指南
• 编程接口文档
• API 服务文档
• 高级特性文档
• 交互式配置向导
• 离线部署指南

概述

LightRAG 的存储系统采用插件化架构，每种存储类型（KV、向量、图谱、文档状态）都有独立的接口定义和多种实现。版本 v1.4.11 引入了 OpenSearch 作为统一存储后端，可以同时支持所有四种存储类型，简化了部署复杂度。资料来源：README.md:1-50

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]

支持的存储后端

存储后端对比

资料来源：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

配置参数

# .env 配置示例
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=lightrag
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag
POSTGRES_ENABLE_VECTOR=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 配置

# 启动 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 查询语言：强大的图查询能力
• 原生图遍历：高效的节点和关系查询
• 图算法支持：内置中心性、路径查找等图算法

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

配置示例

# .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 访问场景

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

索引类型选择

资料来源：docs/MilvusConfigurationGuide.md:1-100

配置参数

# .env 配置示例
MILVUS_HOST=localhost
MILVUS_PORT=19530
MILVUS_COLLECTION=lightrag_vectors
MILVUS_INDEX_TYPE=HNSW
MILVUS_METRIC_TYPE=COSINE

向量维度与嵌入模型

重要约束

警告：向量维度必须在首次创建向量表时确定，且必须与使用的嵌入模型输出维度匹配。更换嵌入模型（如从 bge-m3 切换到 text-embedding-3-large）需要删除现有向量表并重新创建。资料来源：README.md:1-50

维度对应关系

资料来源：README.md:1-50

交互式配置向导

LightRAG 提供了交互式配置向导简化存储后端配置：

# 基础环境配置（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

相关文档

• 快速开始指南
• 交互式配置向导
• Milvus 配置指南
• Docker 部署指南
• 离线部署指南
• 使用 Core 编程
• 高级功能

参见

• LightRAG Server - 完整 API 服务器文档
• 评估与部署 - 存储性能评估方法

概述

文本分块（Text Chunking）是 LightRAG 系统中文档处理的核心环节之一。原始文档被切分成较小的文本块后，系统会对每个块进行向量化处理，并建立与知识图谱的关联关系。合理的分块策略直接影响检索质量和查询准确性。

LightRAG 支持多种分块策略，开发者可根据文档类型和业务需求选择合适的方案。分块策略在文档索引阶段生效，通过 chunking_strategy 参数指定。资料来源：lightrag/chunker/__init__.py:1-50

分块策略类型

LightRAG 提供了以下几种内置分块策略，每种策略适用于不同的场景：

资料来源：lightrag/chunker/__init__.py:10-30

TokenSize 分块策略

TokenSize 是最基础的分块策略，按照预设的 token 数量将文本切分成固定大小的块。这种方式简单高效，适合大多数通用场景。

核心参数：

# 示例配置
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. 重复此过程直到所有块符合大小限制

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 参数指定分块策略：

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 接口上传文档时，可在请求中指定分块策略：

资料来源：lightrag_webui/src/api/lightrag.ts:1-100

文件类型与分块处理

LightRAG 根据文件类型自动应用适当的处理流程。系统支持以下文件类型的分块处理：

资料来源：lightrag_webui/src/lib/constants.ts:1-50

分块策略与检索质量

块大小对检索的影响

选择策略的建议

代码类文档：

• 推荐使用 Recursive 策略
• 保留代码块、函数边界的完整性
• 适当增大块大小以保持代码逻辑

自然语言文档：

• 推荐使用 Paragraph 或 SemanticVector 策略
• 保持段落语义完整
• 自动识别主题边界

结构化数据：

• 推荐使用 TokenSize 策略
• 固定大小便于批量处理
• 通过重叠 token 保持连续性

常见问题与解决方案

问题一：同名文档区分

问题描述： 上传多个同名但内容不同的文档时，无法区分来源。

解决方案： LightRAG 通过文档 ID 追踪文档来源，而非文件名。查询时可通过 file_path 字段获取源文件信息。

# 查询时获取源文件信息
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. 存储 - 分别存入向量库和图数据库

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

分块策略直接影响实体抽取的质量。较大的块可能包含更多上下文，但也会增加抽取难度；较小的块则可能丢失实体间的关系信息。

进阶配置

自定义分块参数

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 支持异步批量插入：

# 批量插入文档
await rag.ainsert_many(
    documents=document_list,
    chunking_strategy=ChunkingStrategy(name="Recursive")
)

相关文档

• 段落语义分块详解 - 深入了解 Paragraph 策略原理
• 非对称嵌入 - 了解查询与文档嵌入的差异
• 核心编程指南 - 完整的 API 使用说明
• 高级特性 - 多模态处理和评估功能

参考资料

• LightRAG 官方仓库：https://github.com/HKUDS/LightRAG
• 分块策略源码：lightrag/chunker/

概述

什么是知识图谱提取

知识图谱提取是指使用大语言模型（LLM）从非结构化文档中自动识别和抽取实体（Entity）与关系（Relation），并将抽取结果存储为图结构数据的过程。与传统的向量检索仅关注文本片段的相似性不同，知识图谱能够捕捉实体之间的语义关联，形成"实体-关系-实体"的三元组结构。

在 LightRAG 中，文档经过分块处理后，每个文本块会经过 LLM 分析，识别出其中的实体节点及其属性、关系边及其类型。随后，这些节点和边被持久化到图数据库中，支持后续的局部检索（Local Search）和全局检索（Global Search）操作。

为什么需要知识图谱提取

传统的 RAG 系统在处理复杂查询时存在明显局限：当用户问题涉及多个实体之间的关系推理时，纯向量检索难以有效捕捉跨文档的关联信息。LightRAG 通过知识图谱提取解决了这一问题：

• 结构化语义表示：将文本中的隐含关系显式化为图结构，便于精确查询
• 多跳推理支持：支持多跳查询，如"某实体的邻居的邻居"
• 可解释性增强：检索结果可以追溯到具体的实体和关系路径
• 检索精度提升：结合向量检索和图检索，显著提高混合查询的准确率

资料来源：README.md:1-50

系统架构

整体数据流

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/ 目录下，主要包括：

资料来源：lightrag/prompt.py、lightrag/utils_graph.py

提取流程详解

文本分块策略

文档在进入实体提取之前需要先进行分块处理。LightRAG 支持多种分块策略，可通过配置参数 chunk_token_size 和 chunk_method 进行调整：

分块策略的选择直接影响实体提取的质量：较小的块有助于提取细粒度实体，但可能丢失上下文信息；较大的块则相反。建议根据文档类型和领域特点进行调优。

资料来源：README.md - 分块配置说明

实体识别与提取

每个文本块被发送给 LLM 进行实体提取。LightRAG 使用精心设计的提示词模板，引导模型识别以下信息：

实体节点属性：

• entity_name：实体名称（唯一标识）
• entity_type：实体类型（如：人物、地点、概念、事件等）
• entity_description：实体的简要描述

关系边属性：

• src_entity：源实体名称
• tgt_entity：目标实体名称
• relation：关系类型（如：属于、工作于、创建于等）
• weight：关系强度权重（1-10）
• relation_description：关系的详细描述

graph LR
    A[文本块] --> B[LLM实体提取]
    B --> C[实体节点列表]
    B --> D[关系边列表]
    C --> E[去重合并]
    D --> E
    E --> F[知识图谱存储]

实体类型映射

LightRAG 支持多语言实体类型识别，并提供自动类型映射功能。系统定义了标准的实体类型及其同义词：

资料来源：lightrag_webui/src/utils/graphColor.ts

配置与使用

LLM 模型配置

实体提取对 LLM 的能力要求较高，LightRAG 提供了角色级别的 LLM 配置，可以为提取任务单独指定模型：

配置示例（.env）：

# 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选择指南

自定义知识图谱插入

对于已有结构化知识的场景，LightRAG 支持通过 insert_custom_kg 功能批量导入外部知识图谱：

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

知识图谱存储后端

LightRAG 支持多种图数据库作为知识图谱的存储后端：

选择存储后端时需考虑：部署复杂度、社区支持、扩展性需求等因素。MongoDB 和 OpenSearch 提供了一体化存储方案，可减少系统复杂度。

资料来源：README.md - v1.4.11 发布说明

知识图谱可视化

WebUI 可视化

LightRAG Server 提供了交互式知识图谱可视化界面，支持：

• 多种重力布局算法
• 节点类型筛选和查询
• 子图过滤和导出
• 节点/边的属性查看

界面中不同类型的实体节点以不同颜色区分，便于直观理解知识图谱的结构。

资料来源：README.md - LightRAG Server

3D 图谱查看器

LightRAG 提供了独立的 3D 图谱可视化工具：

pip install lightrag-hku[tools]
lightrag-viewer

功能特性：

• 高性能 3D 渲染（基于 ModernGL）
• 多种布局算法：Spring、Circular、Shell、Random
• 社区检测和可视化
• 键盘+鼠标交互控制

控制方式：

资料来源：lightrag/tools/lightrag_visualizer/README.md

自定义可视化集成

LightRAG 支持导出图数据用于第三方可视化工具：

Neo4j 导出示例：

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、examples/graph_visual_with_html.py

查询模式与提取的配合

局部检索（Local Search）

当查询涉及特定实体时，局部检索首先定位该实体节点，然后沿着关系边探索其邻居节点：

graph TD
    A[用户查询] --> B[关键词提取]
    B --> C[定位目标实体]
    C --> D[探索一层邻居]
    D --> E[探索二层邻居]
    E --> F[收集关联文本块]
    F --> G[返回上下文]

全局检索（Global Search）

当查询需要跨领域综合分析时，全局检索使用社区检测算法（如 Leiden）将知识图谱划分为多个社区，每个社区代表一个语义聚类：

graph TD
    A[用户查询] --> B[关键词提取]
    B --> C[社区检测]
    C --> D[选择相关社区]
    D --> E[收集社区内实体]
    E --> F[聚合社区描述]
    F --> G[返回综合上下文]

混合模式（Mix Mode）

v1.4.9 引入的混合模式结合了局部和全局检索的优势，通过重排序（Reranker）机制动态调整检索结果的优先级：

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 发布说明

常见问题与故障排除

实体提取质量不佳

症状：检索结果不准确，实体遗漏或错误关联。

排查步骤：

1. 检查 LLM 模型配置是否正确加载
2. 确认 chunk_token_size 是否适合文档长度（过小的块可能丢失上下文）
3. 查看 lightrag/prompt.py 中的提示词是否与领域匹配
4. 考虑定制提示词模板以适应特定领域术语

解决方案：自定义 prompt.py 中的提取提示词，针对特定领域优化实体类型和关系描述。

资料来源：lightrag/evaluation/sample_documents/README.md - 提示词优化建议

文档区分问题

症状：同名文档的内容被混淆。

背景：这是社区中反馈较多的问题（参见 Issue #3158）。当前系统通过 file_path 字段区分文档，但由于存储设计限制，同名文件可能覆盖或混淆。

建议方案：

1. 确保上传文件时使用唯一命名（包括相对路径信息）
2. 利用文档上传 API 时指定唯一的 file_key
3. 关注后续版本更新，社区正在讨论改进方案

资料来源：Issue #3158 - 文档区分问题讨论

知识图谱更新与删除

v1.4.10 引入了文档删除功能，删除文档时会自动触发相关知识图谱的重新生成，确保索引一致性：

# 删除文档并自动更新知识图谱
rag.delete_document(document_id)

注意：删除操作会触发完整的知识图谱重建，对于大型知识库可能需要较长时间。

资料来源：README.md - v1.4.10 发布说明

大规模导入性能优化

对于需要导入海量知识图谱数据的场景，insert_custom_kg 函数已进行批量操作优化：

• 启用批量图操作以减少数据库往返
• 支持增量导入避免重复处理
• 建议分批提交（每批 1000-5000 条边）

资料来源：README.md - v1.4.14 性能优化说明

性能考量

模型选择建议

v1.4.9 版本增强了开源模型的实体提取准确性，特别针对 Qwen3-30B-A3B 进行了优化。

Token 预算控制

LightRAG 提供了统一的 Token 预算控制系统，防止单次查询消耗过多上下文：

资料来源：lightrag_webui/src/api/lightrag.ts - QueryRequest 类型定义

相关文档

• LightRAG 核心编程指南 - Core API 完整参考
• 高级功能 - Token 追踪、导出、Langfuse 集成
• 多模态文档处理 - 图片、表格、公式解析
• 交互式部署向导 - 一键部署配置
• 算法详解 - 检索和查询算法原理

参考资料

• LightRAG 官方仓库：https://github.com/HKUDS/LightRAG
• RAG-Anything 多模态扩展：https://github.com/HKUDS/RAG-Anything
• VideoRAG 视频理解：https://github.com/HKUDS/VideoRAG

概述

LightRAG 从 v1.5.0 版本开始全面支持多模态文档处理，能够充分利用文档中的图像、表格和公式来回答查询。所有 RagAnything 的多模态处理能力已合并到 LightRAG 中，用户可以在不依赖外部系统的情况下完成复杂的文档解析和检索任务。

多模态处理功能允许 LightRAG 不仅索引文本内容，还能理解并检索嵌入在文档中的视觉元素（如图片、图表）和结构化数据（如表格、公式）。这对于处理技术文档、学术论文、商业报告等包含丰富多媒体内容的文件尤为重要。

资料来源：README.md

支持的文档格式

LightRAG 多模态处理支持多种常见的文档格式，具体支持的文件类型如下：

文本类文档

代码类文档

LightRAG 支持以下代码文件格式的纯文本处理：

资料来源：lightrag_webui/src/lib/constants.ts

处理架构

整体架构流程

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 通过外部解析服务实现多模态文档处理，主要支持两种解析引擎：

解析服务需要独立部署，LightRAG 通过 API 接口与这些服务通信。用户可以在配置中指定使用的解析服务及其连接参数。

资料来源：docs/AdvancedFeatures.md

多模态索引流程

VLM 角色配置

LightRAG 支持角色特定的 LLM 配置，其中 VLM（视觉语言模型）角色专门用于处理多模态内容的理解和描述生成。

# 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

查询模式与多模态支持

查询模式类型

LightRAG 提供多种查询模式，多模态内容可以在所有模式下被检索和使用：

查询请求示例：

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

配置说明

环境变量配置

启用多模态处理需要在 .env 文件中进行以下配置：

# 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 提供了交互式设置向导来简化配置过程：

# 基础环境配置
make env-base

# 存储后端配置
make env-storage

# 服务器配置
make env-server

运行设置向导后，系统会引导用户完成 LLM、Embedding、重排序模型以及存储后端的配置。

资料来源：docs/InteractiveSetup.md

WebUI 使用指南

文件上传

通过 LightRAG WebUI 上传文档时，系统会自动识别文件类型并调用相应的解析器：

1. 访问 LightRAG Server 的 WebUI 界面
2. 点击上传按钮或拖拽文件到上传区域
3. 选择要上传的文档（支持多选）
4. 系统自动进行多模态内容提取

文档管理

上传后的文档可以在 WebUI 中进行管理：

interface DocStatusResponse {
  id: string;              // 文档唯一标识
  file_name: string;       // 文件名
  file_path: string;       // 文件路径
  status: DocStatus;       // 处理状态
  total_chunks: number;    // 分块数量
  error_msg?: string;      // 错误信息
}

支持按状态筛选文档列表，便于跟踪处理进度和排查问题。

资料来源：lightrag_webui/src/api/lightrag.ts

常见问题与解决方案

文档名称区分问题

社区反馈（Issue #3158）：如何区分名称相同但内容不同的文档？

解决方案：LightRAG 使用文档的唯一标识符（UUID）来区分文档，文件名仅作为显示用途。如果需要按文件名追踪文档，建议在上传时添加额外元数据或使用文件路径中的目录结构来区分。

多模态支持集成方式

社区反馈（Issue #2642）：如何向 LightRAG 添加多模态支持？

说明：从 v1.5.0 开始，RagAnything 的所有核心功能已合并到 LightRAG 中。用户无需额外集成，直接通过配置 VLM 即可启用多模态处理能力。

解析服务部署

评估与测试

使用示例文档进行测试

LightRAG 提供了用于评估的示例文档集，位于 lightrag/evaluation/sample_documents/ 目录：

评估步骤：

# 1. 将示例文档索引到 LightRAG
# 2. 运行评估脚本
python lightrag/evaluation/eval_rag_quality.py

# 3. 预期结果：每个问题的 RAGAS 分数约 91-100%

资料来源：lightrag/evaluation/sample_documents/README.md

性能优化建议

并行处理配置

# 最大并行插入数
MAX_PARALLEL_INSERT=32

# 异步操作配置
MAX_ASYNC=128

# Embedding 批处理数量
EMBEDDING_BATCH_NUM=100

存储后端选择

对于大规模多模态文档处理，推荐使用支持全部四种存储类型的统一后端：

资料来源：README.md

相关文档

• 高级功能指南 - 包含多模态配置的详细说明
• 交互式设置向导 - 使用向导完成环境配置
• 编程接口参考 - Core API 的完整使用说明
• 离线部署指南 - 无法访问外网环境下的部署方法
• LightRAG Server - 服务器部署与 API 使用

系统概述

LightRAG 采用前后端分离的架构设计：

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 兼容接口

graph LR
    A[客户端请求] --> B[FastAPI路由]
    B --> C{认证检查}
    C -->|已认证| D[业务逻辑]
    C -->|未认证| E[返回401错误]
    D --> F[LightRAG Core]
    F --> G[存储后端]

资料来源：lightrag/api/lightrag_server.py

路由模块结构

API 服务器包含以下主要路由模块：

资料来源：lightrag/api/routers/

查询请求参数

LightRAG 支持多种查询模式，通过 QueryRequest 类型定义请求参数：

资料来源：lightrag_webui/src/api/lightrag.ts:18-50

查询模式

LightRAG 支持以下查询模式：

资料来源：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

运行时配置

WebUI 采用运行时配置机制，支持反向代理部署。配置通过 FastAPI 服务器在 HTML 响应时注入：

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 支持通过反向代理挂载到子路径。路径前缀规范化逻辑如下：

// 空值/undefined/"/" → 回退到 "/webui"
function normalizeWebuiPrefix(value: string | undefined | null, fallback = '/webui'): string

资料来源：lightrag_webui/src/lib/pathPrefix.ts:1-30

支持的文件类型

WebUI 和 API 服务器支持以下文档格式：

资料来源：lightrag_webui/src/lib/constants.ts:1-60

认证与安全

认证状态管理

LightRAG API 支持两种认证模式：

认证状态响应包含以下字段：

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

令牌管理

前端实现自动令牌刷新机制，防止多请求同时触发令牌刷新：

let isRefreshingGuestToken = false;
let refreshTokenPromise: Promise<string> | null = null;

资料来源：lightrag_webui/src/api/lightrag.ts:160-170

文档处理管道

文档状态追踪

文档上传后进入异步处理管道，状态流转如下：

stateDiagram-v2
    [*] --> 上传中
    上传中 --> 处理中: 上传完成
    处理中 --> 索引中: 开始索引
    索引中 --> 完成: 索引完成
    处理中 --> 失败: 处理错误
    索引中 --> 失败: 索引错误
    失败 --> [*]
    完成 --> [*]

文档状态响应

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<string, any>
}

资料来源：lightrag_webui/src/api/lightrag.ts:70-90

部署配置

环境变量配置

LightRAG 支持交互式配置向导生成 .env 文件：

# 基础配置（必需）
make env-base              # LLM、嵌入、重排模型配置

# 存储配置（可选）
make env-storage           # 存储后端和数据库服务

# 服务器配置（可选）
make env-server            # 服务器端口、认证、SSL

# 安全审计
make env-security-check    # 检查当前.env的安全风险

资料来源：README.md

Docker 部署

使用 Docker Compose 部署完整服务：

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # 编辑.env配置
docker compose up

官方镜像支持 Cosign 签名验证：

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

反向代理配置注意事项

⚠️ 已知问题：在反向代理子路径部署时，应用对资源使用绝对路径，可能导致资源加载失败。

社区反馈：Issue #2755

解决方案是确保正确配置 LIGHTRAG_API_PREFIX 和 LIGHTRAG_WEBUI_PATH 环境变量。

常见问题

如何区分同名但内容不同的文档？

社区讨论：Issue #3158

当前实现中，文档通过 doc_id 标识，文件名不作为唯一标识。建议在上传时使用包含内容哈希或时间戳的自定义文件名。

如何获取查询使用的源文件？

社区讨论：Issue #323

当前版本已支持引用功能，查询结果可返回检索到的上下文片段。详细配置请参考 AdvancedFeatures.md。

多模态支持

v1.5.0 版本已集成 RAG-Anything 的多模态处理能力，支持：

• PDF 文档中的图片、表格、公式提取
• Office 文档处理
• 图文混合索引

详细配置见 AdvancedFeatures.md。

另请参阅

• LightRAG-API-Server.md - API服务器详细文档
• FrontendBuildGuide.md - 前端构建指南
• InteractiveSetup.md - 交互式配置向导
• AdvancedFeatures.md - 高级功能配置
• ProgramingWithCore.md - Core API编程指南
• DockerDeployment.md - Docker部署指南

概述

LightRAG Core 是整个系统的核心引擎，提供了完整的检索增强生成（RAG）功能。与 LightRAG Server 不同，Core 库专注于为开发者提供嵌入式的编程接口，适用于需要将 RAG 功能直接集成到 Python 应用中的场景。

适用场景：

• 将 LightRAG 嵌入到现有的 Python 应用中
• 研究人员需要进行 RAG 相关的实验和评估
• 需要对文档处理流程进行细粒度控制的场景

不适用场景：

• 生产环境部署（建议使用 REST API）
• 需要 Web UI 和知识图谱可视化的场景
• 不熟悉 Python 编程的用户

资料来源：docs/ProgramingWithCore.md:1-15

Pitfall Log / 踩坑日志

项目：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