README.md

metadata

title: Vietnamese RAG System
emoji: 🔍
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

Hệ thống RAG cho Tài liệu Tiếng Việt

Hệ thống RAG (Retrieval-Augmented Generation) cho tài liệu tài chính tiếng Việt — hybrid BM25+vector search, cross-encoder reranking, Contextual Retrieval và ColPali visual retrieval.

Kết quả nổi bật: Contextual Retrieval cải thiện Context Recall từ 0.40 → 0.72 (+80%); ColPali vượt trội text RAG trên trang bảng số liệu (0.90 vs 0.80).

Tính năng

Tính năng	Chi tiết
Phân tích tài liệu 2 tầng	pypdf cho PDF văn bản, EasyOCR (GPU) cho ảnh hóa đơn tiếng Việt
Tìm kiếm lai (Hybrid Search)	Qdrant (vector) + BM25 (từ khóa) kết hợp bằng Reciprocal Rank Fusion
NLP tiếng Việt	Tách từ underthesea cho BM25, tự động viết lại câu truy vấn
Reranking	Cross-encoder bge-reranker-v2-m3 với trích dẫn nội tuyến [1][2]...
Contextual Retrieval	Sinh context bằng LLM, prepend vào chunk trước khi embedding (theo paper Anthropic)
ColPali Visual Retrieval	vidore/colpali-v1.2 multi-vector MaxSim — tìm kiếm trang PDF dưới dạng ảnh, không cần OCR
Đánh giá	RAGAS dùng LLM-as-judge trên bộ câu hỏi báo cáo tài chính
REST API	FastAPI với giao diện chat SSE streaming
Triển khai	Docker trên HuggingFace Spaces với Qdrant Cloud

Kiến trúc

Pipeline A — Text RAG (production)

Tài liệu (PDF / Ảnh)
        │
        ▼
    Parser (pypdf / EasyOCR)
        │
        ▼
    Chunker  ──► [tùy chọn] Contextual Retrieval (LLM prepend context)
        │
        ├──► Qdrant Cloud (vector)     Gemini gemini-embedding-001 (3072-dim)
        └──► BM25 index (underthesea)
                │
        Query ──┤ (viết lại câu hỏi)
                ├──► Vector search
                ├──► BM25 search
                └──► RRF fusion ──► Reranker (bge-reranker-v2-m3) ──► LLM (Groq) ──► Câu trả lời

Pipeline B — ColPali Visual Retrieval (thực nghiệm so sánh)

Trang PDF ──► render thành ảnh ──► ColPali v1.2 (multi-vector, 128-dim patches)
                                        │
                                   Qdrant local (MaxSim scoring)
                                        │
                              Query ──► encode query ──► MaxSim search ──► top-k trang

Công nghệ sử dụng

Thành phần	Công nghệ
Embedding	Google Gemini gemini-embedding-001 (3072-dim)
LLM	Groq llama-3.3-70b-versatile
Vector DB	Qdrant Cloud (text) + Qdrant local (ColPali)
Visual Retrieval	vidore/colpali-v1.2 (PaliGemma + LoRA, multi-vector MaxSim)
Reranker	BAAI/bge-reranker-v2-m3 cross-encoder
NLP tiếng Việt	underthesea (tách từ)
API	FastAPI + Uvicorn + SSE streaming
Triển khai	Docker trên HuggingFace Spaces

Dữ liệu

• PDF: Báo cáo tài chính doanh nghiệp Việt Nam (niêm yết HOSE, HNX, UPCOM)
• Ảnh: Bộ dữ liệu MC-OCR — hóa đơn bán lẻ tiếng Việt (EasyOCR GPU)

Cài đặt nhanh (Docker)

# 1. Clone repo
git clone https://github.com/thaidinh1206/rag-vietnamese.git
cd rag-vietnamese

# 2. Tạo file .env
cp .env.example .env
# Thêm API keys: GOOGLE_API_KEY, GROQ_API_KEY

# 3. Chạy
docker-compose up

# 4. Mở trình duyệt
# http://localhost:8000

Cài đặt local

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Tạo file .env:

GOOGLE_API_KEY=...
GROQ_API_KEY=...

