docs: Enterprise Edition & Multi-tenancy attribution (#5 )

* Remove outdated documentation files: Quick Start Guide, Apache AGE Analysis, and Scratchpad.

* Add multi-tenant testing strategy and ADR index documentation

- Introduced ADR 008 detailing the multi-tenant testing strategy for the ./starter environment, covering compatibility and multi-tenant modes, testing scenarios, and implementation details.
- Created a comprehensive ADR index (README.md) summarizing all architecture decision records related to the multi-tenant implementation, including purpose, key sections, and reading paths for different roles.

* feat(docs): Add comprehensive multi-tenancy guide and README for LightRAG Enterprise

- Introduced `0008-multi-tenancy.md` detailing multi-tenancy architecture, key concepts, roles, permissions, configuration, and API endpoints.
- Created `README.md` as the main documentation index, outlining features, quick start, system overview, and deployment options.
- Documented the LightRAG architecture, storage backends, LLM integrations, and query modes.
- Established a task log (`2025-01-21-lightrag-documentation-log.md`) summarizing documentation creation actions, decisions, and insights.

2025-12-04 18:09:15 +08:00

20 KiB

Raw Blame History

LightRAG Configuration Reference

Configuration Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                       CONFIGURATION LAYERS                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  1. COMMAND LINE ARGUMENTS (highest priority)                          │ │
│  │     python -m lightrag.api.lightrag_server --port 9621 --workers 2     │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  2. ENVIRONMENT VARIABLES                                              │ │
│  │     export PORT=9621                                                   │ │
│  │     export LLM_MODEL=gpt-4o-mini                                      │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  3. .env FILE                                                          │ │
│  │     LLM_MODEL=gpt-4o-mini                                             │ │
│  │     EMBEDDING_DIM=1536                                                 │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  4. PYTHON DATACLASS DEFAULTS (lowest priority)                        │ │
│  │     LightRAG(working_dir="./rag_storage")                             │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

1. Server Configuration

Basic Server Settings

Variable	CLI Flag	Default	Description
`HOST`	`--host`	`0.0.0.0`	Server bind address
`PORT`	`--port`	`9621`	Server port
`WORKERS`	`--workers`	`2`	Number of worker processes
`TIMEOUT`	`--timeout`	`300`	Request timeout (seconds)
`WORKING_DIR`	`--working-dir`	`./rag_storage`	RAG storage directory
`INPUT_DIR`	`--input-dir`	`./inputs`	Document input directory

SSL/TLS Configuration

Variable	CLI Flag	Default	Description
`SSL`	`--ssl`	`false`	Enable HTTPS
`SSL_CERTFILE`	`--ssl-certfile`	`None`	Path to SSL certificate
`SSL_KEYFILE`	`--ssl-keyfile`	`None`	Path to SSL private key

Logging Configuration

Variable	CLI Flag	Default	Description
`LOG_LEVEL`	`--log-level`	`INFO`	Logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL)
`VERBOSE`	`--verbose`	`false`	Enable verbose debug output
`LOG_MAX_BYTES`	—	`10485760`	Max log file size (10MB)
`LOG_BACKUP_COUNT`	—	`5`	Number of log backups
`LOG_FILENAME`	—	`lightrag.log`	Log filename

2. LLM Configuration

Provider Selection

Variable	CLI Flag	Default	Description
`LLM_BINDING`	`--llm-binding`	`openai`	LLM provider
`LLM_MODEL`	—	`mistral-nemo:latest`	Model name
`LLM_BINDING_HOST`	—	Provider-specific	API endpoint URL
`LLM_BINDING_API_KEY`	—	`None`	API key

Supported LLM Bindings:

openai - OpenAI API (default)
ollama - Local Ollama
lollms - LoLLMs server
azure_openai - Azure OpenAI Service
aws_bedrock - AWS Bedrock
openai-ollama - OpenAI LLM + Ollama embeddings

Provider-Specific Host Defaults

Provider	Default Host
`openai`	`https://api.openai.com/v1`
`ollama`	`http://localhost:11434`
`lollms`	`http://localhost:9600`
`azure_openai`	`AZURE_OPENAI_ENDPOINT` env

LLM Performance Settings

Variable	Default	Description
`MAX_ASYNC`	`4`	Max concurrent LLM requests
`LLM_TIMEOUT`	`180`	LLM request timeout (seconds)
`ENABLE_LLM_CACHE`	`true`	Enable LLM response caching
`ENABLE_LLM_CACHE_FOR_EXTRACT`	`true`	Cache extraction responses
`TEMPERATURE`	`1.0`	LLM temperature setting

