# weiwill88/local_pdf_chat_rag architecture

> Architecture diagram of the GitHub repository weiwill88/local_pdf_chat_rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/weiwill88/local_pdf_chat_rag
- Repository: https://github.com/weiwill88/local_pdf_chat_rag

## Overview

##### Project Type & Purpose
- This is a monolithic Python “full-stack” RAG (Retrieval-Augmented Generation) demo: it combines a lightweight frontend (Gradio UI and optional FastAPI endpoints) with a backend pipeline for PDF ingestion, vectorization (FAISS), keyword indexing (BM25), retrieval, re-ranking, external search, and LLM‐powered answer generation (Ollama or SiliconFlow).

##### File Structure
- Top-level scripts:
- rag_demo_pro.py → launches the Gradio interface and ties together PDF upload, question handling, and the RAG pipeline.
- Configuration: example.env, requirements.txt
- Assets: images/ (UI screenshots, QR codes)
- utils/ → Python modules for PDF parsing, text splitting, indexing, retrieval, LLM calls, etc.

##### Core Components
a. User Interaction Layer
- Gradio Web UI (rag_demo_pro.py)
- FastAPI endpoints (api_router.py—optional)
b. Data Processing & Storage Layer
- PDF Processing Module (pdfminer → text extraction)
- Text Splitting (langchain-text-splitters)
- Vectorization (Sentence-Transformers)
- FAISS Vector Index (faiss-cpu)
- BM25 Index (rank_bm25 + jieba)
- Document store (filesystem or in-memory metadata)
c. Retrieval & Re-ranking Layer
- FAISS semantic search
- BM25 keyword search
- Hybrid merging & CrossEncoder re-ranking
d. Augmentation & Generation Layer
- Optional external SerpAPI search
- LLM Inference Module (local Ollama or cloud SiliconFlow)
- Recursive query generation & iteration logic
e. External Services
- SerpAPI (real-time web search)
- Ollama service (local LLM)
- SiliconFlow API (cloud LLM)

##### Relationships & Data Flow
1. User → UI/API → PDF Processing
2. PDF → Text Split → Vectorize → FAISS & BM25 indices
3. User Query → Vectorize → FAISS → candidate chunks
4. User Query → BM25 → keyword hits
5. Merge FAISS+BM25 → CrossEncoder re-rank → context set
6. (Optional) Query → SerpAPI → external snippets → merge
7. Context + Query → LLM → Answer → UI → (loop for recursive queries)

##### Architectural Patterns & Principles
- Layered architecture: separate UI, processing, storage, retrieval, generation.
- Modular pipeline: each processing step lives in utils/ modules.
- Hybrid retrieval pattern: semantic + keyword + external search.
- Recursive/iterative RAG: LLM can trigger further retrieval rounds.

##### Technologies & Frameworks
- Python 3.9+
- Gradio (UI layer)
- FastAPI + Uvicorn (API layer, optional)
- pdfminer.six (PDF parsing)
- langchain-text-splitters (splitting)
- sentence-transformers (vectorization & cross-encoder)
- faiss-cpu (vector index)
- rank_bm25 + jieba (keyword index)
- requests/urllib3 (HTTP calls)
- python-dotenv (env config)
- Ollama & SiliconFlow APIs (LLM inference)
- SerpAPI (external search)

##### Essential Elements to Capture
- All major modules (PDF Processor, Splitter, Vectorizer, FAISS, BM25, Hybrid Retriever, CrossEncoder, External Search, LLM).
- Data stores (index files or in-memory data structures).
- External dependencies (SerpAPI, Ollama, SiliconFlow).
- Interaction flows (upload, ask, retrieve, rerank, generate, deliver).
- Recursive iteration path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingress Layer
    subgraph "Ingress Layer"
        direction TB
        Gradio["Gradio Web UI"]:::ui
        API["FastAPI Endpoints"]:::ui
        Config["Configuration"]:::ui
        Assets["Static Assets"]:::ui
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        PDFProc["PDF Processing Module"]:::processing
        Splitter["Text Splitting Module"]:::processing
        Vectorizer["Vectorization Module"]:::processing
    end

    %% Storage & Index Layer
    subgraph "Storage & Index Layer"
        direction TB
        FAISSIdx["FAISS Vector Index"]:::storage
        BM25Idx["BM25 Keyword Index"]:::storage
        DocStore["Document Store"]:::storage
    end

    %% Retrieval Layer
    subgraph "Retrieval Layer"
        direction TB
        FAISSSearch["FAISS Semantic Search"]:::retrieval
        BM25Search["BM25 Keyword Search"]:::retrieval
        Hybrid["Hybrid Merger"]:::retrieval
        CrossEncoder["CrossEncoder Re-ranking"]:::retrieval
    end

    %% External Search
    subgraph "External Search"
        direction TB
        SerpAPI["SerpAPI Service"]:::external
    end

    %% Generation Layer
    subgraph "Generation Layer"
        direction TB
        LLM["LLM Inference Module"]:::generation
    end

    %% Flows
    Gradio -->|"上传 PDF"| PDFProc
    API -->|"上传 PDF"| PDFProc
    PDFProc -->|"文本提取"| Splitter
    Splitter -->|"分割"| Vectorizer
    Vectorizer -->|"向量化"| FAISSIdx
    Vectorizer -->|"向量化"| BM25Idx
    FAISSIdx --> FAISSSearch
    BM25Idx --> BM25Search
    FAISSSearch -->|"语义检索结果"| Hybrid
    BM25Search -->|"关键词检索结果"| Hybrid
    Hybrid -->|"混合检索"| CrossEncoder
    SerpAPI -->|"外部检索结果"| Hybrid
    CrossEncoder -->|"重排序结果"| LLM
    LLM -->|"生成回答"| Gradio
    LLM -->|"生成回答"| API
    LLM -.->|"递归查询"| FAISSSearch

    %% Click Events
    click Gradio "https://github.com/weiwill88/local_pdf_chat_rag/blob/main/rag_demo_pro.py"
    click API "https://github.com/weiwill88/local_pdf_chat_rag/blob/main/api_router.py"
    click Config "https://github.com/weiwill88/local_pdf_chat_rag/blob/main/example.env"
    click Config "https://github.com/weiwill88/local_pdf_chat_rag/blob/main/requirements.txt"
    click Assets "https://github.com/weiwill88/local_pdf_chat_rag/tree/main/images/"
    click PDFProc "https://github.com/weiwill88/local_pdf_chat_rag/tree/main/utils/"
    click Splitter "https://github.com/weiwill88/local_pdf_chat_rag/tree/main/utils/"
    click Vectorizer "https://github.com/weiwill88/local_pdf_chat_rag/tree/main/utils/"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064;
    classDef processing fill:#E8F5E9,stroke:#1B5E20;
    classDef storage fill:#FFF8E1,stroke:#FF6F00;
    classDef retrieval fill:#FBE9E7,stroke:#BF360C;
    classDef generation fill:#F3E5F5,stroke:#6A1B9A;
    classDef external fill:#ECEFF1,stroke:#37474F;
```
