安装

💡 使用 uv 进行包管理：本项目使用 uv 进行快速可靠的 Python 包管理。首先安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh（Unix/macOS）或 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"（Windows）

注意：如果你愿意，也可以使用 pip，但推荐使用 uv，以获得更好的性能和更可靠的依赖管理。

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

安装 LightRAG 服务器

• Install from PyPI

### Install LightRAG Server as tool using uv (recommended)
uv tool install "lightrag-hku[api]"

### Or using pip
# python -m venv .venv
# source .venv/bin/activate  # Windows: .venv\Scripts\activate
# pip install "lightrag-hku[api]"

# Setup env file
# Obtain the env.example file by downloading it from the GitHub repository root
# or by copying it from a local source checkout.
cp env.example .env  # Update the .env with your LLM and embedding configurations
# Launch the server. It binds to all interfaces (0.0.0.0) by default.
# SECURITY: before exposing it on a network, configure authentication in .env
# (LIGHTRAG_API_KEY, or AUTH_ACCOUNTS together with TOKEN_SECRET), or bind to
# 127.0.0.1 for local-only access; without auth every endpoint is public.
# Note: the Ollama-compatible /api/* routes stay open by default for client
# compatibility; set WHITELIST_PATHS=/health to require auth on them too.
lightrag-server

• 从源码安装

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

# Bootstrap the development environment (recommended)
make dev
source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
# Or on Windows: .venv\Scripts\activate

# make dev installs the test toolchain plus the full offline stack
# (API, storage backends, and provider integrations), then builds the frontend.
# Run make env-base or copy env.example to .env before starting the server.

# Equivalent manual steps with uv
# Note: uv sync automatically creates a virtual environment in .venv/
uv sync --extra test --extra offline
source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
# Or on Windows: .venv\Scripts\activate

### Or using pip with virtual environment
# python -m venv .venv
# source .venv/bin/activate  # Windows: .venv\Scripts\activate
# pip install -e ".[test,offline]"

# Build front-end artifacts
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

# setup env file
make env-base  # Or: cp env.example .env and update it manually
# Launch API-WebUI server
lightrag-server

• 使用 Docker Compose 启动 LightRAG 服务器

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # Update the .env with your LLM and embedding configurations
# modify LLM and Embedding settings in .env
docker compose up

LightRAG Docker 镜像的历史版本可以在这里找到：LightRAG Docker Images

由 GitHub Actions 发布的官方 GHCR 镜像使用 GitHub OIDC 通过 Sigstore Cosign 签名。有关验证命令，请参见 docs/DockerDeployment.md。

在 Apple Silicon（macOS 26）上没有 Docker Desktop 的情况下，你可以在 Apple 原生的 container 运行时上运行相同的 Postgres/Neo4j/Milvus 存储堆栈 — 参见 docs/AppleContainerSetup.md。

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

不要手动编辑 env.example，使用交互式设置向导生成配置好的 .env 文件，并在需要时生成 docker-compose.final.yml：

make env-base           # Required first step: LLM, embedding, reranker
make env-storage        # Optional: storage backends and database services
make env-server         # Optional: server port, auth, and SSL
make env-base-rewrite   # Optional: force-regenerate wizard-managed compose services
make env-storage-rewrite # Optional: force-regenerate wizard-managed compose services
make env-security-check # Optional: audit the current .env for security risks

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

可选：用于 docx smart_heading 的 spaCy 模型

原生 docx 解析器的可选 smart_heading 引擎参数使用 spaCy 进行句子/命名实体识别启发式分析。spaCy 运行时已经包含在 api 额外依赖中——只需要对两个固定的语言模型（zh_core_web_sm / en_core_web_sm 3.8.0, GitHub 发布的 wheel 未在 PyPI 上发布）执行一个额外步骤：

lightrag-download-cache --spacy-install

针对每个文件/规则启用 smart_heading（例如 LIGHTRAG_PARSER=docx:native(smart_heading=true)），或在 .env 中全局启用：

# .docx files routed to the native engine get smart_heading by default;
# opt a file back out with an explicit native(smart_heading=false) rule/hint.
DOCX_SMART_HEADING=true

当全局开关开启时（或 LIGHTRAG_PARSER 规则带有 native(smart_heading=true)），服务器在启动时会验证模型，如果缺失则会快速失败并提供安装指导。那些从未启用 smart_heading 的部署不需要模型。主 Docker 镜像自带预安装模型（lite 镜像不带）；对于隔离网络的主机，请参阅离线部署指南。

