LightRAG

1. Project/Product Overview

2. What does it mostly do?

2.1 Core Architecture: Two-layer Knowledge Graph Vector Retrieval

The core design of the LightRAG is to bridge the gap between knowledge mapping and vector retrieval, replacing GraphRAG cumbersome community-level clustering with a two-tier architecture:

┌─────────────────────────────────────────────────────┐
│                    LightRAG                          │
│                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ 知识图谱 (KG) │  │ 向量存储 (V)  │  │ KV 缓存     │ │
│  │ 实体+关系图   │  │ 语义相似检索 │  │ LLM 缓存    │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬─────┘ │
│         │                 │                 │        │
│  ┌──────┴─────────────────┴─────────────────┴──────┐ │
│  │             双层检索引擎                           │ │
│  │  • Low-level: 具体实体 + 邻居子图遍历              │ │
│  │  • High-level: 主题关键词 + 全局关系链             │ │
│  │  • 混合模式 (Mix): 图谱 + 向量 + 文本三重融合     │ │
│  └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Index Phase Process:

1. Document segmentation → LLM extraction of entities and relationships → construction of knowledge graph (node = entity, edge = relationship)
2. At the same time, the vector embedding of entities/relationships is generated and stored in the vector database.
3. Generate low-level keys (entity name index) and high-level keys (topic keyword index)
4. Incremental merging of new documents: local maps are directly integrated into the global map through collection merging without reconstruction.

Retrieval phase process:

1. User query → LLM extraction of double-layer keywords (high-level = topic concept, low-level = specific entity)
2. Low-level retrieval: locate entity nodes in the knowledge graph → traverse neighbor subgraphs → obtain relevant relationships and attributes.
3. High-level retrieval: using topic keywords → matching global concept chains in the map → obtaining macro information across documents
4. Vector retrieval: original query embedding-semantic similarity matching text block.
5. Three-level result fusion → LLM generates final answer (with citation source)

2.2 LightRAG vs GraphRAG Core Comparison

Complete List of 2.3 Core Features

- double-layer search : low-level (entity-level exact matching) high-level (subject-level macro understanding), dealing with "what theory Einstein proposed" and "what is the influence of relativity on modern physics"

-Five query modes:Local (entity precision), Global (cross-document topic), Hybrid(Local Global fusion), Naive (traditional vector search), and Mix (triple fusion, recommended by default)

-Incremental Knowledge Base Update: The new document only follows the standard atlas index Pipeline, and the generated local atlas is directly merged into the global atlas through collection merging without reconstruction.

-Document deletion and reconstruction: Use the LLM cache to quickly reconstruct the affected entity relationships to avoid full reconstruction.

-Knowledge Graph Visualization:WebUI has built-in force-guided graph nodes to query sub-graph filters and export HTML

-Citation Traceability: The query result is accompanied by the source document and the reference mark of the specific paragraph.

- Multimodal Processing : Integrated RAG-Anything, supports PDF / Word/Excel/Picture/Form/Formula parsing and cross-modal retrieval, 15 document formats

-Four blocking strategies:Fix (fixed length), Recursive (recursive semantic segmentation), Vector (vector similarity segmentation), and Paragraph (paragraph-aware segmentation)

-Role separation LLM configuration:EXTRACT/QUERY / KEYWORDS / VLM four roles can be independently configured with different models and parameters

-Reorder Enhancement: supports Cohere, Jina, and Alibaba Cloud Reranker, which is enabled by default and significantly improves query quality.

-Evaluation Integration:RAGAS evaluation metrics (context accuracy, fidelity, etc.) Langfuse link tracking

-Offline Deployment: Supports full offline/air gap deployment, including offline LLM and offline storage dependencies

3. Applicable Scenario

4. Not quite the scene

5. Core Competence List

5.1 Indexing and Knowledge Building

5.2 retrieval and query

5.3 deployment and operation and maintenance

5.4 observability

5.5 storage back-end matrix

6. Architecture/deployment/integration approach

6.1 Deployment Mode Overview

