# RAGFlow — Advanced Retrieval-Augmented Generation System

A comprehensive RAG system that transforms PDF documents into searchable knowledge bases using hybrid retrieval (semantic + keyword search), query enhancement, and intelligent reranking. Features modular architecture with multiple LLM and embedding providers.

✨ Key Features

• 🔍 Hybrid Retrieval: Combines vector similarity (FAISS) and keyword search (BM25) for superior accuracy
• 📄 Advanced PDF Processing: OCR integration, table extraction, multi-language support
• 🤖 Multi-Provider Support: Ollama, HuggingFace, Google Gemini, OpenAI
• 🔄 Query Enhancement: Intelligent query expansion using LLMs
• 📊 Result Reranking: Improved relevance through multiple reranking algorithms
• 🎨 Modern UI: Streamlit interface for document processing and chat
• 🏗️ Modular Design: Factory patterns, dependency injection, graceful degradation
• 🌐 Multi-Language: Support for 100+ languages including Vietnamese, English, Chinese

Quick Start

System Requirements

• Python: 3.10+ (recommended)
• Ollama: Local LLM server (optional)
• Memory: 4GB+ RAM for document processing

Installation

# Clone repository
git clone https://github.com/Flowerf19/RAG.git
cd RAG

# Create virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1  # Windows
source .venv/bin/activate   #linux

# Install dependencies
pip install -r requirements.txt

# Install language models
python -c "import spacy; spacy.cli.download('en_core_web_sm')"

Basic Usage

1. Start Ollama (for local embeddings/LLMs):

ollama pull embeddinggemma:latest
ollama pull bge-m3:latest

2. Process Documents:

# Process all PDFs in data/pdf/
python -c "from pipeline.rag_pipeline import RAGPipeline; RAGPipeline().process_directory('data/pdf')"

3. Launch Web Interface:

streamlit run ui/app.py
.venv\Scripts\Activate.ps1; streamlit run ui/dashboard/app.py

Architecture Overview

System Overview

graph TD
    A[PDF Documents] --> B[Document Processing]
    B --> C[Text Extraction & OCR]
    C --> D[Semantic Chunking]
    D --> E[Vector Embeddings]
    D --> F[Keyword Indexing]

    G[User Query] --> H[Query Enhancement]
    H --> I[Hybrid Search]
    I --> J[Result Reranking]
    J --> K[LLM Generation]

    E --> L[(Vector DB)]
    I --> L
    L --> I

    F --> M[(Keyword DB)]
    I --> M
    M --> I

    K --> N[Final Answer]

    style A fill:#e1f5fe
    style N fill:#c8e6c9
    style L fill:#fff3e0
    style M fill:#fff3e0

Core Components

• PDFLoaders: Advanced document processing with OCR and table extraction
• Chunkers: Intelligent text segmentation using spaCy and coherence analysis
• Embedders: Multi-provider embedding generation (Ollama, HuggingFace)
• Pipeline: Orchestrates the complete RAG workflow
• Query Enhancement: Expands queries for better retrieval
• Reranking: Improves result relevance using advanced algorithms
• BM25: Keyword-based search complementing vector search
• LLM: Multiple provider support for response generation
• UI: Streamlit interface for document processing and chat

System Workflows

📥 Ingest Workflow

graph TD
    A[PDF Documents] --> B[PDF Processing]
    B --> C[Page Content]

    C --> D[Semantic Chunking]
    D --> E[spaCy Segmentation]
    E --> F[Coherence Analysis]
    F --> G[ChunkSet]

    G --> H[Embedder]
    H --> I[FAISS Index]
    G --> J[BM25 Index]

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style J fill:#c8e6c9

🔍 Search Workflow

Query Processing

graph TD
    A[User Query] --> B[QueryProcessor]
    B --> C{Enhancement?}
    C -->|Yes| D[QEM Module]
    C -->|No| E[Original Query]

    D --> F[LLM Expansion]
    F --> G[Multi-language]
    G --> H[Enhanced Query]

    H --> I[Embedder]
    E --> I

    I --> N[Query Embeddings]
    H --> O[Keyword Extraction]
    O --> P[BM25 Terms]

    style A fill:#e1f5fe
    style N fill:#fff3e0
    style P fill:#fff3e0

Retrieval & Reranking

graph TD
    A[Query Embeddings] --> B[Vector Search]
    B --> C[FAISS Index]
    C --> D[Top-K Candidates]

    E[BM25 Terms] --> F[Keyword Search]
    F --> G[Whoosh Index]
    G --> H[Top-K Candidates]

    D --> I[Score Fusion]
    H --> I
    I --> J[Z-Score Normalization]
    J --> K[Hybrid Results]

    K --> L{Reranking?}
    L -->|Yes| M[Reranker]
    L -->|No| N[Final Results]

    M --> S[Re-ranked Results]
    S --> N

    style A fill:#e1f5fe
    style N fill:#c8e6c9

Response Generation

graph TD
    A[Final Results] --> B[Context Builder]
    B --> C[Chunk Aggregation]
    C --> D[Metadata Enrichment]
    D --> E[Context Window]

    F[Enhanced Query] --> G[Prompt Builder]
    G --> H[System Prompt]
    H --> I[User Query]
    I --> J[Final Prompt]

    E --> K[LLM Client]
    J --> K

    K --> Q[Generated Response]
    Q --> R[Source Citations]
    R --> S[Confidence Scores]
    S --> T[Final Answer]

    style A fill:#e1f5fe
    style T fill:#c8e6c9

