Merge branch 'main' into optimize-config-management

# Conflicts: # env.example # lightrag/api/utils_api.py
2025-03-31 11:29:29 +08:00
parent 088fc19318 22a4e08439
commit 4dbd5e3899
32 changed files with 1416 additions and 543 deletions
--- a/lightrag/api/README-zh.md
+++ b/lightrag/api/README-zh.md
@@ -52,7 +52,8 @@ LLM_BINDING=openai
 LLM_MODEL=gpt-4o
 LLM_BINDING_HOST=https://api.openai.com/v1
 LLM_BINDING_API_KEY=your_api_key
-MAX_TOKENS=32768                # 发送给 LLM 的最大 token 数（小于模型上下文大小）
+### 发送给 LLM 的最大 token 数（小于模型上下文大小）
+MAX_TOKENS=32768

 EMBEDDING_BINDING=ollama
 EMBEDDING_BINDING_HOST=http://localhost:11434
@@ -68,7 +69,8 @@ LLM_BINDING=ollama
 LLM_MODEL=mistral-nemo:latest
 LLM_BINDING_HOST=http://localhost:11434
 # LLM_BINDING_API_KEY=your_api_key
-MAX_TOKENS=8192                  # 发送给 LLM 的最大 token 数（基于您的 Ollama 服务器容量）
+### 发送给 LLM 的最大 token 数（基于您的 Ollama 服务器容量）
+MAX_TOKENS=8192

 EMBEDDING_BINDING=ollama
 EMBEDDING_BINDING_HOST=http://localhost:11434
@@ -117,9 +119,12 @@ LightRAG 服务器可以在 `Gunicorn + Uvicorn` 预加载模式下运行。Guni
 虽然 LightRAG 服务器使用一个工作进程来处理文档索引流程，但通过 Uvicorn 的异步任务支持，可以并行处理多个文件。文档索引速度的瓶颈主要在于 LLM。如果您的 LLM 支持高并发，您可以通过增加 LLM 的并发级别来加速文档索引。以下是几个与并发处理相关的环境变量及其默认值：

 ```
-WORKERS=2                    # 工作进程数，不大于 (2 x 核心数) + 1
-MAX_PARALLEL_INSERT=2        # 一批中并行处理的文件数
-MAX_ASYNC=4                  # LLM 的最大并发请求数
+### 工作进程数，数字不大于 (2 x 核心数) + 1
+WORKERS=2
+### 一批中并行处理的文件数
+MAX_PARALLEL_INSERT=2
+# LLM 的最大并发请求数
+MAX_ASYNC=4
 ```

 ### 将 Lightrag 安装为 Linux 服务
@@ -201,10 +206,9 @@ LightRAG API 服务器使用基于 HS256 算法的 JWT 认证。要启用安全

 ```bash
 # JWT 认证
-AUTH_USERNAME=admin      # 登录名
-AUTH_PASSWORD=admin123   # 密码
-TOKEN_SECRET=your-key    # JWT 密钥
-TOKEN_EXPIRE_HOURS=4     # 过期时间
+AUTH_ACCOUNTS='admin:admin123,user1:pass456'
+TOKEN_SECRET='your-key'
+TOKEN_EXPIRE_HOURS=4
 ```

 > 目前仅支持配置一个管理员账户和密码。尚未开发和实现完整的账户系统。
@@ -238,8 +242,11 @@ LLM_BINDING=azure_openai
 LLM_BINDING_HOST=your-azure-endpoint
 LLM_MODEL=your-model-deployment-name
 LLM_BINDING_API_KEY=your-azure-api-key
-AZURE_OPENAI_API_VERSION=2024-08-01-preview  # 可选，默认为最新版本
-EMBEDDING_BINDING=azure_openai  # 如果使用 Azure OpenAI 进行嵌入
+### API Version可选，默认为最新版本
+AZURE_OPENAI_API_VERSION=2024-08-01-preview
+
+### 如果使用 Azure OpenAI 进行嵌入
+EMBEDDING_BINDING=azure_openai
 EMBEDDING_MODEL=your-embedding-deployment-name
 ```

@@ -362,7 +369,47 @@ LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
 | --embedding-binding | ollama | 嵌入绑定类型（lollms、ollama、openai、azure_openai） |
 | auto-scan-at-startup | - | 扫描输入目录中的新文件并开始索引 |

-### 使用示例
+### .env 文件示例
+
+```bash
+### Server Configuration
+# HOST=0.0.0.0
+PORT=9621
+WORKERS=2
+
+### Settings for document indexing
+ENABLE_LLM_CACHE_FOR_EXTRACT=true
+SUMMARY_LANGUAGE=Chinese
+MAX_PARALLEL_INSERT=2
+
+### LLM Configuration (Use valid host. For local services installed with docker, you can use host.docker.internal)
+TIMEOUT=200
+TEMPERATURE=0.0
+MAX_ASYNC=4
+MAX_TOKENS=32768
+
+LLM_BINDING=openai
+LLM_MODEL=gpt-4o-mini
+LLM_BINDING_HOST=https://api.openai.com/v1
+LLM_BINDING_API_KEY=your-api-key
+
+### Embedding Configuration (Use valid host. For local services installed with docker, you can use host.docker.internal)
+EMBEDDING_MODEL=bge-m3:latest
+EMBEDDING_DIM=1024
+EMBEDDING_BINDING=ollama
+EMBEDDING_BINDING_HOST=http://localhost:11434
+
+### For JWT Auth
+# AUTH_ACCOUNTS='admin:admin123,user1:pass456'
+# TOKEN_SECRET=your-key-for-LightRAG-API-Server-xxx
+# TOKEN_EXPIRE_HOURS=48
+
+# LIGHTRAG_API_KEY=your-secure-api-key-here-123
+# WHITELIST_PATHS=/api/*
+# WHITELIST_PATHS=/health,/api/*
+```
+
+

 #### 使用 ollama 默认本地服务器作为 llm 和嵌入后端运行 Lightrag 服务器

--- a/lightrag/api/README.md
+++ b/lightrag/api/README.md
@@ -52,7 +52,8 @@ LLM_BINDING=openai
 LLM_MODEL=gpt-4o
 LLM_BINDING_HOST=https://api.openai.com/v1
 LLM_BINDING_API_KEY=your_api_key
-MAX_TOKENS=32768                # Max tokens send to LLM (less than model context size)
+### Max tokens send to LLM (less than model context size)
+MAX_TOKENS=32768

 EMBEDDING_BINDING=ollama
 EMBEDDING_BINDING_HOST=http://localhost:11434
@@ -68,7 +69,8 @@ LLM_BINDING=ollama
 LLM_MODEL=mistral-nemo:latest
 LLM_BINDING_HOST=http://localhost:11434
 # LLM_BINDING_API_KEY=your_api_key
-MAX_TOKENS=8192                  # Max tokens send to LLM (base on your Ollama Server capacity)
+### Max tokens send to LLM (base on your Ollama Server capacity)
+MAX_TOKENS=8192

 EMBEDDING_BINDING=ollama
 EMBEDDING_BINDING_HOST=http://localhost:11434
@@ -90,7 +92,9 @@ 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.
+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.

 Here are some common used startup parameters:

@@ -100,6 +104,8 @@ Here are some common used startup parameters:
 - `--log-level`: Logging level (default: INFO)
 - --input-dir: specifying the directory to scan for documents (default: ./input)

+> 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. Allow different .env files for different instances.
+
 ### Auto scan on startup

 When starting any of the servers with the `--auto-scan-at-startup` parameter, the system will automatically:
@@ -117,9 +123,12 @@ The LightRAG Server can operate in the `Gunicorn + Uvicorn` preload mode. Gunico
 Though LightRAG Server uses one workers to process the document indexing pipeline, with aysnc task supporting of Uvicorn, multiple files can be processed in parallell. The bottleneck of document indexing speed mainly lies with the LLM. If your LLM supports high concurrency, you can accelerate document indexing by increasing the concurrency level of the LLM. Below are several environment variables related to concurrent processing, along with their default values:

 ```
-WORKERS=2                    # Num of worker processes, not greater then (2 x number_of_cores) + 1
-MAX_PARALLEL_INSERT=2        # Num of parallel files to process in one batch
-MAX_ASYNC=4                  # Max concurrency requests of LLM
+### Num of worker processes, not greater then (2 x number_of_cores) + 1
+WORKERS=2
+### Num of parallel files to process in one batch
+MAX_PARALLEL_INSERT=2
+### Max concurrency requests of LLM
+MAX_ASYNC=4
 ```

 ### Install Lightrag as a Linux Service
@@ -203,10 +212,9 @@ LightRAG API Server implements JWT-based authentication using HS256 algorithm. T

 ```bash
 # For jwt auth
-AUTH_USERNAME=admin      # login name
-AUTH_PASSWORD=admin123   # password
-TOKEN_SECRET=your-key    # JWT key
-TOKEN_EXPIRE_HOURS=4     # expire duration
+AUTH_ACCOUNTS='admin:admin123,user1:pass456'
+TOKEN_SECRET='your-key'
+TOKEN_EXPIRE_HOURS=4
 ```

 > Currently, only the configuration of an administrator account and password is supported. A comprehensive account system is yet to be developed and implemented.
@@ -243,10 +251,12 @@ LLM_BINDING=azure_openai
 LLM_BINDING_HOST=your-azure-endpoint
 LLM_MODEL=your-model-deployment-name
 LLM_BINDING_API_KEY=your-azure-api-key
-AZURE_OPENAI_API_VERSION=2024-08-01-preview  # optional, defaults to latest version
-EMBEDDING_BINDING=azure_openai  # if using Azure OpenAI for embeddings
-EMBEDDING_MODEL=your-embedding-deployment-name
+### API version is optional, defaults to latest version
+AZURE_OPENAI_API_VERSION=2024-08-01-preview

+### if using Azure OpenAI for embeddings
+EMBEDDING_BINDING=azure_openai
+EMBEDDING_MODEL=your-embedding-deployment-name
 ```


@@ -370,76 +380,47 @@ You can not change storage implementation selection after you add documents to L
 | --embedding-binding | ollama | Embedding binding type (lollms, ollama, openai, azure_openai) |
 | auto-scan-at-startup | - | Scan input directory for new files and start indexing |

-### Example Usage
-
-#### Running a Lightrag server with ollama default local server as llm and embedding backends
-
-Ollama is the default backend for both llm and embedding, so by default you can run lightrag-server with no parameters and the default ones will be used. Make sure ollama is installed and is running and default models are already installed on ollama.
+### .env Examples

 ```bash
-# Run lightrag with ollama, mistral-nemo:latest for llm, and bge-m3:latest for embedding
-lightrag-server
+### Server Configuration
+# HOST=0.0.0.0
+PORT=9621
+WORKERS=2
+
+### Settings for document indexing
+ENABLE_LLM_CACHE_FOR_EXTRACT=true
+SUMMARY_LANGUAGE=Chinese
+MAX_PARALLEL_INSERT=2
+
+### LLM Configuration (Use valid host. For local services installed with docker, you can use host.docker.internal)
+TIMEOUT=200
+TEMPERATURE=0.0
+MAX_ASYNC=4
+MAX_TOKENS=32768
+
+LLM_BINDING=openai
+LLM_MODEL=gpt-4o-mini
+LLM_BINDING_HOST=https://api.openai.com/v1
+LLM_BINDING_API_KEY=your-api-key
+
+### Embedding Configuration (Use valid host. For local services installed with docker, you can use host.docker.internal)
+EMBEDDING_MODEL=bge-m3:latest
+EMBEDDING_DIM=1024
+EMBEDDING_BINDING=ollama
+EMBEDDING_BINDING_HOST=http://localhost:11434
+
+### For JWT Auth
+# AUTH_ACCOUNTS='admin:admin123,user1:pass456'
+# TOKEN_SECRET=your-key-for-LightRAG-API-Server-xxx
+# TOKEN_EXPIRE_HOURS=48
+
+# LIGHTRAG_API_KEY=your-secure-api-key-here-123
+# WHITELIST_PATHS=/api/*
+# WHITELIST_PATHS=/health,/api/*

-# Using an authentication key
-lightrag-server --key my-key
 ```

-#### Running a Lightrag server with lollms default local server as llm and embedding backends
-
-```bash
-# Run lightrag with lollms, mistral-nemo:latest for llm, and bge-m3:latest for embedding
-# Configure LLM_BINDING=lollms and EMBEDDING_BINDING=lollms in .env or config.ini
-lightrag-server
-
-# Using an authentication key
-lightrag-server --key my-key
-```
-
-#### Running a Lightrag server with openai server as llm and embedding backends
-
-```bash
-# Run lightrag with openai, GPT-4o-mini for llm, and text-embedding-3-small for embedding
-# Configure in .env or config.ini:
-# LLM_BINDING=openai
-# LLM_MODEL=GPT-4o-mini
-# EMBEDDING_BINDING=openai
-# EMBEDDING_MODEL=text-embedding-3-small
-lightrag-server
-
-# Using an authentication key
-lightrag-server --key my-key
-```
-
-#### Running a Lightrag server with azure openai server as llm and embedding backends
-
-```bash
-# Run lightrag with azure_openai
-# Configure in .env or config.ini:
-# LLM_BINDING=azure_openai
-# LLM_MODEL=your-model
-# EMBEDDING_BINDING=azure_openai
-# EMBEDDING_MODEL=your-embedding-model
-lightrag-server
-
-# Using an authentication key
-lightrag-server --key my-key
-```
-
-**Important Notes:**
- For LoLLMs: Make sure the specified models are installed in your LoLLMs instance
- For Ollama: Make sure the specified models are installed in your Ollama instance
- For OpenAI: Ensure you have set up your OPENAI_API_KEY environment variable
- For Azure OpenAI: Build and configure your server as stated in the Prequisites section
-
-For help on any server, use the --help flag:
-```bash
-lightrag-server --help
-```
-
-Note: If you don't need the API functionality, you can install the base package without API support using:
-```bash
-pip install lightrag-hku
-```

 ## API Endpoints

--- a/lightrag/api/init.py
+++ b/lightrag/api/init.py
@@ -1 +1 @@
-__api_version__ = "1.2.7"
+__api_version__ = "1.2.8"
--- a/lightrag/api/auth.py
+++ b/lightrag/api/auth.py
@@ -7,7 +7,10 @@ from pydantic import BaseModel

 from .config import global_args

-load_dotenv()
+# use the .env that is inside the current folder
+# allows to use different .env file for each lightrag instance
+# the OS environment variables take precedence over the .env file
+load_dotenv(dotenv_path=".env", override=False)


 class TokenPayload(BaseModel):
--- a/lightrag/api/lightrag_server.py
+++ b/lightrag/api/lightrag_server.py
@@ -50,15 +50,18 @@ from lightrag.kg.shared_storage import (
 from fastapi.security import OAuth2PasswordRequestForm
 from lightrag.api.auth import auth_handler

-# Load environment variables
-# Updated to use the .env that is inside the current folder
-# This update allows the user to put a different.env file for each lightrag folder
-load_dotenv(".env")
+# use the .env that is inside the current folder
+# allows to use different .env file for each lightrag instance
+# the OS environment variables take precedence over the .env file
+load_dotenv(dotenv_path=".env", override=False)

 # Initialize config parser
 config = configparser.ConfigParser()
 config.read("config.ini")

+# Global authentication configuration
+auth_configured = bool(auth_handler.accounts)
+

 def create_app(args):
    # Setup logging
@@ -429,9 +432,7 @@ def create_app(args):
        try:
            pipeline_status = await get_namespace_data("pipeline_status")

-            username = os.getenv("AUTH_USERNAME")
-            password = os.getenv("AUTH_PASSWORD")
-            if not (username and password):
+            if not auth_configured:
                auth_mode = "disabled"
            else:
                auth_mode = "enabled"
--- a/lightrag/api/routers/document_routes.py
+++ b/lightrag/api/routers/document_routes.py
@@ -540,6 +540,7 @@ def create_document_routes(

        Returns:
            InsertResponse: A response object containing the upload status and a message.
+                status can be "success", "duplicated", or error is thrown.

        Raises:
            HTTPException: If the file type is not supported (400) or other errors occur (500).
@@ -552,6 +553,13 @@ def create_document_routes(
                )

            file_path = doc_manager.input_dir / file.filename
+            # Check if file already exists
+            if file_path.exists():
+                return InsertResponse(
+                    status="duplicated",
+                    message=f"File '{file.filename}' already exists in the input directory.",
+                )
+
            with open(file_path, "wb") as buffer:
                shutil.copyfileobj(file.file, buffer)

--- a/lightrag/api/run_with_gunicorn.py
+++ b/lightrag/api/run_with_gunicorn.py
@@ -11,9 +11,10 @@ from lightrag.api.utils_api import parse_args, display_splash_screen, check_env_
 from lightrag.kg.shared_storage import initialize_share_data, finalize_share_data
 from dotenv import load_dotenv

-# Updated to use the .env that is inside the current folder
-# This update allows the user to put a different.env file for each lightrag folder
-load_dotenv(".env")
+# use the .env that is inside the current folder
+# allows to use different .env file for each lightrag instance
+# the OS environment variables take precedence over the .env file
+load_dotenv(dotenv_path=".env", override=False)


 def check_and_install_dependencies():
--- a/lightrag/api/utils_api.py
+++ b/lightrag/api/utils_api.py
@@ -2,18 +2,17 @@
 Utility functions for the LightRAG API.
 """

-import argparse
 import os
-import sys
+import argparse
 from typing import Optional, List, Tuple
-
+import sys
 from ascii_colors import ASCIIColors
-from dotenv import load_dotenv
+from lightrag.api import __api_version__ as api_version
+from lightrag import __version__ as core_version
 from fastapi import HTTPException, Security, Request, status
+from dotenv import load_dotenv
 from fastapi.security import APIKeyHeader, OAuth2PasswordBearer
 from starlette.status import HTTP_403_FORBIDDEN
-
-from lightrag.api import __api_version__
 from .auth import auth_handler
 from .config import ollama_server_infos
 from ..prompt import PROMPTS
@@ -25,9 +24,7 @@ def check_env_file():
    Returns True if should continue, False if should exit.
    """
    if not os.path.exists(".env"):
-        warning_msg = (
-            "Warning: .env file not found. Some features may not work properly."
-        )
+        warning_msg = "Warning: Startup directory must contain .env file for multi-instance support."
        ASCIIColors.yellow(warning_msg)

        # Check if running in interactive terminal
@@ -39,8 +36,10 @@ def check_env_file():
    return True


-# Load environment variables
-load_dotenv()
+# use the .env that is inside the current folder
+# allows to use different .env file for each lightrag instance
+# the OS environment variables take precedence over the .env file
+load_dotenv(dotenv_path=".env", override=False)

 # Get whitelist paths from environment variable, only once during initialization
 default_whitelist = "/health,/api/*"
@@ -182,7 +181,7 @@ def display_splash_screen(args: argparse.Namespace) -> None:
    # Banner
    ASCIIColors.cyan(f"""
    ╔══════════════════════════════════════════════════════════════╗
-    ║                   🚀 LightRAG Server v{__api_version__}                  ║
+    ║                   🚀 LightRAG Server v{core_version}/{api_version}            ║
    ║          Fast, Lightweight RAG Server Implementation         ║
    ╚══════════════════════════════════════════════════════════════╝
    """)
--- a/lightrag/api/webui/assets/index-CD5HxTy1.css
+++ b/lightrag/api/webui/assets/index-CD5HxTy1.css
--- a/lightrag/api/webui/assets/index-CbzkrOyx.css
+++ b/lightrag/api/webui/assets/index-CbzkrOyx.css
--- a/lightrag/api/webui/assets/index-raheqJeu.js
+++ b/lightrag/api/webui/assets/index-raheqJeu.js
--- a/lightrag/api/webui/index.html
+++ b/lightrag/api/webui/index.html
@@ -8,8 +8,8 @@
    <link rel="icon" type="image/svg+xml" href="logo.png" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Lightrag</title>
-    <script type="module" crossorigin src="/webui/assets/index-DTDDxtXc.js"></script>
-    <link rel="stylesheet" crossorigin href="/webui/assets/index-CbzkrOyx.css">
+    <script type="module" crossorigin src="/webui/assets/index-raheqJeu.js"></script>
+    <link rel="stylesheet" crossorigin href="/webui/assets/index-CD5HxTy1.css">
  </head>
  <body>
    <div id="root"></div>