Recommended Architecture for 6.2 Production Environments

                             ┌─────────────┐
                             │   用户 / 前端  │
                             └──────┬───────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │    LightRAG API Server         │
                    │    • REST API + WebUI           │
                    │    • JWT / API Key 认证         │
                    │    • 端口: 9621 (默认)          │
                    │    • lightrag-server            │
                    └───┬───────┬───────┬───────────┘
                        │       │       │
              ┌─────────┘  ┌────┘       └─────────┐
              ▼            ▼                      ▼
     ┌────────────┐ ┌────────────┐ ┌────────────────────┐
     │ 图谱存储    │ │ 向量存储    │ │ KV + 文档状态存储   │
     │ • Neo4j    │ │ • Milvus   │ │ • PostgreSQL        │
     │   或 PG AGE │ │   或 Qdrant│ │   或 MongoDB        │
     └────────────┘ └────────────┘ └────────────────────┘
              │            │                      │
              └────────────┴──────────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │  LLM 服务（外部/本地）   │
              │  • OpenAI / Azure       │
              │  • Ollama (本地)        │
              │  • Anthropic / Bedrock  │
              │  • Gemini               │
              └────────────────────────┘

6.3 Supported LLM Providers (20)

6.4 storage backend configuration example

PostgreSQL full-stack storage (unified solution recommended):

# .env 关键配置
LIGHTRAG_KV_STORAGE=PGKVStorage
LIGHTRAG_VECTOR_STORAGE=PGVectorStorage
LIGHTRAG_GRAPH_STORAGE=PGGraphStorage
LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=lightrag
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag

# pgvector 索引优化
POSTGRES_VECTOR_INDEX_TYPE=HNSW
POSTGRES_HNSW_M=16
POSTGRES_HNSW_EF=200

Neo4j Map Milvus Vector (Professional Separation Protocol):

LIGHTRAG_GRAPH_STORAGE=Neo4JStorage
LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage

NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password

MILVUS_URI=http://localhost:19530
MILVUS_TOKEN=root:Milvus

How to use #7.

7.1 Minimum Available Sample (Python SDK)

import asyncio
import os
from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed
from lightrag.utils import setup_logger

setup_logger("lightrag", level="INFO")
WORKING_DIR = "./rag_storage"

async def main():
    # 初始化 LightRAG
    rag = LightRAG(
        working_dir=WORKING_DIR,
        embedding_func=openai_embed,
        llm_model_func=gpt_4o_mini_complete,
    )
    await rag.initialize_storages()

    # 插入文档（支持文本、文件路径、或直接调用 ainsert）
    with open("./contracts/supply_agreement.txt", "r", encoding="utf-8") as f:
        await rag.ainsert(f.read())

    # 多模式查询
    # Local 模式：精准实体查询
    result = await rag.aquery(
        "合同中的违约金条款如何规定？",
        param=QueryParam(mode="local")
    )
    print(f"[Local] {result}")

    # Global 模式：宏观主题理解
    result = await rag.aquery(
        "这份合同的整体风险评估如何？",
        param=QueryParam(mode="global")
    )
    print(f"[Global] {result}")

    # Mix 模式（推荐）：图谱 + 向量 + 文本三重融合
    result = await rag.aquery(
        "双方的付款义务和交付义务之间有什么关系？",
        param=QueryParam(mode="mix")
    )
    print(f"[Mix] {result}")

if __name__ == "__main__":
    asyncio.run(main())

7.2 REST API Docker Compose deployment (recommended production scenario)

# 1. 克隆并配置
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG

# 2. 使用交互式向导配置
make env-base        # 配置 LLM + embedding
make env-storage     # 配置存储后端（PostgreSQL / Neo4j 等）
make env-server      # 配置端口、认证、SSL

# 3. 启动服务
docker compose -f docker-compose-full.yml up -d

# 4. 上传文档
curl -X POST http://localhost:9621/documents/upload \
  -H "X-API-Key: your-api-key" \
  -F "file=@contract.pdf"

# 5. 查询
curl -X POST http://localhost:9621/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "双方的权利义务有哪些？", "mode": "mix"}'

