How hkuds/lightrag works
Purpose and Entry Points
LightRAG is a Python graph-based retrieval-augmented generation system: it indexes documents into text/vector/knowledge-graph representations, then answers using local, global, naive, hybrid, or mix retrieval. The embedded SDK centers on lightrag/lightrag.py, with query/index operations in lightrag/operate.py. The primary deployment entry is the ASGI server in lightrag/api/lightrag_server.py; it exposes REST and serves built WebUI assets. Package/CLI definitions are rooted in pyproject.toml.
API, Access, and User Surfaces
The API server composes document, graph, query, Ollama-compatible, and UI-customization routers from lightrag/api/routers/document_routes.py, lightrag/api/routers/graph_routes.py, and lightrag/api/routers/query_routes.py. Authentication, admission/capacity control, body limits, and runtime validation form the public-boundary layer in lightrag/api/auth.py, lightrag/api/admission.py, and lightrag/api/runtime_validation.py. The React/TypeScript UI has distinct admin and query-only entry surfaces: lightrag_webui/src/App.tsx and lightrag_webui/src/features/workspace/WorkspaceApp.tsx.
Ingestion Pipeline
Document ingestion is an asynchronous, status-tracked pipeline coordinated by lightrag/pipeline.py; ingress and scheduling primitives live in lightrag/kg/pipeline_ingress.py and lightrag/kg/scan_job_store.py. It accepts direct text and files, persists lifecycle status, bounds concurrency, and supports retry, cancellation, deletion, and recovery. File parsing is dispatched by rules/registries in lightrag/parser/routing.py and lightrag/parser/registry.py, separating parser engines from downstream indexing.
Parse, Multimodal IR, and Chunking
Native Markdown/DOCX, legacy, and external Docling/MinerU parser implementations normalize files into an intermediate representation/sidecar contract. Key implementations are lightrag/parser/docx/parser.py, lightrag/parser/markdown/parser.py, and lightrag/parser/external/docling/parser.py. Parsed content can include images, tables, and equations; sidecar persistence/backfill is in lightrag/sidecar/ir.py and lightrag/sidecar/writer.py. Chunking then selects fixed/token, recursive, vector-semantic, or paragraph-semantic strategies through lightrag/chunker/registry.py and lightrag/chunker/paragraph_semantic.py.
Extraction and Index Construction
Chunk content is embedded and sent to role-specific model bindings for entity/relation extraction, keyword generation, query answering, and optional visual analysis. Provider adapters are isolated under lightrag/llm/, with representative bindings in lightrag/llm/openai.py and lightrag/llm/ollama.py; role resolution is in lightrag/llm_roles.py. Extraction/query orchestration in lightrag/operate.py writes chunks, entities, relationships, provenance, and LLM caches. This is the main boundary between untrusted/model-produced output and validated persistent graph records.
Storage Abstraction and Consistency
Four logical stores—KV/cache, vectors, graph, and document status—are abstracted behind factories and shared lifecycle/control mechanisms in lightrag/kg/factory.py, lightrag/kg/shared_storage.py, and lightrag/kg/write_seq.py. Local defaults use JSON/NanoVectorDB/NetworkX (lightrag/kg/json_kv_impl.py, lightrag/kg/networkx_impl.py); production options include unified PostgreSQL, MongoDB, or OpenSearch plus specialized Neo4j, Milvus, Qdrant, Redis, and Memgraph adapters. Vector-space provenance and embedding-dimension compatibility are handled in lightrag/kg/vector_space.py.
Query Flow and Operations
Queries enter through API or SDK, are validated in lightrag/query_validation.py, and execute retrieval/generation in lightrag/operate.py. Depending on mode, the system combines vector chunk search with graph entity/relation traversal, optionally reranks via lightrag/rerank.py, constructs bounded context, and invokes the QUERY model; result caching is stored in KV. Administrative graph edits and document deletion must coordinate with pipeline/write gates so affected graph/vector state can be rebuilt. Repair and migration CLIs—including vector rebuild and graph migration—live in lightrag/tools/rebuild_vdb.py and lightrag/tools/migrate_graph_storage.py.
Runtime and Infrastructure
The server targets Python 3.10+, with Gunicorn support in lightrag/api/run_with_gunicorn.py. The frontend is built with Bun/Vite from lightrag_webui/package.json. Docker Compose variants (docker-compose.yml, docker-compose-full.yml) and Helm/Kubernetes manifests under k8s-deploy/lightrag/ deploy the service and optional databases. External dependencies can include LLM/embedding/reranking providers, local Ollama/vLLM-style services, and self-hosted or cloud MinerU/Docling parser services.
Main entry points: pipeline.py Document Pipeline · operate.py Index & Query Orchestration · shared_storage.py Persistent Stores · query_routes.py API Routers
Components 19
User Surfaces
- LightRAG SDK · Embedded indexing and query interface.
lightrag/lightrag.py - ASGI Server · Serves REST APIs and built WebUI assets.
lightrag/api/lightrag_server.py - API Routers · Document, graph, query, Ollama, and UI endpoints.
lightrag/api/routers/query_routes.py - Public Boundary Controls · Authentication, capacity, body-limit, and runtime checks.
lightrag/api/auth.py - WebUI · Admin and query-only workspace surfaces.
lightrag_webui/src/App.tsx
Ingestion & Indexing
- Document Pipeline · Tracks lifecycle, concurrency, retry, cancellation, and recovery.
lightrag/pipeline.py - Pipeline Ingress & Jobs · Accepts documents and persists scan jobs.
lightrag/kg/pipeline_ingress.py - Parser Routing · Selects native, legacy, or external parser engines.
lightrag/parser/routing.py - Multimodal IR & Sidecars · Persists normalized text, images, tables, and equations.
lightrag/sidecar/ir.py - Chunking Strategies · Chooses fixed, recursive, vector, or paragraph semantic chunks.
lightrag/chunker/registry.py
Retrieval & Models
- Index & Query Orchestration · Extracts graph records and executes retrieval/generation.
lightrag/operate.py - LLM Role Bindings · Provider-backed embedding, extraction, keyword, query, and visual roles.
lightrag/llm_roles.py - Query Validation
lightrag/query_validation.py - Hybrid Retrieval & Rerank · Combines vector and graph retrieval into bounded model context.
lightrag/rerank.py
Storage & Operations
- Storage Abstraction · Coordinates KV, vector, graph, and document-status backends.
lightrag/kg/factory.py - Write Sequencing · Gates coordinated pipeline and administrative writes.
lightrag/kg/write_seq.py - Persistent Stores · Local or production database adapters.
lightrag/kg/shared_storage.py - Rebuild & Migration Tools · Rebuilds vectors and migrates graph storage.
lightrag/tools/rebuild_vdb.py - Deployment Manifests · Compose and Helm deployments with optional databases.
docker-compose.yml
Connections 26
- WebUI → ASGI Server: REST requests
- ASGI Server → Public Boundary Controls: applies controls
- Public Boundary Controls → API Routers: admits requests
- API Routers → LightRAG SDK: uses service API
- LightRAG SDK → Document Pipeline: indexes documents
- API Routers → Document Pipeline: document operations
- Document Pipeline → Pipeline Ingress & Jobs: schedules and tracks
- Document Pipeline → Parser Routing: dispatches files
- Parser Routing → Multimodal IR & Sidecars: normalizes content
- Multimodal IR & Sidecars → Chunking Strategies: supplies IR
- Chunking Strategies → Index & Query Orchestration: indexes chunks
- Index & Query Orchestration → LLM Role Bindings: invokes role models
- Index & Query Orchestration → Storage Abstraction: reads and writes records
- Storage Abstraction → Persistent Stores: selects backend adapters
- Document Pipeline → Write Sequencing: coordinates writes
- Write Sequencing → Persistent Stores: serializes mutations
- LightRAG SDK → Query Validation: submits queries
- API Routers → Query Validation: validates queries
- Query Validation → Index & Query Orchestration: approved query
- Index & Query Orchestration → Hybrid Retrieval & Rerank: retrieves context
- Hybrid Retrieval & Rerank → LLM Role Bindings: generates answer
- Hybrid Retrieval & Rerank → Persistent Stores: vector, graph, cache access
- Rebuild & Migration Tools → Write Sequencing: coordinates repair
- Rebuild & Migration Tools → Persistent Stores: rebuilds and migrates
- Deployment Manifests → ASGI Server: deploys service
- Deployment Manifests → Persistent Stores: provisions optional backends