Related Pages

Related topics: System Architecture, Installation Guide

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

Purpose and Scope

LightRAG addresses several key limitations of traditional RAG systems:

Source: 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:

graph TD
    subgraph LightRAG_Architecture
        subgraph Storage_Layer
            KV[KV Storage<br/>JsonFileDB<br/>PostgreSQL<br/>MongoDB<br/>OpenSearch]
            Vector[Vector Storage<br/>NanoVectorDB<br/>PostgreSQL<br/>MongoDB<br/>OpenSearch]
            Graph[Graph Storage<br/>NetworkX<br/>Neo4j<br/>OpenSearch]
            DocStatus[DocStatus Storage<br/>SqliteDB<br/>PostgreSQL<br/>MongoDB<br/>OpenSearch]
        end
        
        subgraph Core_Components
            LLM[LLM Binding<br/>OpenAI<br/>Ollama<br/>Azure<br/>Gemini<br/>HuggingFace]
            Embed[Embedding Binding<br/>OpenAI<br/>Ollama<br/> voyageai<br/>HuggingFace]
            Rerank[Reranker<br/>BAAI/bge-reranker]
        end
        
        subgraph Interfaces
            Server[LightRAG Server<br/>REST API<br/>WebUI]
            Core[LightRAG Core<br/>Python API]
        end
    end
    
    KV <--> LLM
    Vector <--> Embed
    Graph <--> LLM
    DocStatus <--> Server
    Core <--> Server

Source: 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

Query Modes

LightRAG supports six distinct query modes, each optimized for different retrieval strategies:

Source: lightrag_webui/src/api/lightrag.ts

Query Parameters

When performing queries, the following parameters control retrieval behavior:

Source: lightrag_webui/src/api/lightrag.ts

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:

# 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

LightRAG Core (Python Library)

For embedding LightRAG into custom applications:

# From source
cd LightRAG
uv sync
source .venv/bin/activate

# Or via pip
pip install lightrag-hku

Source: README.md

Docker Deployment

For containerized deployments:

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

Interactive Setup Wizard

LightRAG includes an interactive setup wizard for streamlined configuration:

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

Supported Storage Backends

LightRAG provides flexible storage options for each of its four storage types:

KV Storage

Source: README.md

Vector Storage

Source: README.md

Graph Storage

Source: README.md

Document Status Storage

Source: README.md

LLM and Embedding Support

LightRAG integrates with multiple provider ecosystems:

LLM Providers

Source: README.md

Embedding Providers

Source: README.md

Reranker Support

The reranker model significantly improves mixed query performance and is recommended for production deployments:

Source: README.md

Indexing and Knowledge Graph Extraction

During document ingestion, LightRAG performs several processing steps:

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

Entity Type Mapping

The knowledge graph supports semantic entity type classification:

Source: lightrag_webui/src/utils/graphColor.ts

Deployment Options

Production Deployment with Kubernetes

For scalable production deployments:

# 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

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

3D Graph Visualization

LightRAG includes an interactive 3D graph viewer:

# 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

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

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 Source: lightrag_webui/src/lib/runtimeConfig.ts

LLM Requirements

LightRAG has higher LLM requirements than traditional RAG systems due to entity-relationship extraction:

Source: 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

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:

# 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

See Also

• Programing with LightRAG Core - Python API reference
• LightRAG API Server - REST API documentation
• Advanced Features - Multimodal, observability, and evaluation
• Interactive Setup Guide - Configuration wizard documentation
• Docker Deployment - Container deployment guide
• Offline Deployment - Air-gapped installation
• RAG-Anything - Multimodal document processing (merged into LightRAG)
• VideoRAG - Long-context video understanding

Related Pages

Related topics: Deployment Guide, API Server

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

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

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

Installation Methods Overview

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

# Using uv (recommended)
uv pip install lightrag-hku

# Using pip
pip install lightrag-hku

Method 2: Install from Source

# 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

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

Method 1: Install from PyPI

# 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

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

Building the WebUI Frontend

After installing LightRAG Server, you need to build the frontend artifacts:

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

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

Docker Deployment

Docker deployment provides a complete, containerized environment with all storage backends and services pre-configured.

Quick Start with Docker Compose

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

Docker Image Verification

Official GitHub Container Registry (GHCR) images are signed with Sigstore Cosign using GitHub OIDC. To verify an official image:

# See docs/DockerDeployment.md for detailed verification commands

Source: README.md

Starting Specific Services

Docker Compose defines services for different components:

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

Setup Commands

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

Setup Flow

