LightRAG Documentation

File: docs/DockerDeployment.md Copy Chapter

LightRAG Docker Deployment

A lightweight Knowledge Graph Retrieval-Augmented Generation system with multiple LLM backend support.

🚀 Preparation Copy Chapter

Clone the repository: Copy Section

# Linux/MacOS
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# Windows PowerShell
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

Configure your environment: Copy Section

# Linux/MacOS
cp env.example .env
# Edit .env with your preferred configuration

# Windows PowerShell
Copy-Item env.example .env
# Edit .env with your preferred configuration

LightRAG can be configured using environment variables in the .env file:

Server Configuration

• HOST: Server host (default: 0.0.0.0)
• PORT: Server port (default: 9621)

LLM Configuration

• LLM_BINDING: LLM backend to use (lollms/ollama/openai)
• LLM_BINDING_HOST: LLM server host URL
• LLM_MODEL: Model name to use

Embedding Configuration

• EMBEDDING_BINDING: Embedding backend (lollms/ollama/openai)
• EMBEDDING_BINDING_HOST: Embedding server host URL
• EMBEDDING_MODEL: Embedding model name
• EMBEDDING_ASYMMETRIC: Explicitly enable query/document asymmetric embeddings
• EMBEDDING_DOCUMENT_PREFIX: Document prefix for prefix-based asymmetric embeddings (or NO_PREFIX)
• EMBEDDING_QUERY_PREFIX: Query prefix for prefix-based asymmetric embeddings (or NO_PREFIX)

See Asymmetric Embedding Configuration for prefix
validation rules and provider-specific behavior.

RAG Configuration

• MAX_ASYNC_LLM: Base maximum LLM concurrency (deprecated alias: MAX_ASYNC). It also sets the per-document chunk-extraction task limit, while each entity/relation merge phase uses twice that task limit; see File Processing Pipeline Specification for the full pipeline and role-override rules.
• MAX_TOKENS: Maximum token size
• EMBEDDING_DIM: Embedding dimensions

🐳 Docker Deployment Copy Chapter

Docker instructions work the same on all platforms with Docker Desktop installed.

Build Optimization Copy Section

The Dockerfile uses BuildKit cache mounts to significantly improve build performance:

• Automatic cache management: BuildKit is automatically enabled via # syntax=docker/dockerfile:1 directive
• Faster rebuilds: Only downloads changed dependencies when uv.lock or bun.lock files are modified
• Efficient package caching: UV and Bun package downloads are cached across builds
• No manual configuration needed: Works out of the box in Docker Compose and GitHub Actions

Start LightRAG server: Copy Section

docker compose up -d

If you used the interactive setup, start the generated stack with:

docker compose -f docker-compose.final.yml up -d

The interactive setup keeps .env host-usable. Container-only hostnames such as postgres or host.docker.internal, along with staged SSL paths under /app/data/certs/, are injected into the generated docker-compose.final.yml for the lightrag service instead of being persisted back into .env.
On reruns, unchanged wizard-managed service blocks in docker-compose.final.yml are preserved by
default. To repair or fully regenerate those managed blocks from the bundled templates, rerun the
matching setup target with make env-base-rewrite or make env-storage-rewrite.

If the generated stack includes local Milvus, compose resolves MINIO_ACCESS_KEY_ID and
MINIO_SECRET_ACCESS_KEY at startup from the repo .env or exported shell environment. The
generated compose file does not snapshot those values, and docker compose exits immediately if
either variable is missing.

Before exposing the generated stack beyond localhost, run:

make env-security-check

That command audits the current .env for missing authentication, unsafe whitelist settings, weak
JWT secrets, and other setup-level security risks without rewriting any files.

LightRAG Server uses the following paths for data storage:

data/
├── rag_storage/    # RAG data persistence
└── inputs/         # Input documents

Container security (non-root) Copy Section

The official images run the server as a non-root user (lightrag, uid/gid 1000) to satisfy CIS Docker Benchmark 4.1. The behavior is designed so existing deployments keep working on upgrade:

• The container starts as root, takes ownership of the writable data directories, then drops to uid 1000 via gosu. This means existing root-owned bind-mount / PVC data is adopted automatically — no manual chown is needed when upgrading from an older image.
• Ownership is fixed for /app/data and any custom locations you set via WORKING_DIR, INPUT_DIR, PROMPT_DIR, or TIKTOKEN_CACHE_DIR, so pointing data outside /app/data still works.
• If you instead start the container with an explicit non-root user (Compose user: "1000:1000" or Kubernetes runAsUser: 1000), the startup chown is skipped — make sure the mounted directories are already owned by that uid.
• .env is not chowned, so the host keeps ownership and you can edit it freely. It only needs to be readable by uid 1000, which the default 0644 permission satisfies. A .env mounted read-only as 0600/0400 owned by a different uid will fail to load (clear PermissionError at startup); make it readable by uid 1000, or supply configuration via environment variables instead (env_file: / environment:, or k8s env / envFrom).

Passing server flags still works as before, e.g. docker run ghcr.io/hkuds/lightrag:latest --port 9622.

Note: the image starts as root and drops privileges at runtime (the pattern used by the official PostgreSQL/Redis images), so the running process is non-root while the image's configured USER is still root. Scanners that judge CIS 4.1 purely from the USER directive may still flag the image even though no server process runs as root.

Optional: local vLLM embedding and reranker Copy Section