7.3 Ollama local deployment (zero API cost)

# 配置 .env
LLM_BINDING=ollama
LLM_MODEL=qwen2.5:14b
LLM_BINDING_HOST=http://localhost:11434

EMBEDDING_BINDING=ollama
EMBEDDING_MODEL=bge-m3:latest
EMBEDDING_BINDING_HOST=http://localhost:11434

# 启动
docker compose up -d

8. What can I say before sales

8.1 a sentence positioning

• * "LightRAG is the practical answer to the GraphRAG route-retaining the overall understanding advantage of the knowledge map, but reducing the cost to 1/100 of the GraphRAG, increasing the speed by 100 times, and it is the 37K Stars open source project of the top EMNLP paper of HKU and the best map RAG in Chinese ecology. "**

8.2 customer pain points → solutions

8.3 Differentiated Selling Points

vs Microsoft GraphRAG (core competition):

vs Legacy RAG(LlamaIndex / Haystack / LangChain):

-LightRAG is not a replacement for traditional RAG, but an upgrade scheme when traditional RAG fails

-Traditional RAG processing is not good, cross-document relationship reasoning → LightRAG knowledge map is a natural solution

-LightRAG still has built-in vector retrieval (Naive/Mix mode), traditional RAG capabilities are fully retained

vs domestic map RAG products:

-HKU academic products (EMNLP 2025), more solid theoretical foundation than pure engineering products

-37K Stars Worldwide Validated, Non-Closed Source Locked

-MIT protocol, customers can be arbitrary secondary development

Summary of comprehensive differentiation:

GraphRAG are more "academic", more expensive and slower; LightRAG are more "pragmatic", faster, cheaper and easier to deploy. Core difference: LightRAG replaces the GraphRAG community clustering with a two-tier search-which works equally or even better in most scenarios, but at a cost of 1/100.

8.4 Customer Value Story Line

1. Cut to the pain point :"When your RAG system deals with cross-document problems, does it often only find fragments and cannot connect points into faces?"
2. Point out the root cause :"Because traditional RAG only do' similarity matching'-Paragraph 3 of Document A and Paragraph 7 of Document B both talk about a company, but the system does not know that there is an investment relationship between them."
3. Introduction of Graph :"Knowledge Graph is not only about similarity, but also about relationships. -LightRAG automatically extract entities and relationships at the indexing stage, connecting scattered points into a network."
4. Eliminate worries :"But GraphRAG is too expensive? LightRAG removed the community clustering and replaced it with double-level search-the cost was reduced by more than 95%, but the effect was not reduced."
5. Show Empirical :"EMNLP 2025 top papers, surpassing GraphRAG in the four fields of agriculture/computer/law/mixed. 37K Stars open source community."
6. Demo landing :Docker one-click start → WebUI upload document → visual map → multi-mode query comparison → RAGAS evaluation index
7. End heavy :"MIT agreement, all open source. You can run in your own data center, with Qwen + Ollama zero API cost."

9. Frequently Asked Customer Questions

10. PoC Recommendations

Recommended PoC Direction: Enterprise Document Knowledge Graph Question Answering System

Total: Approximately 4.5 person-days (1 engineer)

Key validation metrics:

-Entity extraction coverage> 80% (identification of business terms and core concepts)

-End-to-end accuracy of cross-document reasoning problems> 75%

-Mix mode vs Naive mode is improved by> 15% (proving the value of map)

-Average query latency <5 seconds (including LLM generation time)

-Incremental update: after adding 10 new documents, the new content can be retrieved without rebuilding the index.

11. Risks and Considerations

12. My Pre-Sales Judgment

• Recommendation: Highly recommended * (★★★★★)

• * In a word, LightRAG is the pragmatic first choice for the current map RAG route-it has turned GraphRAG core pain point of "too expensive and too slow" into its own core selling point, while not losing GraphRAG in effect.**

Reason for recommendation

1. Solve the real pain point :GraphRAG innovation but not available (expensive, slow, not incremental update),LightRAG is the only map RAG that reduces the cost by 1-2 orders of magnitude on the premise of equivalent effect.