# Ingest tài liệu
python ingest.py pdf                # PDF (text pipeline)
python ingest.py pdf --contextual   # PDF với Contextual Retrieval
python ingest.py images             # Ảnh (yêu cầu GPU)
python ingest_colpali.py            # PDF pages dạng ảnh (ColPali pipeline)

# Chạy API
uvicorn api:app --reload --port 8000

# Chế độ CLI
python main.py

# Đánh giá
python evaluate.py                           # QA hóa đơn ảnh
python evaluate.py data/golden_set_pdf.json  # QA báo cáo tài chính

# So sánh hai pipeline
python compare_retrieval.py
python evaluate_colpali.py

Demo trực tuyến

🔗 Live demo: huggingface.co/spaces/thaidinhz1/rag-vietnamese

🔗 Source code: github.com/thaidinh1206/rag-vietnamese

Lưu ý: Lần đầu tải có thể mất ~60s (cold start). Nginx proxy của HF Spaces free tier buffer SSE — streaming hoạt động đúng trên local/VPS nhưng hiển thị theo batch trên HF Spaces.

So sánh Retrieval: ColPali vs Text RAG

Đánh giá trên 10 câu hỏi báo cáo tài chính tiếng Việt, dùng LLM-as-judge chấm điểm mức độ liên quan của nguồn tài liệu:

Chỉ số	Text RAG	ColPali
Source Relevance (trung bình)	0.790	0.520

Loại câu hỏi	Text RAG	ColPali
Bảng số liệu (doanh thu, lợi nhuận)	0.80	0.90 ✓
Tên công ty / mã chứng khoán	0.90 ✓	0.00–0.50
So sánh nhiều kỳ	0.90 ✓	0.20
Thông tin ngành / lĩnh vực	0.80	0.90 ✓

Nhận xét: Text RAG thắng tổng thể (0.79 vs 0.52) nhờ BM25 xử lý chính xác tên công ty và mã chứng khoán tiếng Việt. ColPali ngang bằng hoặc vượt trội trên các trang chứa bảng số liệu phức tạp — đúng với trường hợp sử dụng thiết kế của nó (nơi pypdf mất cấu trúc bảng). Kết hợp cả hai pipeline sẽ cho kết quả tối ưu.

Đánh giá RAGAS (LLM-as-judge)

Đánh giá trên bộ câu hỏi báo cáo tài chính tiếng Việt:

Pipeline	Faithfulness	Answer Relevancy	Context Recall	Trung bình
Text RAG (baseline)	0.633	0.767	0.400	0.600
Text RAG + Contextual Retrieval	0.590	0.720	0.720	0.677

Nhận xét: Contextual Retrieval cải thiện Context Recall đáng kể (+0.32) — context được prepend vào chunk giúp retrieval tìm đúng đoạn liên quan hơn. Faithfulness và Relevancy giảm nhẹ do câu trả lời dài hơn khi có context.

Context Recall baseline thấp (0.40) phản ánh điểm yếu của pypdf với bảng tài chính — đúng khoảng trống mà ColPali nhắm tới.

Quyết định kiến trúc

Quyết định	Lý do
HF Spaces thay vì Render/Railway	Free tier duy nhất có 16GB RAM — đủ cho bge-reranker + Gemini embeddings. Render (512MB) và Railway (0.5GB) không thể load model.
Qdrant Cloud cho text vectors	Disk HF Spaces reset khi restart — Qdrant Cloud free tier (1GB) giữ vectors qua các lần deploy.
Qdrant local cho ColPali	Multi-vector ColPali ~500KB/trang — quá lớn cho Qdrant Cloud free tier. Dùng cho thực nghiệm so sánh local.
Không chạy OCR trong pipeline live	EasyOCR trên CPU quá chậm (~30s/ảnh). Kết quả OCR được baked sẵn vào corpus qua offline ingestion.
Groq thay vì Gemini cho LLM	Gemini free tier có rate limit nghiêm ngặt. Groq cho inference nhanh với quota thoải mái hơn.
Contextual Retrieval offline	Cần 1 LLM call/chunk (~219 calls). Chạy một lần lúc ingest; query time không tốn thêm latency.
Streaming qua SSE	Triển khai tại API layer (/stream). Nginx proxy HF Spaces buffer stream — hoạt động đúng trên deploy trực tiếp.