gmakstutis/LightRAG
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
LightRAG/docs/0007-configuration-reference.md
Raphael MANSUY 2b292d4924
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

536 lines
20 KiB
Markdown
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:**
```python
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
```python
@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
```bash
# =============================================================================
# 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
```python
@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:**
- [Architecture Overview](0002-architecture-overview.md)
- [Storage Backends](0004-storage-backends.md)
- [LLM Integration](0005-llm-integration.md)
- [Deployment Guide](0006-deployment-guide.md)
Reference in a new issue View git blame Copy permalink