快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• setup.py
• pyproject.toml
• requirements-offline.txt
• examples/lightrag_openai_demo.py
• examples/lightrag_ollama_demo.py
• examples/lightrag_openai_compatible_demo.py
• examples/rerank_example.py
• examples/lightrag_vllm_demo.py
• examples/modalprocessors_example.py

LightRAG 是一个简单高效的检索增强生成（RAG）框架，支持知识图谱提取、多模态文档处理和多种 LLM 后端。本章节将介绍如何快速安装、配置和运行 LightRAG。

环境要求

系统与语言要求

LightRAG 对运行环境有以下基本要求：

• Python 版本：需要 Python 3.10 或更高版本（pyproject.toml:14）
• 操作系统：支持 Linux、macOS 和 Windows
• 包管理器：推荐使用 uv 进行依赖管理，也支持 pip

核心依赖项

项目的主要依赖包括（pyproject.toml:23-42）：

可选依赖组

LightRAG 提供多个可选依赖组以满足不同使用场景（pyproject.toml:44-154）：

安装方式

LightRAG 提供两种主要安装模式：LightRAG Server（带 Web UI 和 API）和 LightRAG Core（核心库）。

推荐安装路径

安装 LightRAG Server

LightRAG Server 提供 Web UI 界面和 API 支持，适合需要可视化操作的场景。

方式一：从 PyPI 安装（推荐）

bash
1# 安装 uv 包管理器（首次使用）
2curl -LsSf https://astral.sh/uv/install.sh | sh  # Unix/macOS
3# 或 Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
4
5# 安装 LightRAG Server
6uv tool install "lightrag-hku[api]"
7
8# 或使用 pip
9# python -m venv .venv
10# source .venv/bin/activate  # Windows: .venv\Scripts\activate
11# pip install "lightrag-hku[api]"

（README.md:107-145）

方式二：从源码安装

bash
1git clone https://github.com/HKUDS/LightRAG.git
2cd LightRAG
3
4# 使用 uv（推荐）
5uv sync --extra api
6source .venv/bin/activate  # Linux/macOS
7# 或 Windows: .venv\Scripts\activate
8
9# 或使用 pip
10# python -m venv .venv
11# source .venv/bin/activate
12# pip install -e ".[api]"

（README.md:145-172）

安装 LightRAG Core

仅需核心功能进行开发集成时，可安装轻量级 Core 版本。

从源码安装（推荐）

bash
1cd LightRAG
2uv sync
3source .venv/bin/activate  # Linux/macOS
4# 或 Windows: .venv\Scripts\activate

（README.md:205-217）

从 PyPI 安装

bash
1uv pip install lightrag-hku
2# 或: pip install lightrag-hku

（README.md:219-224）

模型配置要求

LightRAG 对模型配置有特定要求，正确选择模型对系统性能至关重要。

LLM 模型选择

LightRAG 需要 LLM 执行实体关系提取任务，对模型能力要求较高（README.md:228-235）：

Embedding 模型配置

Embedding 模型对 RAG 性能影响显著（README.md:237-241）：

• 推荐使用主流多语言模型：BAAI/bge-m3、text-embedding-3-large
• 重要：索引和查询阶段必须使用相同的 Embedding 模型
• 更换模型时需删除现有向量表并重建

Reranker 模型配置

配置 Reranker 可显著提升检索性能（README.md:241-244）：

• 推荐模型：BAAI/bge-reranker-v2-m3 或 Jina 提供的模型
• 启用 Reranker 时，建议将 "mix mode" 设为默认查询模式

Docker 部署

Docker Compose 是快速部署 LightRAG Server 的推荐方式。

部署步骤

bash
1# 克隆仓库
2git clone https://github.com/HKUDS/LightRAG.git
3cd LightRAG
4
5# 配置环境变量
6cp env.example .env
7# 编辑 .env 文件，配置 LLM 和 Embedding 设置
8
9# 启动服务
10docker compose up