To run embedding and/or reranking locally with vLLM, run make env-base and answer yes when prompted to run the embedding model and rerank service locally via Docker.
That configures the embedding service to use BAAI/bge-m3 on port 8001 with a local vLLM server, and can also add a vllm-rerank service on port 8000.

Alternatively, rerun make env-base later and enable only the rerank Docker prompt to add the vllm-rerank service automatically.
vLLM provides a v1/rerank endpoint that works with the cohere binding.

Example docker-compose.override.yml for GPU hosts (embedding + reranker):

services:
  vllm-embed:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    command: >
      --model BAAI/bge-m3
      --port 8001
      --dtype float16
    ports:
      - "8001:8001"
    volumes:
      - ./data/hf-cache:/root/.cache/huggingface
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  vllm-rerank:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    command: >
      --model BAAI/bge-reranker-v2-m3
      --port 8000
      --dtype float16
    ports:
      - "8000:8000"
    volumes:
      - ./data/hf-cache:/root/.cache/huggingface
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

For CPU-only hosts, use the official CPU image instead:

services:
  vllm-embed:
    image: vllm/vllm-openai-cpu:latest
    command: >
      --model BAAI/bge-m3
      --port 8001
      --dtype float32
    ports:
      - "8001:8001"
    volumes:
      - ./data/hf-cache:/root/.cache/huggingface

  vllm-rerank:
    image: vllm/vllm-openai-cpu:latest
    command: >
      --model BAAI/bge-reranker-v2-m3
      --port 8000
      --dtype float32
    ports:
      - "8000:8000"
    volumes:
      - ./data/hf-cache:/root/.cache/huggingface

Add the embedding and rerank config to .env:

EMBEDDING_BINDING=openai
EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_DIM=1024
EMBEDDING_BINDING_HOST=http://localhost:8001/v1
EMBEDDING_BINDING_API_KEY=local-key
VLLM_EMBED_DEVICE=cpu

RERANK_BINDING=cohere
RERANK_MODEL=BAAI/bge-reranker-v2-m3
RERANK_BINDING_HOST=http://localhost:8000/rerank
RERANK_BINDING_API_KEY=local-key
VLLM_RERANK_DEVICE=cpu

If LightRAG runs in Docker while vLLM runs on the host, the generated compose file rewrites those endpoints to:

EMBEDDING_BINDING_HOST=http://host.docker.internal:8001/v1
RERANK_BINDING_HOST=http://host.docker.internal:8000/rerank

For GPU, set:

VLLM_EMBED_DEVICE=cuda
VLLM_RERANK_DEVICE=cuda

Ensure the NVIDIA Container Toolkit is installed and the host has CUDA drivers available.
The setup wizard uses the CPU image by default for cpu device and the GPU image for cuda device.
When rerunning make env-base, an existing VLLM_EMBED_DEVICE / VLLM_RERANK_DEVICE value is
preserved instead of being overwritten by a fresh GPU auto-detection result.
Those templates already pin the matching vLLM --dtype (float32 on CPU, float16 on CUDA), so no separate VLLM_*_DTYPE environment variables are needed.

SSL certificates Copy Section

The setup wizard stages TLS certificate files under ./data/certs/ before generating the compose file.
This keeps generated host mounts under the same ./data root used by the default Docker deployment.

Custom UI content Copy Section

docker-compose.yml and docker-compose-full.yml mount ./data/ui_templates
read-only at /app/data/ui_templates and set UI_TEMPLATES_DIR to it. That
entry overrides the same key in .env, like WORKING_DIR and INPUT_DIR, so
one .env full of host paths keeps serving a source run as well. Both stay
inert until the directory actually holds a bundle: with no manifest.json
in it the server logs a warning naming the directory and serves its built-in
branding, so the default deployment starts normally. Drop a bundle in and
restart, and the server replaces the welcome page, the login-page text and user
agreement, the query empty state, the copyright line and the brand logo with the
bundle's content — per language, without rebuilding the frontend. From that point on the bundle
is validated in full: an invalid one makes the server refuse to start.

Create the directory before the first up so it is not created root-owned by
Docker:

mkdir -p ./data/ui_templates
cp -r docs/ui_templates_example/* ./data/ui_templates/

Podman: docker-compose.podman.yml keeps the mount and UI_TEMPLATES_DIR
commented out, because Podman is stricter than Docker about a bind mount whose
host source is missing. There, create the directory first and then uncomment
both — uncommenting the environment entry alone leaves the server pointed
at a path that is not mounted, and it refuses to start.

See UserDefinedUI.md (中文) for
the bundle format and the full deployment guide.

PostgreSQL image Copy Section

The interactive setup defaults PostgreSQL to gzdaniel/postgres-for-rag:pg18-age-pgvector. This image bundles both Apache AGE and pgvector so the generated stack works with PGGraphStorage and PGVectorStorage without extra extension setup. The published tag is a multi-architecture manifest covering linux/amd64 and linux/arm64.

The image no longer ships fixed credentials; on first start it creates the user, password, and database from the POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB environment variables. The setup wizard prompts for these values (defaulting to rag / rag / lightrag) and injects them into the generated docker-compose.final.yml, so you can choose any user, password, and database name.

Prefer the official pgvector image when you don't need AGE: Apache AGE is required only by PGGraphStorage. The recommended PostgreSQL graph storage is PGTableGraphStorage, which keeps the entity-relation graph in ordinary indexed tables and needs no extension at all — so if graph storage is PGTableGraphStorage (or lives on another backend such as Neo4j entirely), replace the image above with the latest official pgvector image pgvector/pgvector:pg18. Only PGGraphStorage still requires the AGE-bundled image. Please note that data file formats are incompatible across different PostgreSQL major versions; once this Docker image is deployed, it cannot be rolled back to a previous version.

Build the PostgreSQL image

The default PostgreSQL image can be rebuilt from the repository root with Dockerfile.postgres. The Dockerfile starts from pgvector/pgvector:pg18-trixie, builds Apache AGE for PostgreSQL 18, and installs an init script that creates both the vector and age extensions for new databases.

For local development or single-host deployment:

docker build -f Dockerfile.postgres \
  -t gzdaniel/postgres-for-rag:pg18-age-pgvector \
  .

To publish the image to your own registry, use a private tag:

docker build -f Dockerfile.postgres \
  -t registry.example.com/postgres-for-rag:pg18-age-pgvector \
  .
docker push registry.example.com/postgres-for-rag:pg18-age-pgvector

For a multi-architecture image:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f Dockerfile.postgres \
  -t registry.example.com/postgres-for-rag:pg18-age-pgvector \
  --push \
  .

After building a custom tag, update the postgres.image value in the generated docker-compose.final.yml to point at that tag. On later setup wizard reruns, existing wizard-managed service images are preserved.

Updates Copy Section

To update the Docker container:

docker compose pull
docker compose down
docker compose up

Offline deployment Copy Section

Software packages requiring transformers, torch, or cuda are not preinstalled in the docker images. Consequently, document extraction tools such as Docling, as well as local LLM models like Hugging Face and LMDeploy, cannot be used in an offline environment. These high-compute-resource-demanding services should not be integrated into LightRAG. Docling will be decoupled and deployed as a standalone service.

The main image bundles everything the native docx parser's opt-in smart_heading engine parameter needs: the spaCy runtime plus the pinned zh_core_web_sm / en_core_web_sm 3.8.0 models are baked in at build time, so smart_heading works fully offline out of the box. The lite image ships the spaCy runtime (it comes with the api extra) but not the models — enabling smart_heading there requires installing them first (lightrag-download-cache --spacy-install, or see OfflineDeployment.md for air-gapped hosts).

📦 Build Docker Images Copy Chapter

For local development and testing Copy Section

# Build and run with Docker Compose (BuildKit automatically enabled)
docker compose up --build

# Or explicitly enable BuildKit if needed
DOCKER_BUILDKIT=1 docker compose up --build

Note: BuildKit is automatically enabled by the # syntax=docker/dockerfile:1 directive in the Dockerfile, ensuring optimal caching performance.

For production release Copy Section

multi-architecture build and push:

# Use the provided build script
./docker-build-push.sh

The build script will:

• Check Docker registry login status
• Create/use buildx builder automatically
• Build for both AMD64 and ARM64 architectures
• Push to GitHub Container Registry (ghcr.io)
• Verify the multi-architecture manifest

Prerequisites:

Before building multi-architecture images, ensure you have:

• Docker 20.10+ with Buildx support
• Sufficient disk space (20GB+ recommended for offline image)
• Registry access credentials (if pushing images)

Verify official GHCR images with Cosign Copy Section

Official LightRAG images published to GitHub Container Registry by GitHub Actions are signed with Sigstore Cosign using GitHub OIDC keyless signing.

Install cosign, then verify the image tag you want to run:

cosign verify ghcr.io/HKUDS/LightRAG:<tag> \
  --certificate-identity-regexp '^https://github.com/HKUDS/LightRAG/.github/workflows/(docker-publish|docker-build-manual|docker-build-lite)\.yml@refs/.+$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Replace <tag> with the version tag you want to validate, for example a release tag, latest, <tag>-lite, or lite.

File: README-zh.md Copy Chapter

🚀 LightRAG: 简单且快速的检索增强生成（RAG）框架

🎉 新闻 Copy Chapter

• [2026.07]🎯[新功能]: 添加 Word 文档 智能章节标题 识别功能。

• [2026.05]🎯[新功能]：将 RagAnything 合并至 LightRAG🎉。支持通过 MinerU / Docling 服务进行多模态内容解析与提取。

• [2026.05]🎯[新功能]：引入四种可选的文本分块策略：Fix（固定）、Recursive（递归）、Vector（向量）和 Paragraph（段落语义）。

• [2026.05]🎯[新功能]：支持按角色配置 LLM，提供四个独立角色：EXTRACT、QUERY、KEYWORDS 和 VLM，每个角色拥有独立的 LLM 设置。

• [2026.03]🎯[新功能]: 集成了 OpenSearch 作为统一存储后端，为 LightRAG 的全部四种存储类型提供全面支持。

• [2026.03]🎯[新功能]: 推出交互式安装向导，支持通过 Docker 在本地部署 Embedding、Reranking 及存储后端服务。

• [2025.11]🎯[新功能]: 集成了 RAGAS 评估和 Langfuse 追踪。更新了 API 以在查询结果中返回召回上下文，支持上下文精度指标。

• [2025.10]🎯[可扩展性增强]: 消除了处理瓶颈，以高效支持大规模数据集。

• [2025.09]🎯[新功能]: 显著提升了 Qwen3-30B-A3B 等开源 LLM 的知识图谱提取准确性。

• [2025.08]🎯[新功能]: 现已支持 Reranker，显著提升混合查询性能（已设为默认查询模式）。

• [2025.08]🎯[新功能]: 添加了文档删除功能，并支持自动重新生成知识图谱，以确保最佳查询性能。

• [2025.06]🎯[新发布]: 我们的团队发布了 RAG-Anything —— 一个用于无缝处理文本、图像、表格和方程式的全功能多模态 RAG 系统。

• [2025.06]🎯[新功能]: LightRAG 现已集成 RAG-Anything，支持全面的多模态数据处理，实现对 PDF、图像、Office 文档、表格和公式等多种格式的无缝文档解析和 RAG 能力。详见多模态文档处理部分。

• [2025.03]🎯[新功能]: LightRAG 现已支持引用功能，实现了准确的源归因和增强的文档可追溯性。

• [2025.02]🎯[新功能]: 现在您可以使用 MongoDB 作为一体化存储解决方案，实现统一的数据管理。

• [2025.02]🎯[新发布]: 我们的团队发布了 VideoRAG —— 一个用于理解超长上下文视频的 RAG 系统。

• [2025.01]🎯[新发布]: 我们的团队发布了 MiniRAG，使用小型模型简化 RAG。

• [2025.01]🎯现在您可以使用 PostgreSQL 作为一体化存储解决方案进行数据管理。

• [2024.11]🎯[新资源]: LightRAG 的综合指南现已在 LearnOpenCV 上发布 —— 探索深入的教程和最佳实践。非常感谢博客作者的杰出贡献！

• [2024.11]🎯[新功能]: 推出 LightRAG WebUI —— 一个允许您通过直观的 Web 界面插入、查询和可视化 LightRAG 知识的仪表板。

• [2024.11]🎯[新功能]: 现在您可以使用 Neo4J 进行存储 —— 开启图数据库支持。

• [2024.10]🎯[新功能]: 我们添加了 LightRAG 介绍视频 的链接 —— 演示 LightRAG 的各项功能。感谢作者的杰出贡献！

• [2024.10]🎯[新频道]: 我们创建了一个 Discord 频道！💬 欢迎加入我们的社区进行分享、讨论和协作！ 🎉🎉

  算法流程图

图1：LightRAG索引流程图 - 图片来源：Source

图2：LightRAG检索和查询流程图 - 图片来源：Source

安装 Copy Chapter

💡 使用 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，但为了获得更好的性能 and 更可靠的依赖管理，建议使用 uv。

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

安装LightRAG服务器 Copy Section

• 从PyPI安装

### 使用 uv 安装 LightRAG 服务器（作为工具，推荐)
uv tool install "lightrag-hku[api]"

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

# 配置 env 文件
# 从 GitHub 仓库的根目录上下载 env.example 文件
# 或从本地检出的源代码中获取 env.example 文件
cp env.example .env  # 使用你的LLM和Embedding模型访问参数更新.env文件
# 启动 API-WebUI 服务。默认绑定所有网络接口(0.0.0.0)。
# 安全提示:对外网暴露前,请在 .env 中配置认证(LIGHTRAG_API_KEY,或
# AUTH_ACCOUNTS 搭配 TOKEN_SECRET);若仅需本机访问,可绑定 127.0.0.1;
# 否则所有接口都将公开可访问。
# 注意:为兼容 Ollama 客户端,/api/* 路由默认不鉴权;如需对其启用认证,
# 请将 WHITELIST_PATHS 收窄为 /health。
lightrag-server

• 从源代码安装

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

# 一键初始化开发环境（推荐）
make dev
source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
# Windows 系统: .venv\Scripts\activate

# make dev 会安装测试工具链以及完整的离线依赖栈
# （API、存储后端与各类 Provider 集成），并构建前端；不会生成 .env。
# 启动服务前请先运行 make env-base，或手动从 env.example 复制并配置 .env。

# 使用 uv 的等价手动步骤
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
uv sync --extra test --extra offline
source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
# Windows 系统: .venv\Scripts\activate

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

# 构建前端代码
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..

# 配置 env 文件
make env-base  # 或: cp env.example .env 后手动修改
# 启动API-WebUI服务
lightrag-server

• 使用 Docker Compose 启动 LightRAG 服务器

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env  # 使用你的LLM和Embedding模型访问参数更新.env文件
# 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 文件 Copy Section

除了手动编辑 env.example 之外，您还可以使用交互式向导生成配置好的 .env，并在需要时生成 docker-compose.final.yml：

make env-base           # 必跑第一步：配置 LLM、Embedding、Reranker
make env-storage        # 可选：配置存储后端和数据库服务
make env-server         # 可选：配置服务端口、鉴权和 SSL
make env-base-rewrite   # 可选：强制重建向导托管的 compose 服务块
make env-storage-rewrite # 可选：强制重建向导托管的 compose 服务块
make env-security-check # 可选：审计当前 .env 中的安全风险

设置向导工具的详细说明请参阅 docs/InteractiveSetup.md。

可选：docx smart_heading 的 spaCy 模型 Copy Section

Native docx 解析器的可选引擎参数 smart_heading 使用 spaCy 做分句/NER 启发式判断。spaCy 运行时已包含在 api extra 中——只有两个钉定版本的语言模型（zh_core_web_sm / en_core_web_sm 3.8.0，GitHub release wheel，未发布到 PyPI）需要额外一步安装：

lightrag-download-cache --spacy-install

可以按文件/规则启用 smart_heading（如 LIGHTRAG_PARSER=docx:native(smart_heading=true)），也可以在 .env 中全局启用：

# 路由到 native 引擎的 .docx 文件默认启用 smart_heading；
# 单个文件/规则可用显式 native(smart_heading=false) 关闭。
DOCX_SMART_HEADING=true

全局开关开启（或 LIGHTRAG_PARSER 规则携带 native(smart_heading=true)）时，服务器会在启动阶段校验模型并在缺失时立即报错（附安装指引）。从不启用 smart_heading 的部署无需安装模型。Docker 主镜像已内置模型（lite 镜像不含）；离线环境请参阅离线部署指南。

可选：SVG 栅格化所需的 libcairo（native md/textpack） Copy Section

Native markdown/textpack 解析器会通过 cairosvg 把内嵌的 SVG 图片栅格化为 PNG。cairosvg 是对 cairo 的 cffi 绑定：pip install cairosvg（随 api extra 一起安装）总能成功，但只有宿主机同时装了原生的 libcairo 共享库，栅格化才真正能跑——pip/uv 装不了系统库。缺失时栅格化会在运行时失败，对应的 SVG 会被跳过（不影响文档其余内容）；服务器会在启动时探测这一能力，缺失时以醒目的黄色警告提示，避免这个缺口一直藏到某篇文档处理时才被发现。

按平台安装对应的系统包：

# Debian / Ubuntu（官方 Docker 镜像已内置）
sudo apt-get install -y libcairo2

# RHEL / Fedora
sudo dnf install -y cairo

# macOS（Homebrew）
brew install cairo

# Windows：安装内含 libcairo-2.dll 的 GTK3 运行时

从不处理带内嵌 SVG 的 markdown/textpack 文档的部署，可以忽略这条启动警告。

关于LightRAG Copy Chapter

基于图的轻量级RAG框架 Copy Section

LightRAG 是一个轻量级的知识图谱 RAG 框架，被视为 Microsoft GraphRAG 的高效替代方案。它采用双层架构来同时管理知识图谱（KG）和向量嵌入，完美填补了传统基于向量的 RAG 与基于图谱的 RAG 之间的技术鸿沟。LightRAG专为高扩展性而设计，有效地解决了大规模图谱索引和查询时计算开销大、响应缓慢以及增量更新成本高等问题；LightRAG在支持大规模数据集的同时，即使搭载 30B开源大语言模型（LLM），也能保持极高的RAG质量。

特点与优势 Copy Section

1. 深度上下文理解：通过图结构索引，LightRAG 能够捕捉实体间复杂的语义依赖关系，克服了传统分块检索方法上下文割裂的缺陷。在需要全局理解或逻辑推理的垂直领域（如法律、金融），其生成质量与上下文感知能力尤为突出。
2. 卓越的全面性与多样性：LightRAG的双层检索机制使其能够同时整合详细事实与抽象概念，让其在查询结果全面性（Comprehensiveness）和多样性（Diversity）取得卓越的成绩，有效应对复杂的跨文档查询。
3. 极高的检索效率与低成本：LightRAG不需要依赖低效的社区报告和复杂查询时的多跳推理，大幅度减少了索引和查询阶段对LLM的调用，显著减少了响应延迟与LLM计算成本。
4. 支持增量更新与局部删除：LightRAG 解决了基于图的知识库难以增量更新和局部删除的问题，保证系统在动态数据环境下的时效性。删除文档时，系统可以利用构建阶段的 LLM 缓存快速重建受影响的实体与关系，大幅提升知识库的更新效率。
5. 支持多种文档解析引擎：LightRAG 的文件处理管线支持 MinerU、Docling 和 Native 等文档解析引擎，也支持第三方扩展解析引擎。LightRAG 专属的 Native 引擎可高效解析 Word 和 Markdown 文档中的图片、表格和公式，尤其适合处理多模态内容丰富的文档。Native 引擎还支持自动识别和纠正 Word 文档的章节标题，即使文档大纲不规范，也能改善内容提取效果，为后续按章节进行文本分块打下基础。
6. 支持多种文本分块策略：LightRAG 支持 4 种文本分块策略，分别是 固定长度分块(F)、递归字符分块(R)、向量语义分块(V) 和 段落语义分块(P)。其中，段落语义分块(P) 是 LightRAG 专属的分块策略，可以让分块边界尽可能对齐文档原生的语义边界（标题、段落和表格），从而减少标题与内容错配、长表格切分后丢失标题行等问题。
7. 支持多种存储后端：LightRAG 默认的 KV、向量和图存储均采用基于本地文件持久化的内存数据库，仅适合小数据量的测试与效果评估，不适用于生产环境。LightRAG 还支持多种主流后端存储（推荐 PostgreSQL），可用于大规模数据集的生产部署。

多模态能力的升级 Copy Section

传统 RAG 系统缺乏有效处理文档中图片、公式和表格等多模态内容的能力。从 v1.5 版本开始，LightRAG 将多模态处理能力无缝集成到文件处理管线和查询流程中。LightRAG 通过知识图谱将这些多模态内容与正文有机联系起来，在回答用户查询时能够结合多模态信息，给出更准确、更可靠的答案。这一能力可大幅提升操作说明书、学术论文等多模态内容丰富文档的 RAG 质量。

LightRAG API 服务器 Copy Section

LightRAG 服务器不仅提供给了一个供出选择体验LightRAG功能的Web UI，还提供了一个完整的 REST API。有关LightRAG服务器的更多信息，请参阅LightRAG服务器。

关键配置说明 Copy Chapter

LLM 模型的选择 Copy Section

LightRAG 的工作过程中需要使用到 4 种角色的 LLM/VLM。应该为不同角色的 LLM 配置不同能力和速度的模型，以获得速度和能力之间的平衡。LightRAG 对大型语言模型（LLM）的能力要求会高于传统 RAG，因为它需要 LLM 执行文档中的实体关系抽取任务。在查询阶段，LLM 模型需要处理 LightRAG 召回的实体、关系和文本块等大量信息，需要模型具备在含有噪声的长上下文中作出高质量回答的能力。

按角色推荐的模型：

• 抽取 LLM（EXTRACT）：实体关系抽取会对每个文本块调用，选择主流的高速模型即可，并强烈推荐使用非思考模型（关闭 reasoning/thinking 模式），以免抽取变慢、变贵。国外可选 GPT-5.6-luna、Claude Haiku、Gemini-mini；国内可选 DeepSeek-V4-lite、Kimi。本地部署最低可考虑 Qwen3-30B-A3B-Instruct。
• 查询 LLM（QUERY）：负责在长且嘈杂的召回内容上生成最终答案，应选择比抽取模型更强的模型，尽量提高回答质量；此处使用带思考能力的模型没有问题。
• 关键词 LLM（KEYWORD）：轻量、对延迟敏感的环节，一定要选择非思考模型以降低查询延迟；选用与抽取模型相当的高速模型即可。
• VLM（VLM）：主流的多模态模型均可，需支持图片输入。本地部署可考虑 Qwen3.6-35B-A3B。

在可接受的时间和价格范围内，优先选择评分（各类公开榜单/基准）越高的模型越好。详细的模型配置请参见 RoleSpecificLLMConfiguration-zh.md

查询模式的选择 Copy Section

LightRAG 支持 4 种查询模式：

• local：聚焦于局部上下文与具体实体的精准匹配。在知识图谱中检索对应的候选实体及其直接关联属性，适用于针对特定对象、具体概念或细节事实的问答，能够提供高度相关且细致的局部上下文支持。
• global：侧重于宏观主题、跨文档推理与实体间的深层关系。检索覆盖广泛主题与概念的关系链，适用于需要跨多个上下文进行总结、趋势分析或理解复杂语义依赖关系的查询。
• hybrid：融合 local 和 global 两种模式的检索结果。通过同时召回具体实体与全局关系上下文，进行综合推理与生成。
• naive：基于文本块的传统 RAG 检索，不使用知识图谱，直接依赖向量相似性在原始文本块中进行检索。
• mix：全功能模式，融合 local、global 和 naive 三种模式的检索结果，提供最为丰富和全面的检索结果。

LightRAG 的默认查询模式为 mix。使用 mix 模式通常可以获得最为理想的查询结果。mix 模式比 naive 耗时略长；其他查询模式在耗时上基本相当。

Embedding 模型 Copy Section

在选择 Embedding 模型的时候需要注意其对多语言的支持能力。LightRAG 的检索质量对 Embedding 模型的依赖有限，因此建议尽量选择低维度和速度快的模型。选择主流最新的 Embedding 模型即可；本地部署首选 BAAI/bge-m3。建议尽量本地部署 Embedding 模型，以获得最好的性能。

重要提示：在文档索引前必须确定使用的 Embedding 模型，且在文档查询阶段必须沿用与索引阶段相同的模型。嵌入模型一旦选定通常就不能修改。如果修改的话，需要对所有文本块、实体和关系进行重新嵌入。LightRAG 目前没有提供重新嵌入的工具。有些存储（例如 PostgreSQL）在首次建立数据表的时候需要确定向量维度，因此更换 Embedding 模型后需要删除向量相关库表，以便让 LightRAG 重建新的库表。

开启 Rerank 选项 Copy Section

查询阶段开启 Rerank 选项可以显著提高查询的质量。开启 Rerank 通常会引入 1～2 秒的延时。为了降低延时，建议尽量在本地部署 Rerank 模型。主流最新的 Reranker 皆可，本地部署推荐 BAAI/bge-reranker-v2-m3。Rerank 的相关配置方式请参考 .env.example 文件。Rerank 模型与 Embedding 模型不同，可以在查询阶段随时更换。

文档处理流水线的配置 Copy Section

LightRAG 的默认流水线配置并不能让系统发挥最好的性能。文件内容解析的好坏会极大地影响文档的索引和查询效果。因此建议配置流水线开启 MinerU 文件解析引擎，并开启流水线的图片分析功能。建议添加的配置为：

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

VLM_PROCESS_ENABLE=true
VLM_LLM_MODEL=<your_vlm_model_name>

由于云端的 MinerU 服务有使用量、文件大小和页数等限制，建议使用本地部署的 MinerU。文件处理流水线的具体配置方法请参考 FileProcessingPipeline-zh.md

文件处理并发优化 Copy Section

对于大规模的文档处理，需要提高文档处理的并发能力。几个涉及文件并发处理性能的关键环境变量包括：

• MAX_ASYNC_LLM：设置 LLM 角色的基础并发数（MAX_ASYNC 仍作为兼容旧名保留）。文件处理时，它还限制单个文档内各文本块的实体/关系抽取 task 数；每个实体合并或关系合并阶段最多可运行其两倍数量的 task。
• EXTRACT_MAX_ASYNC_LLM：可选地覆盖 Extract 角色的实际 LLM 请求并发数，适用于抽取和合并时的摘要请求。未设置时继承 MAX_ASYNC_LLM；它不会改变前述流水线 task 上限。
• MAX_PARALLEL_INSERT：控制可并行处理的文件数量，而非单个文档内的 chunk 或图合并 task 上限。建议约为 MAX_ASYNC_LLM 的 1/3。
• MAX_PARALLEL_PARSE_MINERU：控制 MinerU 文件解析的并发处理文件数。
• MAX_PARALLEL_PARSE_DOCLING：控制 Docling 文件解析的并发处理文件数。
• EMBEDDING_FUNC_MAX_ASYNC：控制嵌入模型的最大并发数。
• EMBEDDING_BATCH_NUM：控制每个嵌入模型请求包含的待嵌入文本的数量（每批做多少个嵌入）；提高这个数量可以大幅度减少调用嵌入模型的次数，提高嵌入存储的落盘速度。

# 设置示例
MAX_ASYNC_LLM=8
MAX_PARALLEL_INSERT=3
EMBEDDING_FUNC_MAX_ASYNC=16
EMBEDDING_BATCH_NUM=32

后台存储的选择 Copy Section

LightRAG 需要使用到 4 种后台存储类型，分别是：

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

4 种默认存储全部都是内存数据库（JsonKVStorage、NanoVectorDBStorage、NetworkXStorage、JsonDocStatusStorage）：全部数据常驻服务进程的内存中，WORKING_DIR 下的本地文件仅用于持久化，因此容量受可用内存限制。默认存储仅适合小数据量的测试、效果评估与开发调试，不能用于生产环境部署。

生产环境推荐使用 PostgreSQL —— 它可以独自承担全部 4 种类型的后台存储；MongoDB 与 OpenSearch 是另外两个单一后端方案。也可以单独为向量存储或图存储选择专业化的数据库，例如使用 Milvus 或 Qdrant 作为向量存储，使用 Neo4j 或 Memgraph 作为图存储。

各存储类型的完整可选实现列表，请参考 支持的存储类型。

文档处理阶段其他重要配置 Copy Section

在文档插入阶段还有以下环境变量建议根据实际需要进行调整：

• 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：控制每个实体/关系能够最多与多少个文本块保持关联
• SOURCE_IDS_LIMIT_METHOD：控制实体/关系关联文本块超过限制后是否继续更新实体关系的描述（默认不再更新，因为此时实体关系的描述已经足够丰富，继续更新的意义不大；放弃更新可以极大地提高知识库的构建速度）
• DEFAULT_MAX_FILE_PATHS：控制实体/关系关联的原始文件的最大数量，超过这个数量之后新的文件名不再写入到向量存储。

解决实体关系抽取阶段的 LLM 超时 Copy Section

实体关系抽取阶段的 LLM 超时通常源于以下三种原因之一。先判断原因，再采用对应的解决方案（参数可以组合使用）：

• 模型太慢。 速度低于约 50 tokens/秒的模型，可能无法在请求超时前完成包含大量实体关系的文本块的抽取。可以通过 *_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 × 每秒token数（例如 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。

文档查询阶段其他重要配置 Copy Section

在文档查询阶段还有以下环境变量建议根据实际需要进行调整：

• MAX_ENTITY_TOKENS / MAX_RELATION_TOKENS / MAX_TOTAL_TOKENS：控制召回内容送给LLM上下文的Token长度。召回内容包含实体、关系和文本块三部分，实体和关系的长度可以单独控制长度，文本块的长度由总长度减去实体和关系的长度来控制。
• ENABLE_CONTENT_HEADINGS：控制是否把文本块所在的章节标题送给LLM；默认开启，可以为LLM提供更加丰富的上下文信息，提高回答质量。
• ENABLE_LLM_CACHE：是否允许缓存查询结果。默认开启，相同的查询问题、查询模式、LLM模型参数将返回相同的结果。
• USER_PROMPT_PREFIX / USER_PROMPT_PREFIX_FILE：拼接在每个请求的 user_prompt 前面的全局指令（对应回答提示词中的"Additional Instructions"部分），为运维方提供一个统一定制LLM输出的入口。拼接是逐字节的、不会自动插入分隔符，请自行在内容结尾加上 \n\n。如果请求的 user_prompt 为空，该前缀将单独成为送给 LLM 的指令；只有 API 字段 disable_user_prompt_prefix 能禁用它，且请求无法读取或替换它。较长或多段落的内容请使用 USER_PROMPT_PREFIX_FILE（PROMPT_DIR/user_prompt 目录下的 .md/.txt 文件名），因为 .env 中的值必须写在一行内。

WebUI 入口与默认入口 Copy Section

服务器基于同一次前端构建挂载两个 WebUI 入口。/webui 是后台管理界面：文档管理、知识图谱浏览，以及带完整查询参数面板的查询调试。/workspace 是面向日常查询用户的纯问答入口：只有聊天界面（无文档管理、无知识图谱、无查询参数侧栏、无 API 文档入口），针对移动端优化，未登录的访客会先看到欢迎页。

• LIGHTRAG_DEFAULT_UI：根路径 / 重定向到哪个入口——webui（默认）或 workspace。它只控制这一个行为：该重定向。无论取值如何，两个入口都保持挂载、各自的 URL 始终可访问；取其它值会导致启动失败。当部署的主要使用者是查询用户而非管理员时，可将其设为 workspace。
• UI_TEMPLATES_DIR：指向一个可选的多语言定制包，用你自己的内容替换欢迎页、登录页文案、查询空白页、品牌 Logo 和版权行，无需重新构建 WebUI。参见 UserDefinedUI-zh.md。
• ENABLE_AI_CONTENT_NOTICE：在两个查询界面（/workspace 与 /webui 的检索面板）中为每条由 LLM 生成的回答标注"由AI生成"；不是模型写的文本——无检索结果时的固定回复、管理面板的调试输出——不会被标注。默认关闭；它只是界面元素，不会进入 API 响应，也不会写入聊天历史。

把最终用户引导到 /workspace 之前有两点需要了解。其一，那里的查询参数只继承、不可编辑：每次查询使用同一浏览器中 /webui 保存的设置（未保存时使用前端默认值），这是按浏览器的本地状态，不是服务端全局策略。其二，隐藏后台界面是使用体验上的划分，不是安全边界——服务端仍会对每个接口执行鉴权。查询入口的完整行为参见 LightRAG-API-Server-zh.md。

使用LightRAG SDK Copy Chapter

⚠️ 如果您希望将LightRAG集成到您的项目中，建议您使用LightRAG Server提供的REST API。LightRAG SDK通常用于嵌入式应用，或供希望进行研究与评估的学者使用。

安装LightRAG SDK Copy Section

• 从源代码安装

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示例代码 Copy Section

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：在运行 demo 程序的时候需要注意，不同的测试程序可能使用的是不同的 embedding 模型。一个模型写入的向量对另一个模型不可用，所以更换 embedding 模型后必须重建向量。对 demo 数据而言，最简单的做法是直接删除 demo 目录（./dickens）后重跑——语料很小且可丢弃；想保留 LLM 缓存可以保留 kv_store_llm_response_cache.json 文件。但生产部署请不要删除工作目录：它保存着知识图谱和文本块，删掉会把重新嵌入变成全量重新摄取。正确做法是运行 lightrag-rebuild-vdb，参见 Switching embedding models。

注意2：官方支持的示例代码仅为 lightrag_openai_demo.py 和 lightrag_openai_compatible_demo.py 两个文件。其他示例文件均为社区贡献内容，尚未经过完整测试与优化。

使用SDK的注意事项 Copy Section

SDK的使用说明详见 docs/ProgramingWithCore.md（英文）。有部份LightRAG功能没有提供 REST API，仅能够通过SDK使用。这部份功能往往是不稳定，不能保证在将来的版本上可以兼容。

重现论文结果 Copy Chapter

LightRAG 在农业、计算机科学、法律和混合等领域均显著优于 NaiveRAG、RQ-RAG、HyDE 和 GraphRAG。完整评估方法论、提示词和复现步骤详见 docs/Reproduce.md（英文）。

总体性能表 Copy Section

📚 文档与工具清单 Copy Chapter

参考文档（`docs/`） Copy Section

下表优先给出中文版链接；同目录下的同名 *.md 为对应的英文原版。

部署与安装

服务器与 API

文档处理

模型与存储

SDK 与开发

运维工具（`lightrag/tools/`） Copy Section

涉及存储的工具与服务器一样读取 .env 和环境变量，请在项目根目录下、使用同一套配置运行。其中若干工具会原地改写存储——是否必须先停掉服务器（以及其它写入方）请查看对应指南，rebuild_vdb 必须先停。

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

丢弃并从权威数据源（图节点/边、text_chunks KV 存储）重建全部向量存储。用于向量写入失败后的恢复，以及更换 embedding 模型或维度之后的重建；另提供只读的一致性检查模式。

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 存储后端之间迁移 default 模式缓存（抽取、摘要、多模态分析），并保持 workspace 隔离。

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

列出争用同一个规范 source key 的文档，并把运维人员未选中的候选降级为重复项。工具本身从不自行裁定胜者，也从不删除内容。

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

预先下载离线部署及 docx smart_heading 引擎参数所需的 tiktoken 编码与钉版 spaCy 模型。

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

生成可直接粘贴进 AUTH_ACCOUNTS 的 bcrypt 口令值。

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

SDK 诊断工具：校验 LightRAG 实例是否已完整初始化，用于排查最常见的「忘记 await rag.initialize_storages()」问题。

🔗 相关项目 Copy Chapter

生态与扩展

**RAG-Anything**
      <sub>多模态 RAG</sub>
    </a>
  
  
    <a href="https://github.com/HKUDS/VideoRAG">
      
        🎥
      
      **VideoRAG**
      <sub>极端长上下文视频 RAG</sub>
    </a>
  
  
    <a href="https://github.com/HKUDS/MiniRAG">
      
        ✨
      
      **MiniRAG**
      <sub>极简 RAG</sub>
    </a>

🤝 贡献 Copy Chapter

📖 引用 Copy Chapter

@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}
}

<a href="https://github.com/HKUDS/LightRAG" style="text-decoration: none;">
  
</a>
<a href="https://github.com/HKUDS/LightRAG/issues" style="text-decoration: none;">
  
</a>
<a href="https://github.com/HKUDS/LightRAG/discussions" style="text-decoration: none;">
  
</a>