GEO
AI大模型

LightRAG是什么？2026年开源RAG框架部署与使用指南

2026/3/23
LightRAG是什么？2026年开源RAG框架部署与使用指南
AI Summary (BLUF)

LightRAG is an open-source RAG framework that simplifies document indexing, knowledge graph exploration, and querying through a web interface and API. It supports multiple LLM and embedding backends, offers Ollama compatibility, and provides flexible deployment options including Docker and Linux services.

原文翻译： LightRAG 是一个开源 RAG 框架，通过 Web 界面和 API 简化文档索引、知识图谱探索和查询。它支持多种 LLM 和嵌入后端，提供 Ollama 兼容性，并支持 Docker 和 Linux 服务等多种灵活的部署选项。

LightRAG: Implementing RAG Has Never Been Easier

LightRAG 服务器与 Web 界面

LightRAG Server and Web Interface

LightRAG 服务器旨在提供 Web 界面和 API 支持。其 Web 界面便于文档索引、知识图谱探索和简单的 RAG 查询。此外，LightRAG 服务器还提供了一个与 Ollama 兼容的接口，旨在将 LightRAG 模拟为 Ollama 聊天模型。这使得 AI 聊天机器人（如 Open WebUI）能够轻松访问 LightRAG。

The LightRAG server is designed to provide Web interface and API support. Its Web interface facilitates document indexing, knowledge graph exploration, and a simple RAG query interface. Furthermore, the LightRAG server offers an Ollama-compatible interface, aiming to simulate LightRAG as an Ollama chat model. This enables AI chatbots (such as Open WebUI) to easily access LightRAG.

Image 1: LightRAG Web Interface

Image 2: Knowledge Graph Exploration

Image 3: RAG Query Interface

入门指南

Getting Started

安装

Installation

  • 从 PyPI 安装 (Install from PyPI)

    pip install "lightrag-hku[api]"

  • 从源代码安装 (Install from Source)

    # 克隆仓库 (Clone the repository)
git clone https://github.com/HKUDS/lightrag.git

# 切换到仓库目录 (Switch to the repository directory)
cd lightrag

# 如有必要，创建 Python 虚拟环境 (Create a Python virtual environment if necessary)
# 以可编辑模式安装并支持 API (Install in editable mode with API support)
pip install -e ".[api]"

启动前的准备：配置 LLM 与嵌入模型

Pre-Launch Preparation: Configuring LLM and Embedding Models

LightRAG 需要集成 LLM（大型语言模型）和嵌入模型以有效执行文档索引和查询。在首次部署服务器前，必须配置这些模型。LightRAG 支持多种后端：

LightRAG requires integration with both an LLM (Large Language Model) and an embedding model to effectively perform document indexing and queries. These models must be configured before the first deployment. LightRAG supports various backends:

  • ollama
  • lollms
  • openai 或 openai 兼容 (openai or openai-compatible)
  • azure_openai

建议使用环境变量进行配置。项目根目录提供了一个 env.example 示例文件。将其复制到启动目录并重命名为 .env，然后修改其中的参数。请注意：LightRAG 服务器启动时会加载 .env 文件中的变量，但会优先使用系统环境变量中已存在的设置。

It is recommended to use environment variables for configuration. An example file env.example is provided in the project root directory. Copy it to the launch directory, rename it to .env, and modify the parameters within. Important: The LightRAG server loads variables from the .env file upon startup but gives priority to settings already present in the system environment variables.

由于安装了 Python 扩展的 VS Code 可能会在集成终端中自动加载 .env 文件，请在每次修改 .env 文件后打开新的终端会话。

Since VS Code with the Python extension may automatically load .env files in the integrated terminal, please open a new terminal session after each modification to the .env file.

以下是两种常见的配置示例：

Here are two common configuration examples:

  • OpenAI LLM + Ollama 嵌入 (OpenAI LLM + Ollama Embedding)

    LLM_BINDING=openai
LLM_MODEL=gpt-4o
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=your_api_key
### 发送给 LLM 的最大 token 数（小于模型上下文大小）(Max tokens sent to LLM (less than model context size))
MAX_TOKENS=32768