1. Solid academic endorsement : Hong Kong University produced, EMNLP 2025 will officially accept (non-arXiv preprint), the paper has strict experimental verification

1. The open source community is strong :37K Stars (5 times as many as GraphRAG), 8,594 submissions, 95 Release, and the iteration speed is astonishingly fast.

1. Production Ready :Docker Compose K8s JWT Certified Multi-Storage Backend RAGAS Evaluation Langfuse Tracking-This is commonly missing in other graph RAG projects

1. Chinese ecology is the best : three-language README, Qwen special optimization, active Chinese community, domestic LLM friendly-the threshold for landing in China is much lower than GraphRAG

1. Ecological integrity : not only LightRAG, but also RAG-Anything (multimodal), VideoRAG (video) and MiniRAG (small model) to form a complete matrix.

Recommended Customer Portrait

-Enterprise Knowledge Base Upgrade: Customers who already have traditional RAG but have poor cross-document results are LightRAG upgraded naturally.

-Legal/Compliance/Financial Customers: Relational reasoning between documents is just needed, and the map is naturally adapted.

- Chinese-based enterprises :Qwen optimized Chinese document Chinese community, the most smooth landing in China

-Budget sensitive but requires map RAG: Don't want to pay for the high cost of GraphRAG

-Neo4j/PostgreSQL infrastructure: Directly reusable, zero new infrastructure

-Requires Privatization Deployment: Complete Offline Scheme K8s Certification

-Academic/Research Institution:MIT Protocol Python SDK Reproduction Experiment

Not recommended

- pure simple question and answer : if 90% of the questions are "what does this document say", the traditional RAG is enough, and the LightRAG knowledge map cost is not cost-effective

-Low-code platform required: The LightRAG WebUI is a manager tool rather than a low-code development platform. Dify / MaxKB is recommended.

-Community global summary report required: If the core requirement is to "generate a structured overview of the entire knowledge base", the GraphRAG community summary function is more direct

-No technical team: Although deployment is simple, tuning still requires some RAG engineering experience.

-Very small amount of data (< 10 documents): overhead of graph construction may exceed revenue

13. REFERENCE

Official Resources

-GitHub repository: https://github.com/HKUDS/LightRAG

-Thesis (arXiv):https://arxiv.org/abs/2410.05779

-Thesis (EMNLP 2025):https://preview.aclanthology.org/manual-author-scripts/2025.findings-emnlp. 568.pdf

-Discord Community: https://discord.gg/yF2MmDJyGJ

-PyPI package: https://pypi.org/project/lightrag-hku/

-Docker image: https://github.com/HKUDS/LightRAG/pkgs/container/lightrag

Ecological Project

-RAG-Anything (Multimodal RAG):https://github.com/HKUDS/RAG-Anything

-VideoRAG (video understanding):https://github.com/HKUDS/VideoRAG

-MiniRAG (small model optimization):https://github.com/HKUDS/MiniRAG

Technical Articles

-Neo4j Official Blog-In-depth Analysis of LightRAG Retrieval Mechanism: https://neo4j.com/blog/developer/under-the-covers-with-lightrag-retrieval/

-Complete guide to LearnOpenCV-LightRAG: https://learnopencv.com/lightrag

-DeepWiki-Database Implementation Details: https://deepwiki.com/lanarich/LightRAG/3.2-database-implementations

-Railway-LightRAG deployment template: https://railway.com/deploy/light-rag

-Overview of Lettria-LightRAG Technology: https://www.lettria.com/blogpost/what-is-lightrag-definition-core-approaches-and-examples

Competition Reference

-Microsoft GraphRAG:https://github.com/microsoft/graphrag

-E² GraphRAG (East China Normal University):https://arxiv.org/abs/2505.24226

-GraphRAG-Bench (benchmark):https://arxiv.org/abs/2506.02404

• Analysis Date: 2026-07-02 | Data Aging: GitHub Real-Time Pull (37,212 Stars / 5,244 Forks / 8,594 Commits / 95 Tags), Product Features Based on v1.5.x Series Official Documents *