Merge branch 'main' into add-Memgraph-graph-db

README-zh.md

@@ -90,6 +90,8 @@ LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知
 
 ```bash
 pip install "lightrag-hku[api]"
+cp env.example .env
+lightrag-server
 ```
 
 * 从源代码安装
@@ -100,6 +102,8 @@ cd LightRAG
 # 如有必要，创建Python虚拟环境
 # 以可编辑模式安装并支持API
 pip install -e ".[api]"
+cp env.example .env
+lightrag-server
 ```
 
 * 使用 Docker Compose 启动 LightRAG 服务器

README.md

@@ -89,6 +89,8 @@ The LightRAG Server is designed to provide Web UI and API support. The Web UI fa
 
 ```bash
 pip install "lightrag-hku[api]"
+cp env.example .env
+lightrag-server
 ```
 
 * Installation from Source
@@ -99,6 +101,8 @@ cd LightRAG
 # create a Python virtual enviroment if neccesary
 # Install in editable mode with API support
 pip install -e ".[api]"
+cp env.example .env
+lightrag-server
 ```
 
 * Launching the LightRAG Server with Docker Compose

env.example

@@ -1,6 +1,5 @@
 ### This is sample file of .env
 
-
 ### Server Configuration
 HOST=0.0.0.0
 PORT=9621
@@ -51,7 +50,7 @@ OLLAMA_EMULATING_MODEL_TAG=latest
 # MAX_TOKEN_RELATION_DESC=4000
 # MAX_TOKEN_ENTITY_DESC=4000
 
-### Entity and ralation summarization configuration
+### Entity and relation summarization configuration
 ### Language: English, Chinese, French, German ...
 SUMMARY_LANGUAGE=English
 ### Number of duplicated entities/edges to trigger LLM re-summary on merge ( at least 3 is recommented)
@@ -111,7 +110,7 @@ EMBEDDING_BINDING_HOST=http://localhost:11434
 ###########################
 ### Data storage selection
 ###########################
-### In-memory database with data persistence to local files
+### In-memory database with local file persistence(Recommended for small scale deployment)
 # LIGHTRAG_KV_STORAGE=JsonKVStorage
 # LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage
 # LIGHTRAG_GRAPH_STORAGE=NetworkXStorage
@@ -122,18 +121,18 @@ EMBEDDING_BINDING_HOST=http://localhost:11434
 # LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
 # LIGHTRAG_GRAPH_STORAGE=PGGraphStorage
 # LIGHTRAG_VECTOR_STORAGE=PGVectorStorage
-### MongoDB (recommended for production deploy)
+### MongoDB (Vector storage only available on Atlas Cloud)
 # LIGHTRAG_KV_STORAGE=MongoKVStorage
 # LIGHTRAG_DOC_STATUS_STORAGE=MongoDocStatusStorage
 # LIGHTRAG_GRAPH_STORAGE=MongoGraphStorage
 # LIGHTRAG_VECTOR_STORAGE=MongoVectorDBStorage
-### Redis Storage (recommended for production deploy)
+### Redis Storage (Recommended for production deployment)
 # LIGHTRAG_KV_STORAGE=RedisKVStorage
 # LIGHTRAG_DOC_STATUS_STORAGE=RedisDocStatusStorage
-### Vector Storage (recommended for production deploy)
+### Vector Storage (Recommended for production deployment)
 # LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage
 # LIGHTRAG_VECTOR_STORAGE=QdrantVectorDBStorage
-### Graph Storage (recommended for production deploy)
+### Graph Storage (Recommended for production deployment)
 # LIGHTRAG_GRAPH_STORAGE=Neo4JStorage
 
 ####################################################################

lightrag/api/README-zh.md

@@ -43,7 +43,7 @@ LightRAG 需要同时集成 LLM（大型语言模型）和嵌入模型以有效
 
 建议使用环境变量来配置 LightRAG 服务器。项目根目录中有一个名为 `env.example` 的示例环境变量文件。请将此文件复制到启动目录并重命名为 `.env`。之后，您可以在 `.env` 文件中修改与 LLM 和嵌入模型相关的参数。需要注意的是，LightRAG 服务器每次启动时都会将 `.env` 中的环境变量加载到系统环境变量中。**LightRAG 服务器会优先使用系统环境变量中的设置**。
 