Ollama-Specific Settings

Variable	Default	Description
`OLLAMA_NUM_CTX`	`32768`	Context window size
`OLLAMA_EMULATING_MODEL_NAME`	`lightrag`	Simulated model name
`OLLAMA_EMULATING_MODEL_TAG`	`latest`	Simulated model tag

3. Embedding Configuration

Embedding Provider

Variable	CLI Flag	Default	Description
`EMBEDDING_BINDING`	`--embedding-binding`	`openai`	Embedding provider
`EMBEDDING_MODEL`	—	`bge-m3:latest`	Embedding model name
`EMBEDDING_DIM`	—	`1024`	Embedding dimensions
`EMBEDDING_BINDING_HOST`	—	Provider-specific	API endpoint
`EMBEDDING_BINDING_API_KEY`	—	`""`	API key

Supported Embedding Bindings:

openai - OpenAI embeddings
ollama - Local Ollama embeddings
azure_openai - Azure OpenAI embeddings
aws_bedrock - AWS Bedrock Titan
jina - Jina embeddings

Embedding Performance

Variable	Default	Description
`EMBEDDING_FUNC_MAX_ASYNC`	`8`	Max concurrent embedding requests
`EMBEDDING_BATCH_NUM`	`10`	Batch size for embeddings
`EMBEDDING_TIMEOUT`	`30`	Embedding request timeout (seconds)

4. Storage Configuration

Storage Backend Selection

Variable	Default	Description
`LIGHTRAG_KV_STORAGE`	`JsonKVStorage`	Key-value storage backend
`LIGHTRAG_VECTOR_STORAGE`	`NanoVectorDBStorage`	Vector storage backend
`LIGHTRAG_GRAPH_STORAGE`	`NetworkXStorage`	Graph storage backend
`LIGHTRAG_DOC_STATUS_STORAGE`	`JsonDocStatusStorage`	Document status storage

Available Storage Backends

KV Storage Options:

Value	Use Case
`JsonKVStorage`	Development, file-based
`RedisKVStorage`	Production, distributed
`PGKVStorage`	Production, PostgreSQL
`MongoKVStorage`	Production, MongoDB

Vector Storage Options:

Value	Use Case
`NanoVectorDBStorage`	Development, in-memory
`PGVectorStorage`	Production, PostgreSQL
`MilvusVectorDBStorage`	Production, high-scale
`QdrantStorage`	Production, managed
`FAISSStorage`	Production, local
`RedisVectorStorage`	Production, distributed
`MongoDBVectorStorage`	Production, MongoDB

Graph Storage Options:

Value	Use Case
`NetworkXStorage`	Development, in-memory
`Neo4JStorage`	Production, native graph
`PGGraphStorage`	Production, PostgreSQL
`AGEStorage`	Production, PostgreSQL AGE
`MemgraphStorage`	Production, real-time
`GremlinStorage`	Production, Gremlin-compatible

PostgreSQL Configuration

Variable	Default	Description
`POSTGRES_HOST`	`localhost`	PostgreSQL host
`POSTGRES_PORT`	`5432`	PostgreSQL port
`POSTGRES_USER`	—	Database user
`POSTGRES_PASSWORD`	—	Database password
`POSTGRES_DATABASE`	—	Database name

Neo4j Configuration

Variable	Default	Description
`NEO4J_URI`	`bolt://localhost:7687`	Neo4j connection URI
`NEO4J_USERNAME`	`neo4j`	Neo4j username
`NEO4J_PASSWORD`	—	Neo4j password

Redis Configuration

Variable	Default	Description
`REDIS_URI`	`redis://localhost:6379`	Redis connection URI

Milvus Configuration

Variable	Default	Description
`MILVUS_HOST`	`localhost`	Milvus host
`MILVUS_PORT`	`19530`	Milvus port
`MILVUS_USER`	—	Milvus user
`MILVUS_PASSWORD`	—	Milvus password
`MILVUS_DB_NAME`	`default`	Milvus database

5. Document Processing Configuration

Chunking Settings

Variable	Default	Description
`CHUNK_SIZE`	`1200`	Token size per chunk
`CHUNK_OVERLAP_SIZE`	`100`	Overlap between chunks

Entity Extraction

Variable	Default	Description
`SUMMARY_LANGUAGE`	`English`	Language for summaries
`MAX_GLEANING`	`1`	Entity extraction iterations
`ENTITY_TYPES`	See below	Types of entities to extract

Default Entity Types:

ENTITY_TYPES = [
    "Person", "Creature", "Organization", "Location",
    "Event", "Concept", "Method", "Content",
    "Data", "Artifact", "NaturalObject"
]

