Deep Dive: LightRAG Storage, API & WebUI

Phân tích chi tiết từ báo cáo Tổng quan LightRAG — storage contracts, backend matrix và deployable server.

Báo cáo cha: ← LightRAG OverviewTopic: Storage/APIServer port default: 9621Ngày: 2026-04-22

Tổng quan Intro

LightRAG đáng chú ý vì nó không hard-code một database. Core tách bốn vai trò storage: KV, vector, graph và doc-status. Server layer lại đóng gói core thành WebUI/API/Ollama-compatible service, giúp prototype nhanh và deploy như một service riêng.

LightRAG API Server WebUI screenshot với giao diện quản lý tài liệu và graph — LightRAG Server WebUI: document indexing, graph exploration và query interface nằm cùng một runtime. ↗ LightRAG API Server docs

Rule vận hành: bắt đầu bằng default local storage để kiểm tra graph quality, sau đó mới chuyển backend production. Đừng ingest corpus lớn rồi mới đổi embedding/storage schema.

WebUI screenshots UI

LightRAG WebUI screenshot về graph exploration và query interaction — Graph exploration giúp kiểm tra entity/relation quality sau indexing. ↗ LightRAG API Server docs

LightRAG WebUI screenshot về query/document interface — Query/document panels trong WebUI cho phép smoke test API behavior trước khi tích hợp vào app khác. ↗ LightRAG API Server docs

LightRAG WebUI screenshot về trạng thái hoặc cấu hình server — Server-side panels hữu ích cho kiểm tra trạng thái vận hành, workspace và cấu hình. ↗ LightRAG API Server docs

Storage architecture Storage

1. Four storage roles tách trách nhiệm rõ

S.1

lightrag/lightrag.py:640-737; lightrag/base.py

RAG production cần nhiều hơn một vector store. LightRAG lưu documents/chunks/cache trong KV, semantic search trong vector stores, relation structure trong graph store và pipeline state trong doc-status storage.

LightRAG instance ├─ KV storage │ ├─ full_docs │ ├─ text_chunks │ ├─ llm_response_cache │ ├─ full_entities / full_relations │ └─ entity_chunks / relation_chunks ├─ Vector storage │ ├─ entities_vdb │ ├─ relationships_vdb │ └─ chunks_vdb ├─ Graph storage │ └─ chunk_entity_relation_graph └─ Doc status storage └─ pending / processing / processed / failed

Role	Read/write path	Nếu mất/corrupt thì sao
KV	Insert/query/cache/export	Mất full docs/chunks/cache; khó rebuild references
Vector	Entity/relation/chunk semantic retrieval	Graph còn đó nhưng query semantic mất candidates
Graph	Neighbor traversal, degree, subgraph, KG visualization	Chỉ còn vector chunks; mất lợi thế graph RAG
Doc status	Pipeline monitor, retry, deletion	Upload/insert khó recover và UI status sai

2. Initialization lifecycle: create objects trước, initialize sau

S.2

lightrag/lightrag.py:531-797

Storage lifecycle rõ giúp tránh deadlock và side effect sớm. Dataclass init tạo wrapper/config, còn initialize_storages() mới mở backend. Docs nhấn mạnh phải gọi explicit init trước khi dùng core.

initialize_storages khởi tạo từng storage

async def initialize_storages(self):
    if self._storages_status == StoragesStatus.CREATED:
        await initialize_pipeline_status(workspace=self.workspace)

        for storage in (
            self.full_docs,
            self.text_chunks,
            self.full_entities,
            self.full_relations,
            self.entity_chunks,
            self.relation_chunks,
            self.entities_vdb,
            self.relationships_vdb,
            self.chunks_vdb,
            self.chunk_entity_relation_graph,
            self.llm_response_cache,
            self.doc_status,
        ):
            if storage:
                await storage.initialize()

Core integration pitfall: tạo LightRAG(...) xong mà quên await rag.initialize_storages() sẽ lỗi. Khi app shutdown, gọi await rag.finalize_storages() để backend flush/close đúng.

3. Backend selection là quyết định kiến trúc, không phải config phụ

S.3

docs/ProgramingWithCore.md

Backend quyết định scale, consistency và operational burden. Default local stack phù hợp demo; production cần chọn theo workload, team expertise và yêu cầu graph/vector scale.

Scenario	KV	Vector	Graph	Doc status
Local demo	JsonKV	NanoVectorDB	NetworkX	JsonDocStatus
Postgres-centric team	PGKV	PGVector	PGGraph/AGE	PGDocStatus
Graph-heavy analysis	Redis/Postgres	Milvus/Qdrant	Neo4j/Memgraph	Postgres/Mongo
Unified search platform	OpenSearchKV	OpenSearchVector	OpenSearchGraph	OpenSearchDocStatus
Managed document app	MongoKV	MongoVector Atlas	MongoGraph	MongoDocStatus

Ưu điểm

Có thể dùng default storage để iterate nhanh.
Backend matrix đủ rộng để đi từ laptop đến production.
OpenSearch path mới cho phép unify cả 4 storage roles.

Nhược điểm

Mỗi backend có isolation semantics khác nhau.
Một số backend cần plugin/managed service mới đủ capability.
Đổi embedding/vector backend sau ingest có migration cost đáng kể.

4. Server/API/WebUI biến LightRAG thành service

S.4

docs/LightRAG-API-Server.md

Service mode rút ngắn đường từ research sang app. Bạn có thể upload documents, query, visualize graph và tích hợp chatbot ngoài qua Ollama-compatible endpoints mà không cần viết FastAPI wrapper riêng từ đầu.

Cài và chạy server

uv tool install "lightrag-hku[api]"
cp env.example .env
# chỉnh LLM_BINDING, EMBEDDING_BINDING, storage, auth...
lightrag-server

# production non-Windows
lightrag-gunicorn --workers 4

Ollama-compatible interface: Server có thể giả lập LightRAG như một Ollama chat model, giúp Open WebUI hoặc chatbot khác gọi vào LightRAG dễ hơn.

5. Deployment config: .env, wizard, Docker và reverse proxy

S.5

docs/InteractiveSetup.md; docs/LightRAG-API-Server.md

Config sai dễ làm server chạy nhưng dùng nhầm model/storage. LightRAG cố ý đọc .env ở startup directory để mỗi instance có config riêng. System env override `.env`.

1
Generate base env
Chọn LLM, embedding và reranker trước.
```
make env-base
```
2
Generate storage env
Chọn local JSON/NetworkX hoặc backend production như OpenSearch/Postgres/Neo4j.
```
make env-storage
```
3
Generate server env
Chọn port, auth, SSL và server-facing settings.
```
make env-server
make env-security-check
```

Docker compose path

git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
cp env.example .env
# configure LLM/embedding/storage in .env
docker compose up

Production matrix Matrix

Decision	Recommendation	Reason
Embedding model	Chọn trước ingest lớn và freeze	Dimension đổi sẽ ảnh hưởng vector schema
Workspace strategy	Dùng workspace per tenant/project	Storage isolation method khác nhau theo backend
Graph backend	NetworkX cho dev; Neo4j/Memgraph/OpenSearch/Postgres AGE cho scale	Graph traversal và WebUI phụ thuộc backend capability
Vector backend	Qdrant/Milvus/PGVector/OpenSearch theo team stack	Rerank không thay thế vector recall tốt
Reverse proxy	Set upload limit, streaming timeout, disable gzip cho streaming	Tránh 413 và buffering làm stream chậm
Secrets	System env hoặc secret manager; audit bằng env-security-check	.env dễ bị copy/commit sai

Tổng kết Wrap

Storage/API takeaways

LightRAG cần bốn loại storage; đừng thiết kế production như chỉ có vector DB.
Server/WebUI rất hữu ích để inspect graph quality và query behavior trước khi tích hợp app.
Embedding dimension, workspace isolation và backend choice là quyết định migration-cost cao.
OpenSearch là option đáng chú ý nếu muốn unified storage cho cả KV/vector/graph/doc-status.

Tham khảo