可选：用于 SVG 光栅化的 libcairo（本地 md/textpack）

本地 markdown/textpack 解析器通过 cairosvg 将嵌入的 SVG 图像光栅化为 PNG。cairosvg 是 cffi 绑定：pip install cairosvg（通过 api 额外依赖安装）总是成功的，但渲染仅在宿主机上同时存在本地 libcairo 共享库时才可工作 — pip/uv 无法安装系统库。没有它，光栅化在运行时会失败，并且受影响的 SVG 会被跳过（文档的其余部分不受影响）；服务器在启动时会记录警告，因此在稍后以每文档警告形式出现之前，这一问题是可见的。

请为您的平台安装系统软件包：

# Debian / Ubuntu (the official Docker image already includes this)
sudo apt-get install -y libcairo2

# RHEL / Fedora
sudo dnf install -y cairo

# macOS (Homebrew)
brew install cairo

# Windows: install the GTK3 runtime, which bundles libcairo-2.dll

那些从未处理带有嵌入SVG的markdown/textpack文档的部署可以忽略启动警告。

关于 LightRAG

一个轻量级、基于图的RAG框架

LightRAG是一个轻量级知识图谱RAG框架，是Microsoft GraphRAG的高效替代方案。它采用双层架构来管理知识图谱（KG）和向量嵌入，有效弥合了传统基于向量的RAG与基于图的RAG方法之间的差距。LightRAG设计具备高可扩展性，解决了大规模图索引和检索中的关键挑战，包括计算开销大、响应时间慢以及增量更新成本高等问题。在支持大数据集的同时，即使与30B开源大语言模型（LLM）搭配使用，LightRAG仍能提供异常高的RAG质量。

功能与优势

• 深度上下文理解： 通过图结构索引，LightRAG捕捉实体间复杂的语义依赖，克服传统基于分块检索方法的片段化上下文限制。在需要全局理解或逻辑推理的垂直领域（如法律、金融）中，其生成质量和上下文感知能力尤为出色。
• 卓越的全面性与多样性： LightRAG的双层检索机制允许其同时整合详细事实和抽象概念，使系统在查询结果的全面性和多样性上表现出色，并能够高效处理复杂的跨文档查询。
• 极高的检索效率与低成本： LightRAG不依赖低效的社区报告或多跳推理来处理复杂查询。这大幅减少了索引和查询阶段所需的LLM调用次数，显著降低响应延迟和LLM计算成本。
• 增量更新与选择性删除： LightRAG解决了从基于图的知识库中进行增量更新和选择性删除内容的挑战，使其在动态数据环境中保持最新。当文档被删除时，系统可以使用在索引阶段创建的LLM缓存快速重建受影响的实体和关系，大幅提升更新效率。
• 多文档解析引擎： LightRAG的文档处理管线支持MinerU、Docling和Native，并可以扩展第三方解析器。LightRAG的Native引擎能高效解析Word和Markdown文档中的图片、表格与公式，非常适合多模态内容丰富的文档。Native引擎还可自动检测并纠正Word文档中的章节标题，提升对文档结构不一致部分的内容提取能力，为基于章节的文本分块奠定基础。
• 多重文本分块策略： LightRAG 支持四种文本分块策略：Fixed-length (F)、Recursive character (R)、Vector semantic (V) 和 Paragraph semantic (P)。LightRAG 原生的 Paragraph semantic (P) 策略尽可能将分块边界与文档的原生语义边界对齐——如标题、段落和表格。这样可以减少长表格拆分时出现标题与内容不匹配或缺失表头行等问题。
• 多存储后端： LightRAG 默认的键值、向量和图存储是带本地文件持久化的内存数据库——仅适合小规模测试和评估，不适合生产环境。LightRAG 同时支持广泛使用的生产环境存储后端（推荐 PostgreSQL），适用于大规模数据集的部署。

多模态能力升级

传统 RAG 系统缺乏有效处理文档中多模态内容（如图像、公式和表格）的方法。从 v1.5 开始，LightRAG 将多模态处理无缝集成到文档管道和查询流程中。通过知识图谱，LightRAG 将多模态内容与正文连接起来，并在回答查询时利用这些信息，从而生成更准确可靠的响应。该能力可显著提升丰富多模态内容文档（如操作手册和学术论文）的 RAG 质量。

LightRAG API 服务器

LightRAG 服务器不仅提供基于网页的 UI 以探索 LightRAG 功能，还提供完整的 REST API。如需了解 LightRAG 服务器的更多信息，请参阅 LightRAG Server。

关键配置指南

选择 LLM 模型

LightRAG 在工作流程中需要四种不同角色的 LLM/VLM。您应为不同角色配置不同能力和速度的模型，以在性能与处理速度之间取得平衡。LightRAG 对大型语言模型（LLMs）的能力要求高于传统 RAG，因为它需要 LLM 从文档中执行复杂的实体-关系提取任务。在查询阶段，LLM 需处理大量检索信息，包括实体、关系和文本块。这要求模型具备在冗长且噪声环境下生成高质量响应的能力。

按角色推荐模型：

• 抽取型 LLM (EXTRACT)： 实体-关系提取将在每个文本块上运行，因此一款快速且经济的主流模型即可——强烈推荐使用非思考模型（禁用推理/思考模式），以避免提取过程缓慢且昂贵。国际上较好的托管选项包括 GPT-5.6-luna、Claude Haiku 或 Gemini-mini，中国则有 DeepSeek-V4-lite 或 Kimi。本地部署时，Qwen3-30B-A3B-Instruct 是合理的最低选择。
• 查询大语言模型 (QUERY)：该模型从冗长、杂乱的检索上下文中生成最终答案，因此它的能力应当比抽取模型更强，以最大化答案质量。可以从相同系列中选择更高等级的模型；具备思考能力的模型在这里是合适的。
• 关键词 LLM (KEYWORD)：一个轻量级、对延迟敏感的步骤，必须使用不进行思考的模型以保持查询延迟低；一个与提取模型相当的快速模型即可。
• VLM (VLM)：任何支持图像输入的主流多模态模型都可以使用。对于本地部署，可考虑 Qwen3.6-35B-A3B。

在您可接受的延迟和成本预算内，优先选择可用的最高评分模型（基于公开基准/排行榜）。有关详细模型配置，请参阅 RoleSpecificLLMConfiguration.md

查询模式选择

LightRAG 支持五种查询模式：

• 本地：专注于局部上下文和特定实体的精确匹配。它从知识图谱中检索候选实体及其直接关联的属性。该模式适合针对特定对象、具体概念或详细事实的问答，提供高度相关且详尽的本地上下文支持。
• 全局：关注宏观主题、跨文档推理及实体间的深度关系。检索涵盖广泛主题和概念的关系链。该模式适合需要跨多上下文摘要、趋势分析或理解复杂语义依赖的查询。
• 混合模式：合并局部和全局模式的检索结果。通过同时回忆特定实体和全局关系上下文，实现全面的推理和生成。
• 天真：基于文本块的传统RAG检索。它不使用知识图谱，直接依赖向量相似度从原始文本块检索。
• mix：功能齐全的模式，整合本地、全局和天真模式的检索结果，提供最全面、最丰富的检索结果。

LightRAG 的默认查询模式是 mix。使用 mix 模式通常会产生最理想的查询结果。mix 模式比 naive 略慢，而其他查询模式的延迟大致相当。

嵌入模型

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

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

启用重新排序

在查询阶段启用 Rerank 选项可以显著提高查询质量。然而，启用 Rerank 通常会引入 1-2 秒的延迟。为了最小化延迟，强烈建议将 Rerank 模型本地部署。任何主流、最新的 reranker 都可使用；对于本地部署，推荐 BAAI/bge-reranker-v2-m3。有关配置的详细信息，请参考 env.example 文件。与嵌入模型不同，Rerank 模型可以在查询阶段随时更改。

文档处理管道配置

LightRAG 的默认管道配置无法使系统达到最佳性能。文档解析的质量对文档索引和查询影响很大。因此，我们建议配置管道以启用 MinerU 解析引擎，并激活管道的图像分析功能。建议配置如下：

LIGHTRAG_PARSER=*:native-iteP,*:mineru-iteP,*:legacy-R

VLM_PROCESS_ENABLE=true
VLM_LLM_MODEL=<your_vlm_model_name>

由于基于云的 MinerU 服务在使用、文件大小和页面数量上有一定限制，建议使用本地部署的 MinerU。有关配置文件处理管道的详细信息，请参阅 FileProcessingPipeline.md

文件处理的并发优化

对于大规模文档处理，您需要提高并发能力。与并发文件处理相关的关键环境变量包括：