Summary Settings

Variable	Default	Description
`SUMMARY_MAX_TOKENS`	`1200`	Max tokens per summary
`SUMMARY_LENGTH_RECOMMENDED`	`600`	Recommended summary length
`SUMMARY_CONTEXT_SIZE`	`12000`	Context window for summarization
`FORCE_LLM_SUMMARY_ON_MERGE`	`8`	Fragment threshold for LLM summary

Document Loader

Variable	Default	Description
`DOCUMENT_LOADING_ENGINE`	`DEFAULT`	Document parser (DEFAULT/DOCLING)

6. Query Configuration

QueryParam Class

@dataclass
class QueryParam:
    mode: str = "mix"                    # Query mode
    only_need_context: bool = False      # Return only context
    only_need_prompt: bool = False       # Return only prompt
    response_type: str = "Multiple Paragraphs"
    stream: bool = False                 # Enable streaming
    top_k: int = 40                      # Top results
    chunk_top_k: int = 20                # Top chunks
    max_entity_tokens: int = 6000        # Entity token budget
    max_relation_tokens: int = 8000      # Relation token budget
    max_total_tokens: int = 30000        # Total token budget
    enable_rerank: bool = True           # Enable reranking
    include_references: bool = False     # Include citations

Query Modes

Mode	Description	Best For
`naive`	Basic vector search	Simple lookups
`local`	Entity-focused retrieval	Specific entities
`global`	High-level summaries	Broad questions
`hybrid`	Local + Global combined	Balanced queries
`mix`	KG + Vector integration	Complex questions
`bypass`	Skip RAG, direct LLM	Testing

Query Environment Variables

Variable	Default	Description
`TOP_K`	`40`	Top-K entities/relations
`CHUNK_TOP_K`	`20`	Top-K text chunks
`MAX_ENTITY_TOKENS`	`6000`	Entity context budget
`MAX_RELATION_TOKENS`	`8000`	Relation context budget
`MAX_TOTAL_TOKENS`	`30000`	Total context budget
`COSINE_THRESHOLD`	`0.2`	Similarity threshold
`RELATED_CHUNK_NUMBER`	`5`	Related chunks to retrieve
`HISTORY_TURNS`	`0`	Conversation history turns

7. Reranking Configuration

Variable	CLI Flag	Default	Description
`RERANK_BINDING`	`--rerank-binding`	`null`	Rerank provider
`RERANK_MODEL`	—	`None`	Rerank model name
`RERANK_BINDING_HOST`	—	`None`	Rerank API endpoint
`RERANK_BINDING_API_KEY`	—	`None`	Rerank API key
`MIN_RERANK_SCORE`	—	`0.0`	Minimum rerank score
`RERANK_BY_DEFAULT`	—	`true`	Enable reranking by default

Supported Rerank Bindings:

null - Disabled
cohere - Cohere rerank
jina - Jina rerank
aliyun - Aliyun rerank

8. Authentication & Security

API Authentication

Variable	CLI Flag	Default	Description
`LIGHTRAG_API_KEY`	`--key`	`None`	Simple API key auth
`AUTH_ACCOUNTS`	—	`""`	Format: `user1:pass1,user2:pass2`
`AUTH_USER`	—	`""`	Single username (if AUTH_ACCOUNTS not set)
`AUTH_PASS`	—	`""`	Single password

JWT Configuration

Variable	Default	Description
`TOKEN_SECRET`	`lightrag-jwt-default-secret`	JWT signing secret
`TOKEN_EXPIRE_HOURS`	`48`	Token expiration (hours)
`GUEST_TOKEN_EXPIRE_HOURS`	`24`	Guest token expiration
`JWT_ALGORITHM`	`HS256`	JWT algorithm

CORS & Network

Variable	Default	Description
`CORS_ORIGINS`	`*`	Allowed CORS origins
`WHITELIST_PATHS`	`/health,/api/*`	Public paths

Multi-Tenant Security

Variable	Default	Description
`LIGHTRAG_MULTI_TENANT_STRICT`	`true`	Enforce tenant isolation
`LIGHTRAG_REQUIRE_USER_AUTH`	`true`	Require user authentication
`LIGHTRAG_SUPER_ADMIN_USERS`	`admin`	Comma-separated admin usernames

9. Multi-Tenancy Configuration

Variable	Default	Description
`ENABLE_MULTI_TENANTS`	`false`	Enable multi-tenant mode
`WORKSPACE`	`""`	Default workspace name
`MAX_GRAPH_NODES`	`1000`	Max graph nodes per query
`MAX_PARALLEL_INSERT`	`2`	Max parallel inserts

10. Complete .env Example

# =============================================================================
# SERVER CONFIGURATION
# =============================================================================
HOST=0.0.0.0
PORT=9621
WORKERS=2
TIMEOUT=300
WORKING_DIR=./rag_storage
INPUT_DIR=./inputs
LOG_LEVEL=INFO

# =============================================================================
# LLM CONFIGURATION
# =============================================================================
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=sk-xxx
MAX_ASYNC=4
ENABLE_LLM_CACHE=true

# =============================================================================
# EMBEDDING CONFIGURATION
# =============================================================================
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-ada-002
EMBEDDING_DIM=1536
EMBEDDING_BINDING_API_KEY=sk-xxx
EMBEDDING_FUNC_MAX_ASYNC=8
EMBEDDING_BATCH_NUM=10

# =============================================================================
# STORAGE CONFIGURATION
# =============================================================================
LIGHTRAG_KV_STORAGE=JsonKVStorage
LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage
LIGHTRAG_GRAPH_STORAGE=NetworkXStorage
LIGHTRAG_DOC_STATUS_STORAGE=JsonDocStatusStorage

# PostgreSQL (if using PG storage)
# POSTGRES_HOST=localhost
# POSTGRES_PORT=5432
# POSTGRES_USER=lightrag
# POSTGRES_PASSWORD=secret
# POSTGRES_DATABASE=lightrag

# Neo4j (if using Neo4J storage)
# NEO4J_URI=bolt://localhost:7687
# NEO4J_USERNAME=neo4j
# NEO4J_PASSWORD=secret

# =============================================================================
# DOCUMENT PROCESSING
# =============================================================================
CHUNK_SIZE=1200
CHUNK_OVERLAP_SIZE=100
SUMMARY_LANGUAGE=English
SUMMARY_MAX_TOKENS=1200
SUMMARY_CONTEXT_SIZE=12000

# =============================================================================
# QUERY CONFIGURATION
# =============================================================================
TOP_K=40
CHUNK_TOP_K=20
MAX_ENTITY_TOKENS=6000
MAX_RELATION_TOKENS=8000
MAX_TOTAL_TOKENS=30000
COSINE_THRESHOLD=0.2

# =============================================================================
# RERANKING (optional)
# =============================================================================
# RERANK_BINDING=cohere
# RERANK_MODEL=rerank-english-v2.0
# RERANK_BINDING_API_KEY=xxx

# =============================================================================
# AUTHENTICATION
# =============================================================================
AUTH_USER=admin
AUTH_PASS=admin123
TOKEN_SECRET=your-secure-secret-key
TOKEN_EXPIRE_HOURS=48
CORS_ORIGINS=*

# =============================================================================
# MULTI-TENANCY (optional)
# =============================================================================
# ENABLE_MULTI_TENANTS=true
# LIGHTRAG_MULTI_TENANT_STRICT=true
# LIGHTRAG_REQUIRE_USER_AUTH=true
# LIGHTRAG_SUPER_ADMIN_USERS=admin

11. Python LightRAG Dataclass

@dataclass
class LightRAG:
    # Directory configuration
    working_dir: str = "./rag_storage"
    
    # LLM configuration
    llm_model_name: str = "gpt-4o-mini"
    llm_model_func: Callable = openai_complete_if_cache
    llm_model_max_async: int = 4
    llm_model_max_token_size: int = 32768
    llm_model_kwargs: dict = field(default_factory=dict)
    
    # Embedding configuration
    embedding_model_name: str = "text-embedding-ada-002"
    embedding_func: EmbeddingFunc = None
    embedding_batch_num: int = 10
    embedding_func_max_async: int = 8
    
    # Chunking configuration
    chunk_token_size: int = 1200
    chunk_overlap_token_size: int = 100
    tiktoken_model_name: str = "gpt-4o"
    
    # Entity extraction
    entity_extract_max_gleaning: int = 1
    entity_summary_to_max_tokens: int = 1200
    
    # Storage backends
    kv_storage: str = "JsonKVStorage"
    vector_storage: str = "NanoVectorDBStorage"
    graph_storage: str = "NetworkXStorage"
    doc_status_storage: str = "JsonDocStatusStorage"
    
    # Advanced options
    enable_llm_cache: bool = True
    enable_llm_cache_for_entity_extract: bool = True
    auto_manage_storages_states: bool = True
    
    # Namespace (for multi-tenancy)
    namespace: str = None

Related Documentation:

20 KiB Raw Blame History