graph LR
    A[make env-base] --> B[Configure LLM<br/>Configure Embedding<br/>Configure Reranker]
    B --> C[make env-storage]
    C --> D[Choose Storage Backend<br/>PostgreSQL, Neo4j, MongoDB<br/>OpenSearch, etc.]
    D --> E[make env-server]
    E --> F[Server Configuration<br/>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

Configuration

Environment Variables Setup

Copy the example environment file and configure your settings:

cp env.example .env
# Edit .env with your preferred text editor

Key Configuration Options

Source: env.example

Role-Specific LLM Configuration

LightRAG v1.5+ supports role-specific LLM configuration with 4 distinct roles:

Installing Visualization Tools

LightRAG includes a 3D graph visualization tool for exploring knowledge graphs.

Installation

# 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

Launch the Viewer

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 for instructions on pre-installing all dependencies and cache files. Source: README.md

Verifying Installation

Quick Verification

After installation, verify LightRAG is working:

# 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:

make env-security-check

This audits the current .env for security risks. Source: README.md

Common Installation Issues

Issue: uv not found

Install uv first:

# 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:

cd lightrag_webui
npm install
npm run build

Source: lightrag_webui/README.md

Issue: Docker images not starting

Ensure Docker and Docker Compose are properly installed:

docker --version
docker compose version

Next Steps

After installation, proceed to:

• Quick Start Guide - Get started with your first RAG query
• Configuration Reference - Complete configuration options
• API Documentation - Server API reference
• Programming with Core - Core API for Python integration

See Also

• LightRAG Server Documentation
• Interactive Setup Guide
• Docker Deployment Guide
• Offline Deployment Guide
• Advanced Features

Related Pages

Related topics: Text Chunking Strategies, Storage Backends

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.

Related Pages

Related topics: System Architecture, Multimodal Document Processing

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

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

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

Comparison Table

Paragraph Semantic Chunking

The default and recommended strategy that splits text at paragraph boundaries while respecting semantic units.

Source: 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

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

Usage Example

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

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

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

Usage Example

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

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

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

Usage Example

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

Token Size Chunking

A simple strategy that splits text purely by token count without semantic awareness.

Source: 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

Usage Example

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:

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:

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

API Parameters

When inserting documents via the API:

{
  "file": "<binary>",
  "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 (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

*n = document length, d = embedding dimension*

See Also

• LightRAG Server Documentation
• Programming with Core
• Advanced Features
• Interactive Setup Guide

Related Pages

Related topics: System Architecture, Programming with LightRAG Core

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.

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<br/>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<br/>Default]
    D1 --> D1b[Neo4jGraphImpl]
    D1 --> D1c[PostgresGraphImpl]
    D1 --> D1d[MongoGraphImpl]
    D1 --> D1e[OpenSearchGraphImpl]
    
    E --> E1[NetworkXImpl<br/>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:

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:

Source: lightrag/kg/factory.py

Neo4j (Graph Storage)

Neo4j provides enterprise-grade graph database capabilities with Cypher query language support.

Configuration Options:

Schema:

// 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

PostgreSQL

PostgreSQL with the pgvector extension provides a unified relational backend for all storage types.

Configuration Options:

Table Schemas:

-- 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

MongoDB

MongoDB provides flexible document storage with native vector search capabilities in MongoDB Atlas.

Configuration Options:

Collection Schemas:

// 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

OpenSearch

OpenSearch provides a unified storage backend supporting all four storage types, introduced in v1.4.11.

Configuration Options:

Index Mappings:

// 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

Milvus

Milvus is a dedicated vector database optimized for high-performance similarity search at scale.

Configuration Options:

Collection Schema:

{
    "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:

Source: lightrag/kg/milvus_impl.py Source: docs/MilvusConfigurationGuide.md

Configuration Guide

Environment Variables

Storage backends are configured through environment variables. The StorageFactory reads these at initialization:

# 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:

# 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

Backend Selection Guidelines

Development and Testing

For local development and testing, use default backends:

# No special configuration needed - defaults to:
# KV: SqliteKVImpl
# Vector: NetworkXImpl  
# Graph: NetworkXImpl
# DocStatus: SqliteDocStatusImpl

Single-Node Production

For single-node production deployments:

Distributed Production

For distributed deployments requiring high availability:

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.

1. Graph Data: Entity and relationship semantics are preserved across backends, but indexing strategies differ.

1. Vector Data: Embedding dimensions must match the configured embedding model.

1. DocStatus: Document IDs are consistent, but status schemas may vary slightly.

Exporting Knowledge Graph Data

LightRAG supports exporting graph data for migration:

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

See Also

• ProgramingWithCore.md - Core API reference including storage initialization
• InteractiveSetup.md - Setup wizard documentation
• DockerDeployment.md - Containerized deployment with storage services
• AdvancedFeatures.md - Additional features including multimodal processing
• MilvusConfigurationGuide.md - Detailed Milvus setup guide

Related Pages

Related topics: Programming with LightRAG Core, Deployment Guide

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

Key Capabilities

Source: docs/LightRAG-API-Server.md

Architecture

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

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

Query Modes

LightRAG supports six distinct query modes, each optimized for different retrieval strategies:

Source: lightrag_webui/src/api/lightrag.ts:10

Query Request Parameters

Source: lightrag_webui/src/api/lightrag.ts:20-40

Document Management API

Supported File Types

The API Server processes documents through an intelligent pipeline that handles multiple formats:

Source: lightrag_webui/src/lib/constants.ts:1-80

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:

Source: docs/LightRAG-API-Server.md

Authentication

Auth Configuration

The API Server supports token-based authentication with the following configuration options:

Source: docs/LightRAG-API-Server.md

Auth Status Response

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

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

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

Prefix Normalization

The normalizeWebuiPrefix function ensures consistent path handling with a leading / and trailing /.

Source: 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

Pipeline Status Monitoring

The API provides real-time pipeline status for monitoring document processing:

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<string, any>
}

Source: lightrag_webui/src/api/lightrag.ts:165-180

Queue Status Monitoring

The API also exposes queue statistics for LLM and embedding operations:

Source: lightrag_webui/src/api/lightrag.ts:120-130

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

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

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

Installation and Deployment

Docker Deployment

The recommended deployment method uses Docker Compose:

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:

make env-base           # Configure LLM, embedding, reranker
make env-storage        # Configure storage backends
make env-server         # Configure server settings

Source: README.md:60-90

Environment Variables

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

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
• Advanced Features
• Interactive Setup Guide
• Docker Deployment
• Offline Deployment

Related Pages

Related topics: API Server, System Architecture

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

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

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<br/>Vector Store<br/>Graph Store<br/>Doc Status")]
    end

Query Modes

LightRAG Core supports six distinct retrieval modes, each optimized for different query types:

Note: When a Reranker model is enabled, it is recommended to set "mix mode" as the default query mode.

Source: 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

# 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 for pre-installation instructions.

Initialization

Basic Initialization

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:

Source: lightrag/lightrag.py — see __init__ method

LLM Provider Configuration

LightRAG Core supports multiple LLM providers through a binding system.

OpenAI

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

Ollama (Local Models)

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

Azure OpenAI

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

Google Gemini

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:

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

HuggingFace Local Inference

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

Role-Specific LLM Configuration

LightRAG supports configuring different LLM models for different roles:

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:

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

Source: lightrag_webui/src/api/lightrag.ts — see QueryRequest type

Document Insertion

Inserting Text

# 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

documents = [
    "Document 1 content...",
    "Document 2 content...",
    "Document 3 content..."
]

# Insert multiple documents
results = await rag.ainsert(documents)

Inserting Custom Knowledge Graph Data

# 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

# Perform a query
result = await rag.aquery(
    "What is LightRAG and how does it work?",
    param=QueryParam(mode="mix")
)

print(result)

Query with Streaming

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

# 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

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:

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

Entity and Relationship Management

Query Entities

# 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

# Query relationships
relationships = await rag.query_relations(
    entity_info=[("LightRAG", "Framework")],
    mode="byRelation"
)

Delete Entities

# Delete an entity by name
await rag.delete_entity(entity_name="LightRAG")

Delete Relationships

# Delete a relationship
await rag.delete_relation(
    src_id="LightRAG",
    tgt_id="GPT-4",
    relation_type="uses"
)

Merge Entities

# 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:

# 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 — 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

Advanced Features

Token Usage Tracking

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

Knowledge Graph Data Export

# Export the knowledge graph
kg_data = await rag.export_graph_data()

# kg_data contains:
# {
#     "entities": [...],
#     "relationships": [...]
# }

LLM Cache Management

# 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

# 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:

# 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

Multimodal Document Processing

LightRAG Core supports multimodal document processing through integration with external parsing services (MinerU or Docling):

# 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

Storage Backend Configuration

Supported Storage Backends

PostgreSQL Configuration

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

rag = LightRAG(
    graph_storage="Neo4JStorage",
    # Neo4j connection settings via env vars
)

Environment variables:

• NEO4J_URI
• NEO4J_USERNAME
• NEO4J_PASSWORD

MongoDB Configuration

rag = LightRAG(
    kv_storage="MongoKVStorage",
    vector_storage="MongoVectorStorage",
    doc_status_storage="MongoDocStatusStorage",
    # MongoDB connection settings via env vars
)

Environment variables:

• MONGO_URI

OpenSearch Configuration

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

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

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

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

Debug Mode

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

rag = LightRAG(working_dir="./rag_working")

See Also

• LightRAG API Server — REST API and Web UI documentation
• Advanced Features — Token tracking, Langfuse, RAGAS evaluation
• Interactive Setup — Configuration wizard documentation
• Docker Deployment — Containerized deployment
• Offline Deployment — Air-gapped environment setup
• Example Codes — Sample implementations in the examples folder

Related Pages

Related topics: Text Chunking Strategies, Advanced Features

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 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

Supported Document Formats

LightRAG supports a variety of document formats through its multimodal processing pipeline:

Source: 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:

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

Multimodal Context Management

The multimodal_context.py module handles the assembly and management of content extracted from various modalities:

# 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

Configuration

Environment Variables for Multimodal Processing

To enable multimodal document processing, configure the following environment variables:

Source: 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:

Source: README.md

File Processing Pipeline

The file processing pipeline coordinates the flow from document upload to queryable storage:

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

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:

MINERU_URL=http://localhost:8080

Source: 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:

DOCLING_URL=http://localhost:5000

Source: lightrag/parser/external/docling/__init__.py

Usage Patterns

Uploading Multimodal Documents via API

# Upload a PDF with images and tables
curl -X POST "http://localhost:8080/api/v1/documents/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "process_multimodal=true"

Querying with Multimodal Context

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

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:

# 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

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:

LIGHTRAG_WEBUI_PATH=/lightrag/

Source: GitHub Issue #2755, lightrag_webui/src/lib/runtimeConfig.ts

Performance Considerations

Batch Processing

For large-scale multimodal document ingestion, consider the following optimizations:

VLM Model Selection

Vision Language Models have significant performance implications:

Source: README.md

Limitations

1. External Service Dependency: Multimodal parsing requires either MinerU or Docling services to be running and accessible.

1. VLM Requirements: Image, table, and formula understanding requires a properly configured Vision Language Model with sufficient context length.

1. Processing Time: Multimodal documents typically take longer to process than plain text documents due to additional extraction and VLM inference steps.

1. 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

See Also

• LightRAG Server Documentation - Full server setup including multimodal endpoints
• Advanced Features - Token tracking, exports, and observability
• Programming with Core - Python API reference for multimodal operations
• Interactive Setup - Wizard-based configuration for parsing services
• Docker Deployment - Containerized deployment with all services
• RAG-Anything Repository - Original multimodal project (now merged into LightRAG)

Related Pages

Related topics: Installation Guide, API Server

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:

Source: README.md

Architecture Overview

graph TB
    subgraph "Client Layer"
        WebUI["Web UI<br/>(React)"]
        API["REST API<br/>(FastAPI)"]
        Ollama["Ollama Compatible<br/>Interface"]
    end
    
    subgraph "LightRAG Core"
        Indexer["Document Indexer"]
        QueryEngine["Query Engine"]
        KGBuilder["Knowledge Graph<br/>Builder"]
    end
    
    subgraph "Storage Layer"
        VectorDB["Vector Database<br/>(PGVector/Milvus/Qdrant/Weaviate]"]
        GraphDB["Graph Database<br/>(Neo4j)"]
        KVStore["KV Store<br/>(PostgreSQL/MongoDB/OpenSearch]"]
        DocStatus["Document Status<br/>(PostgreSQL/MongoDB]"]
    end
    
    subgraph "AI Providers"
        LLM["LLM Provider<br/>(OpenAI/Gemini/Local Ollama]"]
        Embedder["Embedding Model"]
        Reranker["Reranker Model"]
    end
    
    WebUI --> API
    API --> LightRAGCore
    Ollama --> API
    LightRAGCore --> StorageLayer
    LightRAGCore --> AIProviders

Prerequisites

Hardware Requirements

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

Environment Configuration

Configuration File Generation

LightRAG provides an interactive setup wizard to generate the .env configuration file:

# 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

Environment Variables Reference

Source: env.example

Docker Deployment

Quick Start with Docker Compose

The fastest way to deploy LightRAG with all dependencies:

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

Docker Service Architecture

graph LR
    subgraph "Docker Compose Services"
        direction TB
        Server["lightrag-server<br/>:56789"]
        WebUI["lightrag-webui<br/>:56790"]
        Neo4j["neo4j<br/>:7474, :7687"]
        PostgreSQL["postgres<br/>:5432"]
        Qdrant["qdrant<br/>:6333"]
        MinIO["minio<br/>:9000, :9001"]
    end
    
    Server <--> Neo4j
    Server <--> PostgreSQL
    Server <--> Qdrant
    Server <--> MinIO
    WebUI --> Server

Configuration Options for Docker

Verifying Official Docker Images

Official GHCR images are signed with Sigstore Cosign using GitHub OIDC:

# 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

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:

Source: k8s-deploy/README.md

Installing with Helm

# 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:

# 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

Kubernetes Resource Scaling

graph TD
    subgraph "Kubernetes Cluster"
        subgraph "Namespaces"
            Frontend["frontend-ns"]
            Backend["backend-ns"]
            Data["data-ns"]
        end
        
        subgraph "Backend Namespace"
            Server["lightrag-server<br/>Deployment"]
            HPA["Horizontal Pod<br/>Autoscaler"]
        end
        
        subgraph "Data Namespace"
            Postgres["PostgreSQL<br/>StatefulSet"]
            Neo4j["Neo4j<br/>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:

# 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

1. Transfer files to the air-gapped environment:

# 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/

1. Install in the offline environment:

# 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

Offline Embedding and LLM Support

In offline environments, configure local model providers:

# 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

# 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

Runtime Path Configuration

The WebUI supports deployment behind reverse proxies with custom path prefixes. Configuration is injected at runtime:

# 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:

<!-- __LIGHTRAG_RUNTIME_CONFIG__ -->  <!-- Replaced at runtime -->

Source: 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

Recommended Reverse Proxy Setup

For Apache:

<VirtualHost *:443>
    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]
</VirtualHost>

For 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

# 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:

source .venv/bin/activate  # Linux/macOS
# Or: .venv\Scripts\activate  # Windows

# Start the development server
lightrag-server

Source: docs/InteractiveSetup.md

Storage Backend Selection

LightRAG supports multiple storage backends for different components:

OpenSearch as Unified Backend

OpenSearch can serve as a unified backend for all four storage types:

# 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

Troubleshooting Common Deployment Issues

Port Conflicts

If ports 56789 or 56790 are already in use:

# 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

# 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:

# 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.

# 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:

make env-server
# Select authentication options during wizard execution

Passwords are hashed with bcrypt prefix for secure storage.

Source: docs/InteractiveSetup.md

Security Audit

Run the security audit tool to check for configuration risks:

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 - Detailed setup wizard documentation
• Docker Deployment - Advanced Docker configuration
• Offline Deployment - Air-gapped environment setup
• Programming with Core - Core API usage
• Advanced Features - Token tracking, exports, and evaluation
• Multi-Site Deployment - Distributed deployment topology

Related Pages

Related topics: Multimodal Document Processing, Programming with LightRAG Core

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.

Doramagic Pitfall Log

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
• 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.
• Recommended 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
• 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.
• Recommended 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.10. Context: Observed when using windows
• 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
• 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
• Recommended 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
• Evidence: failure_mode_cluster:github_issue | fmev_13dbaaeb506c72cc5b9ecd91cdabc2a2 | https://github.com/HKUDS/LightRAG/issues/2755

5. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11. Context: Observed when using docker
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.11rc2. Context: Observed during installation or first-run setup.
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.12. Context: Observed when using python
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.13. Context: Observed when using node
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.14. Context: Observed when using python, docker
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.5.0rc3. Context: Observed when using python
• 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
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended 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
• 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?
• Recommended 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
• Evidence: failure_mode_cluster:github_issue | fmev_dfedf4f77da9bdcac28253497ad6ce68 | https://github.com/HKUDS/LightRAG/issues/2642

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using LightRAG with real data or production workflows.

• [[Question]: How to distinguish documents with same name but different co](https://github.com/HKUDS/LightRAG/issues/3158) - github / github_issue
• Guidance on Adding Multimodal Support to LightRAG: Wrap with RAG‑Anythin - github / github_issue
• [[Bug]: Not working on reverse proxy - sub path](https://github.com/HKUDS/LightRAG/issues/2755) - github / github_issue
• v1.5.0rc3 - github / github_release
• v1.4.16 - github / github_release
• v1.4.15 - github / github_release
• v1.4.14 - github / github_release
• v1.4.13 - github / github_release
• v1.4.12 - github / github_release
• v1.4.11 - github / github_release
• v1.4.11rc2 - github / github_release
• v1.4.10 - github / github_release