`

Key Differentiators

• Hybrid Search: Combines semantic and keyword-based retrieval for comprehensive coverage
• Query Enhancement: Uses LLMs to expand queries in multiple languages
• Intelligent Reranking: Multiple algorithms to improve result relevance
• Production-Ready: Error handling, caching, and performance optimization
• Multi-Modal: Supports text, tables, and images from PDFs
• Local-First: Works offline with local models and embeddings

Project Structure

RAG-2/
├── PDFLoaders/           # Advanced PDF processing with OCR
├── chunkers/             # Semantic text segmentation
├── embedders/            # Multi-provider embeddings
├── pipeline/             # Core RAG orchestration
├── query_enhancement/    # Query expansion module
├── reranking/            # Result reranking
├── BM25/                 # Keyword-based search
├── llm/                  # LLM provider integration
├── ui/                   # Streamlit web interface
│   └── dashboard/        # Evaluation dashboard
├── evaluation/           # Model evaluation system
│   ├── metrics/          # Database and logging
│   ├── evaluators/       # Auto-evaluation functions
│   └── backend_dashboard/# Dashboard API
├── data/                 # Indexes and processed data
├── config/               # Configuration files
├── prompts/              # System prompts
├── .github/              # GitHub workflows and templates
└── .streamlit/           # Streamlit configuration

Configuration

Embedding Providers

The table below lists common embedding providers and models that the project supports or can be configured to use. Dimensions are approximate where noted. Cost / Performance / Security columns are qualitative and depend on deployment (local vs cloud) and model variant.

Notes:

• Cost: qualitative (Low / Medium / High). "Low" often means free to run locally (open-source) but may require hardware; "High" indicates paid cloud APIs or high compute costs for large models.
• Performance: qualitative (Low / Medium / High) for embedding quality and retrieval effectiveness. Higher-dimensional, newer models generally give better semantic retrieval.
• Security: indicates typical deployment: Local (best) means data stays on-prem; Cloud (managed) means data sent to third-party API — consider privacy/compliance impacts.

Reranking Providers

The following table summarizes common reranking options used after initial retrieval. Columns are qualitative; actual cost and latency depend on model size and whether you run locally or via cloud APIs.

Notes:

• Cost: relative cost (Low / Medium / High). Local open-source models are Low cost but require hardware; cloud APIs incur usage fees.
• Performance: overall reranking quality (Low → High). Cross-encoders and specialized rerankers tend to perform best.
• Latency: expected response time for reranking; cloud APIs often provide lower latency but at higher cost.
• Security: indicates whether data stays local or is sent to third-party services; self-hosted rerankers keep data on-prem.

Dependencies

Key libraries used by this project (grouped by purpose).

If you want, I can (a) add a short note about which packages are optional (e.g., Ollama/Gemini/OpenAI wrappers), or (b) create a minimal requirements-core.txt for a lightweight install.

Environment Setup

# HuggingFace API (optional)
export HF_TOKEN="your_token_here"

# Google Gemini (optional)
export GOOGLE_API_KEY="your_key_here"

# OpenAI (optional)
export OPENAI_API_KEY="your_key_here"

API Keys Setup

For full functionality, you'll need to set up API keys for various services:

1. Copy the secrets template:

   cp .streamlit/secrets.example .streamlit/secret.toml
   

2. Edit the secrets file with your actual API keys:

   # HuggingFace API Token (required for E5-Large Multilingual embeddings via HF API)
   HF_TOKEN = "hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   
   # Google Gemini API Key (required for Gemini LLM inference)
   gemini_api_key = "AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   

3. Environment Variables (alternative to secrets.toml):

   export GOOGLE_API_KEY="your_gemini_key"
   export HF_TOKEN="your_huggingface_token"
   

⚠️ Security Note: Never commit actual API keys to version control. The .streamlit/secret.toml file is already in .gitignore.

Use Cases

• Document Q&A: Ask questions about your PDF collection
• Research Assistant: Analyze academic papers and reports
• Knowledge Base: Build searchable company documentation
• Legal Research: Query legal documents with high precision
• Technical Documentation: Search API docs and manuals

Performance & Monitoring

Benchmark Results

• PDF Processing: ~50 pages/minute with OCR enhancement
• Vector Search: < 10ms for 10K documents
• BM25 Search: < 5ms for keyword queries
• Query Enhancement: < 50ms per query
• Reranking: < 100ms for 20 candidates
• Memory Usage: ~2GB for 1K documents

Troubleshooting

Common Issues

• Ollama Connection: Ensure Ollama is running on localhost:11434
• PDF Processing: Clear cache if processing fails
• Memory Issues: Reduce batch size or use smaller models
• Embedding Mismatch: Rebuild indexes when switching embedders

Contributing

Development Setup

git clone https://github.com/Flowerf19/RAG.git
cd RAG
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Guidelines

• Write clear, documented code
• Add tests for new features
• Follow modular architecture patterns
• Update documentation for changes

Roadmap

Phase 1 (Current)

• Advanced PDF processing with OCR
• Hybrid retrieval (FAISS + BM25)
• Query enhancement and reranking
• Multi-LLM and embedder support
• Streamlit web interface

Phase 2 (Future)

• Cloud storage integration
• Real-time document streaming
• Advanced caching system
• REST API endpoints
• Performance analytics dashboard

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with FAISS, Ollama, spaCy, Whoosh, Streamlit, PaddleOCR, and HuggingFace Transformers.

---

RAGFlow Transforming documents into conversational knowledge bases.

Support

• Developer: Nguyễn Hoà (Hoaf.n.v@gmail.com)
• Developer: Lê Chiến (Bachien0987@gmail.com)
• Documentation: See individual module READMEs