📚 RAG System — Full Pipeline Knowledge Base

ระบบค้นหาและตอบคำถามจากหนังสืออัจฉริยะ ผสม HyDE Query Transform + Hybrid Search + Adaptive Reranking + Gemini LLM Generation + 🧠 Agentic RAG พร้อม Premium Web UI (Gemini Style) และระบบจัดการข้อมูลแบบครบวงจร

Developed by Aetox.dev

สถานะ: ✅ System Stable & Optimized (v4.1)
Version: 4.1 — Web Search (DuckDuckGo) + Sentence-Level Context Compression + Persona Management + Agentic Evaluation

📘 เอกสารเทคนิคฉบับเต็ม (Technical Guide) 📘 แผนการพัฒนาระบบ (Sentence Compression Plan)

📸 Screenshots

หน้าแรก (Welcome Page) — Dark Theme + Suggestion Chips

หน้าตอบคำถาม — ผลลัพธ์การค้นหา + แหล่งอ้างอิง

หน้าเพิ่มข้อมูล (Admin Panel) — สำหรับจัดการเอกสาร

หน้าการตั้งค่า (Settings Page) — สำหรับตั้งค่าระบบ

🏗️ Architecture (Modular Design)

ระบบถูกออกแบบใหม่เป็น Modular & Service-Oriented Architecture เพื่อความยืดหยุ่นและการขยายตัว:

API Layer (api/): แยก Routing (Chat/Admin) และ SSE Handlers ออกจากกัน
Service Layer (services/): Orchestrator หลักที่ประสานงานทุกโมดูล
Retrieval Pipeline (core/retrieval/): แยกขั้นตอน Tokenize, Search (Dense/BM25) และ Rerank
Agentic Engine (core/agentic/): แยก Business Logic ของการคิดวิเคราะห์ออกจาก UI
LLM & Prompt Management (core/llm/, core/prompts/): แยก Prompt templates ออกเป็นไฟล์ และจัดการ LLM Provider อิสระ
Web Searcher (core/web_searcher.py): ค้นหาข้อมูลจากอินเทอร์เน็ตแบบ Real-time (DuckDuckGo)

graph TD
    UI[Web UI / JS] <--> API[FastAPI Routers]
    API <--> CHAT[Chat Service]
    CHAT <--> RET[Retrieval Pipeline]
    CHAT <--> WEB[Web Searcher]
    CHAT <--> AGENT[Agentic Engine]
    CHAT <--> GEN[LLM Generator]
    
    AGENT <--> DEC[Query Decomposer]
    AGENT <--> EVAL[Sufficiency Evaluator]
    AGENT <--> WEB
    
    RET <--> FAISS[FAISS Index]
    RET <--> BM25[BM25 Corpus]
    RET <--> RERANK[Cross-Encoder Reranker]
    
    GEN <--> PROMPTS[Prompt Registry]
    GEN <--> PROVIDER[Gemini Provider]

Pipeline Stages

Stage	Method	หน้าที่	ทำงานบน
W1	Web Search (DuckDuckGo)	🌐 ค้นหาข้อมูลล่าสุดจากอินเทอร์เน็ต (ถ้าเปิดโหมด Web)	Cloud API
0	HyDE (Groq LLaMA)	สร้างเอกสารสมมติเพื่อปรับปรุงคำค้น	Cloud API
1a	Dense (FAISS)	จับ "ความหมาย" — คำต่างกันแต่หมายถึงเรื่องเดียวกัน	GPU
1b	BM25 (Sparse)	จับ "คำตรงกัน" — ชื่อคน, ชื่อหนังสือ, ศัพท์เฉพาะ	CPU
2	Score Merge	รวม Dense (70%) + BM25 (30%) แล้ว normalize	CPU
3	Adaptive Reranker	⚡ Skip ถ้าชัด / 🔬 Rerank ถ้ากำกวม (gap ≤ 0.15)	GPU
4	Sentence Compressor	✂️ ตัด Chunk เป็นประโยค + กรองหยาบ (Embedding) + จัดเรียงใหม่ (Cross-Encoder) ให้ได้ประโยคที่ตรงที่สุด	GPU
5	Gemini Generation	สร้างคำตอบ SSE streaming จากเนื้อหาที่ถูกบีบอัดแล้ว	Cloud API
A1	Query Decomposer	🧠 แตกคำถามซับซ้อนเป็น sub-queries (Agentic)	Cloud API
A2	Evaluator	📊 ประเมินว่าข้อมูลครบหรือยัง + สร้าง follow-up (Agentic)	Cloud API
A3	Balanced Selection	⚖️ round-robin เลือก chunks จากทุก source (Agentic)	CPU

📁 Project Structure

BookMind/
├── web_server.py           # 🚀 Entry Point: FastAPI App initialization
├── config.py               # ⚙️ Global App Config (Constants, Weights)
├── rag_creator.py          # 🔨 Index Builder (Indexing logic)
├── rag_searcher.py         # 🔍 Search Wrapper (Backward compatibility)
│
├── api/                    # 🌐 API Layer
│   ├── routes/             #   📄 FastAPI Routers (chat, admin)
│   └── sse_handlers.py     #   ⚡ SSE Event Generators (Classic/Agentic)
│
├── services/               # 🧠 Service Layer (Business Logic)
│   └── chat_service.py     #   Orchestrator for all search pipelines
│
├── core/                   # 📦 Core Engine Modules
│   ├── retrieval/          #   🔍 Modular Retrieval Pipeline
│   │   ├── tokenizer.py    #     Thai/English text tokenization
│   │   ├── reranker.py     #     Cross-Encoder Reranking logic
│   │   ├── base_search.py  #     Dense/BM25 low-level search
│   │   ├── compressor.py   #     ✂️ Sentence-Level Context Compressor
│   │   └── pipeline.py     #     Retrieval Pipeline orchestrator
│   │
│   ├── agentic/            #   🧠 Agentic Reasoning Engine
│   │   ├── engine.py       #     Pure multi-hop orchestration
│   │   ├── formatter.py    #     Thai UI message formatting
│   │   └── types.py        #     Shared data structures
│   │
│   ├── llm/                #   🤖 LLM Providers
│   │   ├── gemini_provider.py#     Gemini API with Key Rotation
│   │   └── generator.py    #     High-level Answer Generator
│   │
│   ├── prompts/            #   📜 Prompt Management
│   │   ├── prompt_registry.py#     Central prompt loader
│   │   └── *.txt           #     Prompt templates (system, agentic)
│   │
│   ├── config.py           #   🔐 Environment & Key loading
│   ├── key_manager.py      #   🔑 Key Rotation logic
│   ├── query_transformer.py#   🪄 HyDE (via Groq)
│   ├── document_loader.py  #   📄 File loader (Excel, PPTX, etc.)
│   └── agent_memory.py     #   💾 Working memory for Agentic mode
│
├── web/                    # 🎨 Frontend (HTML/CSS/JS)
├── data/                   # 📂 Source Documents
├── storage/                # 💾 Vector & Keyword Indices
└── .env                    # 🔐 API Keys

🛠️ การติดตั้งและตั้งค่า (Setup)

1. เตรียม Environment

# สร้าง Virtual Environment (ถ้ายังไม่มี)
python3 -m venv venv

# เปิดใช้งาน (Activate) Environment
source venv/bin/activate

# ติดตั้ง Dependencies
pip install -r requirements.txt

2. ตั้งค่า API Keys

คัดลอกไฟล์ .env.example เป็น .env
ใส่ API Keys ของ Gemini และ Groq ในไฟล์ .env

3. ตั้งค่า Discord Bot (กรณีใช้งาน)

ไปที่ Discord Developer Portal
เลือก Application ของคุณ > ไปที่เมนู Bot
ภายใต้หัวข้อ Privileged Gateway Intents ให้เปิด Message Content Intent เป็น On
บันทึกการเปลี่ยนแปลง (Save Changes)

🐳 WSL Networking Fix (for Ollama)

หากคุณใช้งานผ่าน WSL2 และต้องการเชื่อมต่อกับ Ollama ที่รันบน Windows คุณอาจพบปัญหา Connection refused เนื่องจากการแยก Network ระหว่าง WSL และ Windows

เราได้เตรียมสคริปต์อัตโนมัติเพื่อแก้ปัญหานี้ (ตั้งค่า Environment และ Firewall ในคลิกเดียว):

chmod +x fix_ollama_network.sh
./fix_ollama_network.sh

Tip

อ่านรายละเอียดเชิงลึกและวิธีแก้ปัญหาด้วยตนเองได้ที่: Developer Guide: Ollama WSL Fix

🚀 Quick Start

0. เตรียมข้อมูล (Data Preparation)

นำไฟล์ข้อมูลที่คุณต้องการใช้ค้นหา (รองรับ .jsonl, .pdf, .docx, .xlsx, .pptx, .md, .html, .csv, .svg, .txt) ไปใส่ไว้ในโฟลเดอร์ data/ (สร้างโฟลเดอร์ขึ้นมาหากไม่มี)

หากยังไม่มี สามารถสร้างไฟล์ .jsonl ตัวอย่างที่มีโครงสร้างแบบนี้:

{"book_title": "หนังสือตัวอย่าง", "title": "บทที่ 1", "content": "เนื้อหาที่ต้องการให้อ่าน..."}

1. Build Index

python3 build_index.py            # สร้าง index ครั้งแรก
python3 build_index.py --force    # สร้างใหม่ (ลบของเก่า)

Note

การรันครั้งแรกจะมีการดาวน์โหลดโมเดล Embedding และ Reranker ขนาดรวมประมาณ 4.5 GB จาก Hugging Face โดยอัตโนมัติ กรุณาตรวจสอบการเชื่อมต่ออินเทอร์เน็ต

2. CLI — Classic Pipeline

python3 ask.py                         # Interactive mode
python3 ask.py "สามก๊กสอนอะไร"          # Single question
python3 ask.py --no-hyde "วิธีสร้างนิสัย" # ไม่ใช้ HyDE
python3 ask.py --no-stream "Growth Mindset" # ไม่ streaming

3. CLI — 🧠 Agentic Pipeline (Multi-hop)

python3 ask.py --agentic "เปรียบเทียบ Rich Dad กับ Psychology of Money"
python3 ask.py --agentic "วิเคราะห์ความเชื่อมโยงระหว่าง Atomic Habits กับ 7 Habits"
python3 ask.py --agentic --no-hyde ".."  # Agentic ไม่ใช้ HyDE

4. Web UI

python3 web_server.py
# → Open http://localhost:8080
# → เปิด toggle 🧠 Agentic สำหรับคำถามซับซ้อน

5. Search Only (ไม่ต่อ LLM)

python3 search.py
python3 test_rag.py
python3 test_agentic.py             # Unit tests (agentic)
python3 test_agentic.py --live      # Live API tests

⚙️ Configuration

RAG Tuning — `config.py`

# Hybrid Search weights (must sum to 1.0)
HYBRID_DENSE_WEIGHT = 0.7    # Semantic meaning
HYBRID_BM25_WEIGHT  = 0.3    # Keyword matching

# Adaptive Reranking
RERANK_SCORE_GAP = 0.15      # Skip reranker if gap > threshold

# Search tuning
TOP_K_RETRIEVAL = 10    # FAISS candidates
TOP_K_DISPLAY   = 5     # Final results shown
ENABLE_HYDE     = True  # HyDE query transform on/off

# Sentence Compression
COMPRESSION_ENABLED = True
COMPRESSION_EMBEDDING_THRESHOLD = 0.45  
COMPRESSION_TOP_N_SIMPLE = 5            
COMPRESSION_TOP_N_COMPLEX = 12          

# 🧠 Agentic RAG
AGENTIC_MAX_ITERATIONS = 3        # Max search loop iterations
AGENTIC_SUFFICIENCY_THRESHOLD = 0.7  # Stop searching when confidence ≥ 0.7
AGENTIC_MAX_CHUNKS = 20           # Max total chunks across all iterations

LLM & API Keys — `core/config.py` + `.env`

# .env
GEMINI_API_KEYS='key1,key2,...'    # Round-robin rotation
GROQ_API_KEYS='key1,key2,...'

# Optional overrides
GEMINI_MODEL=gemini-2.5-flash
GEMINI_TEMPERATURE=0.3
GROQ_MODEL=llama-3.3-70b-versatile
GROQ_TEMPERATURE=0.7

💾 VRAM Usage (RTX 4060 — 8 GB)

Component	VRAM
e5-large (Embedding)	~2.2 GB
bge-reranker-v2-m3	~2.2 GB
FAISS Index	~0.01 GB
BM25	0 GB (CPU only)
CUDA overhead	~0.8 GB
Total	~5.2 / 8 GB ✅

📊 Performance

Metric	Classic	🧠 Agentic (complex)
Total Chunks	5,738	5,738
Embedding Dimension	1,024	1,024
Search Latency (skip rerank)	~15ms	~15ms × N sub-queries
Search Latency (with rerank)	~300ms	~300ms × N sub-queries
HyDE Transform	~1.5s	~1.5s × N sub-queries
LLM Generation	~5-8s	~8-15s (more context)
API Calls	2 (HyDE + Gen)	4-8 (Decompose + HyDE×N + Eval + Gen)
Total	~7-10s	~15-30s

💡 คำถาม simple ใน Agentic mode จะ bypass ไป Classic pipeline → ไม่มี overhead เพิ่ม

✨ ความสามารถล่าสุดในเวอร์ชัน 4.1

วิเคราะห์คำถามสำหรับ Web Search (HyDE): ระบบจะปรับปรุงและทำความสะอาดคำค้นหา (Purification) ภาษาไทยให้แม่นยำที่สุดก่อนดึงข้อมูลจากอินเทอร์เน็ต
เปิด/ปิดโหมดอัจฉริยะได้จากหน้าเว็บ: สามารถควบคุมการทำงานของโหมด HyDE และโหมด Agentic ได้ทันทีผ่านปุ่ม Toggle ในหน้าการตั้งค่า
ระบบค้นหาเว็บที่มีเสถียรภาพ: มีระบบสลับช่องทางการค้นหาอัตโนมัติ (Multi-backend Fallback) หากเซิร์ฟเวอร์ DuckDuckGo หลักเกิดข้อขัดข้อง
หน้าการตั้งค่าดีไซน์ใหม่: ออกแบบการนำทางใหม่แบบแนวนอน พร้อมแผนภาพแสดงการทำงานของระบบ RAG (Visualization) ให้เข้าใจง่ายขึ้น
ประมวลผลคำถามปลอดภัย (Query Sanitization): ระบบจะคัดกรองคำถามก่อนนำไปประมวลผลเพื่อป้องกันข้อผิดพลาด
จัดการข้อมูล JSON ดียิ่งขึ้น: ปรับปรุงการอ่านและจัดเตรียมข้อมูลจากไฟล์ JSON ให้เป็นระเบียบและแม่นยำมากขึ้น

🗺️ Roadmap

🛠️ Tech Stack

Category	Technology
Language	Python 3.12
Embedding	sentence-transformers + e5-large
Vector DB	FAISS (GPU-accelerated)
Sparse Search	rank-bm25
Reranker	CrossEncoder (bge-reranker-v2-m3)
LLM Generation	Gemini 2.5 Flash (via google-genai)
Query Transform	Groq LLaMA 3.3 70B
🧠 Agentic RAG	Query Decomposition + Multi-hop + Evaluator
API Key Management	Round-robin rotation (KeyManager)
Web Backend	FastAPI + uvicorn
Web Frontend	Vanilla HTML/CSS/JS + SSE
Streaming	Server-Sent Events (SSE)
GPU	NVIDIA RTX 4060 (CUDA)
Data Format	JSONL

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
api		api
core		core
docs		docs
scripts		scripts
services		services
web		web
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
ask.py		ask.py
build_index.py		build_index.py
check_ollama_memory.py		check_ollama_memory.py
config.py		config.py
discord_bot.py		discord_bot.py
fix_ollama_network.sh		fix_ollama_network.sh
rag_creator.py		rag_creator.py
rag_searcher.py		rag_searcher.py
requirements.txt		requirements.txt
run_all.sh		run_all.sh
search.py		search.py
test_agentic.py		test_agentic.py
test_rag.py		test_rag.py
web_server.py		web_server.py

Folders and files

Latest commit

History

Repository files navigation

📚 RAG System — Full Pipeline Knowledge Base

📸 Screenshots

หน้าแรก (Welcome Page) — Dark Theme + Suggestion Chips

หน้าตอบคำถาม — ผลลัพธ์การค้นหา + แหล่งอ้างอิง

หน้าเพิ่มข้อมูล (Admin Panel) — สำหรับจัดการเอกสาร

หน้าการตั้งค่า (Settings Page) — สำหรับตั้งค่าระบบ

🏗️ Architecture (Modular Design)

Pipeline Stages

📁 Project Structure

🛠️ การติดตั้งและตั้งค่า (Setup)

1. เตรียม Environment

2. ตั้งค่า API Keys

3. ตั้งค่า Discord Bot (กรณีใช้งาน)

🐳 WSL Networking Fix (for Ollama)

🚀 Quick Start

0. เตรียมข้อมูล (Data Preparation)

1. Build Index

2. CLI — Classic Pipeline

3. CLI — 🧠 Agentic Pipeline (Multi-hop)

4. Web UI

5. Search Only (ไม่ต่อ LLM)

⚙️ Configuration

RAG Tuning — config.py

LLM & API Keys — core/config.py + .env

💾 VRAM Usage (RTX 4060 — 8 GB)

📊 Performance

✨ ความสามารถล่าสุดในเวอร์ชัน 4.1

🗺️ Roadmap

🛠️ Tech Stack

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

RAG Tuning — `config.py`

LLM & API Keys — `core/config.py` + `.env`

Packages