• MAX_ASYNC_LLM：设置 LLM 角色的基础并发量（MAX_ASYNC仍为废弃别名）。在文件处理期间，它还限制一个文档的块的实体/关系提取任务数量；每个实体合并或关系合并阶段可以运行的任务数量最多为该值的两倍。
• EXTRACT_MAX_ASYNC_LLM：可选地覆盖 Extract 角色的实际提取和合并摘要 LLM 请求的限制。如果未设置，则继承 MAX_ASYNC_LLM；它不会更改上述管道任务限制。
• MAX_PARALLEL_INSERT：控制并行处理文件的最大数量，而非每个文档块或图合并任务的限制。理想情况下，它应设置为 MAX_ASYNC_LLM 的约 1/3。
• MAX_PARALLEL_PARSE_MINERU：控制 MinerU 解析并行处理的文件数量。
• MAX_PARALLEL_PARSE_DOCLING：控制 Docling 解析并行处理的文件数量。
• EMBEDDING_FUNC_MAX_ASYNC：控制嵌入模型的最大并发量。
• EMBEDDING_BATCH_NUM：控制每个嵌入模型请求中包含的文本数量（每批次嵌入的数量）。增加此数量可以显著减少对嵌入模型的 API 调用次数，并加快嵌入存储中数据的持久化速度。

# Sample Configuration
MAX_ASYNC_LLM=8
MAX_PARALLEL_INSERT=3
EMBEDDING_FUNC_MAX_ASYNC=16
EMBEDDING_BATCH_NUM=32

选择后端存储

LightRAG 需要四种类型的后端存储：

• KV_STORAGE：用于保存 LLM 响应缓存、文本分块结果、实体-关系提取结果等。
• VECTOR_STORAGE：用于存储文本分块、实体和关系的向量信息。
• GRAPH_STORAGE：用于保存知识图谱。
• DOC_STATUS_STORAGE：用于存储文档列表。

所有四种默认存储都是内存数据库（JsonKVStorage、NanoVectorDBStorage、NetworkXStorage、JsonDocStatusStorage）：整个数据集驻留在服务器进程的内存中，本地文件在 WORKING_DIR 下仅用作持久化存储，因此容量受可用内存限制。因此默认配置仅适用于小规模测试、评估和调试，并不适合生产环境。

对于生产环境，推荐使用 PostgreSQL 作为后端——它可以独自提供四种存储类型；MongoDB 和 OpenSearch 是其他单一后端选项。或者，你也可以为向量或图存储选择专门的数据库，例如使用 Milvus 或 Qdrant 来存储向量，使用 Neo4j 或 Memgraph 来存储图。

关于每种存储类型可用实现的完整列表，请参见 支持的存储类型。

文档处理的其他重要配置

在文档插入阶段，你可能还希望根据需要调整以下环境变量：

• SUMMARY_LANGUAGE：控制 LLM 输出实体-关系名称和摘要时使用的语言，例如 Chinese、English。
• ENTITY_EXTRACTION_USE_JSON：控制 LLM 是否以 JSON 格式输出实体-关系提取结果。使用 JSON 格式通常能获得更稳定的结果，但会消耗更多 token，并且可能稍慢。
• ENABLE_CONTENT_HEADINGS：控制在查询阶段是否将文本分块的章节标题信息发送给 LLM（默认启用，为 LLM 提供更多上下文）。
• FORCE_LLM_SUMMARY_ON_MERGE / MAX_SOURCE_IDS_PER_RELATION：控制一个 entity/relation 可以关联的文本块的最大数量。
• SOURCE_IDS_LIMIT_METHOD：控制当某个 entity/relation 超过其关联文本块限制时，是否继续更新实体/关系描述（默认情况下会停止更新，因为此时实体-关系描述已经足够丰富，进一步更新价值不大；跳过更新可以大大加快知识库构建速度）。
• MAX_FILE_PATHS：控制一个 entity/relation 可以关联的源文件的最大数量；一旦超过此限制，新的文件名将不再写入向量存储。

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

在实体-关系抽取过程中，LLM 超时通常可追溯到以下三种原因之一。先识别原因，然后应用相应的解决方法（参数可以组合使用）：

