Hệ thống hỏi đáp thông minh sử dụng RAG (Retrieval-Augmented Generation) cho nội quy lớp học trực tuyến.

---

Giới thiệu

EDU RAG Platform Test là hệ thống chatbot thử nghiệm, sử dụng kỹ thuật RAG để trả lời các câu hỏi liên quan đến nội quy lớp học trực tuyến. Hệ thống kết hợp:

• Retrieval: Hybrid Search kết hợp tìm kiếm vector (pgvector) và keyword matching.
• Augmented Generation: Sử dụng Google Gemini để sinh câu trả lời dựa trên ngữ cảnh.

---

Cấu trúc thư mục

edu-rag-platform-test/
├── backend/                    # API Backend (FastAPI)
│   ├── routes/                 # Định nghĩa các endpoint
│   │   ├── auth.py             # Xác thực PIN
│   │   └── chat.py             # Chat API
│   ├── tests/                  # Unit tests cho backend
│   ├── main.py                 # Entry point
│   └── schemas.py              # Pydantic schemas
│
├── core/                       # RAG Core Logic
│   ├── tests/                  # Unit tests cho core
│   ├── config.py               # Cấu hình từ .env
│   ├── embedder.py             # Tạo embeddings
│   ├── generator.py            # Sinh câu trả lời (LLM)
│   ├── ingest.py               # Nạp dữ liệu vào vector store
│   ├── retriever.py            # Truy xuất ngữ cảnh
│   └── vector_store.py         # Kết nối pgvector
│
├── data/                       # Dữ liệu
│   ├── chunks/                 # Các đoạn văn bản đã chia
│   ├── processed/              # Văn bản đã xử lý
│   └── raw/                    # Dữ liệu gốc
│
├── frontend/                   # Giao diện (React + Vite)
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── pages/              # Các trang (PIN, Chat)
│   │   ├── services/           # API calls
│   │   └── types/              # TypeScript types
│   ├── Dockerfile              # Build frontend image
│   └── nginx.conf              # Cấu hình Nginx
│
├── .github/workflows/          # GitHub Actions
│   └── deploy.yml              # Auto deploy khi push tag
│
├── Dockerfile.backend          # Build backend image
├── docker-compose.yml          # Docker Compose config (build từ source)
├── docker-compose.images.yml   # Docker Compose config (dùng pre-built images)
├── build-and-save.bat          # Script build và save images (Windows)
├── deploy.sh                   # Script deploy trên server (Linux)
├── requirements.txt            # Python dependencies
├── LICENSE                     # MIT License
└── .env.example                # File mẫu .env

---

Yêu cầu

Chạy local

• Python 3.11+
• Node.js 18+
• PostgreSQL với extension pgvector

Chạy với Docker

• Docker 20.10+
• Docker Compose 1.29+

---

Chạy trên local

1. Clone repository:

git clone https://github.com/tynnp/edu-rag-platform-test.git
cd edu-rag-platform-test

2. Tạo file .env ở thư mục gốc:

# Database
DB_HOST=your_db_host
DB_PORT=5432
DB_NAME=edu_rag
DB_USER=your_user
DB_PASSWORD=your_password

# Embedding
EMBEDDING_MODEL=models/text-embedding-004

# LLM
LLM_MODEL=gemini-3-flash-preview
LLM_API_KEY=your_gemini_api_key

# Retrieval
TOP_K=5

# Auth
PIN_CODE=123456

3. Cài đặt dependencies:

pip install -r requirements.txt

4. Xây dựng hệ thống RAG:

Ingestion (Nạp dữ liệu vào Vector DB):

python -m core.ingest

Script sẽ đọc chunks từ data/chunks/, tạo embeddings và lưu vào PostgreSQL pgvector.

Query (Test):

python core/tests/test_chat.py

5. Chạy Backend:

uvicorn backend.main:app --reload

6. Chạy Frontend:

cd frontend
npm install
npm run dev

7. Truy cập http://localhost:5173 và nhập PIN để sử dụng.

---

Chạy với Docker

1. Clone repository:

git clone https://github.com/tynnp/edu-rag-platform-test.git
cd edu-rag-platform-test

2. Tạo file .env ở thư mục gốc (xem mẫu ở trên).

3. Build và chạy:

docker-compose up -d --build

4. Truy cập http://localhost:3508 và nhập PIN để sử dụng.

---

Cấu hình

Biến môi trường	Mô tả
DB_HOST	Địa chỉ PostgreSQL server
DB_PORT	Cổng PostgreSQL
DB_NAME	Tên database
DB_USER	Tên người dùng database
DB_PASSWORD	Mật khẩu database
EMBEDDING_MODEL	Model embedding (mặc định: models/text-embedding-004)
LLM_MODEL	Model LLM (mặc định: gemini-3-flash-preview)
LLM_API_KEY	API Key của Google Gemini
TOP_K	Số lượng chunks truy xuất (mặc định: 5)
PIN_CODE	Mã PIN để truy cập hệ thống

---

Triển khai

Hệ thống hỗ trợ tự động deploy qua GitHub Actions khi push tag.

Cấu hình GitHub Secrets

Vào Settings > Secrets and variables > Actions của repository và thêm:

Secret	Mô tả
SSH_HOST	IP của server
SSH_USER	Username SSH (vd: root)
SSH_PASSWORD	Mật khẩu SSH
SSH_PORT	Cổng SSH (vd: 22)
ENV_FILE	Toàn bộ nội dung file .env

Triển khai tự động

git tag v1.0.0
git push origin v1.0.0

Workflow sẽ tự động:

1. Copy source code lên server.
2. Tạo file .env từ secret.
3. Build và chạy docker-compose up -d --build

Triển khai thủ công

Nếu muốn build images trên máy local và copy lên server:

Bước 1: Build images trên Windows

build-and-save.bat

Kết quả: docker-images/edu-rag-backend.tar và docker-images/edu-rag-frontend.tar

Bước 2: Copy folder docker-images/ lên server

Bước 3: Trên server, sử dụng deploy.sh

Lệnh	Mô tả
./deploy.sh load	Load images từ file .tar
./deploy.sh up	Khởi động containers
./deploy.sh down	Dừng containers
./deploy.sh restart	Khởi động lại
./deploy.sh logs	Xem logs
./deploy.sh status	Xem trạng thái
./deploy.sh clean	Xóa tất cả images/containers
./deploy.sh build	Build lại từ source

---

Dự án này được phát hành theo giấy phép MIT License