Add uv package manager support to installation docs
(cherry picked from commit 7bc6ccea19)
This commit is contained in:
yangdx
Raphaël MANSUY
parent
1daf35a77d
commit
db508954d1
4 changed files with 325 additions and 127 deletions
105
README-zh.md
105
README-zh.md
|
|
@ -53,13 +53,17 @@
|
|||
|
||||
## 🎉 新闻
|
||||
|
||||
- [X] [2025.06.16]🎯📢我们的团队发布了[RAG-Anything](https://github.com/HKUDS/RAG-Anything)，一个用于无缝处理文本、图像、表格和方程式的全功能多模态 RAG 系统。
|
||||
- [x] [2025.11.05]🎯📢添加**基于RAGAS的**评估框架和**Langfuse**可观测性支持。
|
||||
- [x] [2025.10.22]🎯📢消除处理**大规模数据集**的瓶颈。
|
||||
- [x] [2025.09.15]🎯📢显著提升**小型LLM**（如Qwen3-30B-A3B）的知识图谱提取准确性。
|
||||
- [x] [2025.08.29]🎯📢现已支持**Reranker**，显著提升混合查询性能。
|
||||
- [x] [2025.08.04]🎯📢支持**文档删除**并重新生成知识图谱以确保查询性能。
|
||||
- [x] [2025.06.16]🎯📢我们的团队发布了[RAG-Anything](https://github.com/HKUDS/RAG-Anything)，一个用于无缝处理文本、图像、表格和方程式的全功能多模态 RAG 系统。
|
||||
- [X] [2025.06.05]🎯📢LightRAG现已集成[RAG-Anything](https://github.com/HKUDS/RAG-Anything)，支持全面的多模态文档解析与RAG能力（PDF、图片、Office文档、表格、公式等）。详见下方[多模态处理模块](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#多模态文档处理rag-anything集成)。
|
||||
- [X] [2025.03.18]🎯📢LightRAG现已支持引文功能。
|
||||
- [X] [2025.02.05]🎯📢我们团队发布了[VideoRAG](https://github.com/HKUDS/VideoRAG)，用于理解超长上下文视频。
|
||||
- [X] [2025.01.13]🎯📢我们团队发布了[MiniRAG](https://github.com/HKUDS/MiniRAG)，使用小型模型简化RAG。
|
||||
- [X] [2025.01.06]🎯📢现在您可以[使用PostgreSQL进行存储](#using-postgresql-for-storage)。
|
||||
- [X] [2024.12.31]🎯📢LightRAG现在支持[通过文档ID删除](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete)。
|
||||
- [X] [2024.11.25]🎯📢LightRAG现在支持无缝集成[自定义知识图谱](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#insert-custom-kg)，使用户能够用自己的领域专业知识增强系统。
|
||||
- [X] [2024.11.19]🎯📢LightRAG的综合指南现已在[LearnOpenCV](https://learnopencv.com/lightrag)上发布。非常感谢博客作者。
|
||||
- [X] [2024.11.11]🎯📢LightRAG现在支持[通过实体名称删除实体](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete)。
|
||||
|
|
@ -86,6 +90,11 @@
|
|||
|
||||
## 安装
|
||||
|
||||
> **💡 使用 uv 进行包管理**: 本项目使用 [uv](https://docs.astral.sh/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服务器
|
||||
|
||||
LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知识图谱探索和简单的RAG查询界面。LightRAG服务器还提供兼容Ollama的接口，旨在将LightRAG模拟为Ollama聊天模型。这使得AI聊天机器人（如Open WebUI）可以轻松访问LightRAG。
|
||||
|
|
@ -93,7 +102,11 @@ LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知
|
|||
* 从PyPI安装
|
||||
|
||||
```bash
|
||||
pip install "lightrag-hku[api]"
|
||||
# 使用 uv (推荐)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
# 或使用 pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
|
||||
cp env.example .env
|
||||
lightrag-server
|
||||
```
|
||||
|
|
@ -103,19 +116,35 @@ lightrag-server
|
|||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
# 如有必要，创建Python虚拟环境
|
||||
# 以可编辑模式安装并支持API
|
||||
pip install -e ".[api]"
|
||||
cp env.example .env
|
||||
|
||||
# 使用 uv (推荐)
|
||||
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
|
||||
uv sync --extra api
|
||||
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 ".[api]"
|
||||
|
||||
cp env.example .env # 使用你的LLM和Embedding模型访问参数更新.env文件
|
||||
|
||||
# 构建前端代码
|
||||
cd lightrag_webui
|
||||
bun install --frozen-lockfile
|
||||
bun run build
|
||||
cd ..
|
||||
|
||||
lightrag-server
|
||||
```
|
||||
|
||||
* 使用 Docker Compose 启动 LightRAG 服务器
|
||||
|
||||
```
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
cp env.example .env
|
||||
cp env.example .env # 使用你的LLM和Embedding模型访问参数更新.env文件
|
||||
# modify LLM and Embedding settings in .env
|
||||
docker compose up
|
||||
```
|
||||
|
|
@ -128,13 +157,19 @@ docker compose up
|
|||
|
||||
```bash
|
||||
cd LightRAG
|
||||
pip install -e .
|
||||
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
|
||||
uv sync
|
||||
source .venv/bin/activate # 激活虚拟环境 (Linux/macOS)
|
||||
# Windows 系统: .venv\Scripts\activate
|
||||
|
||||
# 或: pip install -e .
|
||||
```
|
||||
|
||||
* 从PyPI安装
|
||||
|
||||
```bash
|
||||
pip install lightrag-hku
|
||||
uv pip install lightrag-hku
|
||||
# 或: pip install lightrag-hku
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
|
@ -1451,6 +1486,54 @@ LightRAG服务器提供全面的知识图谱可视化功能。它支持各种重
|
|||
|
||||
|
||||
|
||||
## Langfuse 可观测性集成
|
||||
|
||||
Langfuse 为 OpenAI 客户端提供了直接替代方案，可自动跟踪所有 LLM 交互，使开发者能够在无需修改代码的情况下监控、调试和优化其 RAG 系统。
|
||||
|
||||
### 安装 Langfuse 可选依赖
|
||||
|
||||
```
|
||||
pip install lightrag-hku
|
||||
pip install lightrag-hku[observability]
|
||||
|
||||
# 或从源代码安装并启用调试模式
|
||||
pip install -e .
|
||||
pip install -e ".[observability]"
|
||||
```
|
||||
|
||||
### 配置 Langfuse 环境变量
|
||||
|
||||
修改 .env 文件：
|
||||
|
||||
```
|
||||
## Langfuse 可观测性（可选）
|
||||
# LLM 可观测性和追踪平台
|
||||
# 安装命令: pip install lightrag-hku[observability]
|
||||
# 注册地址: https://cloud.langfuse.com 或自托管部署
|
||||
LANGFUSE_SECRET_KEY=""
|
||||
LANGFUSE_PUBLIC_KEY=""
|
||||
LANGFUSE_HOST="https://cloud.langfuse.com" # 或您的自托管实例地址
|
||||
LANGFUSE_ENABLE_TRACE=true
|
||||
```
|
||||
|
||||
### Langfuse 使用说明
|
||||
|
||||
安装并配置完成后，Langfuse 会自动追踪所有 OpenAI LLM 调用。Langfuse 仪表板功能包括：
|
||||
|
||||
- **追踪**：查看完整的 LLM 调用链
|
||||
- **分析**：Token 使用量、延迟、成本指标
|
||||
- **调试**：检查提示词和响应内容
|
||||
- **评估**：比较模型输出结果
|
||||
- **监控**：实时告警功能
|
||||
|
||||
### 重要提示
|
||||
|
||||
**注意**：LightRAG 目前仅把 OpenAI 兼容的 API 调用接入了 Langfuse。Ollama、Azure 和 AWS Bedrock 等 API 还无法使用 Langfuse 的可观测性功能。
|
||||
|
||||
## RAGAS评估
|
||||
|
||||
**RAGAS**（Retrieval Augmented Generation Assessment，检索增强生成评估）是一个使用LLM对RAG系统进行无参考评估的框架。我们提供了基于RAGAS的评估脚本。详细信息请参阅[基于RAGAS的评估框架](lightrag/evaluation/README.md)。
|
||||
|
||||
## 评估
|
||||
|
||||
### 数据集
|
||||
|
|
|
|||
111
README.md
111
README.md
|
|
@ -51,13 +51,17 @@
|
|||
|
||||
---
|
||||
## 🎉 News
|
||||
- [X] [2025.06.16]🎯📢Our team has released [RAG-Anything](https://github.com/HKUDS/RAG-Anything) an All-in-One Multimodal RAG System for seamless text, image, table, and equation processing.
|
||||
- [x] [2025.11.05]🎯📢Add **RAGAS-based** Evaluation Framework and **Langfuse** observability for LightRAG.
|
||||
- [x] [2025.10.22]🎯📢Eliminate bottlenecks in processing **large-scale datasets**.
|
||||
- [x] [2025.09.15]🎯📢Significantly enhances KG extraction accuracy for **small LLMs** like Qwen3-30B-A3B.
|
||||
- [x] [2025.08.29]🎯📢**Reranker** is supported now , significantly boosting performance for mixed queries.
|
||||
- [x] [2025.08.04]🎯📢**Document deletion** with KG regeneration to ensure query performance.
|
||||
- [x] [2025.06.16]🎯📢Our team has released [RAG-Anything](https://github.com/HKUDS/RAG-Anything) an All-in-One Multimodal RAG System for seamless text, image, table, and equation processing.
|
||||
- [X] [2025.06.05]🎯📢LightRAG now supports comprehensive multimodal data handling through [RAG-Anything](https://github.com/HKUDS/RAG-Anything) integration, enabling seamless document parsing and RAG capabilities across diverse formats including PDFs, images, Office documents, tables, and formulas. Please refer to the new [multimodal section](https://github.com/HKUDS/LightRAG/?tab=readme-ov-file#multimodal-document-processing-rag-anything-integration) for details.
|
||||
- [X] [2025.03.18]🎯📢LightRAG now supports citation functionality, enabling proper source attribution.
|
||||
- [X] [2025.02.05]🎯📢Our team has released [VideoRAG](https://github.com/HKUDS/VideoRAG) understanding extremely long-context videos.
|
||||
- [X] [2025.01.13]🎯📢Our team has released [MiniRAG](https://github.com/HKUDS/MiniRAG) making RAG simpler with small models.
|
||||
- [X] [2025.01.06]🎯📢You can now [use PostgreSQL for Storage](#using-postgresql-for-storage).
|
||||
- [X] [2024.12.31]🎯📢LightRAG now supports [deletion by document ID](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).
|
||||
- [X] [2024.11.25]🎯📢LightRAG now supports seamless integration of [custom knowledge graphs](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#insert-custom-kg), empowering users to enhance the system with their own domain expertise.
|
||||
- [X] [2024.11.19]🎯📢A comprehensive guide to LightRAG is now available on [LearnOpenCV](https://learnopencv.com/lightrag). Many thanks to the blog author.
|
||||
- [X] [2024.11.11]🎯📢LightRAG now supports [deleting entities by their names](https://github.com/HKUDS/LightRAG?tab=readme-ov-file#delete).
|
||||
|
|
@ -84,6 +88,11 @@
|
|||
|
||||
## Installation
|
||||
|
||||
> **💡 Using uv for Package Management**: This project uses [uv](https://docs.astral.sh/uv/) for fast and reliable Python package management.
|
||||
> Install uv first: `curl -LsSf https://astral.sh/uv/install.sh | sh` (Unix/macOS) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows)
|
||||
>
|
||||
> **Note**: You can also use pip if you prefer, but uv is recommended for better performance and more reliable dependency management.
|
||||
>
|
||||
> **📦 Offline Deployment**: For offline or air-gapped environments, see the [Offline Deployment Guide](./docs/OfflineDeployment.md) for instructions on pre-installing all dependencies and cache files.
|
||||
|
||||
### Install LightRAG Server
|
||||
|
|
@ -93,7 +102,11 @@ The LightRAG Server is designed to provide Web UI and API support. The Web UI fa
|
|||
* Install from PyPI
|
||||
|
||||
```bash
|
||||
pip install "lightrag-hku[api]"
|
||||
# Using uv (recommended)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
# Or using pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
|
||||
cp env.example .env
|
||||
lightrag-server
|
||||
```
|
||||
|
|
@ -103,19 +116,35 @@ lightrag-server
|
|||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
# create a Python virtual enviroment if neccesary
|
||||
# Install in editable mode with API support
|
||||
pip install -e ".[api]"
|
||||
cp env.example .env
|
||||
|
||||
# Using uv (recommended)
|
||||
# Note: uv sync automatically creates a virtual environment in .venv/
|
||||
uv sync --extra api
|
||||
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 ".[api]"
|
||||
|
||||
cp env.example .env # Update the .env with your LLM and embedding configurations
|
||||
|
||||
# Build front-end artifacts
|
||||
cd lightrag_webui
|
||||
bun install --frozen-lockfile
|
||||
bun run build
|
||||
cd ..
|
||||
|
||||
lightrag-server
|
||||
```
|
||||
|
||||
* Launching the LightRAG Server with Docker Compose
|
||||
|
||||
```
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
cp env.example .env
|
||||
cp env.example .env # Update the .env with your LLM and embedding configurations
|
||||
# modify LLM and Embedding settings in .env
|
||||
docker compose up
|
||||
```
|
||||
|
|
@ -124,23 +153,27 @@ docker compose up
|
|||
|
||||
### Install LightRAG Core
|
||||
|
||||
* Install from source (Recommend)
|
||||
* Install from source (Recommended)
|
||||
|
||||
```bash
|
||||
cd LightRAG
|
||||
pip install -e .
|
||||
# Note: uv sync automatically creates a virtual environment in .venv/
|
||||
uv sync
|
||||
source .venv/bin/activate # Activate the virtual environment (Linux/macOS)
|
||||
# Or on Windows: .venv\Scripts\activate
|
||||
|
||||
# Or: pip install -e .
|
||||
```
|
||||
|
||||
* Install from PyPI
|
||||
|
||||
```bash
|
||||
pip install lightrag-hku
|
||||
uv pip install lightrag-hku
|
||||
# Or: pip install lightrag-hku
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
> 🚀 **Recommended for Most Users**: LightRAG uses **OpenAI by default** for optimal performance. See [OPENAI_CONFIGURATION.md](./OPENAI_CONFIGURATION.md) for a complete setup guide (5-minute quick start included).
|
||||
|
||||
### LLM and Technology Stack Requirements for LightRAG
|
||||
|
||||
LightRAG's demands on the capabilities of Large Language Models (LLMs) are significantly higher than those of traditional RAG, as it requires the LLM to perform entity-relationship extraction tasks from documents. Configuring appropriate Embedding and Reranker models is also crucial for improving query performance.
|
||||
|
|
@ -1533,6 +1566,54 @@ The LightRAG Server offers a comprehensive knowledge graph visualization feature
|
|||
|
||||
|
||||
|
||||
## Langfuse observability integration
|
||||
|
||||
Langfuse provides a drop-in replacement for the OpenAI client that automatically tracks all LLM interactions, enabling developers to monitor, debug, and optimize their RAG systems without code changes.
|
||||
|
||||
### Installation with Langfuse option
|
||||
|
||||
```
|
||||
pip install lightrag-hku
|
||||
pip install lightrag-hku[observability]
|
||||
|
||||
# Or install from souce code with debug mode enabled
|
||||
pip install -e .
|
||||
pip install -e ".[observability]"
|
||||
```
|
||||
|
||||
### Config Langfuse env vars
|
||||
|
||||
modify .env file:
|
||||
|
||||
```
|
||||
## Langfuse Observability (Optional)
|
||||
# LLM observability and tracing platform
|
||||
# Install with: pip install lightrag-hku[observability]
|
||||
# Sign up at: https://cloud.langfuse.com or self-host
|
||||
LANGFUSE_SECRET_KEY=""
|
||||
LANGFUSE_PUBLIC_KEY=""
|
||||
LANGFUSE_HOST="https://cloud.langfuse.com" # or your self-hosted instance
|
||||
LANGFUSE_ENABLE_TRACE=true
|
||||
```
|
||||
|
||||
### Langfuse Usage
|
||||
|
||||
Once installed and configured, Langfuse automatically traces all OpenAI LLM calls. Langfuse dashboard features include:
|
||||
|
||||
- **Tracing**: View complete LLM call chains
|
||||
- **Analytics**: Token usage, latency, cost metrics
|
||||
- **Debugging**: Inspect prompts and responses
|
||||
- **Evaluation**: Compare model outputs
|
||||
- **Monitoring**: Real-time alerting
|
||||
|
||||
### Important Notice
|
||||
|
||||
**Note**: LightRAG currently only integrates OpenAI-compatible API calls with Langfuse. APIs such as Ollama, Azure, and AWS Bedrock are not yet supported for Langfuse observability.
|
||||
|
||||
## RAGAS-based Evaluation
|
||||
|
||||
**RAGAS** (Retrieval Augmented Generation Assessment) is a framework for reference-free evaluation of RAG systems using LLMs. There is an evaluation script based on RAGAS. For detailed information, please refer to [RAGAS-based Evaluation Framework](lightrag/evaluation/README.md).
|
||||
|
||||
## Evaluation
|
||||
|
||||
### Dataset
|
||||
|
|
@ -1541,7 +1622,7 @@ The dataset used in LightRAG can be downloaded from [TommyChien/UltraDomain](htt
|
|||
|
||||
### Generate Query
|
||||
|
||||
LightRAG uses the following prompt to generate high-level queries, with the corresponding code in `example/generate_query.py`.
|
||||
LightRAG uses the following prompt to generate high-level queries, with the corresponding code in `examples/generate_query.py`.
|
||||
|
||||
<details>
|
||||
<summary> Prompt </summary>
|
||||
|
|
|
|||
|
|
@ -15,7 +15,11 @@ LightRAG 服务器旨在提供 Web 界面和 API 支持。Web 界面便于文档
|
|||
* 从 PyPI 安装
|
||||
|
||||
```bash
|
||||
pip install "lightrag-hku[api]"
|
||||
# 使用 uv (推荐)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
|
||||
# 或使用 pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
```
|
||||
|
||||
* 从源代码安装
|
||||
|
|
@ -24,12 +28,25 @@ pip install "lightrag-hku[api]"
|
|||
# 克隆仓库
|
||||
git clone https://github.com/HKUDS/lightrag.git
|
||||
|
||||
# 切换到仓库目录
|
||||
# 进入仓库目录
|
||||
cd lightrag
|
||||
|
||||
# 如有必要，创建 Python 虚拟环境
|
||||
# 以可编辑模式安装并支持 API
|
||||
pip install -e ".[api]"
|
||||
# 使用 uv (推荐)
|
||||
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
|
||||
uv sync --extra api
|
||||
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 ".[api]"
|
||||
|
||||
# 构建前端代码
|
||||
cd lightrag_webui
|
||||
bun install --frozen-lockfile
|
||||
bun run build
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 启动 LightRAG 服务器前的准备
|
||||
|
|
@ -109,36 +126,10 @@ lightrag-gunicorn --workers 4
|
|||
|
||||
### 使用 Docker 启动 LightRAG 服务器
|
||||
|
||||
* 配置 .env 文件：
|
||||
通过复制示例文件 [`env.example`](env.example) 创建个性化的 .env 文件，并根据实际需求设置 LLM 及 Embedding 参数。
|
||||
* 创建一个名为 docker-compose.yml 的文件：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
lightrag:
|
||||
container_name: lightrag
|
||||
image: ghcr.io/hkuds/lightrag:latest
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
tags:
|
||||
- ghcr.io/hkuds/lightrag:latest
|
||||
ports:
|
||||
- "${PORT:-9621}:9621"
|
||||
volumes:
|
||||
- ./data/rag_storage:/app/data/rag_storage
|
||||
- ./data/inputs:/app/data/inputs
|
||||
- ./data/tiktoken:/app/data/tiktoken
|
||||
- ./config.ini:/app/config.ini
|
||||
- ./.env:/app/.env
|
||||
env_file:
|
||||
- .env
|
||||
environment:
|
||||
- TIKTOKEN_CACHE_DIR=/app/data/tiktoken
|
||||
restart: unless-stopped
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
```
|
||||
使用 Docker Compose 是部署和运行 LightRAG Server 最便捷的方式。
|
||||
- 创建一个项目目录。
|
||||
- 将 LightRAG 仓库中的 `docker-compose.yml` 文件复制到您的项目目录中。
|
||||
- 准备 `.env` 文件：复制示例文件 [`env.example`](https://ai.znipower.com:5013/c/env.example) 创建自定义的 `.env` 文件，并根据您的具体需求配置 LLM 和嵌入参数。
|
||||
|
||||
* 通过以下命令启动 LightRAG 服务器：
|
||||
|
||||
|
|
@ -146,11 +137,11 @@ services:
|
|||
docker compose up
|
||||
# 如果希望启动后让程序退到后台运行，需要在命令的最后添加 -d 参数
|
||||
```
|
||||
> 可以通过以下链接获取官方的docker compose文件：[docker-compose.yml]( https://raw.githubusercontent.com/HKUDS/LightRAG/refs/heads/main/docker-compose.yml) 。如需获取LightRAG的历史版本镜像，可以访问以下链接: [LightRAG Docker Images]( https://github.com/HKUDS/LightRAG/pkgs/container/lightrag)
|
||||
> 可以通过以下链接获取官方的docker compose文件：[docker-compose.yml]( https://raw.githubusercontent.com/HKUDS/LightRAG/refs/heads/main/docker-compose.yml) 。如需获取LightRAG的历史版本镜像，可以访问以下链接: [LightRAG Docker Images]( https://github.com/HKUDS/LightRAG/pkgs/container/lightrag). 如需获取更多关于docker部署的信息，请参阅 [DockerDeployment.md](./../../docs/DockerDeployment.md).
|
||||
|
||||
### 离线部署
|
||||
|
||||
对于离线或隔离环境，请参阅[离线部署指南](./../../docs/OfflineDeployment.md)，了解如何预先安装所有依赖项和缓存文件。
|
||||
官方的 LightRAG Docker 镜像完全兼容离线或隔离网络环境。如需搭建自己的离线部署环境，请参考 [离线部署指南](./../../docs/OfflineDeployment.md)。
|
||||
|
||||
### 启动多个LightRAG实例
|
||||
|
||||
|
|
@ -201,24 +192,16 @@ MAX_ASYNC=4
|
|||
|
||||
### 将 Lightrag 安装为 Linux 服务
|
||||
|
||||
从示例文件 `lightrag.service.example` 创建您的服务文件 `lightrag.service`。修改服务文件中的 WorkingDirectory 和 ExecStart：
|
||||
从示例文件 `lightrag.service.example` 创建您的服务文件 `lightrag.service`。修改服务文件中的服务启动定义：
|
||||
|
||||
```text
|
||||
Description=LightRAG Ollama Service
|
||||
WorkingDirectory=<lightrag 安装目录>
|
||||
ExecStart=<lightrag 安装目录>/lightrag/api/lightrag-api
|
||||
```
|
||||
|
||||
修改您的服务启动脚本：`lightrag-api`。根据需要更改 python 虚拟环境激活命令：
|
||||
|
||||
```shell
|
||||
#!/bin/bash
|
||||
|
||||
# 您的 python 虚拟环境激活命令
|
||||
source /home/netman/lightrag-xyj/venv/bin/activate
|
||||
# 启动 lightrag api 服务器
|
||||
lightrag-server
|
||||
# Set Enviroment to your Python virtual enviroment
|
||||
Environment="PATH=/home/netman/lightrag-xyj/venv/bin"
|
||||
WorkingDirectory=/home/netman/lightrag-xyj
|
||||
# ExecStart=/home/netman/lightrag-xyj/venv/bin/lightrag-server
|
||||
ExecStart=/home/netman/lightrag-xyj/venv/bin/lightrag-gunicorn
|
||||
```
|
||||
> ExecStart命令必须是 lightrag-gunicorn 或 lightrag-server 中的一个，不能使用其它脚本包裹它们。因为停止服务必须要求主进程必须是这两个进程。
|
||||
|
||||
安装 LightRAG 服务。如果您的系统是 Ubuntu，以下命令将生效：
|
||||
|
||||
|
|
@ -425,6 +408,10 @@ LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
|
|||
|
||||
在向 LightRAG 添加文档后，您不能更改存储实现选择。目前尚不支持从一个存储实现迁移到另一个存储实现。更多配置信息请阅读示例 `env.exampl`e文件。
|
||||
|
||||
### 在不同存储类型之间迁移LLM缓存
|
||||
|
||||
当LightRAG更换存储实现方式的时候，可以LLM缓存从就的存储迁移到新的存储。先以后在新的存储上重新上传文件时，将利用利用原有存储的LLM缓存大幅度加快文件处理的速度。LLM缓存迁移工具的使用方法请参考[README_MIGRATE_LLM_CACHE.md](../tools/README_MIGRATE_LLM_CACHE.md)
|
||||
|
||||
### LightRag API 服务器命令行选项
|
||||
|
||||
| 参数 | 默认值 | 描述 |
|
||||
|
|
|
|||
|
|
@ -15,7 +15,11 @@ The LightRAG Server is designed to provide a Web UI and API support. The Web UI
|
|||
* Install from PyPI
|
||||
|
||||
```bash
|
||||
pip install "lightrag-hku[api]"
|
||||
# Using uv (recommended)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
|
||||
# Or using pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
```
|
||||
|
||||
* Installation from Source
|
||||
|
|
@ -27,9 +31,22 @@ git clone https://github.com/HKUDS/lightrag.git
|
|||
# Change to the repository directory
|
||||
cd lightrag
|
||||
|
||||
# create a Python virtual environment if necessary
|
||||
# Install in editable mode with API support
|
||||
pip install -e ".[api]"
|
||||
# Using uv (recommended)
|
||||
# Note: uv sync automatically creates a virtual environment in .venv/
|
||||
uv sync --extra api
|
||||
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 ".[api]"
|
||||
|
||||
# Build front-end artifacts
|
||||
cd lightrag_webui
|
||||
bun install --frozen-lockfile
|
||||
bun run build
|
||||
cd ..
|
||||
```
|
||||
|
||||
### Before Starting LightRAG Server
|
||||
|
|
@ -41,6 +58,7 @@ LightRAG necessitates the integration of both an LLM (Large Language Model) and
|
|||
* openai or openai compatible
|
||||
* azure_openai
|
||||
* aws_bedrock
|
||||
* gemini
|
||||
|
||||
It is recommended to use environment variables to configure the LightRAG Server. There is an example environment variable file named `env.example` in the root directory of the project. Please copy this file to the startup directory and rename it to `.env`. After that, you can modify the parameters related to the LLM and Embedding models in the `.env` file. It is important to note that the LightRAG Server will load the environment variables from `.env` into the system environment variables each time it starts. **LightRAG Server will prioritize the settings in the system environment variables to .env file**.
|
||||
|
||||
|
|
@ -63,6 +81,8 @@ EMBEDDING_DIM=1024
|
|||
# EMBEDDING_BINDING_API_KEY=your_api_key
|
||||
```
|
||||
|
||||
> When targeting Google Gemini, set `LLM_BINDING=gemini`, choose a model such as `LLM_MODEL=gemini-flash-latest`, and provide your Gemini key via `LLM_BINDING_API_KEY` (or `GEMINI_API_KEY`).
|
||||
|
||||
* Ollama LLM + Ollama Embedding:
|
||||
|
||||
```
|
||||
|
|
@ -110,37 +130,13 @@ During startup, configurations in the `.env` file can be overridden by command-l
|
|||
|
||||
### Launching LightRAG Server with Docker
|
||||
|
||||
* Prepare the .env file:
|
||||
Create a personalized .env file by copying the sample file [`env.example`](env.example). Configure the LLM and embedding parameters according to your requirements.
|
||||
Using Docker Compose is the most convenient way to deploy and run the LightRAG Server.
|
||||
|
||||
* Create a file named `docker-compose.yml`:
|
||||
* Create a project directory.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
lightrag:
|
||||
container_name: lightrag
|
||||
image: ghcr.io/hkuds/lightrag:latest
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
tags:
|
||||
- ghcr.io/hkuds/lightrag:latest
|
||||
ports:
|
||||
- "${PORT:-9621}:9621"
|
||||
volumes:
|
||||
- ./data/rag_storage:/app/data/rag_storage
|
||||
- ./data/inputs:/app/data/inputs
|
||||
- ./data/tiktoken:/app/data/tiktoken
|
||||
- ./config.ini:/app/config.ini
|
||||
- ./.env:/app/.env
|
||||
env_file:
|
||||
- .env
|
||||
environment:
|
||||
- TIKTOKEN_CACHE_DIR=/app/data/tiktoken
|
||||
restart: unless-stopped
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
```
|
||||
* Copy the `docker-compose.yml` file from the LightRAG repository into your project directory.
|
||||
|
||||
* Prepare the `.env` file: Duplicate the sample file [`env.example`](https://ai.znipower.com:5013/c/env.example)to create a customized `.env` file, and configure the LLM and embedding parameters according to your specific requirements.
|
||||
|
||||
* Start the LightRAG Server with the following command:
|
||||
|
||||
|
|
@ -149,11 +145,11 @@ docker compose up
|
|||
# If you want the program to run in the background after startup, add the -d parameter at the end of the command.
|
||||
```
|
||||
|
||||
> You can get the official docker compose file from here: [docker-compose.yml](https://raw.githubusercontent.com/HKUDS/LightRAG/refs/heads/main/docker-compose.yml). For historical versions of LightRAG docker images, visit this link: [LightRAG Docker Images](https://github.com/HKUDS/LightRAG/pkgs/container/lightrag)
|
||||
You can get the official docker compose file from here: [docker-compose.yml](https://raw.githubusercontent.com/HKUDS/LightRAG/refs/heads/main/docker-compose.yml). For historical versions of LightRAG docker images, visit this link: [LightRAG Docker Images](https://github.com/HKUDS/LightRAG/pkgs/container/lightrag). For more details about docker deployment, please refer to [DockerDeployment.md](./../../docs/DockerDeployment.md).
|
||||
|
||||
### Offline Deployment
|
||||
|
||||
For offline or air-gapped environments, see the [Offline Deployment Guide](./../../docs/OfflineDeployment.md) for instructions on pre-installing all dependencies and cache files.
|
||||
Official LightRAG Docker images are fully compatible with offline or air-gapped environments. If you want to build up you own offline enviroment, please refer to [Offline Deployment Guide](./../../docs/OfflineDeployment.md).
|
||||
|
||||
### Starting Multiple LightRAG Instances
|
||||
|
||||
|
|
@ -204,24 +200,18 @@ MAX_ASYNC=4
|
|||
|
||||
### Install LightRAG as a Linux Service
|
||||
|
||||
Create your service file `lightrag.service` from the sample file: `lightrag.service.example`. Modify the `WorkingDirectory` and `ExecStart` in the service file:
|
||||
Create your service file `lightrag.service` from the sample file: `lightrag.service.example`. Modify the start options the service file:
|
||||
|
||||
```text
|
||||
Description=LightRAG Ollama Service
|
||||
WorkingDirectory=<lightrag installed directory>
|
||||
ExecStart=<lightrag installed directory>/lightrag/api/lightrag-api
|
||||
# Set Enviroment to your Python virtual enviroment
|
||||
Environment="PATH=/home/netman/lightrag-xyj/venv/bin"
|
||||
WorkingDirectory=/home/netman/lightrag-xyj
|
||||
# ExecStart=/home/netman/lightrag-xyj/venv/bin/lightrag-server
|
||||
ExecStart=/home/netman/lightrag-xyj/venv/bin/lightrag-gunicorn
|
||||
|
||||
```
|
||||
|
||||
Modify your service startup script: `lightrag-api`. Change your Python virtual environment activation command as needed:
|
||||
|
||||
```shell
|
||||
#!/bin/bash
|
||||
|
||||
# your python virtual environment activation
|
||||
source /home/netman/lightrag-xyj/venv/bin/activate
|
||||
# start lightrag api server
|
||||
lightrag-server
|
||||
```
|
||||
> The ExecStart command must be either `lightrag-gunicorn` or `lightrag-server`; no wrapper scripts are allowed. This is because service termination requires the main process to be one of these two executables.
|
||||
|
||||
Install LightRAG service. If your system is Ubuntu, the following commands will work:
|
||||
|
||||
|
|
@ -428,6 +418,10 @@ LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
|
|||
|
||||
You cannot change storage implementation selection after adding documents to LightRAG. Data migration from one storage implementation to another is not supported yet. For further information, please read the sample env file or config.ini file.
|
||||
|
||||
### LLM Cache Migration Between Storage Types
|
||||
|
||||
When switching the storage implementation in LightRAG, the LLM cache can be migrated from the existing storage to the new one. Subsequently, when re-uploading files to the new storage, the pre-existing LLM cache will significantly accelerate file processing. For detailed instructions on using the LLM cache migration tool, please refer to[README_MIGRATE_LLM_CACHE.md](../tools/README_MIGRATE_LLM_CACHE.md)
|
||||
|
||||
### LightRAG API Server Command Line Options
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|
|
@ -484,6 +478,59 @@ The `/query` and `/query/stream` API endpoints include an `enable_rerank` parame
|
|||
RERANK_BY_DEFAULT=False
|
||||
```
|
||||
|
||||
### Include Chunk Content in References
|
||||
|
||||
By default, the `/query` and `/query/stream` endpoints return references with only `reference_id` and `file_path`. For evaluation, debugging, or citation purposes, you can request the actual retrieved chunk content to be included in references.
|
||||
|
||||
The `include_chunk_content` parameter (default: `false`) controls whether the actual text content of retrieved chunks is included in the response references. This is particularly useful for:
|
||||
|
||||
- **RAG Evaluation**: Testing systems like RAGAS that need access to retrieved contexts
|
||||
- **Debugging**: Verifying what content was actually used to generate the answer
|
||||
- **Citation Display**: Showing users the exact text passages that support the response
|
||||
- **Transparency**: Providing full visibility into the RAG retrieval process
|
||||
|
||||
**Important**: The `content` field is an **array of strings**, where each string represents a chunk from the same file. A single file may correspond to multiple chunks, so the content is returned as a list to preserve chunk boundaries.
|
||||
|
||||
**Example API Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "What is LightRAG?",
|
||||
"mode": "mix",
|
||||
"include_references": true,
|
||||
"include_chunk_content": true
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response (with chunk content):**
|
||||
|
||||
```json
|
||||
{
|
||||
"response": "LightRAG is a graph-based RAG system...",
|
||||
"references": [
|
||||
{
|
||||
"reference_id": "1",
|
||||
"file_path": "/documents/intro.md",
|
||||
"content": [
|
||||
"LightRAG is a retrieval-augmented generation system that combines knowledge graphs with vector similarity search...",
|
||||
"The system uses a dual-indexing approach with both vector embeddings and graph structures for enhanced retrieval..."
|
||||
]
|
||||
},
|
||||
{
|
||||
"reference_id": "2",
|
||||
"file_path": "/documents/features.md",
|
||||
"content": [
|
||||
"The system provides multiple query modes including local, global, hybrid, and mix modes..."
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
- This parameter only works when `include_references=true`. Setting `include_chunk_content=true` without including references has no effect.
|
||||
- **Breaking Change**: Prior versions returned `content` as a single concatenated string. Now it returns an array of strings to preserve individual chunk boundaries. If you need a single string, join the array elements with your preferred separator (e.g., `"\n\n".join(content)`).
|
||||
|
||||
### .env Examples
|
||||
|
||||
```bash
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue