This project has been archived by its maintainers, and is no longer receiving any updates.
DlightRAG
DlightRAG is a production multimodal RAG service built on LightRAG. It combines knowledge-graph and vector retrieval with metadata filtering, BM25, visual retrieval, reranking, citations, highlights, and durable agentic answers. The same runtime is available through Web, REST, MCP, and an in-process Python API.
Runtime: Python ≥3.14.7 · PostgreSQL 18 ecosystem · Apache-2.0
LightRAG storage defaults are exactly PGKVStorage, PGVectorStorage,
PGTableGraphStorage, and PGDocStatusStorage. Writer deployments may
explicitly replace only the vector leg with MilvusVectorDBStorage (including
Milvus-compatible Zilliz endpoints) by installing dlightrag[milvus]; reader
processes currently remain PostgreSQL-vector-only.
Architecture
LightRAG supplies graph and vector retrieval. DlightRAG owns product policy, multimodal alignment, durable ingestion and answers, security, storage adapters, and public interfaces. Fast and Research answers share one durable conversation tree; Research adds a per-run workspace, tools, memory, and child agents. See Architecture for module and storage ownership.
Deployment Paths
| Path | PostgreSQL | Parser | Security |
|---|---|---|---|
| Local Docker | Compose PG18 | Self-hosted MinerU by default | Loopback, auth_mode: none |
| Native API | Compose or external PG18 | Any reachable MinerU or Docling | Local or explicit auth |
| Shared service | Managed or self-hosted PG18 | Independently operated parser | simple or jwt |
| Enterprise | Managed PG18 | Independently operated parser | JWKS plus claim access control |
The parser runs outside the DlightRAG app container. The checked-in Docker
configuration uses self-hosted MinerU at
http://host.docker.internal:8210. Docling and MinerU cloud remain supported.
Quick Start
Install Docker + Compose,
uv, git, and make.
Interactive setup
git clone https://github.com/hanlianlu/dlightrag.git
cd dlightrag
uv run prerequisite_setup.py
The wizard configures models, parser, secrets, and the local stack. It defaults to self-hosted MinerU and is safe to rerun.
Manual setup
git clone https://github.com/hanlianlu/dlightrag.git
cd dlightrag
cp .env.example .env
mkdir -p "${HOME}/.dlightrag/skills"
The last command prepares the default read-only operator Skills bind source;
when COMPOSE_GLOBAL_SKILLS_DIR selects another host path, create that directory
instead. Add the keys required by your config.yaml model blocks:
DLIGHTRAG_MODELS__CHAT__DEFAULT__API_KEY=...
DLIGHTRAG_MODELS__EMBEDDING__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__EXTRACT__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__KEYWORD__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__QUERY__API_KEY=...
DLIGHTRAG_MODELS__CHAT__ROLES__VLM__API_KEY=...
DLIGHTRAG_MODELS__RERANK__API_KEY=...
Install and start MinerU, then start DlightRAG:
make mineru-install
make mineru-service-install # installs and starts the background service
curl http://127.0.0.1:8210/health
docker compose up -d
docker compose ps
Open http://localhost:8100/web/. The stack publishes:
| Service | Address |
|---|---|
| REST API and Web | http://127.0.0.1:8100 |
| MCP streamable HTTP | http://127.0.0.1:8101 |
| PostgreSQL | 127.0.0.1:5432 |
Use make mineru-api when the platform cannot install a background user
service. To use Docling, replace the MinerU block in config.yaml; a commented
example is included there. Parser changes affect only new parses.
Configuration fields and parser operations are documented in Configuration and Operations.
Native API
Run PostgreSQL in Docker and the API on the host:
docker compose up -d postgres
uv sync
DLIGHTRAG_CORPUS__SIDECARS__MINERU__LOCAL_ENDPOINT=http://127.0.0.1:8210 \
uv run dlightrag-api
The checked-in config is Docker-first, so a native process overrides the parser
host alias with loopback. Native managed inputs live under
./dlightrag_storage/inputs/<workspace>.
Use DlightRAG
Web
The Web UI supports workspace and file management, durable Fast and Research conversations, answer attachments, citations, source highlights, child-agent status, and typed Answer Artifacts. Research publishes only workspace roots it explicitly attaches; prose links alone never publish files. English, Chinese, and automatic browser language modes are available under Settings.
REST
Ingestion, Retrieval, and Answer create durable Runs and return 202 Accepted.
Corpus mutations require a stable idempotency key.
INGEST_RUN=$(curl -sS -X POST http://localhost:8100/runs/corpus/ingest \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ingest-report-1" \
-d '{"source_type":"local","path":"report.pdf"}' | jq -r .run_id)
curl "http://localhost:8100/runs/$INGEST_RUN"
RETRIEVAL_RUN=$(curl -sS -X POST http://localhost:8100/retrieve \
-H "Content-Type: application/json" \
-d '{"query":"What are the key findings?"}' | jq -r .run_id)
curl "http://localhost:8100/runs/$RETRIEVAL_RUN"
RUN=$(curl -sS -X POST http://localhost:8100/answer \
-H "Content-Type: application/json" \
-d '{"query":"What are the key findings?"}' | jq -r .run_id)
curl -N "http://localhost:8100/runs/$RUN/events"
curl "http://localhost:8100/runs/$RUN"
See Interfaces for requests, responses, pagination, SSE, attachments, citations, and all transport contracts.
MCP
For a local stdio client:
{
"mcpServers": {
"dlightrag": {
"command": "uvx",
"args": ["dlightrag-mcp", "--env-file", "/absolute/path/to/.env"]
}
}
}
The Compose stack also exposes streamable HTTP on port 8101. MCP supports durable Retrieval and Answer Runs, steering, follow-up/fork, child status, corpus administration, and capability discovery. The authoritative tool list is in Interfaces.
Python
uv add dlightrag
Create an application with create_application(config), use
application.corpus_mutations for durable corpus writes,
application.retrieval for durable Retrieval, and application.answers for
durable Answers, then call
application.aclose(). Complete typed examples are in
Interfaces.
Core Concepts
| Concept | Meaning | Reference |
|---|---|---|
| Workspace | Isolation unit for indexed data, metadata, files, and queries | Domain language |
| Ingestion | One durable contract for local files, uploads, object storage, URLs, and SDK sources | Interfaces |
| Retrieval | One durable Query-lane Run returning LightRAG mix plus metadata, BM25, visual fusion, and rerank evidence | Retrieval and Answer |
| Run | Common durable lifecycle for Retrieval, Answer, and Corpus Mutation across REST, MCP, Web, Python, and evaluation | RunRuntime |
| Answer Run | A Query-lane Run that resolves Fast or Research and generates an Answer | Retrieval and Answer |
| Resource | Request-local attachment read deterministically or inspected visually on demand | Retrieval and Answer |
| Published Artifact | Owner-visible Research output authorized by a settled root attachment and validated at publication | Domain language |
| Source | Durable provenance and download contract for an ingested document | Interfaces |
Security
Loopback development can use access.auth_mode: none. Shared deployments should
use a bearer token or externally issued JWT; JWKS and claim-based workspace/action
rules are supported. DlightRAG does not issue tokens or replace an ingress WAF,
rate limiter, TLS terminator, or identity provider. See
Security.
Development
uv sync
npm --prefix frontend ci
make hooks
make ci # lint, security, format, types, architecture, frontend, unit
make ci-full # plus integration tests
make ci-e2e # plus E2E smoke
Use Operations for reset, rebuild, parser, Langfuse, and maintenance runbooks. RAGAS evaluation is documented in Evaluation.
Documentation
| Document | Owns |
|---|---|
| Architecture | Runtime ownership, flows, storage topology, layering |
| Domain Language | Canonical product vocabulary |
| Configuration | Configuration precedence, fields, defaults, examples |
| Interfaces | Python, REST, MCP, and Web contracts |
| Retrieval and Answer | Retrieval, fusion, rerank, packing, citations, highlights |
| RunRuntime and Durable Execution | Common Query and Corpus Mutation state machine, leases, events, recovery, retention |
| RunRuntime and Scaling Target | Accepted workload model, lane bounds, lifecycle guarantees, and ownership boundary |
| RunRuntime Slice 6 Validation | Failure matrix, reproducible commands, 10k control-plane evidence, accepted bounds, limitations |
| Security | Authentication, authorization, ingress and content boundaries |
| PostgreSQL | PostgreSQL requirements, schema ownership, tuning |
| Operations | Executable runbooks and recovery workflows |
| Evaluation | RAGAS workflow |
| Web Theme Design | Web appearance and interaction decisions |
Plans, ADRs, and research notes under docs/ are historical design evidence,
not required reading for operating DlightRAG.
License
Apache License 2.0. See LICENSE.
Built by HanlianLyu. Contributions welcome.
1 maintainer
Metadata
1 maintainer
Release files for dlightrag 2.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dlightrag-2.0.7.tar.gz | 6.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dlightrag-2.0.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 12.9 MB
Release files / dlightrag-2.0.7.tar.gz
| Download URL | dlightrag-2.0.7.tar.gz |
|---|---|
| Size | 6.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ac33cc6646a0eaa8255f5c9f92f1c4538f5e72c710dea4d2ddf215cf7d1917c
|
|
BLAKE2b-256 checksum How to use checksums |
61c795b87975be0fac7dc56f0e49e3df0f6cea915743785417da780864cb45e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logRelease files / dlightrag-2.0.7-py3-none-any.whl
| Download URL | dlightrag-2.0.7-py3-none-any.whl |
|---|---|
| Size | 6.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
419d851919359d507749972ce201dbe986b66ce243253e0113eebd5fe6c8d684
|
|
BLAKE2b-256 checksum How to use checksums |
922156eaee43f0cc492fc52ab34c335259a7a63953dfdc0595a3daddf21e996c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency log