• 模型运行缓慢。 如果模型的速度低于约每秒 50 个 token，可能无法在请求超时前完成包含大量实体和关系的文本块。通过 *_LLM_TIMEOUT 增加超时时间——可以是全局 LLM_TIMEOUT 或抽取阶段的角色特定参数 EXTRACT_LLM_TIMEOUT。请注意，有效执行超时时间是配置值的两倍，因此 EXTRACT_LLM_TIMEOUT=300 最多允许 600 秒。
• 文本块产生的实体和关系过多。 例如参考文献块可能导致模型生成大量记录，这些记录无法在规定时间内完成。使用 OPENAI_LLM_MAX_TOKENS 或 OPENAI_LLM_MAX_COMPLETION_TOKENS 限制输出长度（具体参数名称取决于 LLM 提供商——见 env.example）。一个实用的计算规则是 max_output_tokens < LLM_TIMEOUT × tokens_per_second（例如 9000 < 240s × 50 tps）。
• 模型陷入输出循环。 一些模型（尤其是本地部署的 Qwen 模型）在处理某些文本时偶尔会进入无限输出循环。若这种情况是间歇性的，通常重新处理文档一次即可解决。
• 参考文献特别情况（P 块分割策略）。 在使用段落语义（P）分块策略（例如 LIGHTRAG_PARSER=...-iteP）时，设置 CHUNK_P_DROP_REFERENCES=true 可在分块前自动丢弃匹配的参考文献块。这可以防止参考文献产生大量低价值实体和关系，是常见的超时原因。也可以通过文件名提示单独启用，例如 paper.[-P(drop_rf=true)].pdf；相关检测参数（CHUNK_P_REFERENCES_TAIL_N，CHUNK_P_REFERENCES_HEADINGS）已在 env.example 中记录。

文档查询的其他重要配置

在文档查询阶段，你可能还需要根据需求调整以下环境变量：

• MAX_ENTITY_TOKENS / MAX_RELATION_TOKENS / MAX_TOTAL_TOKENS：控制发送到 LLM 上下文的检索内容的 token 长度。检索内容包括三部分：entities、relations 和 text chunks。实体和关系的长度可以独立控制，而文本块长度由总长度减去实体和关系的长度确定。
• ENABLE_CONTENT_HEADINGS：控制是否将文本块所在的章节标题发送给 LLM；默认启用，为 LLM 提供更丰富的上下文并提高回答质量。
• ENABLE_LLM_CACHE：是否缓存查询结果。默认启用；相同的查询问题、查询模式和 LLM 模型参数将返回相同结果。
• USER_PROMPT_PREFIX / USER_PROMPT_PREFIX_FILE：全局指令，预先添加到每个请求的 user_prompt 中（即回答提示的“附加指令”部分），为操作员提供一个自定义 LLM 输出的集中位置。它按字面连接，因此请在值末尾自己加上 \n\n。如果请求的 user_prompt 为空，则仅前缀将成为发送给 LLM 的指令；只有 API 字段 disable_user_prompt_prefix 可以禁止此行为，并且请求永远无法读取或替换它。对于长文本或多段文本，请使用 USER_PROMPT_PREFIX_FILE（位于 PROMPT_DIR/user_prompt 下的 .md/.txt 文件名），因为 .env 的值必须保持在一行内。

WebUI 条目和默认条目

服务器从单个前端构建挂载两个 WebUI 条目。/webui 是管理控制台：文档管理、知识图探索，以及带完整查询参数面板的查询调试。/workspace 是一个仅限查询的入口，为日常知识库用户设计：聊天界面，其他功能（无文档管理，无知识图，无查询参数侧栏，无 API 文档链接）均不可用，适合移动使用，并向未登录的访客显示欢迎页面。

• LIGHTRAG_DEFAULT_UI：根路径 / 重定向到的条目——webui（默认）或 workspace。它只控制 一个 行为：该重定向。无论如何，两个条目都会保持挂载并能通过各自 URL 访问；任何其他值将导致启动失败。当部署的主要用户是查询用户而非管理员时，请将其设置为 workspace。
• UI_TEMPLATES_DIR：指向可选的多语言包，可替换欢迎页面、登录页面文本、查询空状态、品牌标志和版权行，无需重建 WebUI。详见 UserDefinedUI.md。
• ENABLE_AI_CONTENT_NOTICE：在两个查询 UI（/workspace 和 /webui 检索面板）中，将每个 LLM 生成的 答案标记为 AI 生成；模型未编写的文本——如预设无上下文回复、管理面板的调试输出——保持未标记。默认关闭；仅为 UI 元素，从不进入 API 响应或存储的聊天历史。

在指向最终用户 /workspace 之前需要了解两点。第一，那里查询参数是 继承的，不可编辑：每个查询使用 /webui 在 同一浏览器 中保存的设置（若未保存则使用前端默认值），这是按浏览器本地状态保存，而非服务器全局策略。第二，隐藏管理员 UI 是 UX 区分，非 安全边界——API 仍会在服务器端授权所有端点。有关查询入口的完整行为，详见 LightRAG-API-Server.md。

