cherry-pick 8af8bd80
This commit is contained in:
Raphaël MANSUY
parent
dd73dd3c9f
commit
7fa4f883a6
2 changed files with 96 additions and 251 deletions
166
README-zh.md
166
README-zh.md
|
|
@ -53,17 +53,13 @@
|
|||
|
||||
## 🎉 新闻
|
||||
|
||||
- [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.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)。
|
||||
|
|
@ -90,11 +86,6 @@
|
|||
|
||||
## 安装
|
||||
|
||||
> **💡 使用 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。
|
||||
|
|
@ -102,11 +93,7 @@ LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知
|
|||
* 从PyPI安装
|
||||
|
||||
```bash
|
||||
# 使用 uv (推荐)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
# 或使用 pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
|
||||
pip install "lightrag-hku[api]"
|
||||
cp env.example .env
|
||||
lightrag-server
|
||||
```
|
||||
|
|
@ -116,17 +103,9 @@ lightrag-server
|
|||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
|
||||
# 使用 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]"
|
||||
# 如有必要，创建Python虚拟环境
|
||||
# 以可开发（编辑）模式安装LightRAG服务器
|
||||
pip install -e ".[api]"
|
||||
|
||||
cp env.example .env # 使用你的LLM和Embedding模型访问参数更新.env文件
|
||||
|
||||
|
|
@ -157,19 +136,13 @@ docker compose up
|
|||
|
||||
```bash
|
||||
cd LightRAG
|
||||
# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
|
||||
uv sync
|
||||
source .venv/bin/activate # 激活虚拟环境 (Linux/macOS)
|
||||
# Windows 系统: .venv\Scripts\activate
|
||||
|
||||
# 或: pip install -e .
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
* 从PyPI安装
|
||||
|
||||
```bash
|
||||
uv pip install lightrag-hku
|
||||
# 或: pip install lightrag-hku
|
||||
pip install lightrag-hku
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
|
@ -221,10 +194,6 @@ python examples/lightrag_openai_demo.py
|
|||
|
||||
> ⚠️ **如果您希望将LightRAG集成到您的项目中，建议您使用LightRAG Server提供的REST API**。LightRAG Core通常用于嵌入式应用，或供希望进行研究与评估的学者使用。
|
||||
|
||||
### ⚠️ 重要：初始化要求
|
||||
|
||||
LightRAG 在使用前需要显式初始化。 创建 LightRAG 实例后，您必须调用 await rag.initialize_storages()，否则将出现错误。
|
||||
|
||||
### 一个简单程序
|
||||
|
||||
以下Python代码片段演示了如何初始化LightRAG、插入文本并进行查询：
|
||||
|
|
@ -234,6 +203,7 @@ import os
|
|||
import asyncio
|
||||
from lightrag import LightRAG, QueryParam
|
||||
from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed
|
||||
from lightrag.kg.shared_storage import initialize_pipeline_status
|
||||
from lightrag.utils import setup_logger
|
||||
|
||||
setup_logger("lightrag", level="INFO")
|
||||
|
|
@ -248,7 +218,9 @@ async def initialize_rag():
|
|||
embedding_func=openai_embed,
|
||||
llm_model_func=gpt_4o_mini_complete,
|
||||
)
|
||||
await rag.initialize_storages() return rag
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
return rag
|
||||
|
||||
async def main():
|
||||
try:
|
||||
|
|
@ -410,11 +382,6 @@ LightRAG 需要利用LLM和Embeding模型来完成文档索引和知识库查询
|
|||
* LightRAG还支持类OpenAI的聊天/嵌入API：
|
||||
|
||||
```python
|
||||
import os
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.openai import openai_complete_if_cache, openai_embed
|
||||
|
||||
async def llm_model_func(
|
||||
prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs
|
||||
) -> str:
|
||||
|
|
@ -428,9 +395,8 @@ async def llm_model_func(
|
|||
**kwargs
|
||||
)
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=4096, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await openai_embed.func(
|
||||
return await openai_embed(
|
||||
texts,
|
||||
model="solar-embedding-1-large-query",
|
||||
api_key=os.getenv("UPSTAGE_API_KEY"),
|
||||
|
|
@ -441,17 +407,18 @@ async def initialize_rag():
|
|||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=llm_model_func,
|
||||
embedding_func=embedding_func # 直接传入装饰后的函数
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=4096,
|
||||
func=embedding_func
|
||||
)
|
||||
)
|
||||
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
```
|
||||
|
||||
> **关于嵌入函数封装的重要说明：**
|
||||
>
|
||||
> `EmbeddingFunc` 不能嵌套封装。已经被 `@wrap_embedding_func_with_attrs` 装饰过的嵌入函数（如 `openai_embed`、`ollama_embed` 等）不能再次使用 `EmbeddingFunc()` 封装。这就是为什么在创建自定义嵌入函数时，我们调用 `xxx_embed.func`（底层未封装的函数）而不是直接调用 `xxx_embed`。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
|
@ -488,20 +455,19 @@ rag = LightRAG(
|
|||
然后您只需要按如下方式设置LightRAG：
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.ollama import ollama_model_complete, ollama_embed
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await ollama_embed.func(texts, embed_model="nomic-embed-text")
|
||||
|
||||
# 使用Ollama模型初始化LightRAG
|
||||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=ollama_model_complete, # 使用Ollama模型进行文本生成
|
||||
llm_model_name='your_model_name', # 您的模型名称
|
||||
embedding_func=embedding_func, # 直接传入装饰后的函数
|
||||
# 使用Ollama嵌入函数
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=768,
|
||||
func=lambda texts: ollama_embed(
|
||||
texts,
|
||||
embed_model="nomic-embed-text"
|
||||
)
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
|
|
@ -540,27 +506,22 @@ ollama create -f Modelfile qwen2m
|
|||
您可以使用`llm_model_kwargs`参数配置ollama：
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.ollama import ollama_model_complete, ollama_embed
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await ollama_embed.func(texts, embed_model="nomic-embed-text")
|
||||
|
||||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=ollama_model_complete, # 使用Ollama模型进行文本生成
|
||||
llm_model_name='your_model_name', # 您的模型名称
|
||||
llm_model_kwargs={"options": {"num_ctx": 32768}},
|
||||
embedding_func=embedding_func, # 直接传入装饰后的函数
|
||||
# 使用Ollama嵌入函数
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=768,
|
||||
func=lambda texts: ollama_embed(
|
||||
texts,
|
||||
embed_model="nomic-embed-text"
|
||||
)
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
> **关于嵌入函数封装的重要说明：**
|
||||
>
|
||||
> `EmbeddingFunc` 不能嵌套封装。已经被 `@wrap_embedding_func_with_attrs` 装饰过的嵌入函数（如 `openai_embed`、`ollama_embed` 等）不能再次使用 `EmbeddingFunc()` 封装。这就是为什么在创建自定义嵌入函数时，我们调用 `xxx_embed.func`（底层未封装的函数）而不是直接调用 `xxx_embed`。
|
||||
|
||||
* **低RAM GPU**
|
||||
|
||||
为了在低RAM GPU上运行此实验，您应该选择小型模型并调整上下文窗口（增加上下文会增加内存消耗）。例如，在6Gb RAM的改装挖矿GPU上运行这个ollama示例需要将上下文大小设置为26k，同时使用`gemma2:2b`。它能够在`book.txt`中找到197个实体和19个关系。
|
||||
|
|
@ -583,6 +544,7 @@ from lightrag import LightRAG
|
|||
from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed
|
||||
from llama_index.embeddings.openai import OpenAIEmbedding
|
||||
from llama_index.llms.openai import OpenAI
|
||||
from lightrag.kg.shared_storage import initialize_pipeline_status
|
||||
from lightrag.utils import setup_logger
|
||||
|
||||
# 为LightRAG设置日志处理程序
|
||||
|
|
@ -599,6 +561,8 @@ async def initialize_rag():
|
|||
)
|
||||
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
|
||||
def main():
|
||||
|
|
@ -848,6 +812,8 @@ async def initialize_rag():
|
|||
# 初始化数据库连接
|
||||
await rag.initialize_storages()
|
||||
# 初始化文档处理的管道状态
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
```
|
||||
|
||||
|
|
@ -897,8 +863,8 @@ rag = LightRAG(
|
|||
|
||||
对于生产级场景，您很可能想要利用企业级解决方案。PostgreSQL可以为您提供一站式储解解决方案，作为KV存储、向量数据库（pgvector）和图数据库（apache AGE）。支持 PostgreSQL 版本为16.6或以上。
|
||||
|
||||
* 如果您是初学者并想避免麻烦，推荐使用docker，请从这个镜像开始（默认帐号密码:rag/rag）：https://hub.docker.com/r/gzdaniel/postgres-for-rag
|
||||
* Apache AGE的性能不如Neo4j。追求高性能的图数据库请使用Noe4j。
|
||||
* 如果您是初学者并想避免麻烦，推荐使用docker，请从这个镜像开始（请务必阅读概述）：https://hub.docker.com/r/shangor/postgres-for-rag
|
||||
* Apache AGE的性能不如Neo4j。最求高性能的图数据库请使用Noe4j。
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -1493,54 +1459,6 @@ 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)。
|
||||
|
||||
## 评估
|
||||
|
||||
### 数据集
|
||||
|
|
|
|||
181
README.md
181
README.md
|
|
@ -51,17 +51,13 @@
|
|||
|
||||
---
|
||||
## 🎉 News
|
||||
- [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.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).
|
||||
|
|
@ -88,11 +84,6 @@
|
|||
|
||||
## 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
|
||||
|
|
@ -102,11 +93,7 @@ The LightRAG Server is designed to provide Web UI and API support. The Web UI fa
|
|||
* Install from PyPI
|
||||
|
||||
```bash
|
||||
# Using uv (recommended)
|
||||
uv pip install "lightrag-hku[api]"
|
||||
# Or using pip
|
||||
# pip install "lightrag-hku[api]"
|
||||
|
||||
pip install "lightrag-hku[api]"
|
||||
cp env.example .env
|
||||
lightrag-server
|
||||
```
|
||||
|
|
@ -116,17 +103,9 @@ lightrag-server
|
|||
```bash
|
||||
git clone https://github.com/HKUDS/LightRAG.git
|
||||
cd LightRAG
|
||||
|
||||
# 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]"
|
||||
# Create a Python virtual enviroment if neccesary
|
||||
# Install in editable mode with API support
|
||||
pip install -e ".[api]"
|
||||
|
||||
cp env.example .env # Update the .env with your LLM and embedding configurations
|
||||
|
||||
|
|
@ -149,29 +128,21 @@ cp env.example .env # Update the .env with your LLM and embedding configuration
|
|||
docker compose up
|
||||
```
|
||||
|
||||
> Tip: 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`). The server now understands this binding out of the box.
|
||||
|
||||
> Historical versions of LightRAG docker images can be found here: [LightRAG Docker Images]( https://github.com/HKUDS/LightRAG/pkgs/container/lightrag)
|
||||
|
||||
### Install LightRAG Core
|
||||
|
||||
* Install from source (Recommended)
|
||||
* Install from source (Recommend)
|
||||
|
||||
```bash
|
||||
cd LightRAG
|
||||
# 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 .
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
* Install from PyPI
|
||||
|
||||
```bash
|
||||
uv pip install lightrag-hku
|
||||
# Or: pip install lightrag-hku
|
||||
pip install lightrag-hku
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
|
@ -225,7 +196,10 @@ For a streaming response implementation example, please see `examples/lightrag_o
|
|||
|
||||
### ⚠️ Important: Initialization Requirements
|
||||
|
||||
**LightRAG requires explicit initialization before use.** You must call `await rag.initialize_storages()` after creating a LightRAG instance, otherwise you will encounter errors.
|
||||
**LightRAG requires explicit initialization before use.** You must call both `await rag.initialize_storages()` and `await initialize_pipeline_status()` after creating a LightRAG instance, otherwise you will encounter errors like:
|
||||
|
||||
- `AttributeError: __aenter__` - if storages are not initialized
|
||||
- `KeyError: 'history_messages'` - if pipeline status is not initialized
|
||||
|
||||
### A Simple Program
|
||||
|
||||
|
|
@ -236,6 +210,7 @@ import os
|
|||
import asyncio
|
||||
from lightrag import LightRAG, QueryParam
|
||||
from lightrag.llm.openai import gpt_4o_mini_complete, gpt_4o_complete, openai_embed
|
||||
from lightrag.kg.shared_storage import initialize_pipeline_status
|
||||
from lightrag.utils import setup_logger
|
||||
|
||||
setup_logger("lightrag", level="INFO")
|
||||
|
|
@ -251,7 +226,9 @@ async def initialize_rag():
|
|||
llm_model_func=gpt_4o_mini_complete,
|
||||
)
|
||||
# IMPORTANT: Both initialization calls are required!
|
||||
await rag.initialize_storages() # Initialize storage backends return rag
|
||||
await rag.initialize_storages() # Initialize storage backends
|
||||
await initialize_pipeline_status() # Initialize processing pipeline
|
||||
return rag
|
||||
|
||||
async def main():
|
||||
try:
|
||||
|
|
@ -408,11 +385,6 @@ LightRAG requires the utilization of LLM and Embedding models to accomplish docu
|
|||
* LightRAG also supports Open AI-like chat/embeddings APIs:
|
||||
|
||||
```python
|
||||
import os
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.openai import openai_complete_if_cache, openai_embed
|
||||
|
||||
async def llm_model_func(
|
||||
prompt, system_prompt=None, history_messages=[], keyword_extraction=False, **kwargs
|
||||
) -> str:
|
||||
|
|
@ -426,9 +398,8 @@ async def llm_model_func(
|
|||
**kwargs
|
||||
)
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=4096, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await openai_embed.func(
|
||||
return await openai_embed(
|
||||
texts,
|
||||
model="solar-embedding-1-large-query",
|
||||
api_key=os.getenv("UPSTAGE_API_KEY"),
|
||||
|
|
@ -439,17 +410,18 @@ async def initialize_rag():
|
|||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=llm_model_func,
|
||||
embedding_func=embedding_func # Pass the decorated function directly
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=4096,
|
||||
func=embedding_func
|
||||
)
|
||||
)
|
||||
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
```
|
||||
|
||||
> **Important Note on Embedding Function Wrapping:**
|
||||
>
|
||||
> `EmbeddingFunc` cannot be nested. Functions that have been decorated with `@wrap_embedding_func_with_attrs` (such as `openai_embed`, `ollama_embed`, etc.) cannot be wrapped again using `EmbeddingFunc()`. This is why we call `xxx_embed.func` (the underlying unwrapped function) instead of `xxx_embed` directly when creating custom embedding functions.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
|
@ -488,20 +460,19 @@ If you want to use Ollama models, you need to pull model you plan to use and emb
|
|||
Then you only need to set LightRAG as follows:
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.ollama import ollama_model_complete, ollama_embed
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await ollama_embed.func(texts, embed_model="nomic-embed-text")
|
||||
|
||||
# Initialize LightRAG with Ollama model
|
||||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=ollama_model_complete, # Use Ollama model for text generation
|
||||
llm_model_name='your_model_name', # Your model name
|
||||
embedding_func=embedding_func, # Pass the decorated function directly
|
||||
# Use Ollama embedding function
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=768,
|
||||
func=lambda texts: ollama_embed(
|
||||
texts,
|
||||
embed_model="nomic-embed-text"
|
||||
)
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
|
|
@ -540,27 +511,22 @@ ollama create -f Modelfile qwen2m
|
|||
Tiy can use `llm_model_kwargs` param to configure ollama:
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
from lightrag.utils import wrap_embedding_func_with_attrs
|
||||
from lightrag.llm.ollama import ollama_model_complete, ollama_embed
|
||||
|
||||
@wrap_embedding_func_with_attrs(embedding_dim=768, max_token_size=8192)
|
||||
async def embedding_func(texts: list[str]) -> np.ndarray:
|
||||
return await ollama_embed.func(texts, embed_model="nomic-embed-text")
|
||||
|
||||
rag = LightRAG(
|
||||
working_dir=WORKING_DIR,
|
||||
llm_model_func=ollama_model_complete, # Use Ollama model for text generation
|
||||
llm_model_name='your_model_name', # Your model name
|
||||
llm_model_kwargs={"options": {"num_ctx": 32768}},
|
||||
embedding_func=embedding_func, # Pass the decorated function directly
|
||||
# Use Ollama embedding function
|
||||
embedding_func=EmbeddingFunc(
|
||||
embedding_dim=768,
|
||||
func=lambda texts: ollama_embed(
|
||||
texts,
|
||||
embed_model="nomic-embed-text"
|
||||
)
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
> **Important Note on Embedding Function Wrapping:**
|
||||
>
|
||||
> `EmbeddingFunc` cannot be nested. Functions that have been decorated with `@wrap_embedding_func_with_attrs` (such as `openai_embed`, `ollama_embed`, etc.) cannot be wrapped again using `EmbeddingFunc()`. This is why we call `xxx_embed.func` (the underlying unwrapped function) instead of `xxx_embed` directly when creating custom embedding functions.
|
||||
|
||||
* **Low RAM GPUs**
|
||||
|
||||
In order to run this experiment on low RAM GPU you should select small model and tune context window (increasing context increase memory consumption). For example, running this ollama example on repurposed mining GPU with 6Gb of RAM required to set context size to 26k while using `gemma2:2b`. It was able to find 197 entities and 19 relations on `book.txt`.
|
||||
|
|
@ -583,6 +549,7 @@ from lightrag import LightRAG
|
|||
from lightrag.llm.llama_index_impl import llama_index_complete_if_cache, llama_index_embed
|
||||
from llama_index.embeddings.openai import OpenAIEmbedding
|
||||
from llama_index.llms.openai import OpenAI
|
||||
from lightrag.kg.shared_storage import initialize_pipeline_status
|
||||
from lightrag.utils import setup_logger
|
||||
|
||||
# Setup log handler for LightRAG
|
||||
|
|
@ -599,6 +566,8 @@ async def initialize_rag():
|
|||
)
|
||||
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
|
||||
def main():
|
||||
|
|
@ -850,6 +819,8 @@ async def initialize_rag():
|
|||
# Initialize database connections
|
||||
await rag.initialize_storages()
|
||||
# Initialize pipeline status for document processing
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
```
|
||||
|
||||
|
|
@ -863,7 +834,7 @@ see test_neo4j.py for a working example.
|
|||
For production level scenarios you will most likely want to leverage an enterprise solution. PostgreSQL can provide a one-stop solution for you as KV store, VectorDB (pgvector) and GraphDB (apache AGE). PostgreSQL version 16.6 or higher is supported.
|
||||
|
||||
* PostgreSQL is lightweight,the whole binary distribution including all necessary plugins can be zipped to 40MB: Ref to [Windows Release](https://github.com/ShanGor/apache-age-windows/releases/tag/PG17%2Fv1.5.0-rc0) as it is easy to install for Linux/Mac.
|
||||
* If you prefer docker, please start with this image if you are a beginner to avoid hiccups (Default user password:rag/rag): https://hub.docker.com/r/gzdaniel/postgres-for-rag
|
||||
* If you prefer docker, please start with this image if you are a beginner to avoid hiccups (DO read the overview): https://hub.docker.com/r/shangor/postgres-for-rag
|
||||
* How to start? Ref to: [examples/lightrag_zhipu_postgres_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_zhipu_postgres_demo.py)
|
||||
* For high-performance graph database requirements, Neo4j is recommended as Apache AGE's performance is not as competitive.
|
||||
|
||||
|
|
@ -934,6 +905,8 @@ async def initialize_rag():
|
|||
# Initialize database connections
|
||||
await rag.initialize_storages()
|
||||
# Initialize pipeline status for document processing
|
||||
await initialize_pipeline_status()
|
||||
|
||||
return rag
|
||||
```
|
||||
|
||||
|
|
@ -968,8 +941,7 @@ maxclients 500
|
|||
The `workspace` parameter ensures data isolation between different LightRAG instances. Once initialized, the `workspace` is immutable and cannot be changed.Here is how workspaces are implemented for different types of storage:
|
||||
|
||||
- **For local file-based databases, data isolation is achieved through workspace subdirectories:** `JsonKVStorage`, `JsonDocStatusStorage`, `NetworkXStorage`, `NanoVectorDBStorage`, `FaissVectorDBStorage`.
|
||||
- **For databases that store data in collections, it's done by adding a workspace prefix to the collection name:** `RedisKVStorage`, `RedisDocStatusStorage`, `MilvusVectorDBStorage`, `MongoKVStorage`, `MongoDocStatusStorage`, `MongoVectorDBStorage`, `MongoGraphStorage`, `PGGraphStorage`.
|
||||
- **For Qdrant vector database, data isolation is achieved through payload-based partitioning (Qdrant's recommended multitenancy approach):** `QdrantVectorDBStorage` uses shared collections with payload filtering for unlimited workspace scalability.
|
||||
- **For databases that store data in collections, it's done by adding a workspace prefix to the collection name:** `RedisKVStorage`, `RedisDocStatusStorage`, `MilvusVectorDBStorage`, `QdrantVectorDBStorage`, `MongoKVStorage`, `MongoDocStatusStorage`, `MongoVectorDBStorage`, `MongoGraphStorage`, `PGGraphStorage`.
|
||||
- **For relational databases, data isolation is achieved by adding a `workspace` field to the tables for logical data separation:** `PGKVStorage`, `PGVectorStorage`, `PGDocStatusStorage`.
|
||||
- **For the Neo4j graph database, logical data isolation is achieved through labels:** `Neo4JStorage`
|
||||
|
||||
|
|
@ -1541,13 +1513,16 @@ If you encounter these errors when using LightRAG:
|
|||
|
||||
2. **`KeyError: 'history_messages'`**
|
||||
- **Cause**: Pipeline status not initialized
|
||||
- **Solution**: Call `
|
||||
- **Solution**: Call `await initialize_pipeline_status()` after initializing storages
|
||||
|
||||
3. **Both errors in sequence**
|
||||
- **Cause**: Neither initialization method was called
|
||||
- **Solution**: Always follow this pattern:
|
||||
```python
|
||||
rag = LightRAG(...)
|
||||
await rag.initialize_storages() ```
|
||||
await rag.initialize_storages()
|
||||
await initialize_pipeline_status()
|
||||
```
|
||||
|
||||
### Model Switching Issues
|
||||
|
||||
|
|
@ -1563,54 +1538,6 @@ 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue