# https://github.com/HKUDS/LightRAG Project Manual
Generated at: 2026-05-30 18:26:10 UTC
## Table of Contents
- [Introduction to LightRAG](#page-introduction)
- [Installation Guide](#page-installation)
- [System Architecture](#page-architecture)
- [Text Chunking Strategies](#page-chunking-strategies)
- [Storage Backends](#page-storage-backends)
- [API Server](#page-api-server)
- [Programming with LightRAG Core](#page-programming-core)
- [Multimodal Document Processing](#page-multimodal)
- [Deployment Guide](#page-deployment)
- [Advanced Features](#page-advanced-features)
## Introduction to LightRAG
### Related Pages
Related topics: [System Architecture](#page-architecture), [Installation Guide](#page-installation)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
- [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts)
- [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
- [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
# Introduction to LightRAG
LightRAG is a lightweight, high-performance Retrieval-Augmented Generation (RAG) system developed by HKUDS that combines **vector similarity search** with **knowledge graph extraction** to enable efficient and accurate retrieval over large document collections. Unlike traditional RAG approaches that rely solely on chunk-level embedding retrieval, LightRAG extracts entities and relationships from documents to build a structured knowledge graph, enabling multi-hop reasoning and context-aware retrieval.
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Purpose and Scope
LightRAG addresses several key limitations of traditional RAG systems:
| Challenge | LightRAG Solution |
|-----------|-------------------|
| Flat embedding retrieval | Knowledge graph with entity-relationship extraction |
| Poor multi-hop reasoning | Dual-level retrieval (local + global) |
| Limited contextual understanding | Graph traversal with related chunks |
| Slow query processing | Async operations with token budget control |
| Single-modal limitation | Multimodal support for PDFs, images, tables |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
The system is designed for:
- **Research and evaluation** using built-in RAGAS metrics
- **Production deployments** with multiple storage backend options
- **Enterprise applications** requiring knowledge graph visualization
- **Multimodal document processing** including PDFs, Office documents, and images
## Architecture Overview
LightRAG's architecture consists of four primary storage layers working in coordination:
```mermaid
graph TD
subgraph LightRAG_Architecture
subgraph Storage_Layer
KV[KV Storage
JsonFileDB
PostgreSQL
MongoDB
OpenSearch]
Vector[Vector Storage
NanoVectorDB
PostgreSQL
MongoDB
OpenSearch]
Graph[Graph Storage
NetworkX
Neo4j
OpenSearch]
DocStatus[DocStatus Storage
SqliteDB
PostgreSQL
MongoDB
OpenSearch]
end
subgraph Core_Components
LLM[LLM Binding
OpenAI
Ollama
Azure
Gemini
HuggingFace]
Embed[Embedding Binding
OpenAI
Ollama
voyageai
HuggingFace]
Rerank[Reranker
BAAI/bge-reranker]
end
subgraph Interfaces
Server[LightRAG Server
REST API
WebUI]
Core[LightRAG Core
Python API]
end
end
KV <--> LLM
Vector <--> Embed
Graph <--> LLM
DocStatus <--> Server
Core <--> Server
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Dual-Level Retrieval Paradigm
LightRAG employs a unique dual-level retrieval mechanism that combines:
1. **Entity-level retrieval**: Extracts and indexes individual entities (concepts, objects, data points)
2. **Relationship-level retrieval**: Captures connections between entities and their attributes
This approach enables efficient answering of both specific factual queries and complex analytical questions requiring synthesis across multiple documents.
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Query Modes
LightRAG supports six distinct query modes, each optimized for different retrieval strategies:
| Mode | Description | Use Case |
|------|-------------|----------|
| `naive` | Standard vector similarity search without graph | Simple single-hop queries |
| `local` | Entity-based retrieval focusing on specific nodes | Queries about particular entities |
| `global` | Relationship-based retrieval across the graph | Queries requiring broad context |
| `hybrid` | Combines local and global retrieval | Balanced queries |
| `mix` | Integrates reranking with hybrid search (default) | Best overall performance |
| `bypass` | Direct LLM query without retrieval | Simple conversational responses |
Source: [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts#L1-L7)
### Query Parameters
When performing queries, the following parameters control retrieval behavior:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `top_k` | integer | varies | Number of top entities/relations to retrieve |
| `chunk_top_k` | integer | varies | Maximum text chunks after reranking |
| `max_entity_tokens` | integer | varies | Token budget for entity context |
| `max_relation_tokens` | integer | varies | Token budget for relationship context |
| `max_total_tokens` | integer | varies | Total token budget for entire query |
| `only_need_context` | boolean | false | Return only retrieved context |
| `only_need_prompt` | boolean | false | Return generated prompt only |
| `response_type` | string | — | Desired response format (e.g., "Multiple Paragraphs") |
Source: [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts#L8-L41)
## Installation Options
LightRAG offers multiple installation paths depending on your deployment requirements:
### LightRAG Server (Full Stack)
The complete deployment including Web UI, REST API, and all integrations:
```bash
# Install via uv (recommended)
uv tool install "lightrag-hku[api]"
# Or using pip
pip install "lightrag-hku[api]"
# Build frontend
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
# Configure environment
cp env.example .env
# Edit .env with your LLM and embedding configurations
# Launch server
lightrag-server
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### LightRAG Core (Python Library)
For embedding LightRAG into custom applications:
```bash
# From source
cd LightRAG
uv sync
source .venv/bin/activate
# Or via pip
pip install lightrag-hku
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Docker Deployment
For containerized deployments:
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env
# Configure .env with your settings
docker compose up
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Interactive Setup Wizard
LightRAG includes an interactive setup wizard for streamlined configuration:
```bash
make env-base # LLM, embedding, reranker configuration
make env-storage # Storage backends (optional)
make env-server # Server settings (optional)
make env-security-check # Audit configuration for security risks
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Supported Storage Backends
LightRAG provides flexible storage options for each of its four storage types:
### KV Storage
| Backend | Description |
|---------|-------------|
| JsonFileDB | Local JSON file storage (default, lightweight) |
| PostgreSQL | Production-grade relational storage |
| MongoDB | Document-oriented storage |
| OpenSearch | Unified backend for all storage types |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Vector Storage
| Backend | Description |
|---------|-------------|
| NanoVectorDB | Built-in lightweight vector store (default) |
| PostgreSQL (pgvector) | Production vector search with SQL |
| MongoDB Atlas | Cloud-native vector search |
| OpenSearch | Unified vector and full-text search |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Graph Storage
| Backend | Description |
|---------|-------------|
| NetworkX | In-memory graph (default, lightweight) |
| Neo4j | Enterprise graph database |
| OpenSearch | Graph + search in one platform |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Document Status Storage
| Backend | Description |
|---------|-------------|
| SqliteDB | Local SQLite database (default) |
| PostgreSQL | Production relational storage |
| MongoDB | Document-oriented storage |
| OpenSearch | Unified backend |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## LLM and Embedding Support
LightRAG integrates with multiple provider ecosystems:
### LLM Providers
| Provider | Binding | Features |
|----------|---------|----------|
| OpenAI | `openai` | Chat completions API |
| Ollama | `ollama` | Local model serving |
| Azure OpenAI | `azure_openai` | Enterprise deployment |
| Gemini | `gemini` | Google Vertex AI support |
| HuggingFace | `huggingface` | Inference endpoints |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Embedding Providers
| Provider | Features |
|----------|----------|
| OpenAI | `text-embedding-3-small`, `text-embedding-3-large` |
| Ollama | Local embedding models |
| VoyageAI | Explicit support |
| HuggingFace | Sentence transformers |
| BGE | `BAAI/bge-*-v1.5` |
| Nomic | `nomic-embed-text-v1.5` |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Reranker Support
The reranker model significantly improves mixed query performance and is recommended for production deployments:
| Model | Example |
|-------|---------|
| BAAI | `BAAI/bge-reranker-v2-m3` |
| Jina | Provider reranker services |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Indexing and Knowledge Graph Extraction
During document ingestion, LightRAG performs several processing steps:
```mermaid
graph LR
A[Document Upload] --> B[Text Chunking]
B --> C[Embedding Generation]
C --> D[Entity Extraction]
D --> E[Relationship Extraction]
E --> F[Knowledge Graph Construction]
D --> G[Vector Storage]
E --> H[KV Storage]
F --> I[Graph Storage]
B --> J[Related Chunks]
J --> G
```
Source: [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
### Entity Type Mapping
The knowledge graph supports semantic entity type classification:
| Category | Synonyms |
|----------|----------|
| `concept` | object, type, category, model, project, condition, rule, regulation, article, law |
| `method` | process, technique, approach |
| `artifact` | technology, product, equipment, device, component, material, drug, medicine |
| `naturalobject` | phenomena, substance, plant |
| `data` | figure, value |
| `content` | book, video, document |
| `event` | activity, occurrence |
| `location` | place, site |
| `organization` | company, institution |
Source: [lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts#L1-L60)
## Deployment Options
### Production Deployment with Kubernetes
For scalable production deployments:
```bash
# Add the Helm repository
helm repo add lightrag https://hkuds.github.io/LightRAG
helm repo update
# Install with production storage
helm install lightrag lightrag/lightrag \
--set storage.backend=postgresql \
--set storage.neo4j.enabled=true
```
Source: [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
Two deployment modes are recommended:
1. **Lightweight Deployment**: Built-in storage for testing and small-scale usage
2. **Production Deployment**: External databases (PostgreSQL + Neo4j) for enterprise workloads
Source: [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
### 3D Graph Visualization
LightRAG includes an interactive 3D graph viewer:
```bash
# Install with visualization tools
pip install lightrag-hku[tools]
# Launch viewer
lightrag-viewer
```
Features include:
- Spring, circular, shell, and random layout algorithms
- Automatic community detection
- WASD + QE camera controls
- Node selection and connection highlighting
Source: [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
## Common Issues and Considerations
### Document Identification
**Issue**: Users may have difficulty distinguishing documents with the same filename but different content.
LightRAG assigns unique document IDs internally but does not currently expose filename-based metadata for source tracking in query results. Users should reference document IDs for precise identification.
Source: [GitHub Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
### Reverse Proxy Deployment
**Issue**: When deploying behind a reverse proxy with a sub-path, the application may use absolute paths for assets and iframes, causing broken resources.
The LightRAG Server now supports runtime path configuration via `LIGHTRAG_API_PREFIX` and `LIGHTRAG_WEBUI_PATH` environment variables, which are injected at request time rather than build time.
Source: [GitHub Issue #2755](https://github.com/HKUDS/LightRAG/issues/2755)
Source: [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
### LLM Requirements
LightRAG has higher LLM requirements than traditional RAG systems due to entity-relationship extraction:
| Requirement | Recommended |
|-------------|-------------|
| Model size | At least 32 billion parameters |
| Context length | Minimum 32KB |
| Capabilities | Entity extraction, relationship reasoning |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Advanced Features
### Multimodal Document Processing
LightRAG v1.5.0+ integrates multimodal capabilities from RAG-Anything, supporting:
- PDF parsing with structure preservation
- Office document processing (DOCX, PPTX, XLSX)
- Image extraction and analysis
- Table structure recognition
- Formula detection and indexing
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Token Usage Tracking
LightRAG includes comprehensive token usage monitoring for:
- LLM calls during extraction
- Embedding generation
- Query processing
### Langfuse Integration
Observability and tracing support via Langfuse for monitoring retrieval quality and system performance.
## Evaluation and Testing
LightRAG includes evaluation tools using RAGAS metrics:
```bash
# Index sample documents
# Then run evaluation
python lightrag/evaluation/eval_rag_quality.py
```
Expected results: ~91-100% RAGAS score per question with default sample documents.
Source: [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
## See Also
- [Programing with LightRAG Core](./ProgramingWithCore.md) - Python API reference
- [LightRAG API Server](./LightRAG-API-Server.md) - REST API documentation
- [Advanced Features](./AdvancedFeatures.md) - Multimodal, observability, and evaluation
- [Interactive Setup Guide](./InteractiveSetup.md) - Configuration wizard documentation
- [Docker Deployment](./DockerDeployment.md) - Container deployment guide
- [Offline Deployment](./OfflineDeployment.md) - Air-gapped installation
- [RAG-Anything](https://github.com/HKUDS/RAG-Anything) - Multimodal document processing (merged into LightRAG)
- [VideoRAG](https://github.com/HKUDS/VideoRAG) - Long-context video understanding
---
## Installation Guide
### Related Pages
Related topics: [Deployment Guide](#page-deployment), [API Server](#page-api-server)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)
- [docker-compose.yml](https://github.com/HKUDS/LightRAG/blob/main/docker-compose.yml)
- [Makefile](https://github.com/HKUDS/LightRAG/blob/main/Makefile)
- [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
- [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
# Installation Guide
This guide covers all supported methods for installing and deploying LightRAG, from Python package installation to full-stack Docker deployments with the Web UI. Choose the installation path that matches your use case.
## Prerequisites
### System Requirements
| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Python | 3.10+ | 3.11+ |
| RAM | 8 GB | 16 GB+ |
| Disk Space | 2 GB | 10 GB+ (with vector storage) |
| Docker (optional) | 20.x | Latest |
### LLM and Model Requirements
LightRAG's demands on Large Language Models are significantly higher than traditional RAG systems because it requires the LLM to perform entity-relationship extraction tasks from documents. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
| Model Type | Requirement | Notes |
|------------|-------------|-------|
| **LLM** | At least 32B parameters, 32K+ context | Used for entity extraction and query synthesis |
| **Embedding** | Compatible with chosen vector store | Configurable via environment variables |
| **Reranker** | Optional but recommended | Significantly boosts mixed query performance |
> **Important**: When a Reranker model is enabled, it is recommended to set the "mix mode" as the default query mode. Recommended reranker models include `BAAI/bge-reranker-v2-m3` or services like Jina. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Installation Methods Overview
```mermaid
graph TD
A[Start Installation] --> B{Use Case}
B --> C[Python Development]
B --> D[Server with Web UI]
B --> E[Docker Deployment]
B --> F[Offline/Air-gapped]
C --> C1[uv pip install lightrag-hku]
C --> C2[Clone + uv sync]
D --> D1[Install from PyPI]
D --> D2[Build WebUI]
D --> D3[Configure .env]
E --> E1[Clone Repository]
E --> E2[Interactive Setup Wizard]
E --> E3[docker compose up]
F --> F1[See Offline Deployment Guide]
```
## Installing LightRAG Core (Python Library)
Use this method when you want to embed LightRAG as a library in your Python applications.
### Method 1: Install from PyPI
```bash
# Using uv (recommended)
uv pip install lightrag-hku
# Using pip
pip install lightrag-hku
```
### Method 2: Install from Source
```bash
# Clone the repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# Install dependencies using uv (recommended)
uv sync
source .venv/bin/activate # Linux/macOS
# Or on Windows: .venv\Scripts\activate
# Alternative: pip install
# pip install -e .
```
> **Note**: `uv sync` automatically creates a virtual environment in `.venv/`. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Installing LightRAG Server (Web UI + API)
The LightRAG Server provides a Web UI for document indexing, knowledge graph exploration, and a simple RAG query interface. It also offers Ollama-compatible interfaces for integration with AI chat bots like Open WebUI. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Method 1: Install from PyPI
```bash
# Install LightRAG Server as a tool using uv (recommended)
uv tool install "lightrag-hku[api]"
# Or using pip with virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "lightrag-hku[api]"
```
### Method 2: Install from Source with Development Bootstrap
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# Bootstrap the development environment (recommended)
make dev
source .venv/bin/activate
# make dev installs:
# - Test toolchain
# - Full offline stack (API, storage backends, provider integrations)
# - Frontend build
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Building the WebUI Frontend
After installing LightRAG Server, you need to build the frontend artifacts:
```bash
cd LightRAG
# Using Bun (recommended)
cd lightrag_webui
bun install --frozen-lockfile
bun run build
cd ..
# Alternative: Using Node.js/npm
cd lightrag_webui
npm install
npm run build
cd ..
```
Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
> **Note**: Tests (`bun test`) still require Bun. All other scripts (`dev`, `build`, `preview`, `lint`) work with both Bun and Node.js/npm. Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
## Docker Deployment
Docker deployment provides a complete, containerized environment with all storage backends and services pre-configured.
### Quick Start with Docker Compose
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# Copy environment template
cp env.example .env
# Edit .env with your LLM and embedding configurations
# Then start all services
docker compose up
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Docker Image Verification
Official GitHub Container Registry (GHCR) images are signed with Sigstore Cosign using GitHub OIDC. To verify an official image:
```bash
# See docs/DockerDeployment.md for detailed verification commands
```
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Starting Specific Services
Docker Compose defines services for different components:
| Service | Description | Port |
|---------|-------------|------|
| `lightrag-api` | FastAPI server | 5678 |
| `lightrag-webui` | Web interface | 8080 |
| `postgres` | PostgreSQL storage | 5432 |
| `neo4j` | Graph storage | 7474, 7687 |
| `mongodb` | Document status | 27017 |
## Interactive Setup Wizard
Instead of manually editing `env.example`, use the interactive setup wizard to generate a configured `.env` and `docker-compose.final.yml`. Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
### Setup Commands
```bash
make env-base # Required first step: LLM, embedding, reranker
make env-storage # Optional: storage backends and database services
make env-server # Optional: server port, auth, and SSL
make env-base-rewrite # Optional: force-regenerate wizard-managed compose services
make env-storage-rewrite # Optional: force-regenerate wizard-managed storage compose services
make env-security-check # Optional: audit the current .env for security risks
```
Source: [Makefile](https://github.com/HKUDS/LightRAG/blob/main/Makefile)
### Setup Flow
```mermaid
graph LR
A[make env-base] --> B[Configure LLM
Configure Embedding
Configure Reranker]
B --> C[make env-storage]
C --> D[Choose Storage Backend
PostgreSQL, Neo4j, MongoDB
OpenSearch, etc.]
D --> E[make env-server]
E --> F[Server Configuration
Port, Auth, SSL]
F --> G[Run docker compose up]
G --> H[LightRAG Running]
```
> **Note**: By default, rerunning the setup preserves unchanged wizard-managed compose service blocks. Use `*-rewrite` targets only when you need to rebuild those managed blocks from the bundled templates. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Configuration
### Environment Variables Setup
Copy the example environment file and configure your settings:
```bash
cp env.example .env
# Edit .env with your preferred text editor
```
### Key Configuration Options
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `OPENAI_API_KEY` | API key for LLM provider | Yes | - |
| `LLM_MODEL` | LLM model name | Yes | `gpt-4o` |
| `EMBEDDING_MODEL` | Embedding model name | Yes | `text-embedding-3-large` |
| `RERANKER_MODEL` | Reranker model name | No | - |
| `STORAGE_MODE` | Storage backend type | No | `sqlite` |
| `LIGHTRAG_PORT` | Server port | No | `5678` |
| `LIGHTRAG_AUTH_SECRET` | Auth secret for JWT | No | - |
Source: [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)
### Role-Specific LLM Configuration
LightRAG v1.5+ supports role-specific LLM configuration with 4 distinct roles:
| Role | Purpose |
|------|---------|
| `EXTRACT` | Entity and relationship extraction |
| `QUERY` | Query synthesis and response generation |
| `KEYWORDS` | Keyword extraction |
| `VLM` | Vision-language model for multimodal |
## Installing Visualization Tools
LightRAG includes a 3D graph visualization tool for exploring knowledge graphs.
### Installation
```bash
# Install with visualization tool only
pip install lightrag-hku[tools]
# Or with both API and visualization tools
pip install lightrag-hku[api,tools]
```
Source: [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
### Launch the Viewer
```bash
lightrag-viewer
```
### Viewer Features
- **3D Interactive Visualization**: High-performance graphics using ModernGL
- **Multiple Layout Algorithms**: Spring, circular, shell, and random layouts
- **Community Detection**: Automatic visualization of graph community structures
- **Interactive Controls**: WASD + QE keys for camera, right mouse drag for view angle
## Offline/Air-Gapped Deployment
For offline or air-gapped environments, see the [Offline Deployment Guide](./OfflineDeployment.md) for instructions on pre-installing all dependencies and cache files. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Verifying Installation
### Quick Verification
After installation, verify LightRAG is working:
```bash
# Check LightRAG Core is importable
python -c "import lightrag; print(lightrag.__version__)"
# Start the server (if installed)
lightrag-server
```
### Environment Security Check
Before deploying to production, run the security audit:
```bash
make env-security-check
```
This audits the current `.env` for security risks. Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Common Installation Issues
### Issue: uv not found
Install uv first:
```bash
# Unix/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Issue: Bun build fails
If Bun is unavailable or the build fails (e.g., older Linux distributions), use Node.js instead:
```bash
cd lightrag_webui
npm install
npm run build
```
Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
### Issue: Docker images not starting
Ensure Docker and Docker Compose are properly installed:
```bash
docker --version
docker compose version
```
## Next Steps
After installation, proceed to:
- [Quick Start Guide](./QuickStart.md) - Get started with your first RAG query
- [Configuration Reference](./Configuration.md) - Complete configuration options
- [API Documentation](./LightRAG-API-Server.md) - Server API reference
- [Programming with Core](./ProgramingWithCore.md) - Core API for Python integration
## See Also
- [LightRAG Server Documentation](./LightRAG-API-Server.md)
- [Interactive Setup Guide](./InteractiveSetup.md)
- [Docker Deployment Guide](./DockerDeployment.md)
- [Offline Deployment Guide](./OfflineDeployment.md)
- [Advanced Features](./AdvancedFeatures.md)
---
## System Architecture
### Related Pages
Related topics: [Text Chunking Strategies](#page-chunking-strategies), [Storage Backends](#page-storage-backends)
Related Source Files
The following source files were used to generate this page:
- [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
- [lightrag/operate.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py)
- [lightrag/pipeline.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/pipeline.py)
- [lightrag/base.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
- [docs/Algorithm.md](https://github.com/HKUDS/LightRAG/blob/main/docs/Algorithm.md)
- [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
# System Architecture
LightRAG is a retrieval-augmented generation framework that combines **vector similarity search** with **knowledge graph extraction** to enable efficient and accurate information retrieval from large document collections. The system is designed with a modular architecture that separates concerns between the core RAG engine, storage backends, API server, and web interface.
This page provides a comprehensive overview of LightRAG's system architecture, covering the core components, data flow, storage layer, and deployment options.
---
## Architecture Overview
LightRAG follows a layered architecture that decouples the retrieval engine from storage implementations and client interfaces. The system consists of four primary layers:
```mermaid
graph TB
subgraph "Client Layer"
WebUI[Web UI]
API[REST API]
Ollama[Ollama Compatible Interface]
end
subgraph "Application Layer"
Server[LightRAG Server]
Core[LightRAG Core]
end
subgraph "Storage Layer"
KV[KV Store]
Vector[Vector Store]
Graph[Graph Store]
DocStatus[Doc Status Store]
end
subgraph "Provider Layer"
LLM[LLM Provider]
Embed[Embedding Provider]
Rerank[Reranker Provider]
end
WebUI --> Server
API --> Server
Ollama --> Server
Server --> Core
Core --> KV
Core --> Vector
Core --> Graph
Core --> DocStatus
Core --> LLM
Core --> Embed
Core --> Rerank
```
### Component Responsibilities
| Layer | Component | Purpose | Key Files |
|-------|-----------|---------|-----------|
| Client Layer | Web UI | Interactive document management and query interface | `lightrag_webui/src/` |
| Client Layer | REST API | Programmatic access to LightRAG functionality | `lightrag/api/` |
| Client Layer | Ollama Interface | Emulates LightRAG as an Ollama chat model for integration with AI clients like Open WebUI | `lightrag/api/ollama.py` |
| Application Layer | LightRAG Server | Web framework layer handling authentication, routing, and request processing | `lightrag/server.py` |
| Application Layer | LightRAG Core | Core RAG engine implementing retrieval and knowledge graph extraction | `lightrag/lightrag.py` |
| Storage Layer | KV Store | Stores raw text chunks and metadata | Configurable backends |
| Storage Layer | Vector Store | Stores text embeddings for similarity search | Configurable backends |
| Storage Layer | Graph Store | Stores entities and relationships as a knowledge graph | Configurable backends |
| Storage Layer | Doc Status Store | Tracks document processing state and provenance | Configurable backends |
---
## LightRAG Core Architecture
The LightRAG Core is the central engine responsible for document indexing, knowledge graph extraction, and query processing. It is implemented primarily in `lightrag/lightrag.py` and relies on several supporting modules.
### Core Initialization Parameters
The `LightRAG` class accepts configuration through its constructor, which initializes storage clients, LLM providers, and embedding models. Source: [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `working_dir` | `str` | Working directory for LightRAG data storage | Required |
| `llm_model_name` | `str` | LLM model identifier for entity extraction and query answering | Required |
| `llm_model_max_async` | `int` | Maximum async LLM requests | `16` |
| `embedding_model_name` | `str` | Embedding model for vector storage | Required |
| `embedding_batch_num` | `int` | Batch size for embedding operations | `128` |
| `reranker_model_name` | `str` | Optional reranker model for improved retrieval | `None` |
| `vector_storage` | `str` | Vector storage backend (e.g., "AutoVectorStorage") | `"AutoVectorStorage"` |
| `graph_storage` | `str` | Graph storage backend | `"NetworkXStorage"` |
| `kv_storage` | `str` | KV storage backend | `"JsonKVStorage"` |
| `doc_status_storage` | `str` | Document status storage backend | `"JsonDocStatusStorage"` |
| `chunk_token_size` | `int` | Maximum tokens per text chunk | `1200` |
| `chunk_overlap_token_size` | `int` | Overlap tokens between chunks | `100` |
### Dual-Level Retrieval Architecture
LightRAG implements a unique dual-level retrieval strategy that combines **entity-level** and **relationship-level** search with traditional **vector similarity search**. This approach enables both local (specific entity) and global (relationship patterns) information retrieval. Source: [docs/Algorithm.md](https://github.com/HKUDS/LightRAG/blob/main/docs/Algorithm.md)
```mermaid
graph LR
subgraph "Indexing Pipeline"
Doc[Document] --> Chunk[Chunking]
Chunk --> Extract[Entity Extraction]
Extract --> Graph[(Knowledge Graph)]
Chunk --> Embed[Embedding]
Embed --> Vector[(Vector Index)]
Chunk --> KV[(KV Store)]
end
subgraph "Query Pipeline"
Query[Query] --> Keywords[Keyword Extraction]
Keywords --> Local[Local Search]
Keywords --> Global[Global Search]
Local --> Merge[Result Merge]
Global --> Merge
Query --> Vector[Vector Search]
Vector --> Merge
Merge --> Answer[Generated Answer]
end
```
---
## Storage Layer Architecture
LightRAG supports multiple storage backends for each of its four storage types, allowing deployment flexibility from development to production environments. Source: [lightrag/base.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/base.py)
### Supported Storage Backends
| Storage Type | Supported Backends | Description |
|--------------|-------------------|-------------|
| **KV Storage** | `JsonKVStorage`, `PGKVStorage`, `MongoKVStorage`, `AutoKVStorage` | Stores raw text chunks with metadata |
| **Vector Storage** | `NanoVectorDBStorage`, `PGVectorStorage`, `MilvusStorage`, `QdrantStorage`, `ChromaStorage`, `AutoVectorStorage` | Stores embeddings for similarity search |
| **Graph Storage** | `NetworkXStorage`, `Neo4jStorage`, `OpenSearchStorage`, `AutoGraphStorage` | Stores entities and relationships |
| **Doc Status** | `JsonDocStatusStorage`, `PGDocStatusStorage`, `MongoDocStatusStorage`, `OpenSearchDocStatusStorage`, `AutoDocStatusStorage` | Tracks document processing state |
### OpenSearch Unified Backend
As of v1.4.11, OpenSearch can serve as a unified storage backend providing all four storage types, simplifying deployment and management. Source: [lightrag/operate.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py)
```mermaid
graph TB
subgraph "Storage Abstraction"
StorageInterface[Storage Interface]
end
subgraph "Backend Implementations"
Json[Json Storage]
Postgres[(PostgreSQL)]
MongoDB[(MongoDB)]
Neo4j[(Neo4j)]
OpenSearch[(OpenSearch)]
Milvus[(Milvus)]
Qdrant[(Qdrant)]
Chroma[(Chroma)]
end
StorageInterface --> Json
StorageInterface --> Postgres
StorageInterface --> MongoDB
StorageInterface --> Neo4j
StorageInterface --> OpenSearch
StorageInterface --> Milvus
StorageInterface --> Qdrant
StorageInterface --> Chroma
```
### Document Status Tracking
Document status is tracked through a dedicated storage system that maintains processing state, content hashes, and file metadata. The `DocStatus` enum defines the possible states:
| Status | Description |
|--------|-------------|
| `PENDING` | Document uploaded, awaiting processing |
| `PROCESSING` | Currently being indexed |
| `COMPLETED` | Successfully indexed |
| `FAILED` | Processing failed |
| `DELETED` | Marked for deletion |
Source: [lightrag/operate.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py)
---
## Data Flow Architecture
### Document Indexing Flow
When a document is uploaded, LightRAG processes it through a multi-stage pipeline that extracts both text chunks for vector storage and entities/relationships for the knowledge graph. Source: [lightrag/pipeline.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/pipeline.py)
```mermaid
flowchart TD
subgraph "Input"
A[Document Upload] --> B{File Type}
end
subgraph "Processing"
B -->|PDF/Office| C[Multimodal Parser]
B -->|Text/MD| D[Text Extractor]
C --> E[Content Segmenter]
D --> E
E --> F{Multimodal Content?}
F -->|Images| G[Vision Model Analysis]
F -->|Tables| H[Table Extraction]
F -->|Formulas| I[Formula Detection]
G --> J[Chunk Generator]
H --> J
I --> J
F -->|Text Only| J
end
subgraph "Storage"
J --> K[Tokenization & Embedding]
K --> L[(Vector Store)]
J --> M[Entity Extraction]
M --> N[(Graph Store)]
J --> O[(KV Store)]
J --> P[Doc Status Update]
end
```
### Query Retrieval Flow
LightRAG supports multiple query modes that combine different retrieval strategies. The default `mix` mode integrates all approaches for optimal results. Source: [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
```mermaid
flowchart LR
subgraph "Query Modes"
A[Query] --> B[naive]
A --> C[local]
A --> D[global]
A --> E[hybrid]
A --> F[mix]
A --> G[bypass]
end
subgraph "Retrieval Components"
B -->|Vector only| H[Vector Search]
C -->|Entity-based| I[Local KG Search]
D -->|Relationship-based| J[Global KG Search]
E -->|Vectors + KG| K[Hybrid Retrieval]
F -->|All methods| L[Combined Retrieval]
G -->|No retrieval| M[Direct LLM]
end
subgraph "Output"
H --> N[Result Merge]
I --> N
J --> N
K --> N
L --> N
N --> O[LLM Answer Generation]
end
```
---
## Query Mode Reference
LightRAG provides six distinct query modes, each optimized for different retrieval scenarios. Source: [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
```typescript
export type QueryMode = 'naive' | 'local' | 'global' | 'hybrid' | 'mix' | 'bypass'
```
| Mode | Description | Use Case |
|------|-------------|----------|
| `naive` | Direct vector similarity search only | Simple retrieval with exact term matching |
| `local` | Entity-level knowledge graph search | Queries about specific entities and their attributes |
| `global` | Relationship-level knowledge graph search | Queries about connections and patterns between entities |
| `hybrid` | Combines vector and knowledge graph search | Balanced performance across entity and relationship queries |
| `mix` | Integrates all retrieval methods with reranking | **Default mode** - optimal for complex, mixed queries |
| `bypass` | Disables retrieval, uses LLM directly | Testing or when full context is provided in query |
### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `top_k` | `int` | `auto` | Number of top items to retrieve (entities in local, relationships in global) |
| `chunk_top_k` | `int` | `auto` | Maximum text chunks after reranking |
| `max_entity_tokens` | `int` | `6000` | Token budget for entity context |
| `max_relation_tokens` | `int` | `6000` | Token budget for relationship context |
| `max_total_tokens` | `int` | `128000` | Total token budget for entire query context |
| `response_type` | `str` | `"Multiple Paragraphs"` | Desired answer format |
| `stream` | `bool` | `false` | Enable streaming response |
---
## API Server Architecture
The LightRAG Server provides a FastAPI-based REST API and WebSocket interface for document management, querying, and knowledge graph exploration. Source: [lightrag/server.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/server.py)
### API Endpoints Overview
| Endpoint Category | Description | Key Operations |
|-------------------|-------------|----------------|
| **Documents** | Document upload and management | Upload, delete, list, status tracking |
| **Queries** | RAG query operations | Query, streaming query, chat history |
| **Knowledge Graph** | Graph exploration | Get entities, relationships, subgraph |
| **Chunks** | Text chunk management | List, retrieve, delete chunks |
| **LLM Cache** | Token usage tracking | Cache statistics, clearing |
| **Auth** | Authentication | Token-based access control |
### Runtime Path Configuration
The API server supports deployment behind reverse proxies with custom path prefixes. The runtime configuration is injected at request time rather than build time, enabling a single build to serve multiple deployment scenarios. Source: [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
```mermaid
graph LR
A[Reverse Proxy] -->|Custom path prefix| B[LightRAG Server]
B --> C[Config Injection]
C --> D[HTML Response with JS Config]
D --> E[WebUI Reads Config]
```
> **Known Issue**: Earlier versions (< v1.4.12) used absolute paths that broke when deployed behind reverse proxies. The current implementation resolves paths at runtime to support sub-path deployments. Source: [GitHub Issue #2755](https://github.com/HKUDS/LightRAG/issues/2755)
---
## WebUI Architecture
The LightRAG WebUI is a React-based single-page application that provides an interactive interface for document management and knowledge graph visualization. Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
### Supported File Types
The WebUI supports various document formats through automatic parsing:
| Category | MIME Types | Extensions |
|----------|------------|------------|
| **Documents** | `application/pdf` | `.pdf` |
| **Office** | Word, PowerPoint, Excel | `.docx`, `.pptx`, `.xlsx` |
| **Code** | Multiple programming languages | `.py`, `.js`, `.ts`, `.java`, etc. |
| **Data** | Structured formats | `.json`, `.xml`, `.csv`, `.sql` |
| **Text** | Plain and formatted text | `.txt`, `.md`, `.html`, `.css` |
Source: [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
### WebUI Components
| Component | Purpose |
|-----------|---------|
| Document Manager | Upload, track status, and delete documents |
| Query Interface | Execute queries with mode selection and parameter tuning |
| Knowledge Graph Viewer | Interactive Sigma.js-based graph visualization |
| Settings Panel | Configure LLM, embedding, and storage backends |
| Authentication UI | Login and session management |
### Build System
The WebUI uses Vite for development and production builds, with optional Bun support for faster installation and builds:
```bash
# Production build
bun run build # or npm run build
# Development server
bun run dev # or npm run dev
```
Built artifacts are served from `lightrag/api/webui/`. Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
---
## Multimodal Document Processing
LightRAG v1.5.0 integrates multimodal document processing capabilities previously available in RAG-Anything, enabling analysis of images, tables, and formulas within documents. Source: [GitHub Release v1.5.0rc3](https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0rc3)
```mermaid
flowchart TD
subgraph "Input"
A[PDF Document]
end
subgraph "Parsing Layer (External Service)"
A --> B[MinerU or Docling]
B --> C[Text Segments]
B --> D[Images]
B --> E[Tables]
B --> F[Formulas]
end
subgraph "Vision Analysis"
D --> G[Vision Model]
G --> H[Image Captions & Descriptions]
end
subgraph "LightRAG Pipeline"
C --> I[Text Indexing]
H --> I
E --> J[Table Extraction]
F --> K[Formula Detection]
J --> I
K --> I
end
subgraph "Output"
I --> L[(Indexed Content)]
end
```
### Multimodal Configuration
| Component | Options | Description |
|-----------|---------|-------------|
| Parser Service | `MINERU_SERVICE_URL`, `DOCLING_SERVICE_URL` | External service for document parsing |
| Vision Model | `VLM_MODEL_NAME` | Model for image content analysis |
| Processing | `ENABLE_MULTIMODAL` | Toggle multimodal indexing |
---
## Deployment Architecture
LightRAG supports multiple deployment scenarios, from single-machine development to distributed production environments.
### Deployment Options
| Deployment | Use Case | Components |
|------------|----------|------------|
| **Docker Compose** | Single-node deployment | All-in-one container stack |
| **Interactive Setup** | Custom configuration | Wizard-driven `.env` generation |
| **Offline/Air-gapped** | Restricted networks | Pre-cached dependencies |
| **Cloud Providers** | Managed infrastructure | BYO storage backends |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Docker Architecture
```mermaid
graph TB
subgraph "Docker Compose Stack"
subgraph "API Services"
Server[lightrag-server]
end
subgraph "Storage Services"
Postgres[(PostgreSQL)]
MongoDB[(MongoDB)]
Neo4j[(Neo4j)]
OpenSearch[(OpenSearch)]
Qdrant[(Qdrant)]
end
subgraph "Embedding Services"
Embedding[Embedding Model Server]
Reranker[Reranker Model Server]
end
subgraph "Optional Services"
MinerU[MinerU Parser]
Docling[Docling Parser]
Langfuse[Langfuse Tracing]
end
Server --> Postgres
Server --> MongoDB
Server --> Neo4j
Server --> OpenSearch
Server --> Qdrant
Server --> Embedding
Server --> Reranker
Server --> MinerU
Server --> Docling
Server --> Langfuse
end
```
### Setup Wizard Targets
The Makefile provides modular setup targets for configuration generation:
| Target | Purpose |
|--------|---------|
| `make env-base` | LLM, embedding, and reranker configuration |
| `make env-storage` | Storage backend selection and connection settings |
| `make env-server` | Server port, authentication, and SSL settings |
| `make env-*-rewrite` | Force regeneration of managed compose sections |
| `make env-security-check` | Audit `.env` for security risks |
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
---
## Knowledge Graph Visualization
LightRAG includes a 3D graph visualization tool for exploring the extracted knowledge graph. Source: [lightrag/tools/lightrag_visualizer/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/lightrag_visualizer/README.md)
### Visualizer Features
| Feature | Description |
|---------|-------------|
| **3D Rendering** | ModernGL-based high-performance graphics |
| **Layout Algorithms** | Spring, circular, shell, and random layouts |
| **Community Detection** | Automatic graph partitioning visualization |
| **Interactive Controls** | WASD+QE camera, mouse navigation, node selection |
### Entity Type Color Mapping
The WebUI maps entity types to colors for visual distinction:
| Type Category | Color | Examples |
|---------------|-------|----------|
| `concept` | Blue-gray | model, project, regulation |
| `method` | Blue | process, technique |
| `artifact` | Teal | product, equipment, technology |
| `naturalobject` | Green | plant, phenomena |
| `data` | Orange | figures, values |
| `content` | Purple | book, video |
Source: [lightrag_webui/src/utils/graphColor.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/utils/graphColor.ts)
---
## LLM Provider Integration
LightRAG supports multiple LLM providers with role-specific configuration. Each task (extraction, query, keywords, VLM) can use independent LLM settings. Source: [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
### Supported Providers
| Provider | LLM Support | Embedding Support | Reranker Support |
|----------|-------------|-------------------|------------------|
| **OpenAI** | GPT-4, GPT-3.5 | text-embedding-3 | Via API |
| **Azure OpenAI** | GPT-4, GPT-3.5 | text-embedding-3 | Via API |
| **Ollama** | Local models | Local models | Via API |
| **Gemini** | Gemini Pro/Flash | Embedding services | Via API |
| **HuggingFace** | Inference API | Inference API | Via API |
| **Anthropic** | Claude 3 | Via API | Via API |
| **Vertex AI** | Gemini via GCP | Via GCP | Via GCP |
### Role-Specific Configuration
As of recent releases, LightRAG supports configuring separate LLM models for different tasks:
```python
# Example: Role-specific LLM configuration
LightRAG(
llm_model_name="gpt-4", # Default: Query answering
llm_model_name_extract="gpt-4", # Entity extraction
llm_model_name_keywords="gpt-3.5", # Keyword extraction
llm_model_name_vlm="gpt-4-vision", # Vision model for images
)
```
---
## Common Architecture Patterns
### Auto Storage Detection
LightRAG can automatically detect and use available storage backends based on environment configuration:
```python
# Automatic backend selection based on available services
LightRAG(
vector_storage="AutoVectorStorage", # Detects available vector DB
graph_storage="AutoGraphStorage", # Detects available graph DB
kv_storage="AutoKVStorage", # Detects available KV store
doc_status_storage="AutoDocStatusStorage", # Auto-detection
)
```
### Token Budget Management
LightRAG implements a unified token control system to manage context size during queries:
```mermaid
graph TB
A[Query Request] --> B{Token Budget Allocator}
B --> C[Entity Tokens]
B --> D[Relationship Tokens]
B --> E[Chunk Tokens]
B --> F[System Prompt Tokens]
C --> G[Budget Limit Check]
D --> G
E --> G
F --> G
G --> H{Total Within Limit?}
H -->|No| I[Prune Low-Score Items]
I --> G
H -->|Yes| J[Execute Query]
```
---
## Architecture Considerations
### Scalability Notes
- **Large-Scale Imports**: Use `ainsert_custom_kg` for batch graph operations to improve performance during bulk data ingestion. Source: [GitHub Release v1.4.14](https://github.com/HKUDS/LightRAG/releases/tag/v1.4.14)
- **Event Loop Blocking**: Cooperative yielding prevents blocking during large batch operations. Source: [GitHub Release v1.4.13](https://github.com/HKUDS/LightRAG/releases/tag/v1.4.13)
- **PostgreSQL Performance**: Batch upserts use 200 records per operation for optimal throughput. Source: [GitHub Release v1.4.12](https://github.com/HKUDS/LightRAG/releases/tag/v1.4.12)
### Production Deployment
For production use cases, consider:
1. **Storage Backend**: Use managed services (PostgreSQL, Neo4j Aura, OpenSearch) for production; local JSON/MongoDB for development
2. **LLM Capacity**: Require at least 32B parameter models with 32K+ context for optimal entity extraction
3. **Reranking**: Enable reranker models (e.g., `BAAI/bge-reranker-v2-m3`) and use `mix` mode as default
4. **Authentication**: Configure bcrypt-prefixed passwords and token-based access
---
## See Also
- [ProgramingWithCore.md](./ProgramingWithCore.md) - Core API reference and integration patterns
- [AdvancedFeatures.md](./AdvancedFeatures.md) - Token tracking, observability, and evaluation
- [InteractiveSetup.md](./InteractiveSetup.md) - Setup wizard and deployment configuration
- [DockerDeployment.md](./DockerDeployment.md) - Container deployment guide
- [OfflineDeployment.md](./OfflineDeployment.md) - Air-gapped environment setup
- [LightRAG-API-Server.md](./LightRAG-API-Server.md) - Server API documentation
- [Algorithm.md](./Algorithm.md) - Core retrieval algorithms and indexing process
---
## Text Chunking Strategies
### Related Pages
Related topics: [System Architecture](#page-architecture), [Multimodal Document Processing](#page-multimodal)
Related Source Files
The following source files were used to generate this page:
- [lightrag/chunker/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/__init__.py)
- [lightrag/chunker/paragraph_semantic.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/paragraph_semantic.py)
- [lightrag/chunker/recursive_character.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/recursive_character.py)
- [lightrag/chunker/semantic_vector.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/semantic_vector.py)
- [lightrag/chunker/token_size.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/token_size.py)
- [docs/ParagraphSemanticChunking.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ParagraphSemanticChunking.md)
# Text Chunking Strategies
This page documents the text chunking strategies available in LightRAG for breaking documents into manageable pieces suitable for embedding, retrieval, and knowledge graph extraction.
## Overview
Text chunking is a critical preprocessing step in LightRAG's pipeline that divides documents into smaller, semantically coherent segments. The choice of chunking strategy affects retrieval quality, entity extraction accuracy, and overall system performance.
Source: [lightrag/chunker/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/__init__.py)
### Why Chunking Matters
- **Token Limits**: LLM context windows have finite capacity; chunks must fit within these limits while preserving semantic meaning
- **Retrieval Precision**: Smaller, focused chunks enable more accurate retrieval matching
- **Entity Extraction**: Knowledge graph extraction benefits from chunks that align with natural text boundaries (paragraphs, sentences)
- **Overlap Preservation**: Strategic overlapping maintains context continuity between chunks
## Architecture
```mermaid
graph TD
A[Raw Document Input] --> B[Chunking Strategy Selection]
B --> C[Paragraph Semantic]
B --> D[Recursive Character]
B --> E[Semantic Vector]
B --> F[Token Size]
C --> G[Chunk 1..N]
D --> G
E --> G
F --> G
G --> H[Embedding Generation]
G --> I[Knowledge Graph Extraction]
H --> J[Vector Storage]
I --> K[Graph Storage]
```
## Available Chunking Strategies
LightRAG provides four built-in chunking strategies, each suited for different document types and use cases.
Source: [lightrag/chunker/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/__init__.py)
### Comparison Table
| Strategy | Best For | Preserves Semantics | Speed | Configuration Complexity |
|----------|----------|---------------------|-------|-------------------------|
| **Paragraph Semantic** | Structured documents, reports | High | Medium | Low |
| **Recursive Character** | Code, unstructured text | Medium | Fast | Medium |
| **Semantic Vector** | Large documents, diverse content | High | Slow | High |
| **Token Size** | Precise token control | Low | Fast | Low |
## Paragraph Semantic Chunking
The default and recommended strategy that splits text at paragraph boundaries while respecting semantic units.
Source: [lightrag/chunker/paragraph_semantic.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/paragraph_semantic.py)
### How It Works
1. Text is split by paragraph boundaries (double newlines `\n\n`)
2. Each paragraph forms a base chunk
3. Paragraphs exceeding the token limit are recursively split by sentences
4. Adjacent short paragraphs are merged to form coherent chunks
5. Overlap tokens preserve cross-boundary context
```mermaid
graph LR
A[Text Input] --> B[Split by \n\n]
B --> C{Within Token Limit?}
C -->|Yes| D[Create Chunk]
C -->|No| E[Split by Sentence]
E --> F{Merged Size OK?}
F -->|No| G[Recursive Split]
G --> H[Merge Small Paragraphs]
H --> D
D --> I[Add Overlap Tokens]
```
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chunk_token_size` | int | 512 | Target tokens per chunk |
| `chunk_overlap_token_size` | int | 128 | Overlapping tokens between chunks |
| `delimiter` | str | `\n\n` | Primary splitting delimiter |
### Usage Example
```python
from lightrag.chunker.paragraph_semantic import ParagraphChunker
chunker = ParagraphChunker(
chunk_token_size=512,
chunk_overlap_token_size=128,
delimiter="\n\n"
)
chunks = chunker.chunk(document_text)
```
Source: [docs/ParagraphSemanticChunking.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ParagraphSemanticChunking.md)
### Best Practices
- Use for documents with clear paragraph structure (articles, reports, documentation)
- Increase `chunk_token_size` for summarization tasks
- Decrease for precise entity extraction scenarios
## Recursive Character Chunking
A hierarchical splitting strategy that recursively divides text using multiple character delimiters until chunks fit within the target size.
Source: [lightrag/chunker/recursive_character.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/recursive_character.py)
### Delimiter Hierarchy
The strategy attempts splitting in this order:
1. Double newlines (`\n\n`) — paragraph level
2. Single newlines (`\n`) — line level
3. Spaces (` `) — word level
4. Individual characters — character level (fallback)
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chunk_token_size` | int | 512 | Target tokens per chunk |
| `chunk_overlap_token_size` | int | 128 | Overlapping tokens between chunks |
| `delimiters` | list | See hierarchy | Ordered list of split characters |
| `length_function` | callable | token counter | Function to calculate text length |
### Usage Example
```python
from lightrag.chunker.recursive_character import RecursiveCharacterChunker
chunker = RecursiveCharacterChunker(
chunk_token_size=512,
chunk_overlap_token_size=128,
delimiters=["\n\n", "\n", " ", ""]
)
chunks = chunker.chunk(code_document)
```
### Ideal Use Cases
- Source code files with mixed syntax
- Documents with inconsistent paragraph structure
- When semantic boundaries are unclear
## Semantic Vector Chunking
An advanced strategy that uses embeddings to identify semantically coherent boundaries dynamically.
Source: [lightrag/chunker/semantic_vector.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/semantic_vector.py)
### How It Works
1. Text is pre-split into sentences
2. Sentences are embedded using the configured embedding model
3. Semantic similarity is computed between consecutive sentence embeddings
4. Chunk boundaries are placed where similarity drops below threshold
5. Chunks are assembled until the token limit is reached
```mermaid
graph TD
A[Text Input] --> B[Split into Sentences]
B --> C[Generate Embeddings]
C --> D[Compute Similarity Matrix]
D --> E{Similarity < Threshold?}
E -->|Yes| F[New Chunk Boundary]
E -->|No| G[Add to Current Chunk]
F --> H{Token Limit Reached?}
G --> H
H -->|Yes| I[Finalize Chunk]
I --> J[Return Chunks]
```
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chunk_token_size` | int | 512 | Target tokens per chunk |
| `chunk_overlap_token_size` | int | 128 | Overlapping tokens between chunks |
| `similarity_threshold` | float | 0.5 | Minimum similarity for same chunk |
| `embedding_model` | str | configured model | Model for semantic similarity |
### Usage Example
```python
from lightrag.chunker.semantic_vector import SemanticVectorChunker
chunker = SemanticVectorChunker(
chunk_token_size=512,
chunk_overlap_token_size=128,
similarity_threshold=0.5
)
chunks = chunker.chunk(heterogeneous_document)
```
### Trade-offs
| Advantage | Disadvantage |
|-----------|--------------|
| Adapts to natural semantic boundaries | Requires additional embedding calls |
| Preserves context across sentences | Slower than delimiter-based methods |
| Handles diverse document structures | Threshold tuning required |
## Token Size Chunking
A simple strategy that splits text purely by token count without semantic awareness.
Source: [lightrag/chunker/token_size.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/chunker/token_size.py)
### How It Works
1. Text is split into fixed token-sized blocks
2. Splitting occurs at token boundaries (attempting word boundaries)
3. Overlap ensures continuity between consecutive chunks
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chunk_token_size` | int | 512 | Exact tokens per chunk |
| `chunk_overlap_token_size` | int | 128 | Overlapping tokens between chunks |
### Usage Example
```python
from lightrag.chunker.token_size import TokenSizeChunker
chunker = TokenSizeChunker(
chunk_token_size=512,
chunk_overlap_token_size=128
)
chunks = chunker.chunk(simple_text)
```
## Integration with LightRAG Pipeline
Text chunking integrates with the overall LightRAG indexing pipeline:
```mermaid
graph TD
A[Document Upload] --> B[File Type Detection]
B --> C[Text Extraction]
C --> D[Chunking Strategy Applied]
D --> E[Embedding Generation]
D --> F[Entity Extraction]
D --> G[Relationship Extraction]
E --> H[Vector Storage]
F --> G
G --> I[Graph Storage]
H --> J[Query Interface]
I --> J
```
### Selecting Default Chunking Strategy
The default chunking strategy is configured in the LightRAG initialization:
```python
from lightrag import LightRAG
rag = LightRAG(
chunk_token_size=512,
chunk_overlap_token_size=128,
chunking_strategy="paragraph" # Options: "paragraph", "recursive", "semantic", "token"
)
```
## Configuration Reference
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `CHUNK_TOKEN_SIZE` | Target tokens per chunk | 512 |
| `CHUNK_OVERLAP_TOKEN_SIZE` | Overlapping tokens | 128 |
### API Parameters
When inserting documents via the API:
```json
{
"file": "",
"chunk_token_size": 512,
"chunk_overlap_token_size": 128,
"chunking_strategy": "paragraph"
}
```
## Common Issues and Solutions
### Issue: Documents with Same Name
When multiple documents share the same filename, LightRAG assigns unique document IDs internally. Source attribution uses these IDs rather than filenames. To track source files, LightRAG stores the original `file_path` in the document metadata.
Source: [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts) (DocStatusResponse structure)
### Issue: Chunks Too Large for Context
If retrieved chunks exceed your LLM's context capacity:
1. Reduce `chunk_token_size` to 256 or 128
2. Adjust `max_entity_tokens` and `max_relation_tokens` in query parameters
3. Enable reranking to retrieve only the most relevant chunks
### Issue: Lost Context Between Chunks
If information spans chunk boundaries and is lost during retrieval:
1. Increase `chunk_overlap_token_size`
2. Switch to `paragraph` chunking strategy for better semantic preservation
3. Use `hybrid` or `mix` query mode to combine multiple retrieval strategies
## Performance Considerations
| Strategy | Time Complexity | Memory Usage |
|----------|------------------|--------------|
| Paragraph Semantic | O(n) | Low |
| Recursive Character | O(n) | Low |
| Semantic Vector | O(n × d) | High (embeddings) |
| Token Size | O(n) | Lowest |
*n = document length, d = embedding dimension*
## See Also
- [LightRAG Server Documentation](./LightRAG-API-Server.md)
- [Programming with Core](./ProgramingWithCore.md)
- [Advanced Features](./AdvancedFeatures.md)
- [Interactive Setup Guide](./InteractiveSetup.md)
---
## Storage Backends
### Related Pages
Related topics: [System Architecture](#page-architecture), [Programming with LightRAG Core](#page-programming-core)
Related Source Files
The following source files were used to generate this page:
- [lightrag/kg/factory.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/factory.py)
- [lightrag/kg/neo4j_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py)
- [lightrag/kg/postgres_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py)
- [lightrag/kg/mongo_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py)
- [lightrag/kg/opensearch_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py)
- [lightrag/kg/milvus_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/milvus_impl.py)
- [docs/MilvusConfigurationGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/MilvusConfigurationGuide.md)
# Storage Backends
LightRAG supports multiple storage backends for its four core storage types: KV storage, Vector storage, Graph storage, and Document Status storage. This modular architecture allows deployment flexibility—from single-node development setups using SQLite and NetworkX to production-grade deployments using enterprise databases like PostgreSQL, MongoDB, OpenSearch, or Neo4j.
## Architecture Overview
LightRAG's storage layer follows a factory pattern where each storage type can be independently configured with a different backend. The `StorageFactory` class in `lightrag/kg/factory.py` serves as the central registry that maps storage type names to their implementation classes.
```mermaid
graph TD
A[LightRAG Core] --> B[StorageFactory]
B --> C[KV Storage]
B --> D[Vector Storage]
B --> D1[Graph Storage]
B --> E[DocStatus Storage]
C --> C1[SqliteKVImpl
Default]
C --> C2[NetworkXImpl]
C --> C3[MongoKVImpl]
C --> C4[PostgresKVImpl]
C --> C5[OpenSearchKVImpl]
D --> D1[MilvusVectorImpl]
D --> D2[PostgresVectorImpl]
D --> D3[MongoVectorImpl]
D --> D4[OpenSearchVectorImpl]
D1 --> D1a[NetworkXImpl
Default]
D1 --> D1b[Neo4jGraphImpl]
D1 --> D1c[PostgresGraphImpl]
D1 --> D1d[MongoGraphImpl]
D1 --> D1e[OpenSearchGraphImpl]
E --> E1[NetworkXImpl
Default]
E --> E2[SqliteDocStatusImpl]
E --> E3[MongoDocStatusImpl]
E --> E4[PostgresDocStatusImpl]
E --> E5[OpenSearchDocStatusImpl]
```
## Storage Types
LightRAG organizes its data into four distinct storage types, each serving a specific purpose in the retrieval pipeline:
| Storage Type | Purpose | Default Backend | Key Data |
|-------------|---------|-----------------|----------|
| **KV Storage** | Stores text chunks and raw content | SqliteKVImpl | Document chunks, full text content |
| **Vector Storage** | Stores embedding vectors for similarity search | NetworkXImpl | Float arrays with associated metadata |
| **Graph Storage** | Stores entities and relationships (Knowledge Graph) | NetworkXImpl | Nodes, edges, attributes |
| **DocStatus Storage** | Tracks document processing state | SqliteDocStatusImpl | Processing status, file metadata |
### KV Storage
The KV (Key-Value) storage holds the raw text content extracted from documents. Each chunk is stored with a unique identifier and associated metadata including the source document reference.
Key operations exposed by the KV storage interface:
- `kv_get(key)`: Retrieve value by key
- `kv_get_list(keys)`: Batch retrieve values
- `kv_set(key, value)`: Store key-value pair
- `kv_delete(key)`: Remove entry
- `kv_index_done()`: Signal batch indexing completion
### Vector Storage
Vector storage maintains high-dimensional embedding vectors generated from text chunks. This enables semantic similarity search during query-time retrieval.
Key operations exposed by the vector storage interface:
- `vector_search(query, top_k)`: Find similar vectors
- `vector_insert(vid, vector, metadata)`: Store embedding
- `vector_delete(vid)`: Remove embedding
- `vector_get(vid)`: Retrieve by ID
### Graph Storage
The Knowledge Graph storage captures entities and relationships extracted from documents. This structured representation enables global retrieval strategies that traverse relationship networks.
Key data structures:
- **Entities**: Nodes with type, name, description, and source chunk reference
- **Relationships**: Edges with source/target entity references, description, and weight
Key operations exposed by the graph storage interface:
- `get_entities(实体查询)`: Retrieve entities by pattern
- `get_relationships(关系查询)`: Retrieve relationships by pattern
- `insert_entities(entities)`: Batch insert entity nodes
- `insert_relations(relations)`: Batch insert relationship edges
- `delete_entity(entity_id)`: Remove entity and connected edges
- `delete_relation(relation_id)`: Remove specific relationship
### DocStatus Storage
Document status tracking maintains processing state for each uploaded document. This enables tracking of:
- Processing progress (pending, processing, completed, failed)
- File metadata (path, hash, timestamps)
- Error information for failed documents
## Supported Backend Implementations
### Default Backends (Development)
For local development and testing, LightRAG includes lightweight default implementations:
| Implementation | File | Storage Types | Notes |
|---------------|------|---------------|-------|
| `SqliteKVImpl` | storage/sqlite_kv_impl.py | KV | SQLite-based key-value store |
| `SqliteDocStatusImpl` | storage/sqlite_impl.py | DocStatus | SQLite with structured schema |
| `NetworkXImpl` | storage/networkx_impl.py | Vector, Graph | In-memory using NetworkX |
Source: [lightrag/kg/factory.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/factory.py)
### Neo4j (Graph Storage)
Neo4j provides enterprise-grade graph database capabilities with Cypher query language support.
**Configuration Options:**
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `NEO4J_URI` | Neo4j connection URI | bolt://localhost:7687 |
| `NEO4J_USERNAME` | Database username | neo4j |
| `NEO4J_PASSWORD` | Database password | password |
| `NEO4J_DATABASE` | Database name | neo4j |
**Schema:**
```cypher
// Entity nodes
(:Entity {
entity_id: string,
entity_type: string,
entity_name: string,
description: string,
source_chunk_id: string
})
// Relationship edges
[:RELATED_TO {
relation_id: string,
src_id: string,
tgt_id: string,
description: string,
weight: float
}]
```
Source: [lightrag/kg/neo4j_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py)
### PostgreSQL
PostgreSQL with the pgvector extension provides a unified relational backend for all storage types.
**Configuration Options:**
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `POSTGRES_HOST` | Database host | localhost |
| `POSTGRES_PORT` | Database port | 5432 |
| `POSTGRES_USER` | Database user | postgres |
| `POSTGRES_PASSWORD` | Database password | postgres |
| `POSTGRES_DATABASE` | Database name | postgres |
| `POSTGRES_ENABLE_VECTOR` | Enable pgvector extension | true |
**Table Schemas:**
```sql
-- Entities table
CREATE TABLE IF NOT EXISTS entities (
entity_id TEXT PRIMARY KEY,
entity_type TEXT,
entity_name TEXT,
description TEXT,
source_chunk_id TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Relationships table
CREATE TABLE IF NOT EXISTS relations (
relation_id TEXT PRIMARY KEY,
src_id TEXT,
tgt_id TEXT,
description TEXT,
weight REAL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Vector table (requires pgvector)
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS vectors (
id TEXT PRIMARY KEY,
vector VECTOR(1536),
metadata JSONB
);
```
Source: [lightrag/kg/postgres_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/postgres_impl.py)
### MongoDB
MongoDB provides flexible document storage with native vector search capabilities in MongoDB Atlas.
**Configuration Options:**
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `MONGO_URI` | MongoDB connection URI | mongodb://localhost:27017 |
| `MONGO_DATABASE` | Database name | lightrag |
| `ATLAS_LOCAL` | Use Atlas Local Docker | false |
**Collection Schemas:**
```javascript
// Entities collection
{
entity_id: String,
entity_type: String,
entity_name: String,
description: String,
source_chunk_id: String,
created_at: Date
}
// Vectors collection (with $vectorSearch index)
{
_id: String,
vector: [Number], // Requires vector index
metadata: Object
}
// DocStatus collection
{
doc_id: String,
file_path: String,
content_hash: String,
status: String, // "pending", "processing", "completed", "failed"
error_msg: String,
created_at: Date,
updated_at: Date
}
```
Source: [lightrag/kg/mongo_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/mongo_impl.py)
### OpenSearch
OpenSearch provides a unified storage backend supporting all four storage types, introduced in v1.4.11.
**Configuration Options:**
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `OPENSEARCH_HOST` | OpenSearch host | localhost |
| `OPENSEARCH_PORT` | HTTP port | 9200 |
| `OPENSEARCH_USER` | Authentication user | admin |
| `OPENSEARCH_PASSWORD` | Authentication password | admin |
| `OPENSEARCH_USE_SSL` | Enable HTTPS | false |
| `OPENSEARCH_INDEX_PREFIX` | Index name prefix | lightrag |
**Index Mappings:**
```json
// entities index
{
"mappings": {
"properties": {
"entity_id": { "type": "keyword" },
"entity_type": { "type": "keyword" },
"entity_name": { "type": "text" },
"description": { "type": "text" },
"source_chunk_id": { "type": "keyword" }
}
}
}
// vectors index (with approximate k-NN)
{
"settings": {
"index": {
"knn": true
}
},
"mappings": {
"properties": {
"id": { "type": "keyword" },
"vector": { "type": "knn_vector", "dimension": 1536 }
}
}
}
```
**Important Note:** OpenSearch versions below 3.3.0 have a breaking change related to PIT (Point-In-Time) search. Ensure you use OpenSearch 3.3.0 or later for compatibility.
Source: [lightrag/kg/opensearch_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/opensearch_impl.py)
### Milvus
Milvus is a dedicated vector database optimized for high-performance similarity search at scale.
**Configuration Options:**
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `MILVUS_URI` | Milvus server URI | http://localhost:19530 |
| `MILVUS_TOKEN` | Authentication token | (empty) |
| `MILVUS_DB_NAME` | Database name | default |
| `MILVUS_INDEX_TYPE` | Index algorithm | IVF_FLAT |
| `MILVUS_METRIC_TYPE` | Distance metric | IP |
| `MILVUS_LIMITS` | Search result limit | 100 |
**Collection Schema:**
```python
{
"collection_name": "lightrag_vectors",
"dimension": 1536, # Matches embedding model dimension
"description": "LightRAG vector embeddings",
"enable_dynamic_field": True,
"fields": [
{"name": "id", "type": DataType.VARCHAR, "max_length": 256, "is_primary": True},
{"name": "vector", "type": DataType.FLOAT_VECTOR, "dim": 1536},
{"name": "metadata", "type": DataType.JSON}
]
}
```
**Index Types Supported:**
| Index Type | Description |
|------------|-------------|
| `FLAT` | Brute-force search, exact results |
| `IVF_FLAT` | Inverted index with L2 distance |
| `IVF_SQ8` | Scalar quantized IVF |
| `HNSW` | Hierarchical navigable small world |
| `ANNOY` | Approximate nearest neighbors |
Source: [lightrag/kg/milvus_impl.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/milvus_impl.py)
Source: [docs/MilvusConfigurationGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/MilvusConfigurationGuide.md)
## Configuration Guide
### Environment Variables
Storage backends are configured through environment variables. The `StorageFactory` reads these at initialization:
```bash
# KV Storage Backend
KV_STORAGE="Neo4jKVImpl" # Options: SqliteKVImpl, Neo4jKVImpl, PostgresKVImpl, MongoKVImpl, OpenSearchKVImpl
# Vector Storage Backend
VECTOR_STORAGE="MilvusVectorImpl" # Options: NetworkXImpl, PostgresVectorImpl, MongoVectorImpl, MilvusVectorImpl, OpenSearchVectorImpl
# Graph Storage Backend
GRAPH_STORAGE="Neo4jGraphImpl" # Options: NetworkXImpl, Neo4jGraphImpl, PostgresGraphImpl, MongoGraphImpl, OpenSearchGraphImpl
# DocStatus Storage Backend
DOC_STATUS_STORAGE="Neo4jDocStatusImpl" # Options: SqliteDocStatusImpl, Neo4jDocStatusImpl, PostgresDocStatusImpl, MongoDocStatusImpl, OpenSearchDocStatusImpl
```
### Using the Setup Wizard
LightRAG provides an interactive setup wizard to configure storage backends:
```bash
# Initialize base configuration (LLM, embedding, reranker)
make env-base
# Configure storage backends
make env-storage
# Review and audit configuration
make env-security-check
```
The wizard generates a `.env` file and `docker-compose.final.yml` with appropriate service definitions.
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
## Backend Selection Guidelines
### Development and Testing
For local development and testing, use default backends:
```python
# No special configuration needed - defaults to:
# KV: SqliteKVImpl
# Vector: NetworkXImpl
# Graph: NetworkXImpl
# DocStatus: SqliteDocStatusImpl
```
### Single-Node Production
For single-node production deployments:
| Use Case | Recommended Backend | Reasoning |
|----------|---------------------|-----------|
| Small scale (<100K docs) | PostgreSQL | Unified storage, easy backup |
| Medium scale (<1M docs) | PostgreSQL + pgvector | Good performance, SQL interface |
| Large scale (>1M docs) | Milvus | Optimized vector operations |
### Distributed Production
For distributed deployments requiring high availability:
| Component | Recommended Backend | Features |
|-----------|--------------------|----------|
| Graph | Neo4j | Cypher queries, HA clustering |
| Vector | Milvus | Distributed shards, replication |
| KV | MongoDB | Flexible schema, Atlas Search |
| DocStatus | MongoDB | Atomic updates, change streams |
## Storage Backend Migration
When migrating between storage backends, note that:
1. **Data Format Compatibility**: Each backend stores data in its native format. Direct migration requires ETL scripts.
2. **Graph Data**: Entity and relationship semantics are preserved across backends, but indexing strategies differ.
3. **Vector Data**: Embedding dimensions must match the configured embedding model.
4. **DocStatus**: Document IDs are consistent, but status schemas may vary slightly.
### Exporting Knowledge Graph Data
LightRAG supports exporting graph data for migration:
```python
from lightrag import LightRAG
rag = LightRAG()
# Export all entities and relationships
entities = rag KG_EXTRACTION_FUNC(...)
relations = rag.get_relations(...)
# Import to new backend
new_rag = LightRAG(graph_storage="Neo4jGraphImpl")
new_rag.ainsert_custom_kg(entities, relations)
```
## Common Issues and Troubleshooting
### Connection Failures
**Symptom**: `ConnectionError` when initializing storage
**Resolution**:
1. Verify database service is running
2. Check firewall rules for port access
3. Validate credentials in environment variables
4. Test connection with native client tools
### Schema Mismatches
**Symptom**: Query returns empty results despite data existing
**Resolution**:
1. Check index creation completed successfully
2. Verify embedding dimension matches configuration
3. For OpenSearch, ensure index mapping is correct
4. Check for case sensitivity issues in field names
### Performance Degradation
**Symptom**: Slow retrieval or indexing operations
**Resolution**:
1. For vector storage, verify index is created (not `FLAT` for large datasets)
2. Check connection pool settings
3. Monitor database resource usage (CPU, memory, disk I/O)
4. Consider batching operations for bulk inserts
### Document Identification
**Issue**: Users have asked how to distinguish documents with the same filename but different content.
**Current Behavior**: LightRAG uses content hash (`content_hash`) to detect duplicates, not filename alone.
**Source Files**: Document status storage tracks `file_path` and `content_hash` independently, enabling duplicate detection based on content rather than name.
Source: [GitHub Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
## See Also
- [ProgramingWithCore.md](./ProgramingWithCore.md) - Core API reference including storage initialization
- [InteractiveSetup.md](./InteractiveSetup.md) - Setup wizard documentation
- [DockerDeployment.md](./DockerDeployment.md) - Containerized deployment with storage services
- [AdvancedFeatures.md](./AdvancedFeatures.md) - Additional features including multimodal processing
- [MilvusConfigurationGuide.md](./MilvusConfigurationGuide.md) - Detailed Milvus setup guide
---
## API Server
### Related Pages
Related topics: [Programming with LightRAG Core](#page-programming-core), [Deployment Guide](#page-deployment)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
- [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
- [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
# API Server
The LightRAG API Server is a FastAPI-based backend service that provides a comprehensive REST API for document management, knowledge graph operations, and RAG querying. It powers the LightRAG WebUI and enables programmatic access to all LightRAG core functionalities through a well-documented API.
## Overview
The API Server serves as the primary interface for interacting with LightRAG's capabilities. It combines document ingestion pipelines, knowledge graph extraction, vector storage operations, and query processing into a unified service layer.
Source: [README.md:1-50](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Key Capabilities
| Capability | Description |
|------------|-------------|
| **Document Management** | Upload, index, track status, and delete documents |
| **Knowledge Graph Operations** | Extract, query, and visualize entity relationships |
| **RAG Querying** | Multiple retrieval modes including naive, local, global, hybrid, and mix |
| **Ollama-Compatible API** | Emulates Ollama chat model interface for integration with AI tools |
| **Authentication** | Token-based authentication with configurable security |
| **Multimodal Processing** | PDF, Office documents, images, tables, and formula extraction |
Source: [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
## Architecture
```mermaid
graph TD
subgraph "API Server Layer"
A[FastAPI Application] --> B[Document Routes]
A --> C[Query Routes]
A --> D[Graph Routes]
A --> E[Auth Routes]
end
subgraph "LightRAG Core"
F[Document Pipeline] --> G[Entity Extraction]
F --> H[Vector Storage]
G --> I[Knowledge Graph Storage]
H --> I
end
subgraph "Storage Backends"
J[(PostgreSQL)]
K[(MongoDB)]
L[(OpenSearch)]
M[(NetworkX)]
end
B --> F
C --> G
C --> H
D --> I
I --> J
I --> K
I --> L
H --> M
subgraph "External Integrations"
N[LLM Providers]
O[Embedding Services]
P[Reranker Models]
end
G --> N
O --> H
P --> C
```
### Request Flow
```mermaid
sequenceDiagram
participant Client
participant APIServer as API Server
participant LightRAG as LightRAG Core
participant Storage as Storage Backend
participant LLM as LLM Provider
Client->>APIServer: POST /query
APIServer->>APIServer: Validate Request
APIServer->>LightRAG: Retrieve Context
LightRAG->>Storage: Vector/Graph Query
Storage->>LightRAG: Context Results
LightRAG->>LLM: Generate Response
LLM->>APIServer: Generated Answer
APIServer->>Client: Query Response
```
Source: [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
## Query Modes
LightRAG supports six distinct query modes, each optimized for different retrieval strategies:
| Mode | Description | Use Case |
|------|-------------|----------|
| `naive` | Basic vector search without advanced techniques | Simple lookups |
| `local` | Context-dependent retrieval using knowledge graph neighbors | Entity-specific queries |
| `global` | Global knowledge graph traversal | Wide-ranging topic exploration |
| `hybrid` | Combines local and global methods | Balanced comprehensive queries |
| `mix` | Integrates knowledge graph and vector retrieval with reranking | Complex mixed queries (default) |
| `bypass` | Direct LLM response without retrieval | General knowledge questions |
Source: [lightrag_webui/src/api/lightrag.ts:10](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
### Query Request Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | Yes | - | The search query text |
| `mode` | QueryMode | Yes | - | Retrieval mode (see table above) |
| `only_need_context` | boolean | No | false | Return only retrieved context, no response |
| `only_need_prompt` | boolean | No | false | Return generated prompt without response |
| `response_type` | string | No | - | Response format (e.g., 'Multiple Paragraphs', 'Single Paragraph', 'Bullet Points') |
| `stream` | boolean | No | false | Enable streaming output |
| `top_k` | number | No | - | Number of top items to retrieve |
| `chunk_top_k` | number | No | - | Maximum text chunks after reranking |
| `max_entity_tokens` | number | No | - | Max tokens for entity context |
| `max_relation_tokens` | number | No | - | Max tokens for relationship context |
| `max_total_tokens` | number | No | - | Total token budget for entire query |
Source: [lightrag_webui/src/api/lightrag.ts:20-40](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## Document Management API
### Supported File Types
The API Server processes documents through an intelligent pipeline that handles multiple formats:
| Category | MIME Types | Extensions |
|----------|------------|------------|
| **Text** | `text/plain`, `text/markdown`, `text/html`, `text/csv` | `.txt`, `.md`, `.html`, `.csv` |
| **Documents** | `application/pdf` | `.pdf` |
| **Office** | Word, PowerPoint, Excel formats | `.docx`, `.pptx`, `.xlsx` |
| **Code** | Various programming languages | `.py`, `.js`, `.ts`, `.java`, `.go`, etc. |
| **Config** | JSON, YAML, XML | `.json`, `.yaml`, `.yml`, `.xml` |
| **Other** | SQL, Shell, C/C++ | `.sql`, `.sh`, `.c`, `.cpp` |
Source: [lightrag_webui/src/lib/constants.ts:1-80](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
### Document Upload
Documents are uploaded through the pipeline endpoint where they are:
1. Received and validated
2. Parsed for content extraction
3. Chunked into manageable segments
4. Processed through the entity extraction pipeline
5. Stored in configured storage backends
### Document Status Tracking
The API tracks document processing status through a comprehensive status system:
| Status | Description |
|--------|-------------|
| `pending` | Document queued for processing |
| `processing` | Currently being indexed |
| `completed` | Successfully indexed |
| `failed` | Processing error occurred |
| `deleted` | Document removed from index |
Source: [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
## Authentication
### Auth Configuration
The API Server supports token-based authentication with the following configuration options:
| Environment Variable | Description |
|---------------------|-------------|
| `AUTH_ENABLED` | Enable/disable authentication |
| `AUTH_SECRET_KEY` | Secret key for JWT token signing |
| `AUTH_TOKEN_EXPIRE_MINUTES` | Token expiration time |
Source: [docs/LightRAG-API-Server.md](https://github.com/HKUDS/LightRAG/blob/main/docs/LightRAG-API-Server.md)
### Auth Status Response
```typescript
interface AuthStatusResponse {
auth_configured: boolean
access_token?: string
token_type?: string
auth_mode?: 'enabled' | 'disabled'
message?: string
core_version?: string
api_version?: string
webui_title?: string
webui_description?: string
}
```
Source: [lightrag_webui/src/api/lightrag.ts:150-160](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## Runtime Configuration
The API Server supports dynamic path prefix configuration for reverse proxy deployments. This addresses the known issue with sub-path deployments mentioned in community issue #2755.
### Path Prefix Resolution
```typescript
interface RuntimeConfig {
apiPrefix?: string // API endpoint prefix
webuiPrefix?: string // WebUI mount path
}
```
The server resolves paths at request time rather than build time, allowing a single build to serve multiple reverse proxy mount points.
Source: [lightrag_webui/src/lib/runtimeConfig.ts:1-40](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
### Prefix Normalization
| Input | Normalized Output |
|-------|-------------------|
| `""`, `undefined`, `"/"` | `/webui/` |
| `/custom` | `/custom/` |
| `/custom/path/` | `/custom/path/` |
The `normalizeWebuiPrefix` function ensures consistent path handling with a leading `/` and trailing `/`.
Source: [lightrag_webui/src/lib/pathPrefix.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/pathPrefix.ts)
## Ollama-Compatible Interface
LightRAG Server provides an Ollama-compatible API endpoint, allowing it to be used as a drop-in replacement for Ollama in tools like Open WebUI. This interface:
- Emulates the Ollama chat model API
- Accepts standard Ollama request formats
- Returns responses compatible with Ollama clients
- Enables seamless integration with existing AI toolchains
Source: [README.md:20-25](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Pipeline Status Monitoring
The API provides real-time pipeline status for monitoring document processing:
```typescript
interface PipelineStatusResponse {
autoscanned: boolean
busy: boolean
job_name: string
job_start?: string
docs: number
batchs: number
cur_batch: number
request_pending: boolean
cancellation_requested?: boolean
latest_message: string
history_messages?: string[]
update_status?: Record
}
```
Source: [lightrag_webui/src/api/lightrag.ts:165-180](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
### Queue Status Monitoring
The API also exposes queue statistics for LLM and embedding operations:
| Field | Description |
|-------|-------------|
| `llm_queue_status` | Current LLM request queue status |
| `embedding_queue_status` | Current embedding queue status |
| `rerank_queue_status` | Current reranking queue status |
Source: [lightrag_webui/src/api/lightrag.ts:120-130](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## WebUI Integration
The WebUI is a React-based frontend that consumes the API Server. It provides:
- **Document Management**: Upload, browse, and delete documents
- **Knowledge Graph Visualization**: Interactive graph exploration with Sigma.js
- **Query Interface**: Execute queries with mode selection
- **System Status**: Real-time pipeline and queue monitoring
### Building the WebUI
```bash
cd lightrag_webui
bun install --frozen-lockfile
bun run build
```
The built assets are served from `lightrag/api/webui/` by the API Server.
Source: [lightrag_webui/README.md:10-25](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
### API Client
The WebUI uses a TypeScript API client (`lightrag.ts`) that provides:
- Axios-based HTTP client with automatic token refresh
- Type-safe request/response definitions
- Silent token refresh for guest sessions
- Request queuing during token refresh
Source: [lightrag_webui/src/api/lightrag.ts:180-220](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
## Installation and Deployment
### Docker Deployment
The recommended deployment method uses Docker Compose:
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env # Configure LLM and embedding settings
docker compose up
```
### Interactive Setup Wizard
For non-Docker deployments, use the setup wizard:
```bash
make env-base # Configure LLM, embedding, reranker
make env-storage # Configure storage backends
make env-server # Configure server settings
```
Source: [README.md:60-90](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `LIGHTRAG_OPENAI_API_KEY` | OpenAI API key for LLM | Yes |
| `LIGHTRAG_EMBEDding_API_KEY` | Embedding service API key | Yes |
| `LIGHTRAG_RERANKER_MODEL` | Reranker model name | No |
| `LIGHTRAG_STORAGE_BACKEND` | Storage backend type | No |
| `AUTH_ENABLED` | Enable authentication | No |
## Common Issues and Solutions
### Reverse Proxy Sub-Path Deployment
**Issue**: Application uses absolute paths for resources, causing issues behind reverse proxies.
**Solution**: The API Server now supports runtime path prefix configuration. Set `LIGHTRAG_API_PREFIX` and `LIGHTRAG_WEBUI_PATH` environment variables for your reverse proxy mount point.
Source: [lightrag_webui/src/lib/runtimeConfig.ts:1-30](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
### Document Identification
**Issue**: How to distinguish documents with the same name but different content (Issue #3158).
**Solution**: The system tracks documents by a unique document ID assigned during upload. Use the `/documents` API with pagination to browse and identify documents by their ID and metadata.
### Source File Attribution
**Issue**: How to return source files used to answer queries (Issue #323).
**Solution**: Enable citation functionality (added in v2025.03). Query responses include source attribution when citations are enabled in the configuration.
## See Also
- [LightRAG Core Programming Guide](./ProgramingWithCore.md)
- [Advanced Features](./AdvancedFeatures.md)
- [Interactive Setup Guide](./InteractiveSetup.md)
- [Docker Deployment](./DockerDeployment.md)
- [Offline Deployment](./OfflineDeployment.md)
---
## Programming with LightRAG Core
### Related Pages
Related topics: [API Server](#page-api-server), [System Architecture](#page-architecture)
Related Source Files
The following source files were used to generate this page:
- [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py)
- [lightrag/llm/openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/openai.py)
- [lightrag/llm/ollama.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/ollama.py)
- [lightrag/llm/gemini.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/gemini.py)
- [lightrag/llm/azure_openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/azure_openai.py)
- [lightrag/llm/hf.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/hf.py)
- [lightrag/rerank.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/rerank.py)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
- [examples](https://github.com/HKUDS/LightRAG/blob/main/examples)
- [docs/ProgramingWithCore.md](https://github.com/HKUDS/LightRAG/blob/main/docs/ProgramingWithCore.md)
- [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
# Programming with LightRAG Core
This page documents the programmatic API for LightRAG Core — the underlying Python library that powers the LightRAG system. LightRAG Core is designed for embedded applications, researchers conducting studies and evaluations, and developers who need fine-grained control over the retrieval and generation pipeline.
> **Note:** If you want to integrate LightRAG into your project, the documentation recommends utilizing the **REST API provided by the LightRAG Server** for most production use cases. LightRAG Core is intended for embedded applications or for researchers who wish to conduct studies and evaluations.
>
> Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Overview
LightRAG Core provides a Python-native interface for:
- **Document indexing** with automatic entity and relationship extraction
- **Knowledge graph construction** from unstructured text
- **Hybrid retrieval** combining vector similarity, knowledge graph traversal, and keyword matching
- **Query answering** with configurable retrieval modes
- **Storage backend abstraction** supporting multiple databases
The library uses an asynchronous architecture to handle high-throughput document processing and concurrent queries efficiently.
## Architecture
```mermaid
graph TB
subgraph "Input Processing"
DOC[("Documents")] --> CHUNK[("Chunking")]
CHUNK --> EMBED[("Embedding Model")]
EMBED --> VEC_STORE[("Vector Store")]
CHUNK --> LLM[("LLM Entity Extraction")]
LLM --> KG[("Knowledge Graph")]
end
subgraph "Query Processing"
QUERY[("User Query")] --> QUERY_EMBED[("Query Embedding")]
QUERY_EMBED --> RETRIEVE[("Retrieval Module")]
RETRIEVE --> RERANK[("Reranker")]
RERANK --> LLM_GEN[("LLM Generation")]
LLM_GEN --> RESP[("Response")]
end
subgraph "Storage Backends"
VEC_STORE <--> STORAGE[("KV Store
Vector Store
Graph Store
Doc Status")]
end
```
### Query Modes
LightRAG Core supports six distinct retrieval modes, each optimized for different query types:
| Mode | Description | Best For |
|------|-------------|----------|
| `naive` | Basic vector search without advanced techniques | Simple keyword-based queries |
| `local` | Focuses on context-dependent entity information | Queries about specific entities and their attributes |
| `global` | Utilizes graph traversal for overall knowledge structure | Queries requiring understanding of relationships across entities |
| `hybrid` | Combines local and global retrieval methods | Balanced queries needing both entity details and relationship context |
| `mix` | Integrates knowledge graph and vector retrieval (set as default) | Mixed queries with optimal performance |
| `bypass` | Skips retrieval, uses LLM directly | Scenarios where retrieval is not needed |
> **Note:** When a Reranker model is enabled, it is recommended to set "mix mode" as the default query mode.
>
> Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Installation
### Prerequisites
- Python 3.10 or higher
- uv package manager (recommended) or pip
- LLM and embedding model API keys or local model endpoints
### Installing LightRAG Core
```bash
# Using uv (recommended)
cd LightRAG
uv sync
source .venv/bin/activate # Linux/macOS
# Or: .venv\Scripts\activate # Windows
# Or using pip
pip install lightrag-hku
```
For offline or air-gapped environments, see the [Offline Deployment Guide](./OfflineDeployment.md) for pre-installation instructions.
## Initialization
### Basic Initialization
```python
from lightrag import LightRAG, QueryParam
# Initialize with default settings
rag = LightRAG(
working_dir="./lightrag_working_dir"
)
```
### Configuration Parameters
The `LightRAG` constructor accepts numerous configuration parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `working_dir` | `str` | Required | Directory for storing LightRAG working data |
| `llm_model_name` | `str` | `"gpt-4o-mini"` | LLM model identifier |
| `llm_model_kwargs` | `dict` | `None` | Additional LLM model configuration |
| `embedding_model_name` | `str` | `"text-embedding-3-small"` | Embedding model identifier |
| `embedding_batch_num` | `int` | `256` | Batch size for embedding operations |
| `max_token_num` | `int` | `128` | Maximum tokens per chunk |
| `kv_storage` | `str` | `"DiskKVStorage"` | KV storage backend |
| `vector_storage` | `str` | `"NanoVectorStorage"` | Vector storage backend |
| `graph_storage` | `str` | `"NetworkXStorage"` | Graph storage backend |
| `doc_status_storage` | `str` | `"JsonDocStatusStorage"` | Document status storage backend |
| `chunk_token_size` | `int` | `1200` | Token size for text chunking |
| `chunk_overlap_token_size` | `int` | `100` | Overlap between chunks |
| `tokenizer` | `str` | `"cl100k_base"` | Tokenizer name |
| `llm_binding_name` | `str` | `"openai"` | LLM binding provider |
| `embedding_binding_name` | `str` | `"openai"` | Embedding binding provider |
| `llm_host` | `str` | `None` | LLM API host (for custom endpoints) |
| `embedding_host` | `str` | `None` | Embedding API host (for custom endpoints) |
| `max_parallel_insert` | `int` | `32` | Maximum parallel insert operations |
| `max_async` | `int` | `32` | Maximum async operations |
| `enable_rerank` | `bool` | `False` | Enable reranking |
| `rerank_model_name` | `str` | `None` | Reranker model name |
| `rerank_batch_num` | `int` | `100` | Batch size for reranking |
| `cosine_threshold` | `float` | `0.0` | Minimum cosine similarity for retrieval |
| `summary_language` | `str` | `"English"` | Language for summaries |
Source: [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py) — see `__init__` method
## LLM Provider Configuration
LightRAG Core supports multiple LLM providers through a binding system.
### OpenAI
```python
from lightrag import LightRAG
rag = LightRAG(
llm_binding_name="openai",
llm_model_name="gpt-4o-mini",
embedding_model_name="text-embedding-3-small"
)
```
Environment variables:
- `OPENAI_API_KEY` — API key for authentication
Source: [lightrag/llm/openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/openai.py)
### Ollama (Local Models)
```python
from lightrag import LightRAG
rag = LightRAG(
llm_binding_name="ollama",
llm_model_name="qwen3-30b-a3b", # Or other local model
llm_host="http://localhost:11434",
embedding_binding_name="ollama",
embedding_model_name="nomic-embed-text",
embedding_host="http://localhost:11434"
)
```
Environment variables:
- `OLLAMA_BASE_URL` — Base URL for Ollama API (defaults to `http://localhost:11434`)
Source: [lightrag/llm/ollama.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/ollama.py)
### Azure OpenAI
```python
from lightrag import LightRAG
rag = LightRAG(
llm_binding_name="azure_openai",
llm_model_name="gpt-4o-mini",
llm_binding_host="https://your-resource.openai.azure.com",
llm_model_kwargs={
"api_version": "2024-06-01",
"azure_deployment": "gpt-4o-mini"
},
embedding_binding_name="azure_openai",
embedding_model_name="text-embedding-3-small",
embedding_host="https://your-resource.openai.azure.com",
embedding_model_kwargs={
"api_version": "2024-06-01",
"azure_deployment": "text-embedding-3-small"
}
)
```
Source: [lightrag/llm/azure_openai.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/azure_openai.py)
### Google Gemini
```python
from lightrag import LightRAG
rag = LightRAG(
llm_binding_name="gemini",
llm_model_name="gemini-2.0-flash",
llm_model_kwargs={
"api_key": "your-gemini-api-key"
}
)
```
For Vertex AI:
```python
rag = LightRAG(
llm_binding_name="gemini",
llm_model_name="gemini-2.0-flash",
llm_model_kwargs={
"vertex_project": "your-project-id",
"vertex_location": "us-central1"
}
)
```
Source: [lightrag/llm/gemini.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/gemini.py)
### HuggingFace Local Inference
```python
from lightrag import LightRAG
rag = LightRAG(
llm_binding_name="hf",
llm_model_name="Qwen/Qwen2.5-7B-Instruct",
llm_model_kwargs={
"device": "cuda", # or "cpu"
"trust_remote_code": True
}
)
```
Source: [lightrag/llm/hf.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm/hf.py)
### Role-Specific LLM Configuration
LightRAG supports configuring different LLM models for different roles:
```python
rag = LightRAG(
role_llm_config={
"EXTRACT": {
"model_name": "gpt-4o",
"llm_host": "https://api.openai.com/v1",
"llm_model_kwargs": {"temperature": 0}
},
"QUERY": {
"model_name": "gpt-4o-mini",
"llm_host": "https://api.openai.com/v1"
},
"KEYWORDS": {
"model_name": "gpt-4o-mini"
},
"VLM": {
"model_name": "gpt-4o"
}
}
)
```
The four roles are:
- **EXTRACT**: Entity and relationship extraction from documents
- **QUERY**: Query processing and answer generation
- **KEYWORDS**: Keyword extraction for search
- **VLM**: Vision Language Model for multimodal processing
## Query Parameters
The `QueryParam` class configures query execution:
```python
from lightrag import QueryParam
param = QueryParam(
mode="mix", # Query mode (naive, local, global, hybrid, mix, bypass)
only_need_context=False, # Return only retrieved context, no LLM response
only_need_prompt=False, # Return only the generated prompt
response_type="Multiple Paragraphs", # Response format
stream=False, # Enable streaming responses
top_k=60, # Number of top items to retrieve
chunk_top_k=80, # Number of chunks after reranking
max_entity_tokens=4000, # Max tokens for entity context
max_relation_tokens=4000, # Max tokens for relationship context
max_total_tokens=16385, # Total token budget
conversation_history=[] # Past conversation messages
)
```
### QueryParam Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | `str` | `"mix"` | Retrieval mode |
| `only_need_context` | `bool` | `False` | Return only retrieved context |
| `only_need_prompt` | `bool` | `False` | Return only the generated prompt |
| `response_type` | `str` | `"Multiple Paragraphs"` | Response format |
| `stream` | `bool` | `False` | Enable streaming |
| `top_k` | `int` | `60` | Top-K items to retrieve (entities for local, relationships for global) |
| `chunk_top_k` | `int` | `80` | Chunks to retrieve and keep after reranking |
| `max_entity_tokens` | `int` | `4000` | Token budget for entity context |
| `max_relation_tokens` | `int` | `4000` | Token budget for relationship context |
| `max_total_tokens` | `int` | `16385` | Total token budget for all context |
| `conversation_history` | `list` | `[]` | Past conversation messages |
| `history_turns` | `int` | `3` | Number of history turns to include |
Source: [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts) — see `QueryRequest` type
## Document Insertion
### Inserting Text
```python
# Insert a single text document
await rag.ainsert(
"LightRAG is a Retrieval-Augmented Generation system that combines vector search with knowledge graph extraction."
)
# Insert with custom identifier
await rag.ainsert(
"LightRAG supports multiple storage backends including Neo4j, PostgreSQL, and MongoDB.",
identifier="custom_doc_id"
)
```
### Batch Insertion
```python
documents = [
"Document 1 content...",
"Document 2 content...",
"Document 3 content..."
]
# Insert multiple documents
results = await rag.ainsert(documents)
```
### Inserting Custom Knowledge Graph Data
```python
# Insert custom entities and relationships directly
custom_kg = {
"entities": [
{
"entity_name": "LightRAG",
"entity_type": "Framework",
"description": "A RAG system combining vector search with knowledge graphs",
"source_id": "doc1"
},
{
"entity_name": "GPT-4",
"entity_type": "Model",
"description": "Large language model by OpenAI",
"source_id": "doc1"
}
],
"relations": [
{
"src_id": "LightRAG",
"tgt_id": "GPT-4",
"relation_type": "uses",
"description": "LightRAG uses GPT-4 for entity extraction",
"weight": 0.9,
"source_id": "doc1"
}
]
}
await rag.ainsert_custom_kg(custom_kg)
```
## Querying
### Basic Query
```python
# Perform a query
result = await rag.aquery(
"What is LightRAG and how does it work?",
param=QueryParam(mode="mix")
)
print(result)
```
### Query with Streaming
```python
param = QueryParam(
mode="mix",
stream=True
)
result = await rag.aquery(
"Explain the architecture of LightRAG",
param=param
)
# Stream the response
async for chunk in result:
print(chunk, end="", flush=True)
```
### Query for Context Only
```python
# Get only retrieved context without LLM response
param = QueryParam(
mode="local",
only_need_context=True
)
contexts = await rag.aquery(
"What entities are related to RAG?",
param=param
)
print(contexts)
```
### Query with Conversation History
```python
conversation = [
{"role": "user", "content": "What is LightRAG?"},
{"role": "assistant", "content": "LightRAG is a RAG system..."},
{"role": "user", "content": "What models does it support?"}
]
param = QueryParam(
mode="mix",
conversation_history=conversation,
history_turns=3
)
result = await rag.aquery(
"How do I configure it?",
param=param
)
```
## Reranker Integration
The reranker improves retrieval quality by reordering initial search results:
```python
from lightrag import LightRAG
from lightrag.rerank import CohereReranker, JinaReranker
# Initialize with reranker
rag = LightRAG(
enable_rerank=True,
rerank_model_name="BAAI/bge-reranker-v2-m3"
)
# Configure reranker options
rag = LightRAG(
enable_rerank=True,
rerank_model_name="BAAI/bge-reranker-v2-m3",
rerank_batch_num=100,
rerank_max_async=32,
rerank_timeout=30,
min_rerank_score=0.0
)
```
Source: [lightrag/rerank.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/rerank.py)
## Entity and Relationship Management
### Query Entities
```python
# Query entities by name pattern
entities = await rag.query_entities(
entity_name="LightRAG",
mode="byEntityName"
)
# Query entities by content
entities = await rag.query_entities(
entity_name="RAG system",
mode="byEntityContent"
)
```
### Query Relationships
```python
# Query relationships
relationships = await rag.query_relations(
entity_info=[("LightRAG", "Framework")],
mode="byRelation"
)
```
### Delete Entities
```python
# Delete an entity by name
await rag.delete_entity(entity_name="LightRAG")
```
### Delete Relationships
```python
# Delete a relationship
await rag.delete_relation(
src_id="LightRAG",
tgt_id="GPT-4",
relation_type="uses"
)
```
### Merge Entities
```python
# Merge source entity into target entity
await rag.merge_entity(
source_entity="LightRAG",
target_entity="LightRAG-Framework"
)
```
## Document Management
### Document Deletion with KG Regeneration
When a document is deleted, LightRAG automatically regenerates the knowledge graph:
```python
# Delete document and regenerate KG
await rag.adelete文书(
document_id="doc_id_123"
)
```
This operation:
1. Removes the document from the doc status storage
2. Removes associated text chunks from vector storage
3. Removes associated entities and relationships from the knowledge graph
4. Regenerates affected knowledge graph structures
> **Note:** Document deletion with automatic KG regeneration ensures optimal query performance after content removal.
>
> Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md) — v1.4.10 release notes
### Document Identification
> **Known Limitation:** When uploading documents with the same filename but different content, LightRAG currently only tracks documents by internal document IDs, not by filename. This means documents with duplicate names may be treated as the same document depending on the upload method used.
>
> Source: [GitHub Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
## Advanced Features
### Token Usage Tracking
```python
from lightrag import LightRAG
rag = LightRAG(
# ... other config
)
# After querying
result = await rag.aquery("Your question", param=QueryParam(mode="mix"))
# Access token usage statistics
if hasattr(rag, 'llm_token_count'):
print(f"LLM Tokens: {rag.llm_token_count}")
if hasattr(rag, 'embedding_token_count'):
print(f"Embedding Tokens: {rag.embedding_token_count}")
```
Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
### Knowledge Graph Data Export
```python
# Export the knowledge graph
kg_data = await rag.export_graph_data()
# kg_data contains:
# {
# "entities": [...],
# "relationships": [...]
# }
```
### LLM Cache Management
```python
# Configure LLM caching
rag = LightRAG(
# ... other config
)
# The cache is automatically used for repeated queries
# To clear the cache:
rag.llm_cache = {} # or implement custom cache clearing
```
### Langfuse Observability Integration
```python
# Enable Langfuse tracing
rag = LightRAG(
# ... other config
)
# Configure Langfuse via environment variables:
# LANGFUSE_PUBLIC_KEY
# LANGFUSE_SECRET_KEY
# LANGFUSE_HOST
```
### RAGAS Evaluation
LightRAG integrates with RAGAS for quality evaluation:
```python
# The evaluation pipeline returns retrieved contexts alongside query results
# This enables context precision metrics calculation
result = await rag.aquery(
"Your question",
param=QueryParam(mode="mix")
)
# Access the response and context for evaluation
# result contains both the generated answer and retrieved contexts
```
Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
## Multimodal Document Processing
LightRAG Core supports multimodal document processing through integration with external parsing services (MinerU or Docling):
```python
# Enable multimodal processing
rag = LightRAG(
vlm_process_enable=True,
role_llm_config={
"VLM": {
"model_name": "gpt-4o",
# VLM configuration for image understanding
}
}
)
```
The multimodal pipeline processes:
- PDFs with images and tables
- Office documents (docx, pptx, xlsx)
- Images with embedded text
- Tables and formulas
> **Note:** Multimodal indexing runs in the LightRAG pipeline. Parsing is handled through external MinerU or Docling services.
>
> Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
## Storage Backend Configuration
### Supported Storage Backends
| Storage Type | Options |
|--------------|---------|
| KV Storage | `DiskKVStorage`, `PostgreSQLStorage`, `MongoKVStorage`, `OpenSearchStorage` |
| Vector Storage | `NanoVectorStorage`, `PGVectorStorage`, `MongoVectorStorage`, `AtlasVectorStorage`, `OpenSearchStorage` |
| Graph Storage | `NetworkXStorage`, `Neo4JStorage`, `OpenSearchStorage` |
| Doc Status | `JsonDocStatusStorage`, `PostgreSQLStorage`, `MongoDocStatusStorage`, `OpenSearchStorage` |
### PostgreSQL Configuration
```python
rag = LightRAG(
kv_storage="PostgreSQLStorage",
vector_storage="PGVectorStorage",
graph_storage="NetworkXStorage",
doc_status_storage="PostgreSQLStorage",
# PostgreSQL connection settings via env vars
)
```
Environment variables:
- `POSTGRES_HOST`
- `POSTGRES_PORT`
- `POSTGRES_USER`
- `POSTGRES_PASSWORD`
- `POSTGRES_DATABASE`
### Neo4j Configuration
```python
rag = LightRAG(
graph_storage="Neo4JStorage",
# Neo4j connection settings via env vars
)
```
Environment variables:
- `NEO4J_URI`
- `NEO4J_USERNAME`
- `NEO4J_PASSWORD`
### MongoDB Configuration
```python
rag = LightRAG(
kv_storage="MongoKVStorage",
vector_storage="MongoVectorStorage",
doc_status_storage="MongoDocStatusStorage",
# MongoDB connection settings via env vars
)
```
Environment variables:
- `MONGO_URI`
### OpenSearch Configuration
```python
rag = LightRAG(
kv_storage="OpenSearchStorage",
vector_storage="OpenSearchStorage",
graph_storage="OpenSearchStorage",
doc_status_storage="OpenSearchStorage",
# OpenSearch connection settings via env vars
)
```
Environment variables:
- `OPENSEARCH_HOST`
- `OPENSEARCH_PORT`
- `OPENSEARCH_INDEX_PREFIX`
## Common Usage Patterns
### Pattern 1: Simple RAG Query
```python
import asyncio
from lightrag import LightRAG, QueryParam
async def simple_query():
rag = LightRAG(working_dir="./rag_working")
# Insert data
await rag.ainsert("LightRAG is a retrieval-augmented generation system.")
# Query
result = await rag.aquery(
"What is LightRAG?",
param=QueryParam(mode="naive")
)
return result
asyncio.run(simple_query())
```
### Pattern 2: Hybrid Search with Reranking
```python
async def hybrid_search():
rag = LightRAG(
working_dir="./rag_working",
enable_rerank=True,
rerank_model_name="BAAI/bge-reranker-v2-m3"
)
result = await rag.aquery(
"Explain knowledge graph extraction",
param=QueryParam(
mode="mix",
chunk_top_k=40,
top_k=30
)
)
return result
```
### Pattern 3: Custom Knowledge Graph Import
```python
async def import_custom_kg():
rag = LightRAG(working_dir="./rag_working")
# Large-scale import
custom_data = {
"entities": [...], # List of entity dicts
"relations": [...] # List of relation dicts
}
# Batch graph operations for performance
await rag.ainsert_custom_kg(custom_data)
return True
```
## Troubleshooting
### Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Slow embedding generation | Batch size too small | Increase `embedding_batch_num` |
| High memory usage | Too many parallel operations | Reduce `max_async` and `max_parallel_insert` |
| Missing entities in results | Cosine threshold too high | Lower `cosine_threshold` or set to 0 |
| LLM timeout errors | Model or network issue | Increase `llm_timeout` or check model availability |
| Document not found after insertion | Duplicate filename handling | Use unique identifiers for documents |
### Debug Mode
```python
import logging
# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
rag = LightRAG(working_dir="./rag_working")
```
## See Also
- [LightRAG API Server](./LightRAG-API-Server.md) — REST API and Web UI documentation
- [Advanced Features](./AdvancedFeatures.md) — Token tracking, Langfuse, RAGAS evaluation
- [Interactive Setup](./InteractiveSetup.md) — Configuration wizard documentation
- [Docker Deployment](./DockerDeployment.md) — Containerized deployment
- [Offline Deployment](./OfflineDeployment.md) — Air-gapped environment setup
- [Example Codes](../examples) — Sample implementations in the `examples` folder
---
## Multimodal Document Processing
### Related Pages
Related topics: [Text Chunking Strategies](#page-chunking-strategies), [Advanced Features](#page-advanced-features)
```mermaid
graph TD
subgraph "Document Input"
A[User Uploads Document] --> B{Parser Selection}
end
subgraph "External Parsing Services"
B -->|PDF/Office/Image| C[MinerU Service]
B -->|Alternative| D[Docling Service]
end
subgraph "LightRAG Processing Pipeline"
C --> E[Text Extraction]
D --> E
C --> F[Image Extraction]
D --> F
C --> G[Table Extraction]
D --> G
C --> H[Formula Extraction]
D --> H
end
subgraph "Multimodal Context Assembly"
E --> I[Text Chunks]
F --> J[Image References]
G --> K[Table Structures]
H --> L[Formula Data]
J --> M[Multimodal Context]
K --> M
L --> M
I --> M
end
subgraph "LightRAG Storage & Query"
M --> N[Vector Storage]
M --> O[Knowledge Graph]
M --> P[KV Store]
end
N --> Q[Query Results]
O --> Q
P --> Q
Q --> R[Multimodal Response]
```
## Overview
LightRAG's Multimodal Document Processing capability enables the system to ingest and retrieve information from complex documents containing multiple content types. As of v1.5.0rc3, all multimodal processing capabilities from [RAG-Anything](https://github.com/HKUDS/RAG-Anything) have been merged into LightRAG, allowing the system to fully leverage images, tables, and formulas within documents to answer queries.
Source: [GitHub Release v1.5.0rc3](https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0rc3)
### Supported Document Formats
LightRAG supports a variety of document formats through its multimodal processing pipeline:
| Category | Formats | Extensions |
|----------|---------|------------|
| PDF Documents | Portable Document Format | `.pdf` |
| Word Processing | Microsoft Word | `.docx` |
| Presentations | Microsoft PowerPoint | `.pptx` |
| Spreadsheets | Microsoft Excel | `.xlsx` |
| Images | PNG, JPG, GIF, BMP, WebP | `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp` |
| Code Files | Python, JavaScript, Java, C++, Go, etc. | `.py`, `.js`, `.java`, `.cpp`, `.go`, etc. |
Source: [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
## Architecture
### Parser Module Structure
LightRAG uses a modular parser architecture that delegates heavy document parsing to external services while maintaining internal processing logic:
```mermaid
graph LR
subgraph "lightrag/parser/__init__.py"
A[Parser Factory] --> B[Text Parser]
A --> C[Document Parser]
end
subgraph "External Services"
D[MinerU Service]
E[Docling Service]
end
C -->|Delegation| D
C -->|Delegation| E
D --> F[Structured Output]
E --> F
F --> G[LightRAG Pipeline]
```
The parser module exports a factory pattern that instantiates appropriate parsers based on document type. External parsers (MinerU and Docling) handle the complex extraction logic, returning structured data that LightRAG processes further.
Source: [lightrag/parser/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/parser/__init__.py)
### Multimodal Context Management
The `multimodal_context.py` module handles the assembly and management of content extracted from various modalities:
```python
# Conceptual representation of multimodal context structure
class MultimodalContext:
text_chunks: List[TextChunk]
image_references: List[ImageReference]
table_structures: List[TableStructure]
formula_data: List[FormulaData]
```
This module ensures that all extracted modalities are properly indexed and can be retrieved together during query processing, enabling the LLM to reason about the relationships between text, images, tables, and formulas.
Source: [lightrag/multimodal_context.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/multimodal_context.py)
## Configuration
### Environment Variables for Multimodal Processing
To enable multimodal document processing, configure the following environment variables:
| Variable | Description | Required |
|----------|-------------|----------|
| `MINERU_URL` | Base URL for the MinerU parsing service | Yes (if using MinerU) |
| `DOCLING_URL` | Base URL for the Docling parsing service | Yes (if using Docling) |
| `VLM_MODEL` | Vision Language Model for image understanding | Yes |
| `VLM_API_KEY` | API key for the VLM provider | Conditional |
| `VLM_BASE_URL` | Base URL for VLM API endpoint | Conditional |
Source: [examples/lightrag_gemini_workspace_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_gemini_workspace_demo.py)
### Role-Specific LLM Configuration
LightRAG v1.5+ supports role-specific LLM configuration with four distinct roles. For multimodal processing, the **VLM role** is particularly important:
| Role | Purpose | Example Models |
|------|---------|----------------|
| `EXTRACT` | Entity and relationship extraction from text | GPT-4, Claude, Qwen |
| `QUERY` | Query understanding and result synthesis | GPT-4, Claude, Qwen |
| `KEYWORDS` | Keyword extraction for search | BGE, Jina |
| `VLM` | Vision Language Model for image/table/formula understanding | Gemini, GPT-4V |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## File Processing Pipeline
The file processing pipeline coordinates the flow from document upload to queryable storage:
```mermaid
sequenceDiagram
participant User
participant WebUI
participant API
participant Parser
participant Storage
participant QueryEngine
User->>WebUI: Upload Document
WebUI->>API: POST /documents/upload
API->>Parser: Route to MinerU/Docling
Parser-->>API: Structured Content (text, images, tables, formulas)
API->>API: Chunk & Extract Entities
API->>Storage: Index Chunks, KG, Multimodal Context
Storage-->>API: Acknowledgment
API-->>WebUI: Document Status
User->>WebUI: Query Request
WebUI->>API: POST /query
API->>QueryEngine: Retrieve Multimodal Context
QueryEngine->>Storage: Fetch Relevant Content
Storage-->>QueryEngine: Chunks + Images + Tables
QueryEngine->>LLM: Generate Response
LLM-->>QueryEngine: Multimodal Response
QueryEngine-->>WebUI: Response with Citations
WebUI-->>User: Display Results
```
Source: [docs/FileProcessingPipeline.md](https://github.com/HKUDS/LightRAG/blob/main/docs/FileProcessingPipeline.md)
## External Parser Integration
### MinerU Integration
MinerU is a powerful document parsing library that excels at extracting content from complex PDF documents. LightRAG integrates with MinerU through the `lightrag/parser/external/mineru/__init__.py` module.
**Key Capabilities:**
- PDF text extraction with layout preservation
- Table detection and structure recognition
- Image extraction with position metadata
- Formula detection (LaTeX conversion)
**Configuration Example:**
```bash
MINERU_URL=http://localhost:8080
```
Source: [lightrag/parser/external/mineru/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/parser/external/mineru/__init__.py)
### Docling Integration
Docling provides an alternative parsing backend with strong table understanding and document structure recognition.
**Key Capabilities:**
- Native table structure preservation
- Document layout analysis
- Multi-column text handling
- Metadata extraction
**Configuration Example:**
```bash
DOCLING_URL=http://localhost:5000
```
Source: [lightrag/parser/external/docling/__init__.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/parser/external/docling/__init__.py)
## Usage Patterns
### Uploading Multimodal Documents via API
```bash
# Upload a PDF with images and tables
curl -X POST "http://localhost:8080/api/v1/documents/upload" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@report.pdf" \
-F "process_multimodal=true"
```
### Querying with Multimodal Context
```python
from lightrag import LightRAG, QueryParam
rag = LightRAG(
working_dir="./workspace",
llm_model_name="gemini-2.0-flash",
vlm_model_name="gemini-pro-vision" # Enable multimodal understanding
)
# Query that requires reasoning across modalities
result = rag.query(
"What is the relationship between the chart on page 5 and the data in the table on page 7?",
param=QueryParam(
mode="hybrid",
response_type="Multiple Paragraphs"
)
)
```
Source: [examples/lightrag_gemini_workspace_demo.py](https://github.com/HKUDS/LightRAG/blob/main/examples/lightrag_gemini_workspace_demo.py)
## Common Issues and Solutions
### Issue: Documents with Same Name
> **Community Issue:** How to distinguish documents with same name but different content?
**Problem:** When multiple documents with identical filenames are uploaded, LightRAG may have difficulty distinguishing them.
**Solution:** LightRAG generates a unique document ID for each upload. Use the document ID for precise operations:
```python
# List documents to find IDs
statuses = rag.list_doc_statuses()
# Delete specific document by ID
rag.delete_by_document_id("doc_abc123xyz")
```
Source: [GitHub Issue #3158](https://github.com/HKUDS/LightRAG/issues/3158)
### Issue: Reverse Proxy Sub-Path Problems
> **Bug Report:** Not working on reverse proxy with sub-path
**Problem:** LightRAG's WebUI may use absolute paths for resources when deployed behind a reverse proxy with a sub-path.
**Solution:** LightRAG v1.5+ uses runtime configuration injection to handle sub-paths correctly. Ensure `LIGHTRAG_WEBUI_PATH` is set to your sub-path:
```bash
LIGHTRAG_WEBUI_PATH=/lightrag/
```
Source: [GitHub Issue #2755](https://github.com/HKUDS/LightRAG/issues/2755), [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
## Performance Considerations
### Batch Processing
For large-scale multimodal document ingestion, consider the following optimizations:
| Setting | Recommended Value | Purpose |
|---------|-------------------|---------|
| `chunk_token_size` | 1200 | Balance between context and retrieval precision |
| `chunk_overlap_token_size` | 100 | Maintain cross-chunk continuity |
| `vector_batch_size` | 200 | Optimize Postgres upsert performance |
| `max_parallel_inserts` | 5 | Control concurrent parsing operations |
### VLM Model Selection
Vision Language Models have significant performance implications:
| Model | Speed | Accuracy | Cost |
|-------|-------|----------|------|
| Gemini 2.0 Flash | Fast | Good | Low |
| GPT-4V | Medium | Excellent | High |
| Local VLM | Variable | Varies | Infrastructure |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Limitations
1. **External Service Dependency:** Multimodal parsing requires either MinerU or Docling services to be running and accessible.
2. **VLM Requirements:** Image, table, and formula understanding requires a properly configured Vision Language Model with sufficient context length.
3. **Processing Time:** Multimodal documents typically take longer to process than plain text documents due to additional extraction and VLM inference steps.
4. **Duplicate Detection:** Content duplicate detection for document upload is now trackable, but documents with identical content but different filenames may still share chunks.
Source: [GitHub Release v1.4.10](https://github.com/HKUDS/LightRAG/releases/tag/v1.4.10)
## See Also
- [LightRAG Server Documentation](./LightRAG-API-Server.md) - Full server setup including multimodal endpoints
- [Advanced Features](./AdvancedFeatures.md) - Token tracking, exports, and observability
- [Programming with Core](./ProgramingWithCore.md) - Python API reference for multimodal operations
- [Interactive Setup](./InteractiveSetup.md) - Wizard-based configuration for parsing services
- [Docker Deployment](./DockerDeployment.md) - Containerized deployment with all services
- [RAG-Anything Repository](https://github.com/HKUDS/RAG-Anything) - Original multimodal project (now merged into LightRAG)
---
## Deployment Guide
### Related Pages
Related topics: [Installation Guide](#page-installation), [API Server](#page-api-server)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
- [docker-compose.yml](https://github.com/HKUDS/LightRAG/blob/main/docker-compose.yml)
- [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)
- [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
- [k8s-deploy/values.yaml](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/values.yaml)
- [docs/DockerDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/DockerDeployment.md)
- [docs/OfflineDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/OfflineDeployment.md)
- [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
- [docs/FrontendBuildGuide.md](https://github.com/HKUDS/LightRAG/blob/main/docs/FrontendBuildGuide.md)
- [docs/MultiSiteDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/MultiSiteDeployment.md)
# Deployment Guide
This guide covers all supported deployment methods for LightRAG, including local development, Docker-based deployment, Kubernetes production deployments, and offline/air-gapped environments. Choose the deployment method that best matches your infrastructure and operational requirements.
## Overview
LightRAG supports multiple deployment topologies to accommodate different use cases:
| Deployment Type | Use Case | Storage Backend | Recommended For |
|----------------|----------|----------------|-----------------|
| **Local Development** | Testing and prototyping | SQLite / built-in | Individual developers |
| **Docker Standalone** | Single-server deployment | PostgreSQL, Neo4j, MongoDB | Small teams, staging |
| **Docker Compose** | Full-stack deployment | All supported backends | Development environments |
| **Kubernetes** | Production at scale | External databases | Enterprise deployments |
| **Offline/Air-Gapped** | Secure environments | Pre-installed services | Government, finance, healthcare |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
## Architecture Overview
```mermaid
graph TB
subgraph "Client Layer"
WebUI["Web UI
(React)"]
API["REST API
(FastAPI)"]
Ollama["Ollama Compatible
Interface"]
end
subgraph "LightRAG Core"
Indexer["Document Indexer"]
QueryEngine["Query Engine"]
KGBuilder["Knowledge Graph
Builder"]
end
subgraph "Storage Layer"
VectorDB["Vector Database
(PGVector/Milvus/Qdrant/Weaviate]"]
GraphDB["Graph Database
(Neo4j)"]
KVStore["KV Store
(PostgreSQL/MongoDB/OpenSearch]"]
DocStatus["Document Status
(PostgreSQL/MongoDB]"]
end
subgraph "AI Providers"
LLM["LLM Provider
(OpenAI/Gemini/Local Ollama]"]
Embedder["Embedding Model"]
Reranker["Reranker Model"]
end
WebUI --> API
API --> LightRAGCore
Ollama --> API
LightRAGCore --> StorageLayer
LightRAGCore --> AIProviders
```
## Prerequisites
### Hardware Requirements
| Component | Minimum | Recommended |
|-----------|---------|-------------|
| CPU | 2 cores | 4+ cores |
| RAM | 4 GB | 8+ GB |
| Disk | 10 GB | 50+ GB SSD |
| GPU | Optional | NVIDIA GPU with 6+ GB VRAM |
### Software Requirements
- **Docker** (v20.10+) and **Docker Compose** (v2.0+) for containerized deployments
- **Kubernetes** (v1.28+) with **Helm** (v3.12+) for production deployments
- **uv** package manager for Python installations (optional but recommended)
- **kubectl** for Kubernetes management
Source: [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
## Environment Configuration
### Configuration File Generation
LightRAG provides an interactive setup wizard to generate the `.env` configuration file:
```bash
# Required: Base configuration (LLM, embedding, reranker)
make env-base
# Optional: Storage backends and database services
make env-storage
# Optional: Server settings (port, authentication, SSL)
make env-server
# Security audit for the generated .env
make env-security-check
```
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
### Environment Variables Reference
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `OPENAI_API_KEY` | API key for OpenAI LLM | Yes (unless using alternative LLM) | - |
| `LIGHTRAG_DATA_DIR` | Directory for LightRAG data | No | `./rag_data` |
| `LIGHTRAG_LOG_LEVEL` | Logging verbosity | No | `INFO` |
| `VECTOR_DB` | Vector database type | No | `neo4j` |
| `GRAPH_DB` | Graph database type | No | `neo4j` |
| `LLM_BINDING` | LLM provider selection | No | `openai` |
| `EMBEDDING_PROVIDER` | Embedding provider | No | `openai` |
Source: [env.example](https://github.com/HKUDS/LightRAG/blob/main/env.example)
## Docker Deployment
### Quick Start with Docker Compose
The fastest way to deploy LightRAG with all dependencies:
```bash
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# Copy and configure environment
cp env.example .env
# Edit .env with your API keys and settings
# Launch all services
docker compose up
```
The application will be available at `http://localhost:56789` by default.
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
### Docker Service Architecture
```mermaid
graph LR
subgraph "Docker Compose Services"
direction TB
Server["lightrag-server
:56789"]
WebUI["lightrag-webui
:56790"]
Neo4j["neo4j
:7474, :7687"]
PostgreSQL["postgres
:5432"]
Qdrant["qdrant
:6333"]
MinIO["minio
:9000, :9001"]
end
Server <--> Neo4j
Server <--> PostgreSQL
Server <--> Qdrant
Server <--> MinIO
WebUI --> Server
```
### Configuration Options for Docker
| Service | Port | Environment Variable | Description |
|---------|------|---------------------|-------------|
| LightRAG Server | 56789 | `LIGHTRAG_PORT` | Main API server |
| WebUI | 56790 | `LIGHTRAG_WEBUI_PORT` | React frontend |
| Neo4j | 7474/7687 | `NEO4J_*` | Graph and vector storage |
| PostgreSQL | 5432 | `POSTGRES_*` | Relational and vector storage |
| Qdrant | 6333 | `QDRANT_*` | Alternative vector storage |
### Verifying Official Docker Images
Official GHCR images are signed with Sigstore Cosign using GitHub OIDC:
```bash
# Install cosign
curl -sSfL https://docs.sigstore.dev.cosign.com/installation/get | sh
# Verify an official image
cosign verify \
--certificate-identity-regexp="https://github.com/HKUDS/LightRAG/.*" \
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
ghcr.io/hkuds/lightrag:latest
```
Source: [docs/DockerDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/DockerDeployment.md)
## Kubernetes Deployment
### Prerequisites for Kubernetes
- Running Kubernetes cluster (Minikube, EKS, GKE, AKS, or on-premises)
- kubectl configured with cluster access
- Helm v3.x installed
### Deployment Methods
LightRAG supports two deployment configurations via Helm:
| Method | Storage | Recommended For |
|--------|---------|-----------------|
| **Lightweight** | Built-in lightweight storage | Testing and small-scale usage |
| **Production** | External PostgreSQL and Neo4j | Production environments |
Source: [k8s-deploy/README.md](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/README.md)
### Installing with Helm
```bash
# Add the LightRAG Helm repository (if published)
helm repo add lightrag https://hkuds.github.io/LightRAG-charts
helm repo update
# Install with default values
helm install lightrag lightrag/lightrag
# Or install with a custom values file
helm install lightrag lightrag/lightrag -f my-values.yaml
```
### Helm Values Configuration
Key configuration parameters in `values.yaml`:
```yaml
# Service Configuration
service:
type: ClusterIP # or LoadBalancer, NodePort
port: 56789
# LightRAG Configuration
lightrag:
# LLM Provider
llm:
provider: openai # openai, azure, gemini, ollama
apiKey: "" # Set via --set or secrets
# Embedding Configuration
embedding:
provider: openai
model: text-embedding-3-small
# Storage Backend Selection
vectorDb: pgvector # neo4j, pgvector, qdrant, milvus, weaviate
graphDb: neo4j
# External Database Connections (Production)
externalDatabases:
postgres:
enabled: true
host: "postgres.namespace.svc.cluster.local"
port: 5432
database: lightrag
neo4j:
enabled: true
uri: "bolt://neo4j.namespace.svc.cluster.local:7687"
```
Source: [k8s-deploy/values.yaml](https://github.com/HKUDS/LightRAG/blob/main/k8s-deploy/values.yaml)
### Kubernetes Resource Scaling
```mermaid
graph TD
subgraph "Kubernetes Cluster"
subgraph "Namespaces"
Frontend["frontend-ns"]
Backend["backend-ns"]
Data["data-ns"]
end
subgraph "Backend Namespace"
Server["lightrag-server
Deployment"]
HPA["Horizontal Pod
Autoscaler"]
end
subgraph "Data Namespace"
Postgres["PostgreSQL
StatefulSet"]
Neo4j["Neo4j
StatefulSet"]
end
HPA -->|"scales"| Server
Server -->|"reads/writes"| Postgres
Server -->|"reads/writes"| Neo4j
end
External["External Traffic"] --> Ingress["Ingress Controller"]
Ingress --> Server
```
## Offline/Air-Gapped Deployment
For environments without internet access, LightRAG supports fully offline deployment:
### Offline Setup Process
1. **Download dependencies on a connected machine**:
```bash
# Clone the repository
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
# Download all Python dependencies
pip download -r requirements.txt -d ./offline_packages/
# Download Docker images
docker save $(cat requirements-images.txt) -o ./offline_images.tar
```
2. **Transfer files to the air-gapped environment**:
```bash
# Transfer via USB drive or internal artifact repository
rsync -avP ./offline_packages/ user@airgapped-server:/opt/lightrag/packages/
rsync -avP ./offline_images.tar user@airgapped-server:/opt/lightrag/images/
```
3. **Install in the offline environment**:
```bash
# Load Docker images
docker load -i ./offline_images.tar
# Install Python packages
pip install --no-index --find-links=./offline_packages/ -r requirements.txt
# Start services
docker compose up -d
```
Source: [docs/OfflineDeployment.md](https://github.com/HKUDS/LightRAG/blob/main/docs/OfflineDeployment.md)
### Offline Embedding and LLM Support
In offline environments, configure local model providers:
```bash
# Environment variables for offline LLM
OLLAMA_BASE_URL=http://localhost:11434
LLM_BINDING=ollama
OLLAMA_MODEL=llama3.2
# Local embedding model
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBED_MODEL=nomic-embed-text
```
## WebUI Build Configuration
The WebUI is a React application that can be served independently or integrated with the main server.
### Build from Source
```bash
# Navigate to WebUI directory
cd lightrag_webui
# Install dependencies with Bun (recommended)
bun install --frozen-lockfile
# Build for production
bun run build
```
Source: [lightrag_webui/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/README.md)
### Runtime Path Configuration
The WebUI supports deployment behind reverse proxies with custom path prefixes. Configuration is injected at runtime:
```bash
# Set path prefixes via environment variables
export LIGHTRAG_API_PREFIX=/lightrag/api
export LIGHTRAG_WEBUI_PATH=/lightrag/webui
```
The FastAPI server replaces a placeholder in `index.html` with the actual configuration:
```html
```
Source: [lightrag_webui/src/lib/runtimeConfig.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/runtimeConfig.ts)
## Reverse Proxy Configuration
### Known Issue with Sub-Path Deployment
> **Note**: There is a known issue with LightRAG when deployed behind reverse proxies using sub-paths. The application uses absolute paths for some resources (assets, iframes), which may cause loading issues.
>
> Issue Reference: [#2755](https://github.com/HKUDS/LightRAG/issues/2755)
### Recommended Reverse Proxy Setup
For Apache:
```apache
ServerName lightrag.example.com
# Proxy API requests
ProxyPass /api/ http://localhost:56789/api/
ProxyPassReverse /api/ http://localhost:56789/api/
# Proxy WebUI static files
ProxyPass /webui/ http://localhost:56790/
ProxyPassReverse /webui/ http://localhost:56790/
# Enable WebSocket support
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/api/(.*)$ ws://localhost:56789/api/$1 [P,L]
```
For Nginx:
```nginx
server {
listen 443 ssl;
server_name lightrag.example.com;
location /api/ {
proxy_pass http://localhost:56789;
proxy_set_header Host $host;
}
location /webui/ {
proxy_pass http://localhost:56790;
proxy_set_header Host $host;
}
# WebSocket support
location /api/ws {
proxy_pass http://localhost:56789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
## Development Environment Setup
### Quick Bootstrap with Make
```bash
# Bootstrap complete development environment
make dev
# This installs:
# - Test toolchain
# - Full offline stack (API, storage backends, provider integrations)
# - Frontend build
```
After bootstrapping, activate the virtual environment:
```bash
source .venv/bin/activate # Linux/macOS
# Or: .venv\Scripts\activate # Windows
# Start the development server
lightrag-server
```
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
## Storage Backend Selection
LightRAG supports multiple storage backends for different components:
| Component | Supported Backends | Recommended for Production |
|-----------|-------------------|---------------------------|
| **Vector Store** | PostgreSQL (pgvector), Neo4j, Qdrant, Milvus, Weaviate, MongoDB Atlas, OpenSearch | PostgreSQL or Qdrant |
| **Graph Store** | Neo4j, MongoDB, OpenSearch | Neo4j |
| **KV Store** | PostgreSQL, MongoDB, OpenSearch | PostgreSQL or MongoDB |
| **Doc Status** | PostgreSQL, MongoDB, OpenSearch | PostgreSQL |
### OpenSearch as Unified Backend
OpenSearch can serve as a unified backend for all four storage types:
```bash
# Configure OpenSearch as all-in-one storage
make env-storage
# Set in .env:
OPENSEARCH_HOST=https://opensearch:9200
OPENSEARCH_USER=admin
OPENSEARCH_PASSWORD=your_password
```
> **Breaking Change in v1.4.16**: OpenSearch versions prior to 3.3.0 are no longer supported due to changes in PIT search behavior.
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
## Troubleshooting Common Deployment Issues
### Port Conflicts
If ports 56789 or 56790 are already in use:
```bash
# Check what's using the ports
lsof -i :56789
lsof -i :56790
# Change ports in .env
LIGHTRAG_PORT=56800
LIGHTRAG_WEBUI_PORT=56801
```
### Database Connection Failures
```bash
# Verify database containers are running
docker compose ps
# Check database logs
docker compose logs postgres
docker compose logs neo4j
# Test database connectivity
docker compose exec postgres psql -U lightrag -d lightrag -c "SELECT 1;"
```
### Memory Issues with Large Documents
For deployments processing large documents:
```bash
# Increase Docker memory allocation
# Docker Desktop > Settings > Resources > Memory: 8GB+
# Or use environment variable to limit chunk sizes
MAX_CHUNK_SIZE=500
CHUNK_OVERLAP=50
```
### Document Upload Issues
> **Known Issue**: PDF files protected by permission-only restrictions may fail to open. This was fixed in v1.4.12.
```bash
# If using LightRAG v1.4.11 or earlier, upgrade or disable PDF password protection
pip install lightrag-hku>=1.4.12
```
## Security Considerations
### Authentication Setup
LightRAG supports authentication via the setup wizard:
```bash
make env-server
# Select authentication options during wizard execution
```
Passwords are hashed with bcrypt prefix for secure storage.
Source: [docs/InteractiveSetup.md](https://github.com/HKUDS/LightRAG/blob/main/docs/InteractiveSetup.md)
### Security Audit
Run the security audit tool to check for configuration risks:
```bash
make env-security-check
```
This tool audits:
- API key strength
- Database password configuration
- TLS/SSL settings
- Exposed ports
- Authentication status
## See Also
- [Interactive Setup Guide](./InteractiveSetup.md) - Detailed setup wizard documentation
- [Docker Deployment](./DockerDeployment.md) - Advanced Docker configuration
- [Offline Deployment](./OfflineDeployment.md) - Air-gapped environment setup
- [Programming with Core](./ProgramingWithCore.md) - Core API usage
- [Advanced Features](./AdvancedFeatures.md) - Token tracking, exports, and evaluation
- [Multi-Site Deployment](./MultiSiteDeployment.md) - Distributed deployment topology
---
## Advanced Features
### Related Pages
Related topics: [Multimodal Document Processing](#page-multimodal), [Programming with LightRAG Core](#page-programming-core)
Related Source Files
The following source files were used to generate this page:
- [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
- [docs/RoleSpecificLLMConfiguration.md](https://github.com/HKUDS/LightRAG/blob/main/docs/RoleSpecificLLMConfiguration.md)
- [docs/AsymmetricEmbedding.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AsymmetricEmbedding.md)
- [lightrag/llm_roles.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm_roles.py)
- [lightrag/evaluation/eval_rag_quality.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/eval_rag_quality.py)
- [lightrag/tools/clean_llm_query_cache.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/clean_llm_query_cache.py)
- [lightrag/tools/download_cache.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/download_cache.py)
- [lightrag_webui/src/api/lightrag.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
# Advanced Features
LightRAG provides a comprehensive suite of advanced features that extend beyond basic retrieval-augmented generation capabilities. These features enable fine-grained control over LLM interactions, deep observability into system performance, robust evaluation frameworks, efficient cache management, and multimodal document processing.
This page documents the advanced capabilities available in LightRAG, their configuration options, usage patterns, and implementation details. These features are designed for production deployments, research evaluations, and specialized use cases requiring granular control over the RAG pipeline.
---
## 1. Role-Specific LLM Configuration
LightRAG supports role-specific LLM configuration, allowing independent LLM settings for different stages of the RAG pipeline. This feature enables optimal model selection for each task, improving overall system performance and cost efficiency.
### 1.1 Available LLM Roles
LightRAG defines four distinct LLM roles within the pipeline, each serving a specific function during document processing and querying.
| Role | Purpose | Typical Requirements |
|------|---------|---------------------|
| `EXTRACT` | Entity and relationship extraction from documents | High instruction-following, structured output |
| `QUERY` | Generating responses from retrieved context | Strong reasoning and summarization |
| `KEYWORDS` | Keyword and phrase extraction for search | Fast response, good at short outputs |
| `VLM` | Vision-language processing for multimodal content | Vision capabilities, image understanding |
Source: [lightrag/llm_roles.py:1-50](https://github.com/HKUDS/LightRAG/blob/main/lightrag/llm_roles.py)
### 1.2 Configuration Parameters
Each role can be configured independently using environment variables following the pattern `LIGHTRAG__`.
```bash
# Example: Configure different models for different roles
LIGHTRAG_EXTRACT_MODEL=gpt-4o
LIGHTRAG_EXTRACT_API_KEY=sk-...
LIGHTRAG_QUERY_MODEL=gpt-4-turbo
LIGHTRAG_QUERY_API_KEY=sk-...
LIGHTRAG_KEYWORDS_MODEL=gpt-4o-mini
LIGHTRAG_KEYWORDS_API_KEY=sk-...
LIGHTRAG_VLM_MODEL=gpt-4o
LIGHTRAG_VLM_API_KEY=sk-...
```
Source: [docs/RoleSpecificLLMConfiguration.md](https://github.com/HKUDS/LightRAG/blob/main/docs/RoleSpecificLLMConfiguration.md)
### 1.3 Task-Aware Embedding
Beyond LLM roles, LightRAG also supports task-aware embedding configuration. Different embedding models can be specified for various tasks, optimizing retrieval quality for specific use cases.
```bash
# Task-specific embedding configuration
LIGHTRAG_TASK_AWARE_EMBEDDING=true
LIGHTRAG_QUERY_EMBEDDING_MODEL=bge-m3
LIGHTRAG_CHUNK_EMBEDDING_MODEL=bge-m3
```
Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
---
## 2. Observability and Tracing
LightRAG integrates comprehensive observability features that enable deep insight into system behavior, performance metrics, and operational health.
### 2.1 Langfuse Integration
LightRAG supports Langfuse integration for distributed tracing and performance monitoring. When enabled, all LLM calls are traced with detailed metadata including latency, token usage, and call hierarchies.
```mermaid
graph TD
A[User Query] --> B[LightRAG Core]
B --> C[Entity Extraction]
B --> D[Relationship Extraction]
B --> E[Vector Search]
B --> F[Context Assembly]
C --> G[EXTRACT LLM Call]
D --> G
E --> H[Embedding Model]
F --> I[QUERY LLM Call]
G --> J[Langfuse Trace]
H --> J
I --> J
J --> K[Langfuse Dashboard]
```
Configuration:
```bash
# Enable Langfuse tracing
LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key
LANGFUSE_HOST=https://cloud.langfuse.com
```
Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
### 2.2 Token Usage Tracking
LightRAG provides detailed token usage tracking for all LLM interactions, enabling cost analysis and budget management in production environments.
The `QueryParam` structure includes token allocation controls:
| Parameter | Type | Description |
|-----------|------|-------------|
| `max_entity_tokens` | int | Maximum tokens for entity context |
| `max_relation_tokens` | int | Maximum tokens for relationship context |
| `max_total_tokens` | int | Total token budget for entire query |
| `chunk_top_k` | int | Maximum chunks after reranking |
Source: [lightrag_webui/src/api/lightrag.ts:1-50](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
---
## 3. RAG Evaluation Framework
LightRAG includes a comprehensive evaluation framework based on RAGAS (Retrieval-Augmented Generation Assessment) metrics. This enables systematic assessment of retrieval and generation quality.
### 3.1 Evaluation Pipeline
The evaluation pipeline processes queries against indexed documents and produces quality scores based on multiple metrics.
```mermaid
graph LR
A[Test Queries] --> B[LightRAG Query Engine]
C[Indexed Documents] --> B
B --> D[Retrieved Context]
B --> E[Generated Response]
D --> F[RAGAS Metrics]
E --> F
F --> G[Quality Scores]
A --> G
```
Source: [lightrag/evaluation/eval_rag_quality.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/eval_rag_quality.py)
### 3.2 Evaluation Metrics
The RAGAS-based evaluation provides the following metrics:
| Metric | Description | Expected Range |
|--------|-------------|----------------|
| Faithfulness | Alignment between response and retrieved context | 0.0 - 1.0 |
| Answer Relevance | Quality and relevance of generated answers | 0.0 - 1.0 |
| Context Precision | Accuracy of retrieved context | 0.0 - 1.0 |
| Context Recall | Completeness of retrieved information | 0.0 - 1.0 |
Source: [lightrag/evaluation/eval_rag_quality.py:1-100](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/eval_rag_quality.py)
### 3.3 Running Evaluation
```bash
# Index evaluation documents
# Documents are located in: lightrag/evaluation/sample_documents/
# Run evaluation
python lightrag/evaluation/eval_rag_quality.py
# Expected results: ~91-100% RAGAS score per question
```
Source: [lightrag/evaluation/sample_documents/README.md](https://github.com/HKUDS/LightRAG/blob/main/lightrag/evaluation/sample_documents/README.md)
---
## 4. LLM Cache Management
LightRAG provides sophisticated caching mechanisms to reduce LLM API calls and improve response times for repeated queries.
### 4.1 Cache Types
| Cache Type | Purpose | Storage |
|------------|---------|---------|
| Query Cache | Stores LLM responses for repeated queries | File-based SQLite |
| Embedding Cache | Caches document embeddings | Vector store |
| LLM Query Cache | Stores intermediate extraction results | Key-value store |
Source: [lightrag/tools/clean_llm_query_cache.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/clean_llm_query_cache.py)
### 4.2 Cache Management Tools
LightRAG includes command-line tools for cache maintenance:
```bash
# Clean LLM query cache
python -m lightrag.tools.clean_llm_query_cache
# Download cache for offline deployment
python -m lightrag.tools.download_cache --output ./cache
# Options:
# --cache-dir Directory containing cache files
# --output Output directory for downloaded cache
# --days Only include files modified within N days
```
Source: [lightrag/tools/clean_llm_query_cache.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/clean_llm_query_cache.py)
Source: [lightrag/tools/download_cache.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/tools/download_cache.py)
### 4.3 Cache Configuration
```bash
# Enable query result caching
LIGHTRAG_CACHE_TYPE=sqlite
LIGHTRAG_CACHE_DIR=./cache
# Set cache expiration (in days)
LIGHTRAG_CACHE_EXPIRE_DAYS=7
```
---
## 5. Multimodal Document Processing
LightRAG supports comprehensive multimodal document processing, including PDFs, Office documents, images, tables, and formulas. This capability was integrated from RAG-Anything.
### 5.1 Supported Formats
| Format | Extensions | Capabilities |
|--------|------------|--------------|
| PDF | `.pdf` | Text extraction, image extraction, table detection |
| Word | `.docx` | Text and table extraction |
| Excel | `.xlsx` | Table extraction |
| PowerPoint | `.pptx` | Text and image extraction |
| Images | `.jpg`, `.png`, etc. | OCR and visual understanding |
Source: [lightrag_webui/src/lib/constants.ts](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/lib/constants.ts)
### 5.2 Multimodal Processing Pipeline
```mermaid
graph TD
A[Document Upload] --> B{Format Detection}
B -->|PDF| C[MinerU/Docling Parser]
B -->|Office| C
B -->|Image| D[VLM Processing]
C --> E[Text Extraction]
C --> F[Image Extraction]
C --> G[Table Extraction]
C --> H[Formula Extraction]
E --> I[LightRAG Pipeline]
F --> I
G --> I
H --> I
D --> I
I --> J[Indexed Content]
```
### 5.3 Multimodal Configuration
```bash
# Enable multimodal processing
LIGHTRAG_MULTIMODAL_ENABLED=true
LIGHTRAG_PARSER_SERVICE=mineru # or docling
# Configure VLM for image understanding
LIGHTRAG_VLM_MODEL=gpt-4o
LIGHTRAG_VLM_API_KEY=sk-...
```
Source: [docs/AdvancedFeatures.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AdvancedFeatures.md)
---
## 6. Knowledge Graph Data Export
LightRAG supports exporting knowledge graph data for analysis, backup, or migration purposes.
### 6.1 Export Formats
| Format | Use Case | File Extension |
|--------|----------|----------------|
| JSON | Programmatic processing | `.json` |
| GraphML | Graph analysis tools | `.graphml` |
| CSV | Spreadsheet analysis | `.csv` |
### 6.2 Export Process
```python
from lightrag import LightRAG
rag = LightRAG()
# Export knowledge graph
rag.export_graph(
format="json",
output_path="./kg_export.json",
include_entities=True,
include_relationships=True
)
```
---
## 7. Asymmetric Embedding
LightRAG supports asymmetric embedding models, which are optimized for dense retrieval scenarios where query and document embeddings exist in different representation spaces.
### 7.1 Configuration
```bash
# Enable asymmetric embedding
LIGHTRAG_ASYMMETRIC_EMBEDDING=true
LIGHTRAG_ASYMMETRIC_QUERY_MODEL=query-encoder
LIGHTRAG_ASYMMETRIC_PASSAGE_MODEL=passage-encoder
```
Source: [docs/AsymmetricEmbedding.md](https://github.com/HKUDS/LightRAG/blob/main/docs/AsymmetricEmbedding.md)
### 7.2 Use Cases
Asymmetric embeddings are particularly effective for:
- **Long queries with short documents**: Query embeddings capture detailed intent while document embeddings are compact
- **Cross-domain retrieval**: Query encoders trained on diverse queries generalize better
- **Query expansion**: Asymmetric models handle reformulated queries more robustly
---
## 8. Query Modes and Parameters
LightRAG supports multiple query modes optimized for different retrieval scenarios.
### 8.1 Query Modes
| Mode | Description | Best For |
|------|-------------|----------|
| `naive` | Standard vector similarity search | Simple Q&A |
| `local` | Entity-focused retrieval | Questions about specific entities |
| `global` | Relationship-focused retrieval | Questions requiring relationship context |
| `hybrid` | Combines local and global | Complex analytical questions |
| `mix` | Full pipeline with reranking | Mixed query types (default) |
| `bypass` | Returns prompt only | Debugging and prompt engineering |
Source: [lightrag_webui/src/api/lightrag.ts:1-50](https://github.com/HKUDS/LightRAG/blob/main/lightrag_webui/src/api/lightrag.ts)
### 8.2 Query Request Parameters
```typescript
interface QueryRequest {
query: string
mode: QueryMode
only_need_context?: boolean // Return only retrieved context
only_need_prompt?: boolean // Return prompt without response
response_type?: string // e.g., 'Multiple Paragraphs', 'Single Paragraph'
stream?: boolean // Enable streaming output
top_k?: number // Entities/relationships to retrieve
chunk_top_k?: number // Chunks to retrieve after reranking
max_entity_tokens?: number // Token budget for entities
max_relation_tokens?: number // Token budget for relationships
max_total_tokens?: number // Total token budget
}
```
---
## 9. Reranker Integration
LightRAG supports reranker models to improve retrieval precision, particularly effective when combined with the `mix` query mode.
### 9.1 Configuration
```bash
# Enable reranker
LIGHTRAG_RERANKER_ENABLED=true
LIGHTRAG_RERANKER_MODEL=BAAI/bge-reranker-v2-m3
LIGHTRAG_RERANKER_API_KEY=your-api-key
```
### 9.2 Recommended Models
| Model | Provider | Strengths |
|-------|----------|-----------|
| `BAAI/bge-reranker-v2-m3` | HuggingFace | High quality, open source |
| `jina-reranker-v2-base` | Jina | Fast inference |
| `cohere-rerank-3.5` | Cohere | Enterprise-grade |
Source: [README.md](https://github.com/HKUDS/LightRAG/blob/main/README.md)
---
## 10. Common Configuration Patterns
### 10.1 High-Quality Production Setup
```bash
# LLM Configuration
LIGHTRAG_LLM_MODEL=gpt-4o
LIGHTRAG_EMBEDDING_MODEL=bge-m3
LIGHTRAG_RERANKER_MODEL=BAAI/bge-reranker-v2-m3
# Role-specific models
LIGHTRAG_EXTRACT_MODEL=gpt-4o
LIGHTRAG_QUERY_MODEL=gpt-4-turbo
# Observability
LANGFUSE_PUBLIC_KEY=your-key
LANGFUSE_SECRET_KEY=your-secret
# Cache
LIGHTRAG_CACHE_TYPE=sqlite
LIGHTRAG_CACHE_DIR=./cache
```
### 10.2 Research/Evaluation Setup
```bash
# Enable all tracking
LIGHTRAG_EVALUATION_MODE=true
LANGFUSE_TRACING=true
# Configure sample documents
LIGHTRAG_EVAL_DOCS_DIR=./lightrag/evaluation/sample_documents/
```
---
## 11. Troubleshooting Common Issues
### 11.1 Token Budget Exhaustion
If queries return incomplete results, increase token budgets:
```python
params = QueryParam(
max_entity_tokens=3000,
max_relation_tokens=2000,
max_total_tokens=8000
)
result = await rag.aquery("Your question", param=params)
```
### 11.2 Multimodal Processing Failures
For PDF parsing failures:
1. Verify parser service is running (MinerU or Docling)
2. Check file permissions and path accessibility
3. Enable verbose logging: `LIGHTRAG_LOG_LEVEL=DEBUG`
### 11.3 Cache-Related Issues
Clear cache if encountering stale results:
```bash
python -m lightrag.tools.clean_llm_query_cache --force
```
---
## See Also
- [Programming with LightRAG Core](./ProgramingWithCore.md) - Core API reference
- [LightRAG Server](./LightRAG-API-Server.md) - Web UI and API documentation
- [Interactive Setup](./InteractiveSetup.md) - Setup wizard documentation
- [Docker Deployment](./DockerDeployment.md) - Containerized deployment guide
- [Role-Specific LLM Configuration](./RoleSpecificLLMConfiguration.md) - Detailed LLM role configuration
- [Asymmetric Embedding](./AsymmetricEmbedding.md) - Asymmetric embedding documentation
---
---
## Pitfall Log
Project: HKUDS/LightRAG
Summary: Found 22 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.
## 1. Installation risk - Installation risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_9aea67d79c4b46508c4267093ebb19da | https://github.com/HKUDS/LightRAG/issues/2642
## 2. Installation risk - Installation risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_6c7ed97673d041ef92d4ff54a3718289 | https://github.com/HKUDS/LightRAG/issues/3158
## 3. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.4.10
- User impact: Upgrade or migration may change expected behavior: v1.4.10
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.10. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_dceb1b266203b7a89767ff26a0852383 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.10
## 4. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [Bug]: Not working on reverse proxy - sub path
- User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: Not working on reverse proxy - sub path
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Not working on reverse proxy - sub path. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_13dbaaeb506c72cc5b9ecd91cdabc2a2 | https://github.com/HKUDS/LightRAG/issues/2755
## 5. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.4.11
- User impact: Upgrade or migration may change expected behavior: v1.4.11
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11. Context: Observed when using docker
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_eda26a0bfd194234d2eb2fa02f9bdae9 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11
## 6. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.4.11rc2
- User impact: Upgrade or migration may change expected behavior: v1.4.11rc2
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11rc2. Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_0ff3ca856c8031ac2b0c56ec5eb253ab | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.11rc2
## 7. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.4.12
- User impact: Upgrade or migration may change expected behavior: v1.4.12
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.12. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_ded21b8d88cae5cd73ae76e6ec499f47 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.12
## 8. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.4.13
- User impact: Upgrade or migration may change expected behavior: v1.4.13
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.13. Context: Observed when using node
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_9e994731fd7834839bbe18111ec634c6 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.13
## 9. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.4.14
- User impact: Upgrade or migration may change expected behavior: v1.4.14
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.14. Context: Observed when using python, docker
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_a1044f275fce0a09fbf5f7ff15ce5406 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.14
## 10. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.5.0rc3
- User impact: Upgrade or migration may change expected behavior: v1.5.0rc3
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.5.0rc3. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_f612aafe1cfe8a3c51740b6487bd93a7 | https://github.com/HKUDS/LightRAG/releases/tag/v1.5.0rc3
## 11. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 12. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- User impact: Developers may hit a documented source-backed failure mode: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anything or Extend (modify) LightRAGs lightrag‑server?. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_dfedf4f77da9bdcac28253497ad6ce68 | https://github.com/HKUDS/LightRAG/issues/2642
## 13. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: v1.4.16
- User impact: Upgrade or migration may change expected behavior: v1.4.16
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.16. Context: Observed during version upgrade or migration.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_e1bc29ea5c00bb483634fa73149ec8cf | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.16
## 14. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 15. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 16. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 17. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_969a894078ba4625956be8aafdd77a49 | https://github.com/HKUDS/LightRAG/issues/2755
## 18. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [Question]: How to distinguish documents with same name but different content?
- User impact: Developers may hit a documented source-backed failure mode: [Question]: How to distinguish documents with same name but different content?
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Question]: How to distinguish documents with same name but different content?. Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_7de313ae4505d08ac41ea7819dc560ae | https://github.com/HKUDS/LightRAG/issues/3158
## 19. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 20. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:866513204 | https://github.com/HKUDS/LightRAG
## 21. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.4.15
- User impact: Upgrade or migration may change expected behavior: v1.4.15
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.15. Context: Observed when using docker
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_71ec5d7890568d905bed167788b6732f | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.15
## 22. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.4.9.11
- User impact: Upgrade or migration may change expected behavior: v1.4.9.11
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.9.11. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_f875fc1d48e0d9cf17d2b49dd7fa0cf4 | https://github.com/HKUDS/LightRAG/releases/tag/v1.4.9.11