使用 LightRAG 作为 SDK

⚠️ 为了将其集成到您的项目中，我们强烈建议使用 LightRAG 服务器提供的 REST API。 LightRAG SDK 主要用于嵌入式应用或学术研究与评估目的。

安装 LightRAG SDK

• 从源代码安装

cd LightRAG
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
uv sync
source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
# Windows 系统: .venv\Scripts\activate

# 或: pip install -e .

• 从 PyPI 安装

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

LightRAG SDK 示例代码

要开始使用 LightRAG 核心，请参考 examples 文件夹中的示例代码。此外，还提供了一个 视频演示 来指导您完成本地设置过程。如果您已经拥有 OpenAI API 密钥，可以立即运行演示：

### you should run the demo code with project folder
cd LightRAG
### provide your API-KEY for OpenAI
export OPENAI_API_KEY="sk-...your_opeai_key..."
### download the demo document of "A Christmas Carol" by Charles Dickens
curl https://raw.githubusercontent.com/gusye1234/nano-graphrag/main/tests/mock_data.txt > ./book.txt
### run the demo code
python examples/lightrag_openai_demo.py

有关流式响应实现示例，请参见 examples/lightrag_openai_compatible_demo.py。在执行之前，请确保相应修改示例代码中的 LLM 和嵌入配置。

注意 1：运行演示程序时，请注意不同测试脚本可能使用不同的嵌入模型。由一个模型写入的向量无法在另一个模型中使用，因此切换模型需要重新构建它们。对于 演示 数据，最简单的方法是删除演示目录（./dickens）并重新运行——语料库很小且可丢弃；如果你想保留 LLM 缓存，请保留 kv_store_llm_response_cache.json。对于 实际部署，不要删除工作目录：它保存着知识图谱和文本块，删除它会将重新嵌入的操作变为对每个文档的完整重新摄取。请改用 lightrag-rebuild-vdb——参见 切换嵌入模型。

注意 2：官方支持的示例代码只有 lightrag_openai_demo.py 和 lightrag_openai_compatible_demo.py。其他示例文件是社区贡献的，尚未经过全面测试和优化。

SDK 使用注意事项

有关使用 SDK 的详细说明，请参阅 docs/ProgramingWithCore.md。一些 LightRAG 功能未通过 REST API 暴露，仅可通过 SDK 访问。这些功能通常处于实验阶段，并且可能与未来版本不兼容。

复现实验论文中的结果

LightRAG 在农业、计算机科学、法律和混合领域的表现始终优于 NaiveRAG、RQ-RAG、HyDE 和 GraphRAG。有关完整的评估方法、提示和复现步骤，请参见 docs/Reproduce.md。

整体性能表

📚 文档和工具

参考文档（docs/）

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

部署和设置

服务器与 API

文档处理

模型与存储

SDK 和开发

维护工具（lightrag/tools/）

面向存储的工具会像服务器一样读取 .env 和环境变量，因此请从项目根目录以相同配置运行它们。它们中有几个会就地重写存储——检查链接的指南以确认服务器（及其他写入者）是否需要先停止；rebuild_vdb 需要这样做。

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

从权威源（图节点/边和 text_chunks KV 存储）删除并重建每个向量存储。在向量写入失败后，以及更改嵌入模型或维度后，这是恢复的方式。还提供只读一致性检查。

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

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

migrate_llm_cache.py — python -m lightrag.tools.migrate_llm_cache — README_MIGRATE_LLM_CACHE.md

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

kg_integrity_repair.py — python -m lightrag.tools.kg_integrity_repair [--apply] — README_KG_INTEGRITY_REPAIR.md

检查整个图的贡献是否缺失于 full_entities / full_relations 恢复锚点，报告无法恢复的孤儿，并可选择修复锚点，以便删除/重试可以再次发现它们。

source_conflict_repair.py — python -m lightrag.tools.source_conflict_repair list / ... repair — README_SOURCE_CONFLICT_REPAIR.md

列出声称拥有相同典范源密钥的文档，并将未作者选择的候选文件降级为重复。它从不自行选出胜者，也从不删除内容。

download_cache.py — lightrag-download-cache [--spacy-install] — OfflineDeployment.md

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

hash_password.py — lightrag-hash-password [--username USER] — LightRAG-API-Server.md

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

check_initialization.py — python -m lightrag.tools.check_initialization --demo — ProgramingWithCore.md

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

🔗 相关项目

生态系统与扩展

🤝 贡献

📖 引用

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