Integration of LightRAG into RagView; deployment, troubleshooting, and evaluation

Abstract

This document records the process of integrating the LightRAG solution into RAGView. It covers the rationale for selecting LightRAG, an overview of the integration workflow, encountered issues and corresponding solutions, as well as a final assessment of the solution. It is intended as a practical guide and reference for users who wish to integrate LightRAG while avoiding common pitfalls.

1. Introduction: Why Choose LightRAG?

When building RAGView, our goal was to cover representative implementations across different technical paths. LightRAG positions itself as “Simple and Fast Retrieval-Augmented Generation” [1], distinguishing itself by using a knowledge graph as the core retrieval engine rather than relying solely on traditional vector search. By automatically constructing a knowledge graph from documents, it supports “global” retrieval based on entity relations and enables hybrid querying that combines graph-based and vector-based retrieval. This brings a lightweight graph retrieval paradigm into our evaluation framework, allowing us to analyze its performance in semantic understanding and retrieval quality.

Because of this “graph–vector hybrid retrieval” architecture, LightRAG became an indispensable component in our evaluation system. Compared with pure vector retrieval solutions, it introduces deeper semantic understanding through a knowledge-graph-enhanced mechanism; and compared with other heavyweight knowledge-graph systems [2], its lightweight design ensures deployment feasibility and efficiency on general hardware. Achieving this balance between retrieval depth and execution efficiency allows us to precisely assess the real contribution of knowledge-graph techniques to RAG performance.

Through integrating LightRAG into our unified workflow and dataset, we aim to conduct rigorous comparisons across all metrics. As LightRAG maintains strong indexing and querying performance even under constrained resources, and exposes retrieval evidence clearly, we have strong reason to expect it will provide representative baselines and strong performance in a multi-dimensional evaluation setup.

2. Overview of the Integration Scheme

RAGView provides a unified lifecycle interface, abstracting all RAG solutions into standardized processes. LightRAG is encapsulated as a pluggable module via an adapter pattern: the platform orchestrates unified workflows and metrics collection, while the adapter aligns LightRAG’s native behaviors with the platform’s standard interfaces to ensure fair comparison and seamless switching under “same data, same workflow, same metrics.”

In terms of deployment architecture, we launch LightRAG’s indexing and querying services (decoupled) via Docker Compose, using the fixed image version ghcr.io/hkuds/lightrag:v1.4.9.2. Both stages share PostgreSQL as the unified storage backend. Model configurations strictly follow LightRAG’s recommendations—lighter models for retrieval and stronger models for generation. The specific setup is as follows:

Indexing Service: Qwen/Qwen3-32B for document chunking, embedding, and knowledge-graph construction
Query Service: Qwen/Qwen3-235B-A22B for answer generation, balancing throughput and quality under resource constraints
Embedding Model: bge-m3:567m served through Ollama
Reranker: bge-reranker-v2-m3 (TopK=10), significantly improving relevance in hybrid retrieval

This deployment strategy builds a reproducible, observable, and extensible evaluation environment driven by lightweight architecture and high-performance components.

At the capability-mapping layer, the platform’s standardized configuration (retrieval & generation parameters, concurrency, timeouts, context management) is translated into LightRAG’s query strategies and generation preferences. Hybrid retrieval (“mix” mode) is used by default to balance vector- and graph-based recall. To support explainability, answers and retrieval contexts are collected in a unified format for evaluation.

The integration primarily uses the following LightRAG API endpoints:

POST /documents/upload: Batch upload evaluation data, triggering LightRAG’s standard pipeline (chunking, embedding, KG construction), ensuring index quality consistency
GET /documents: Check document states (PROCESSED / FAILED / PENDING / PROCESSING), ensuring indexing completeness
GET /documents/pipeline_status: Monitor pipeline progress and health for debugging
POST /query: Retrieve the final answer with citations (via include_references), using hybrid “mix” retrieval
POST /query/data: Obtain structured retrieval evidence (chunks, entities, relations), enabling recall analysis, context coverage, and explainability
DELETE /documents (by user_id): Task-level cleanup ensuring data isolation
DELETE /documents/delete_document: Fine-grained removal with automatic KG regeneration to maintain consistency
POST /documents/clear_cache: Clear caches to prevent cross-task contamination

Through these APIs, we preserve LightRAG’s native retrieval and graph-enhanced capabilities while minimizing performance variance introduced by abstraction. The combined use of /query and /query/data enables collection of both answers and full retrieval chains, forming a strong basis for evaluating latency, accuracy, and context relevance.

3. Issues Encountered and Practical Recommendations

3.1 API Incompatibility Due to Improper Image Versioning

During early deployment, the latest tag was used, which caused issues: newer versions had changed the API and removed the query/data endpoint—crucial for retrieving structured evidence for evaluation.

After investigation, we fixed the version to ghcr.io/hkuds/lightrag:v1.4.9.2, which reliably provides the necessary interfaces and fully matches our evaluation requirements.

3.2 Practical Recommendations for New Users

1. Environment Setup: Prefer Docker Deployment

Use the official Docker Compose template (e.g., docker-compose.yml) and a specific version (such as v1.4.9.2). This minimizes dependency issues and avoids complex environment configuration.

2. API Validation: Use Documentation and Testing Tools

Use LightRAG Server’s built-in API docs and tools like Postman to test core endpoints such as POST /query. This clarifies request/response formats and quickly verifies service health.

3. Functionality Verification: Start with Basic Modes

Begin with plain text files (e.g., TXT). Focus on simple modes like naive (pure vector) and mix (hybrid) to confirm indexing and querying work correctly.

4. Extend Capabilities: Explore Advanced Features Gradually

After basic workflows succeed, try the following:

Switch between retrieval modes (local, global, hybrid) to compare performance
Integrate a Reranker to observe quality improvements
Process complex formats (PDF, DOCX) or explore multimodal capabilities via RAG-Anything

4. Evaluation and Observations

Overall, LightRAG demonstrates clear advantages for query types involving dense relational structures, cross-document linkage, or multi-hop reasoning. It often outperforms pure vector solutions in answer relevance and context coverage. While LightRAG requires additional time during indexing to build the knowledge graph and embeddings, the enhanced retrieval quality compensates for this overhead.

Compared with other graph-based RAG systems, LightRAG shows significantly stronger lightweight efficiency. According to existing experiments [4]:

Indexing speed: 5× faster than GraphRAG, with 3× cost savings
Retrieval speed: 7× faster, with 27× cost savings
Operational simplicity: Uses PostgreSQL as unified storage, avoiding the need for additional graph databases

This reduces deployment complexity and resource requirements, striking a desirable balance between performance and efficiency.

Our qualitative impression is:

If your knowledge base contains rich entity relations and cross-document clues, LightRAG’s higher retrieval quality and explainability justify the indexing time.
If your scenario mainly involves single-paragraph factual Q&A with minimal relational reasoning, vector-only solutions still hold an advantage in rapid indexing and querying.

Overall, LightRAG’s combination of hybrid retrieval + graph augmentation + reranking + traceable references delivers a reproducible, observable, and user-friendly experience for complex queries.

5. Conclusion and Future Optimization

In summary, LightRAG performs robustly in our unified evaluation framework: it significantly improves answer relevance and explainability for relation-intensive, cross-document queries while remaining deployable and resource-efficient. Although the graph construction phase introduces additional indexing time, the resultant retrieval depth and evidence traceability make the trade-off worthwhile, establishing LightRAG as a reliable baseline in our platform.

For future work, our current system only supports LightRAG’s recommended mix mode. To expand retrieval diversity, we plan to support its other official modes (naive, local, global, hybrid, bypass), providing one-click switching and corresponding evaluation perspectives. This will enable more comprehensive comparisons across speed, recall, and accuracy, enriching our evaluation dimensions and providing users with better decision support.

References

[1] Zirui Guo, Lianghao Xia, Yanhua Yu, Tu Ao, and Chao Huang. 2025. LightRAG: Simple and Fast Retrieval-Augmented Generation. In Findings of the Association for Computational Linguistics: EMNLP 2025, pp. 10746–10761, Suzhou, China. Association for Computational Linguistics.

[2] D. Edge et al., “From Local to Global: A Graph RAG Approach to Query-Focused Summarization,” arXiv preprint, arXiv:2404.16130, 2024.

[3] LightRAG GitHub Repository. https://github.com/HKUDS/LightRAG

[4] LightRAGTest GitHub Repository. https://github.com/NanGePlus/LightRAGTest

LightRAG Dev Journal