LightRAG

LightRAG implements a dual-path retrieval system that routes queries through both semantic vector search and knowledge graph traversal, selecting the optimal retrieval mode based on query characteristics. The system extracts entities and relationships from documents to build a knowledge graph, then during query processing evaluates whether to use vector similarity, graph-based entity matching, or a combined approach. This hybrid approach leverages tree-structured entity hierarchies and relationship patterns to improve retrieval precision beyond pure semantic similarity.

LightRAG processes ingested documents through an LLM-based extraction pipeline that identifies entities, their types, and relationships between them, automatically constructing a knowledge graph without manual schema definition. The system uses prompt-based extraction with configurable entity types and relationship predicates, then deduplicates and normalizes extracted entities across documents using embedding-based similarity matching. The resulting graph is stored in a pluggable backend (Neo4j, relational DB, or file-based) with support for incremental updates as new documents arrive.

LightRAG includes a testing and evaluation framework that measures retrieval quality through metrics like precision, recall, and relevance scoring. The system supports ground-truth based evaluation where expected context chunks are compared against retrieved results, and can generate synthetic evaluation datasets from documents. Evaluation results are tracked over time, enabling measurement of RAG quality improvements as documents are added or retrieval strategies are tuned.

LightRAG supports optional reranking of retrieved context using cross-encoder models that score retrieved chunks based on relevance to the query. The system retrieves a larger candidate set using vector/graph search, then reranks using a cross-encoder to improve precision of top results. Reranking can use local models (sentence-transformers) or API-based services, with configurable reranking thresholds and result limits.

LightRAG includes a 3D graph visualization tool that renders entities as nodes and relationships as edges in an interactive 3D space, enabling visual exploration of knowledge graph structure. The visualization supports filtering by entity type and relationship type, zooming and panning, and clicking on nodes to inspect entity properties and connected relationships. The tool helps users understand graph structure, identify clusters of related entities, and debug entity extraction and deduplication.

LightRAG supports batch processing of multiple documents with detailed status tracking per document (queued, processing, completed, failed) and automatic error recovery. The system maintains a processing queue, retries failed documents with exponential backoff, and provides APIs to query processing status and retrieve error logs. Failed documents can be reprocessed without affecting successfully processed documents, enabling robust handling of large document collections.

LightRAG provides a unified storage abstraction layer that supports multiple backend types (relational databases, NoSQL stores, vector databases, graph databases, and file-based storage) through a consistent interface. Each workspace maintains isolated data with namespace support, enabling multi-tenant deployments and independent knowledge graphs per user or project. The abstraction handles schema evolution, data migration between backends, and concurrent access through locking mechanisms, allowing users to swap storage backends without changing application code.

LightRAG exposes a production-ready REST API server (built with FastAPI) that manages document ingestion, processing status tracking, knowledge graph exploration, and query execution. The API implements document lifecycle states (uploading, processing, completed, failed), provides endpoints for monitoring ingestion progress, and supports both synchronous and asynchronous query processing. Authentication is handled through API keys and password hashing, with role-based access control for multi-user deployments. The server includes Ollama API compatibility for drop-in replacement with local LLM inference.

LightRAG includes a web-based user interface (built with React/TypeScript) that provides document management, interactive knowledge graph visualization, and a retrieval testing sandbox. The UI allows users to upload documents, monitor ingestion progress, visualize entities and relationships in an interactive graph view, test queries in real-time, and inspect retrieved context with source attribution. The frontend supports internationalization (i18n) and configurable settings for retrieval modes, entity types, and LLM parameters without requiring code changes.

LightRAG abstracts LLM provider selection through a binding system that supports OpenAI, Anthropic, Google Gemini, Ollama, and other compatible providers. The system allows configuration of different LLM providers for different tasks (entity extraction, query processing, response generation) without code changes, enabling cost optimization and model selection based on task requirements. Provider bindings handle API authentication, request formatting, and response parsing, with fallback support for provider failures.

LightRAG processes multiple documents concurrently using Python's asyncio and thread pools, with support for incremental knowledge graph updates as new documents arrive. The system maintains processing state (queued, processing, completed, failed) for each document, allowing monitoring of ingestion progress and recovery from failures. Incremental updates merge new entities and relationships into the existing graph, deduplicating entities using embedding similarity and updating relationship counts. Concurrency is coordinated through locking mechanisms to prevent race conditions in shared storage.

LightRAG supports chain-of-thought (CoT) reasoning where complex queries are decomposed into multiple steps, with intermediate reasoning steps and context retrieval between steps. The system uses LLM-guided query decomposition to break down complex questions into simpler sub-queries, retrieves context for each sub-query independently, and then synthesizes final answers using accumulated context. This approach improves reasoning quality for multi-hop questions and enables transparent reasoning traces for debugging.

LightRAG uses embedding-based similarity matching to deduplicate entities across documents, merging entities with similar semantic meaning while preserving distinct entities with different meanings. The system computes embeddings for extracted entity names, compares them against existing entities using cosine similarity with configurable thresholds, and merges entities that exceed the threshold. This approach handles entity name variations (e.g., 'CEO' vs 'Chief Executive Officer') and prevents duplicate entities from fragmenting the knowledge graph.

LightRAG provides production-ready Docker images and Kubernetes manifests for containerized deployment, with environment-based configuration for storage backends, LLM providers, and server settings. The system supports offline deployment with bundled dependencies, Gunicorn-based production serving, and Kubernetes StatefulSet patterns for distributed deployments. Configuration is managed through environment variables and config files, enabling easy customization without rebuilding images.