$ show HKUDS/LightRAG
LightRAG is a production-ready Retrieval-Augmented Generation (RAG) framework that combines knowledge graph construction with vector-based retrieval. The system implements a dual-layer architecture managing both knowledge graphs (entities, relationships) and vector embeddings, enabling both local (entity-focused) and global (theme-focused) query modes plus hybrid combinations. It provides a FastAPI-based REST server with an embedded React WebUI, supporting 10+ LLM providers (OpenAI, Azure, Anthropic, Gemini, Ollama, Bedrock, etc.), 8+ vector/graph storage backends (PostgreSQL+pgvector/AGE, Neo4j, Milvus, Qdrant, Redis, MongoDB, OpenSearch, FAISS, NanoVectorDB), and a multimodal document parsing pipeline integrating MinerU and Docling for PDF/Office documents with tables, equations, and images. The codebase demonstrates strong engineering practices: async-first architecture with configurable concurrency controls, role-specific LLM configuration (EXTRACT, QUERY, KEYWORDS, VLM), atomic file operations for crash-safe persistence, comprehensive test coverage (300+ tests), and production deployment artifacts (Docker, Kubernetes/Helm, systemd). The parser layer is particularly well-designed with a registry-based engine dispatch (native docx/markdown, MinerU, Docling) producing a unified sidecar format. Recent additions include reranking support, asymmetric embeddings, document deletion with KG regeneration, and RAGAS/Langfuse integration for evaluation and observability.
The LLM identified 9 files worth highlighting for reuse:
Central parser engine registry using entry points for third-party extensibility. Declares engine capabilities (suffixes, concurrency, queue groups) and provides lazy-loaded parser instances. Cleanly separates user-selectable engines (native, legacy, mineru, docling) from internal format handlers (reuse, passthrough). The registry is imported early by both the API server and CLI without pulling heavy dependencies (httpx), enabling capability queries in constrained environments.
Native parser dispatcher that routes documents to docx or markdown parsers based on file suffix while presenting a single 'native' engine to the registry. Each concrete parser retains its own sidecar_path_style (docx: basename_only for byte-equivalent golden tests; markdown: with_prefix). The dispatcher delegates the entire parse() call rather than subclassing, avoiding inheritance coupling and preserving engine-specific behavior.
Core utilities including use_llm_func_with_cache which partitions LLM response caches by both response_format (json vs text) and llm_cache_identity (binding/model/host) to prevent cross-contamination. Also provides strip_control_characters for removing C0 separators (FS/GS/RS/US) and surrogates from parser output while preserving tabs/newlines and markup — critical for preventing downstream chunking corruption. The create_prefixed_exception helper safely wraps exceptions with context prefixes even for types with keyword-only constructors (e.g., openai.APIStatusError).
Storage backend factory resolving string names to implementation classes. Four default backends (JsonKVStorage, NanoVectorDBStorage, NetworkXStorage, JsonDocStatusStorage) are imported directly for zero-dependency operation; all others resolve lazily via the STORAGES registry using importlib with 'lightrag' as package anchor. This enables pluggable storage without requiring all optional dependencies at install time.
Main FastAPI application factory with comprehensive production features: workspace isolation via LIGHTRAG-WORKSPACE header, role-specific LLM configuration (4 roles with independent bindings/models/timeouts), optimized embedding function creation with provider-default max_token_size/embedding_dim inheritance, smart static file serving with runtime config injection (window.__LIGHTRAG_CONFIG__) for reverse-proxy mount points, Swagger UI dark/light theme toggle, and Ollama-compatible /api/* routes. The lifespan manager handles storage initialization, data migration, and graceful shutdown with keyed-lock cleanup.
Single executable specification for the LightRAG Sidecar format (docs/LightRAGSidecarFormat-zh.md). Takes an IRDoc (intermediate representation from any parser engine) and emits a spec-compliant *.parsed/ directory with blocks.jsonl, optional tables/equations/drawings JSON, and asset directory. Includes path traversal protection for drawing assets (rejects ../ and absolute paths) while preserving external URLs. The IR builder pattern allows native docx, MinerU, and Docling parsers to share identical output structure.
Chunking strategy registry supporting four selectable strategies: Fixed (F), Recursive (R), Semantic Vector (V), and Paragraph Semantic (P). Maintains backward compatibility with legacy chunking_by_token_size signature while exposing a new file-chunker contract with strategy-specific kwargs. The Paragraph Semantic chunker consumes docx-native .blocks.jsonl sidecars for heading-aware chunking with reference-section dropping, falling back to Recursive when sidecars are unavailable. LangChain wrappers are lazy-imported to avoid mandatory dependency.
OpenAI/Azure OpenAI LLM and embedding implementations with tenacity-based retry (exponential backoff on rate limits, connection errors, timeouts). The openai_embed and azure_openai_embed functions are wrapped as EmbeddingFunc instances with send_dimensions control for Jina/Gemini APIs. The openai_complete_if_cache and azure_openai_complete_if_cache provide raw completion with optional response_format and legacy extraction boolean shims. Shared logic eliminates duplication between OpenAI and Azure paths.
Native DOCX to IRDoc converter extracting text, tables, equations (OMML→LaTeX via ommlparser), and drawings with asset extraction. Produces heading-hierarchical blocks with parent_headings, level, and positions (paraId ranges). Handles missing paraIds gracefully, drops empty blocks, and sanitizes drawing asset paths against traversal. The OMML cleaner fixes common invalid LaTeX patterns (\cbrt, \qdrt, \sfrac, limit operators). Output matches golden test fixtures for regression safety.