->  由于安装了 Python 扩展的 VS Code 可能会在集成终端中自动加载 .env 文件，请在每次修改 .env 文件后打开新的终端会话。
+> 由于安装了 Python 扩展的 VS Code 可能会在集成终端中自动加载 .env 文件，请在每次修改 .env 文件后打开新的终端会话。
 
 以下是 LLM 和嵌入模型的一些常见设置示例：
 
@@ -94,49 +94,23 @@ lightrag-server
 ```
 lightrag-gunicorn --workers 4
 ```
-`.env` 文件必须放在启动目录中。启动时，LightRAG 服务器将创建一个文档目录（默认为 `./inputs`）和一个数据目录（默认为 `./rag_storage`）。这允许您从不同目录启动多个 LightRAG 服务器实例，每个实例配置为监听不同的网络端口。
+启动LightRAG的时候，当前工作目录必须含有`.env`配置文件。**要求将.env文件置于启动目录中是经过特意设计的**。 这样做的目的是支持用户同时启动多个LightRAG实例，并为不同实例配置不同的.env文件。**修改.env文件后，您需要重新打开终端以使新设置生效**。 这是因为每次启动时，LightRAG Server会将.env文件中的环境变量加载至系统环境变量，且系统环境变量的设置具有更高优先级。
 
-以下是一些常用的启动参数：
+启动时可以通过命令行参数覆盖`.env`文件中的配置。常用的命令行参数包括：
 
 - `--host`：服务器监听地址（默认：0.0.0.0）
 - `--port`：服务器监听端口（默认：9621）
 - `--timeout`：LLM 请求超时时间（默认：150 秒）
 - `--log-level`：日志级别（默认：INFO）
-- --input-dir：指定要扫描文档的目录（默认：./input）
-
-> - **要求将.env文件置于启动目录中是经过特意设计的**。 这样做的目的是支持用户同时启动多个LightRAG实例，并为不同实例配置不同的.env文件。
-> - **修改.env文件后，您需要重新打开终端以使新设置生效**。 这是因为每次启动时，LightRAG Server会将.env文件中的环境变量加载至系统环境变量，且系统环境变量的设置具有更高优先级。
+- `--working-dir`：数据库持久化目录（默认：./rag_storage）
+- `--input-dir`：上传文件存放目录（默认：./inputs）
+- `--workspace`: 工作空间名称，用于逻辑上隔离多个LightRAG实例之间的数据（默认：空）
 
 ### 使用 Docker 启动 LightRAG 服务器
 
-* 克隆代码仓库：
-```shell
-git clone https://github.com/HKUDS/LightRAG.git
-cd LightRAG
-```
-
 * 配置 .env 文件：
     通过复制示例文件 [`env.example`](env.example) 创建个性化的 .env 文件，并根据实际需求设置 LLM 及 Embedding 参数。
-
-* 通过以下命令启动 LightRAG 服务器：
-```shell
-docker compose up
-# 如拉取了新版本，请添加 --build 重新构建
-docker compose up --build
-```
-### 无需克隆代码而使用 Docker 部署 LightRAG 服务器
-
-* 为 LightRAG 服务器创建工作文件夹：
-
-```shell
-mkdir lightrag
-cd lightrag
-```
-
-* 准备 .env 文件：
-    通过复制 env.example 文件创建个性化的.env 文件。根据您的需求配置 LLM 和嵌入参数。
-
-* 创建一个名为 docker-compose.yml 的 docker compose 文件：
+* 创建一个名为 docker-compose.yml 的文件：
 
 ```yaml
 services:
@@ -157,26 +131,56 @@ services:
       - "host.docker.internal:host-gateway"
 ```
 
-* 准备 .env 文件：
-    通过复制示例文件 [`env.example`](env.example) 创建个性化的 .env 文件。根据您的需求配置 LLM 和嵌入参数。
+* 通过以下命令启动 LightRAG 服务器：
 
-* 使用以下命令启动 LightRAG 服务器：
 ```shell
 docker compose up
+# 如果希望启动后让程序退到后台运行，需要在命令的最后添加 -d 参数
 ```
-
-> 在此获取LightRAG docker镜像历史版本: [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)
 
 ### 启动时自动扫描
 
-当使用 `--auto-scan-at-startup` 参数启动任何服务器时，系统将自动：
+当使用 `--auto-scan-at-startup` 参数启动LightRAG Server时，系统将自动：
 
 1. 扫描输入目录中的新文件
 2. 为尚未在数据库中的新文档建立索引
 3. 使所有内容立即可用于 RAG 查询
 
+这种工作模式给启动一个临时的RAG任务提供给了方便。
+
 > `--input-dir` 参数指定要扫描的输入目录。您可以从 webui 触发输入目录扫描。
 
+### 启动多个LightRAG实例
+
+有两种方式可以启动多个LightRAG实例。第一种方式是为每个实例配置一个完全独立的工作环境。此时需要为每个实例创建一个独立的工作目录，然后在这个工作目录上放置一个当前实例专用的`.env`配置文件。不同实例的配置文件中的服务器监听端口不能重复，然后在工作目录上执行 lightrag-server 启动服务即可。
+
+第二种方式是所有实例共享一套相同的`.env`配置文件，然后通过命令行参数来为每个实例指定不同的服务器监听端口和工作空间。你可以在同一个工作目录中通过不同的命令行参数启动多个LightRAG实例。例如：
+
+```
+# 启动实例1
+lightrag-server --port 9621 --workspace space1
+
+# 启动实例2
+lightrag-server --port 9622 --workspace space2
+```
+
+工作空间的作用是实现不同实例之间的数据隔离。因此不同实例之间的`workspace`参数必须不同，否则会导致数据混乱，数据将会被破坏。
+
+### LightRAG实例间的数据隔离
+
+每个实例配置一个独立的工作目录和专用`.env`配置文件通常能够保证内存数据库中的本地持久化文件保存在各自的工作目录，实现数据的相互隔离。LightRAG默认存储全部都是内存数据库，通过这种方式进行数据隔离是没有问题的。但是如果使用的是外部数据库，如果不同实例访问的是同一个数据库实例，就需要通过配置工作空间来实现数据隔离，否则不同实例的数据将会出现冲突并被破坏。
+
+命令行的 workspace 参数和`.env`文件中的环境变量`WORKSPACE` 都可以用于指定当前实例的工作空间名字，命令行参数的优先级别更高。下面是不同类型的存储实现工作空间的方式：
+
+- **对于本地基于文件的数据库，数据隔离通过工作空间子目录实现：** JsonKVStorage, JsonDocStatusStorage, NetworkXStorage, NanoVectorDBStorage, FaissVectorDBStorage。
+- **对于将数据存储在集合（collection）中的数据库，通过在集合名称前添加工作空间前缀来实现：** RedisKVStorage, RedisDocStatusStorage, MilvusVectorDBStorage, QdrantVectorDBStorage, MongoKVStorage, MongoDocStatusStorage, MongoVectorDBStorage, MongoGraphStorage, PGGraphStorage。
+- **对于关系型数据库，数据隔离通过向表中添加 `workspace` 字段进行数据的逻辑隔离：** PGKVStorage, PGVectorStorage, PGDocStatusStorage。
+
+* **对于Neo4j图数据库，通过label来实现数据的逻辑隔离**：Neo4JStorage
+
+为了保持对遗留数据的兼容，在未配置工作空间时PostgreSQL的默认工作空间为`default`，Neo4j的默认工作空间为`base`。对于所有的外部存储，系统都提供了专用的工作空间环境变量，用于覆盖公共的 `WORKSPACE`环境变量配置。这些适用于指定存储类型的工作空间环境变量为：`REDIS_WORKSPACE`, `MILVUS_WORKSPACE`, `QDRANT_WORKSPACE`, `MONGODB_WORKSPACE`, `POSTGRES_WORKSPACE`, `NEO4J_WORKSPACE`。
+
 ### Gunicorn + Uvicorn 的多工作进程
 
 LightRAG 服务器可以在 `Gunicorn + Uvicorn` 预加载模式下运行。Gunicorn 的多工作进程（多进程）功能可以防止文档索引任务阻塞 RAG 查询。使用 CPU 密集型文档提取工具（如 docling）在纯 Uvicorn 模式下可能会导致整个系统被阻塞。

lightrag/api/README.md

@@ -94,50 +94,25 @@ lightrag-server
 ```
 lightrag-gunicorn --workers 4
 ```
-The `.env` file **must be placed in the startup directory**.
 
-Upon launching, the LightRAG Server will create a documents directory (default is `./inputs`) and a data directory (default is `./rag_storage`). This allows you to initiate multiple instances of LightRAG Server from different directories, with each instance configured to listen on a distinct network port.
+When starting LightRAG, the current working directory must contain the `.env` configuration file. **It is intentionally designed that the `.env` file must be placed in the startup directory**. The purpose of this is to allow users to launch multiple LightRAG instances simultaneously and configure different `.env` files for different instances. **After modifying the `.env` file, you need to reopen the terminal for the new settings to take effect.** This is because each time LightRAG Server starts, it loads the environment variables from the `.env` file into the system environment variables, and system environment variables have higher precedence.
 
-Here are some commonly used startup parameters:
+During startup, configurations in the `.env` file can be overridden by command-line parameters. Common command-line parameters include:
 
 - `--host`: Server listening address (default: 0.0.0.0)
 - `--port`: Server listening port (default: 9621)
 - `--timeout`: LLM request timeout (default: 150 seconds)
-- `--log-level`: Logging level (default: INFO)
-- `--input-dir`: Specifying the directory to scan for documents (default: ./inputs)
-
-> - The requirement for the .env file to be in the startup directory is intentionally designed this way. The purpose is to support users in launching multiple LightRAG instances simultaneously, allowing different .env files for different instances.
-> - **After changing the .env file, you need to open a new terminal to make  the new settings take effect.** This because the LightRAG Server will load the environment variables from .env into the system environment variables each time it starts, and LightRAG Server will prioritize the settings in the system environment variables.
+- `--log-level`: Log level (default: INFO)
+- `--working-dir`: Database persistence directory (default: ./rag_storage)
+- `--input-dir`: Directory for uploaded files (default: ./inputs)
+- `--workspace`: Workspace name, used to logically isolate data between multiple LightRAG instances (default: empty)
 
 ### Launching LightRAG Server with Docker
 
-* Clone the repository:
-```shell
-git clone https://github.com/HKUDS/LightRAG.git
-cd LightRAG
-```
-
 * Prepare the .env file:
-    Create a personalized .env file from sample file `env.example`. Configure the LLM and embedding parameters according to your requirements.
-
-* Start the LightRAG Server using the following commands:
-```shell
-docker compose up
-# Use --build if you have pulled a new version
-docker compose up --build
-```
-
-### Deploying LightRAG Server with docker without cloneing the repository
-
-* Create a working folder for LightRAG Server:
-
-```shell
-mkdir lightrag
-cd lightrag
-```
-
-* Create a docker compose file named docker-compose.yml:
+    Create a personalized .env file by copying the sample file [`env.example`](env.example). Configure the LLM and embedding parameters according to your requirements.
 
+* Create a file named `docker-compose.yml`:
 
 ```yaml
 services:
@@ -157,26 +132,57 @@ services:
     extra_hosts:
       - "host.docker.internal:host-gateway"
 ```
-* Prepare the .env file:
-    Create a personalized .env file from sample file `env.example`. Configure the LLM and embedding parameters according to your requirements.
 
-* Start the LightRAG Server using the following commands:
+* Start the LightRAG Server with the following command:
+
 ```shell
 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.
 ```
 
-> Historical versions of LightRAG docker images can be found here: [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)
 
 ### Auto scan on startup
 
-When starting any of the servers with the `--auto-scan-at-startup` parameter, the system will automatically:
+When starting the LightRAG 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 that aren't already in the database
 3. Make all content immediately available for RAG queries
 
+This offers an efficient method for deploying ad-hoc RAG processes.
+
 > The `--input-dir` parameter specifies the input directory to scan. You can trigger the input directory scan from the Web UI.
 