EMBEDDING_BINDING=ollama
EMBEDDING_BINDING_HOST=http://localhost:11434
EMBEDDING_MODEL=bge-m3:latest
EMBEDDING_DIM=1024
# EMBEDDING_BINDING_API_KEY=your_api_key

  • Ollama LLM + Ollama 嵌入 (Ollama LLM + Ollama Embedding)

    LLM_BINDING=ollama
LLM_MODEL=mistral-nemo:latest
LLM_BINDING_HOST=http://localhost:11434
# LLM_BINDING_API_KEY=your_api_key
### 发送给 LLM 的最大 token 数（基于您的 Ollama 服务器容量）(Max tokens sent to LLM (based on your Ollama server capacity))
MAX_TOKENS=8192

EMBEDDING_BINDING=ollama
EMBEDDING_BINDING_HOST=http://localhost:11434
EMBEDDING_MODEL=bge-m3:latest
EMBEDDING_DIM=1024
# EMBEDDING_BINDING_API_KEY=your_api_key

启动 LightRAG 服务器

Starting the LightRAG Server

LightRAG 服务器支持两种运行模式：

The LightRAG server supports two operation modes:

  • 简单高效的 Uvicorn 模式 (Simple and Efficient Uvicorn Mode)

    lightrag-server

  • 多进程 Gunicorn + Uvicorn 模式（生产模式，不支持 Windows） (Multi-process Gunicorn + Uvicorn Mode (Production mode, not supported on Windows))

    lightrag-gunicorn --workers 4

.env 文件必须放在启动目录中。服务器启动时会创建文档目录（默认 ./inputs）和数据目录（默认 ./rag_storage）。这允许您从不同目录启动多个实例，每个实例监听不同的端口。

The .env file must be placed in the startup directory. Upon startup, the server creates a document directory (default ./inputs) and a data directory (default ./rag_storage). This allows you to launch multiple instances from different directories, each configured to listen on a different network port.

常用启动参数：

Common startup parameters:

  • --host: 服务器监听地址（默认：0.0.0.0）(Server listening address (default: 0.0.0.0))
  • --port: 服务器监听端口（默认：9621）(Server listening port (default: 9621))
  • --timeout: LLM 请求超时时间（默认：150 秒）(LLM request timeout (default: 150 seconds))
  • --log-level: 日志级别（默认：INFO）(Log level (default: INFO))
  • --input-dir: 指定要扫描文档的目录（默认：./input）(Specify the directory to scan for documents (default: ./input))
  • 要求将.env文件置于启动目录中是经过特意设计的。 这样做的目的是支持用户同时启动多个LightRAG实例，并为不同实例配置不同的.env文件。
  • 修改.env文件后，您需要重新打开终端以使新设置生效。 这是因为每次启动时，LightRAG Server会将.env文件中的环境变量加载至系统环境变量，且系统环境变量的设置具有更高优先级。
  • The requirement to place the .env file in the startup directory is by design. This is intended to support users launching multiple LightRAG instances simultaneously, each with a different .env file.
  • After modifying the .env file, you need to reopen the terminal for the new settings to take effect. This is because each time it starts, the LightRAG Server loads environment variables from the .env file into the system environment variables, and system environment variable settings have higher priority.

使用 Docker 启动

Starting with Docker

  • 克隆代码仓库 (Clone the repository):

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

  • 配置 .env 文件 (Configure the .env file):
    通过复制示例文件 env.example 创建个性化的 .env 文件，并根据实际需求设置 LLM 及 Embedding 参数。

Create a personalized .env file by copying the example file env.example, and configure the LLM and Embedding parameters according to your actual needs.

  • 启动服务器 (Start the server):
    docker compose up
# 如拉取了新版本，请添加 --build 重新构建 (If a new version is pulled, add --build to rebuild)
docker compose up --build

无需克隆代码的 Docker 部署

Docker Deployment Without Cloning Code

  • 创建工作文件夹 (Create a working folder):

    mkdir lightrag
cd lightrag

  • 准备 docker-compose.yml 文件 (Prepare the docker-compose.yml file):

    services:
  lightrag:
    container_name: lightrag
    image: ghcr.io/hkuds/lightrag:latest
    ports:
      - "${PORT:-9621}:9621"
    volumes:
      - ./data/rag_storage:/app/data/rag_storage
      - ./data/inputs:/app/data/inputs
      - ./config.ini:/app/config.ini
      - ./.env:/app/.env
    env_file:
      - .env
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"

  • 准备 .env 文件 (Prepare the .env file):
    通过复制示例文件 env.example 创建个性化的 .env 文件。根据您的需求配置 LLM 和嵌入参数。

Create a personalized .env file by copying the example file env.example. Configure the LLM and embedding parameters according to your needs.

  • 启动服务器 (Start the server):
    docker compose up

在此获取LightRAG docker镜像历史版本: LightRAG Docker Images

Find historical versions of the LightRAG Docker image here: LightRAG Docker Images

启动时自动扫描

Auto-Scan at Startup

当使用 --auto-scan-at-startup 参数启动服务器时，系统将自动：

When starting the server with the --auto-scan-at-startup parameter, the system will automatically:

  1. 扫描输入目录中的新文件 (Scan for new files in the input directory)
  2. 为尚未在数据库中的新文档建立索引 (Index new documents not yet in the database)
  3. 使所有内容立即可用于 RAG 查询 (Make all content immediately available for RAG queries)

--input-dir 参数指定要扫描的输入目录。您也可以从 webui 手动触发输入目录扫描。

The --input-dir parameter specifies the input directory to scan. You can also manually trigger a scan of the input directory from the webui.

核心概念与高级配置

Core Concepts and Advanced Configuration

Ollama 模拟与 Open WebUI 集成

Ollama Simulation and Open WebUI Integration

LightRAG 提供了 Ollama 兼容接口，可将其模拟为 Ollama 聊天模型。这使得支持 Ollama 的 AI 聊天前端（如 Open WebUI）可以轻松访问 LightRAG。

LightRAG provides an Ollama-compatible interface, allowing it to be simulated as an Ollama chat model. This enables AI chat frontends that support Ollama (such as Open WebUI) to easily access LightRAG.

启动 lightrag-server 后，您可以在 Open WebUI 管理面板中添加一个 Ollama 类型的连接。随后，一个名为 lightrag:latest 的模型将出现在模型列表中，用户即可通过聊天界面向 LightRAG 发送查询。

After starting lightrag-server, you can add an Ollama-type connection in the Open WebUI admin panel. Subsequently, a model named lightrag:latest will appear in the model list, and users can then send queries to LightRAG via the chat interface.

Image 4: Open WebUI Integration

在聊天中选择查询模式

Selecting Query Mode in Chat

通过发送带有特定前缀的消息，可以选择 LightRAG 的查询模式。支持的前缀包括：

You can select LightRAG's query mode by sending messages with specific prefixes. Supported prefixes include:

/local
/global
/hybrid
/naive
/mix

/bypass
/context
/localcontext
/globalcontext
/hybridcontext
/naivecontext
/mixcontext

例如，消息 "/mix 唐僧有几个徒弟" 将触发混合模式查询。没有前缀的消息默认使用 hybrid 模式。

For example, the message "/mix How many disciples does Tang Sanzang have?" will trigger a mixed-mode query. Messages without a prefix default to hybrid mode.

"/bypass" 前缀会指示 API 服务器将查询直接传递给底层 LLM，而不经过 RAG 检索。"/context" 前缀则指示 LightRAG 仅返回为 LLM 准备的上下文信息。

The "/bypass" prefix instructs the API server to pass the query directly to the underlying LLM, bypassing RAG retrieval. The "/context" prefix instructs LightRAG to return only the context information prepared for the LLM.

在聊天中添加用户提示词

Adding User Prompts in Chat

用户提示词（user prompt）不参与 RAG 检索，而是在检索完成后指导 LLM 如何处理结果。可以在查询前缀末尾添加方括号来传递用户提示词：

User prompts do not participate in RAG retrieval; instead, they guide the LLM on how to process the results after retrieval is complete. User prompts can be passed by adding square brackets at the end of the query prefix:

/[使用mermaid格式画图] 请画出 Scrooge 的人物关系图谱
/mix[使用mermaid格式画图] 请画出 Scrooge 的人物关系图谱

API 安全与认证

API Security and Authentication

默认情况下，LightRAG 服务器无需认证即可访问。可以通过以下方式配置安全访问：

By default, the LightRAG server is accessible without any authentication. Secure access can be configured in the following ways:

  • API 密钥 (API Key):
    设置环境变量 LIGHTRAG_API_KEY 来启用 API 密钥认证。健康检查 (/health) 和 Ollama 模拟端点默认不进行密钥检查。

Set the environment variable LIGHTRAG_API_KEY to enable API key authentication. Health check (/health) and Ollama simulation endpoints do not perform key checks by default.

  • 账户凭证（JWT 认证） (Account Credentials (JWT Authentication)):
    要启用 Web 界面登录和更细粒度的控制，需要配置基于 JWT 的认证。

To enable Web interface login and finer-grained control, JWT-based authentication needs to be configured.
# JWT 认证 (JWT Authentication) AUTH_ACCOUNTS='admin:admin123,user1:pass456' TOKEN_SECRET='your-key' TOKEN_EXPIRE_HOURS=4

目前仅支持配置一个管理员账户和密码。尚未开发和实现完整的账户系统。

Currently, only one administrator account and password can be configured. A full account system has not yet been developed and implemented.

注意：如果仅配置 API 密钥而未配置账户凭证，Web 界面将以访客身份运行，所有 API 仍可通过访客账户访问。为确保 API 安全，建议同时配置两种认证方法。

Note: If only an API key is configured without account credentials, the Web interface will run as a guest, and all APIs remain accessible via the guest account. To secure the APIs, it is recommended to configure both authentication methods simultaneously.

支持的存储后端

Supported Storage Backends

LightRAG 使用四种类型的存储，每种都有多种实现：

LightRAG uses four types of storage, each with multiple implementations:

  • KV_STORAGE (LLM 响应缓存、文本块、文档信息) (LLM response cache, text chunks, document info):

    • JsonKVStorage (默认/Default, JsonFile)
    • PGKVStorage (Postgres)
    • RedisKVStorage (Redis)
    • MongoKVStorage (MongoDB)

  • VECTOR_STORAGE (实体向量、关系向量、块向量) (Entity vectors, relation vectors, chunk vectors):

    • NanoVectorDBStorage (默认/Default, NanoVector)
    • PGVectorStorage (Postgres)
    • MilvusVectorDBStorage (Milvus)
    • ChromaVectorDBStorage (Chroma)
    • FaissVectorDBStorage (Faiss)
    • QdrantVectorDBStorage (Qdrant)
    • MongoVectorDBStorage (MongoDB)

  • GRAPH_STORAGE (实体关系图) (Entity-relationship graph):

    • NetworkXStorage (默认/Default, NetworkX)
    • Neo4JStorage (Neo4J)
    • PGGraphStorage (PostgreSQL with AGE plugin)

  • DOC_STATUS_STORAGE (文档索引状态) (Document indexing status):

    • JsonDocStatusStorage (默认/Default, JsonFile)
    • PGDocStatusStorage (Postgres)
    • MongoDocStatusStorage (M

常见问题（FAQ）

LightRAG 如何简化 RAG 应用的部署和使用？

LightRAG 提供 Web 界面和 API，支持 Docker、Linux 服务等多种部署方式，无需复杂配置即可进行文档索引、知识图谱探索和查询。

LightRAG 支持哪些 LLM 和嵌入模型后端？

支持 Ollama、lollms、OpenAI（及兼容接口）、Azure OpenAI 等多种后端，可通过环境变量灵活配置 LLM 和嵌入模型组合。

如何快速开始使用 LightRAG 的 Web 界面？

通过 pip 安装后，配置 .env 文件中的 LLM 和嵌入模型参数，启动服务器即可访问 Web 界面进行文档管理和 RAG 查询。

标签
AI应用开发生成式AI大语言模型AI大模型LLMS
← 返回文章列表
分享到：微博
下一篇
LightRAG是什么？2026年知识图谱增强RAG框架深度解析

版权与免责声明：本文仅用于信息分享与交流，不构成任何形式的法律、投资、医疗或其他专业建议，也不构成对任何结果的承诺或保证。

文中提及的商标、品牌、Logo、产品名称及相关图片/素材，其权利归各自合法权利人所有。本站内容可能基于公开资料整理，亦可能使用 AI 辅助生成或润色；我们尽力确保准确与合规，但不保证完整性、时效性与适用性，请读者自行甄别并以官方信息为准。

若本文内容或素材涉嫌侵权、隐私不当或存在错误，请相关权利人/当事人联系本站，我们将及时核实并采取删除、修正或下架等处理措施。 也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。