（README.md:174-182）

环境配置工具

项目提供交互式配置工具生成 .env 文件（README.md:186-203）：

bash
1make env-base           # 配置 LLM、Embedding、Reranker
2make env-storage        # 配置存储后端和数据库服务
3make env-server         # 配置服务器端口、认证和 SSL
4make env-security-check # 安全审计当前 .env 配置

历史版本 Docker 镜像可在 LightRAG Docker Images 获取（README.md:184）。

最短可运行路径

以下是最快运行 LightRAG 的步骤：

方式一：Server 模式（带 Web UI）

bash
1# 1. 安装
2uv tool install "lightrag-hku[api]"
3
4# 2. 配置环境
5cp env.example .env
6# 编辑 .env 设置 LLM_API_KEY 等必要配置
7
8# 3. 启动服务
9lightrag-server

启动命令 lightrag-server 由 pyproject.toml 定义（pyproject.toml:155-156）。

方式二：Core 模式（代码集成）

python
1# 安装: pip install lightrag-hku
2from lightrag import LightRAG
3
4# 初始化并使用
5rag = LightRAG()
6# 后续操作请参考使用指南

运行验证

验证服务状态

Server 模式验证：

启动 lightrag-server 后，可通过以下方式验证：

1. 访问 Web UI 界面（默认端口需确认，建议查看 .env 配置或启动日志）
2. 检查 API 健康状态（健康检查路径需要确认）

预期输出：服务启动时应显示类似以下日志（需要确认具体关键字）：

• 服务监听端口信息
• 数据库连接成功提示
• API 路由注册完成

验证安装完整性

bash
1# 验证命令行工具
2lightrag-server --help
3lightrag-download-cache --help
4lightrag-clean-llmqc --help

这些命令行工具在 pyproject.toml 中定义（pyproject.toml:155-159）。

常见问题与排错

问题 1：Python 版本不兼容

症状：安装时报错 requires-python >=3.10

解决方案：

bash
1# 检查 Python 版本
2python --version
3
4# 如版本过低，使用 pyenv 或 conda 安装 Python 3.10+
5pyenv install 3.10
6pyenv local 3.10

问题 2：依赖安装失败

症状：pip install 或 uv sync 过程中部分包安装失败

解决方案：

1. 确保系统已安装构建工具（Linux: build-essential，macOS: Xcode Command Line Tools）
2. 使用 uv 替代 pip，其依赖解析更可靠（README.md:109-112）
3. 对于离线环境，参考 Offline Deployment Guide（README.md:114）

问题 3：Embedding 模型维度不匹配

症状：查询时报错向量维度不一致

解决方案：

• 确保索引和查询使用相同的 Embedding 模型（README.md:240）
• 更换模型后需删除现有向量表重建索引（README.md:240-241）

问题 4：Docker 容器启动失败

症状：docker compose up 失败

解决方案：

1. 检查 .env 文件是否正确配置（README.md:179-180）
2. 确认 LLM API Key 有效
3. 查看容器日志：docker compose logs

问题 5：LLM 响应质量差

症状：实体提取不准确，查询结果质量低

解决方案：

• 使用参数量至少 32B 的模型（README.md:233）
• 确保上下文长度至少 32KB（README.md:234）
• 配置 Reranker 模型提升检索精度（README.md:242）

下一步建议

完成快速上手后，建议继续探索以下内容：

1. 使用指南：了解 LightRAG 的完整 API 和高级配置选项
2. 存储后端配置：配置 Neo4j、PostgreSQL、MongoDB 等存储方案
3. 多模态处理：通过 RAG-Anything 集成处理 PDF、图像、表格等多模态文档（README.md:81-82）
4. 评估与追踪：使用 RAGAS 进行评估和 Langfuse 进行追踪（README.md:76）
5. 示例代码：参考 examples/ 目录下的演示脚本

更多 Server 相关信息请参考 LightRAG Server 文档（README.md:248）。