+### Starting Multiple LightRAG Instances
+
+There are two ways to start multiple LightRAG instances. The first way is to configure a completely independent working environment for each instance. This requires creating a separate working directory for each instance and placing a dedicated `.env` configuration file in that directory. The server listening ports in the configuration files of different instances cannot be the same. Then, you can start the service by running `lightrag-server` in the working directory.
+
+The second way is for all instances to share the same set of `.env` configuration files, and then use command-line arguments to specify different server listening ports and workspaces for each instance. You can start multiple LightRAG instances in the same working directory with different command-line arguments. For example:
+
+```
+# Start instance 1
+lightrag-server --port 9621 --workspace space1
+
+# Start instance 2
+lightrag-server --port 9622 --workspace space2
+```
+
+The purpose of a workspace is to achieve data isolation between different instances. Therefore, the `workspace` parameter must be different for different instances; otherwise, it will lead to data confusion and corruption.
+
+### Data Isolation Between LightRAG Instances
+
+Configuring an independent working directory and a dedicated `.env` configuration file for each instance can generally ensure that locally persisted files in the in-memory database are saved in their respective working directories, achieving data isolation. By default, LightRAG uses all in-memory databases, and this method of data isolation is sufficient. However, if you are using an external database, and different instances access the same database instance, you need to use workspaces to achieve data isolation; otherwise, the data of different instances will conflict and be destroyed.
+
+The command-line `workspace` argument and the `WORKSPACE` environment variable in the `.env` file can both be used to specify the workspace name for the current instance, with the command-line argument having higher priority. 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`, `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`
+
+To maintain compatibility with legacy data, the default workspace for PostgreSQL is `default` and for Neo4j is `base` when no workspace is configured. For all external storages, the system provides dedicated workspace environment variables to override the common `WORKSPACE` environment variable configuration. These storage-specific workspace environment variables are: `REDIS_WORKSPACE`, `MILVUS_WORKSPACE`, `QDRANT_WORKSPACE`, `MONGODB_WORKSPACE`, `POSTGRES_WORKSPACE`, `NEO4J_WORKSPACE`.
+
 ### Multiple workers for Gunicorn + Uvicorn
 
 The LightRAG Server can operate in the `Gunicorn + Uvicorn` preload mode. Gunicorn's multiple worker (multiprocess) capability prevents document indexing tasks from blocking RAG queries. Using CPU-exhaustive document extraction tools, such as docling, can lead to the entire system being blocked in pure Uvicorn mode.

lightrag/api/__init__.py

@@ -1 +1 @@
-__api_version__ = "0179"
+__api_version__ = "0180"

lightrag/api/config.py

@@ -244,6 +244,9 @@ def parse_args() -> argparse.Namespace:
     # Get MAX_PARALLEL_INSERT from environment
     args.max_parallel_insert = get_env_value("MAX_PARALLEL_INSERT", 2, int)
 
+    # Get MAX_GRAPH_NODES from environment
+    args.max_graph_nodes = get_env_value("MAX_GRAPH_NODES", 1000, int)
+
     # Handle openai-ollama special case
     if args.llm_binding == "openai-ollama":
         args.llm_binding = "openai"

lightrag/api/lightrag_server.py

@@ -326,6 +326,7 @@ def create_app(args):
             enable_llm_cache=args.enable_llm_cache,
             auto_manage_storages_states=False,
             max_parallel_insert=args.max_parallel_insert,
+            max_graph_nodes=args.max_graph_nodes,
             addon_params={"language": args.summary_language},
         )
     else:  # azure_openai
@@ -353,6 +354,7 @@ def create_app(args):
             enable_llm_cache=args.enable_llm_cache,
             auto_manage_storages_states=False,
             max_parallel_insert=args.max_parallel_insert,
+            max_graph_nodes=args.max_graph_nodes,
             addon_params={"language": args.summary_language},
         )
 
@@ -475,7 +477,7 @@ def create_app(args):
                     "enable_llm_cache_for_extract": args.enable_llm_cache_for_extract,
                     "enable_llm_cache": args.enable_llm_cache,
                     "workspace": args.workspace,
-                    "max_graph_nodes": os.getenv("MAX_GRAPH_NODES"),
+                    "max_graph_nodes": args.max_graph_nodes,
                 },
                 "auth_mode": auth_mode,
                 "pipeline_busy": pipeline_status.get("busy", False),

lightrag/api/utils_api.py

@@ -175,12 +175,24 @@ def display_splash_screen(args: argparse.Namespace) -> None:
         args: Parsed command line arguments
     """
     # Banner
-    ASCIIColors.cyan(f"""
-    ╔══════════════════════════════════════════════════════════════╗
-    ║                  🚀 LightRAG Server v{core_version}/{api_version}              ║
-    ║          Fast, Lightweight RAG Server Implementation         ║
-    ╚══════════════════════════════════════════════════════════════╝
-    """)
+    # Banner
+    top_border = "╔══════════════════════════════════════════════════════════════╗"
+    bottom_border = "╚══════════════════════════════════════════════════════════════╝"
+    width = len(top_border) - 4  # width inside the borders
+
+    line1_text = f"LightRAG Server v{core_version}/{api_version}"
+    line2_text = "Fast, Lightweight RAG Server Implementation"
+
+    line1 = f"║ {line1_text.center(width)} ║"
+    line2 = f"║ {line2_text.center(width)} ║"
+
+    banner = f"""
+    {top_border}
+    {line1}
+    {line2}
+    {bottom_border}
+    """
+    ASCIIColors.cyan(banner)
 
     # Server Configuration
     ASCIIColors.magenta("\n📡 Server Configuration:")