# Hướng Dẫn Sử Dụng — Blog RAG

## Mục lục

1. [Yêu cầu hệ thống](#1-yêu-cầu-hệ-thống)
2. [Cài đặt](#2-cài-đặt)
3. [Cấu hình API](#3-cấu-hình-api)
4. [Sử dụng dữ liệu có sẵn](#4-sử-dụng-dữ-liệu-có-sẵn)
5. [Crawl dữ liệu mới](#5-crawl-dữ-liệu-mới)
6. [Build index](#6-build-index)
7. [Chạy giao diện web](#7-chạy-giao-diện-web)
8. [Chế độ CLI](#8-chế-độ-cli)
9. [Cấu hình nâng cao](#9-cấu-hình-nâng-cao)
10. [Xử lý sự cố](#10-xử-lý-sự-cố)

---

## 1. Yêu cầu hệ thống

- Python 3.10+
- RAM: tối thiểu 4GB (để load embedding model)
- Dung lượng ổ cứng: ~500MB cho dữ liệu + index

## 2. Cài đặt

```bash
# Clone repo
git clone https://git.ttcorp.net/orangepivietnam/orangepi-rag
cd orangepi-rag

# Tạo virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Cài dependencies
pip install -r requirements.txt

# Nếu dùng CPU-only (không có GPU), dùng file riêng:
pip install -r requirements-cpu.txt
```

## 3. Cấu hình API

```bash
cp .env.example .env
```

Chỉnh sửa file `.env`:

```env
# BẮT BUỘC: API key cho LLM (OpenAI hoặc tương thích OpenAI)
LLM_API_KEY=sk-...

# Tuỳ chọn: thay đổi base URL (dùng Together.ai, Groq, v.v.)
# LLM_BASE_URL=https://api.groq.com/openai/v1

# Tuỳ chọn: thay đổi model
# LLM_MODEL=llama-3.1-70b-versatile

# Tuỳ chọn: chỉ cần khi crawl dữ liệu mới
# FIRECRAWL_API_KEY=fc-...
```

**Hỗ trợ API:**

| Nhà cung cấp | Base URL | Ví dụ model |
|---|---|---|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| Groq | `https://api.groq.com/openai/v1` | `llama-3.1-70b-versatile` |
| Together.ai | `https://api.together.xyz/v1` | `meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` |
| Ollama (local) | `http://localhost:11434/v1` | `llama3.1` |

## 4. Sử dụng dữ liệu có sẵn

Dữ liệu `orangepi_data/` đã được crawl sẵn từ blog orangepi.vn với 199 bài viết, 36 model Orange Pi.

### Bước 1: Build index lần đầu

```bash
python rag_app.py --build --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index
```

> Quá trình này mất ~2-5 phút tùy máy (load embedding model + tạo vectors cho 901 chunks).

### Bước 2: Chạy web

```bash
python web_app.py --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index --port 5000
```

Mở trình duyệt: `http://localhost:5000`

### Cách dùng trên web

1. Nhấn **nút +** (góc trên sidebar) để tạo phiên chat mới
2. Nhập câu hỏi vào ô nhập liệu
3. Nhấn **Enter** hoặc nút gửi để nhận câu trả lời
4. Mỗi câu trả lời hiển thị **thời gian xử lý** và **nguồn** (tên bài viết + link)
5. Nhấn **biểu tượng mặt trăng/ngày** ở sidebar để chuyển Dark/Light mode

### Ví dụ câu hỏi

- "Orange Pi 5 dùng chip gì?"
- "So sánh Orange Pi Zero 2 và Raspberry Pi Zero 2"
- "Cài Home Assistant trên Orange Pi Zero2 như thế nào?"
- "Orange Pi nào chạy được RISC-V?"
- "Các hệ điều hành nào hỗ trợ Orange Pi 5?"

## 5. Crawl dữ liệu mới

> **Lưu ý:** Cần `FIRECRAWL_API_KEY` trong file `.env`.

### Crawl blog bất kỳ (tổng quát)

```bash
# Crawl 5 bài đầu tiên (test)
python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --limit 5

# Crawl tất cả bài viết
python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --all

# Dùng file từ khóa tuỳ chỉnh
python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --all --keywords my_keywords.json

# Xuất ra thư mục tuỳ chỉnh
python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --all --out-dir ./my_blog_data
```

### Crawl orangepi.vn (đặc thù)

```bash
# Crawl 5 bài
python crawl_orangepi_blog.py --limit 5

# Crawl tất cả
python crawl_orangepi_blog.py --all
```

### File từ khóa (keywords.json)

Định dạng danh mục:

```json
[
  {
    "category": "hardware",
    "keywords": ["Orange Pi 5", "Orange Pi Zero", "RK3588"]
  },
  {
    "category": "software",
    "keywords": ["Docker", "Ubuntu", "Armbian"]
  },
  {
    "category": "smart_home",
    "keywords": ["Home Assistant", "MQTT", "Node-RED"]
  }
]
```

Xem file mẫu: `keywords_example.json`

## 6. Build index

Sau khi crawl xong, build FAISS index:

```bash
# Build từ dữ liệu mới crawl
python rag_app.py --build --data-dir ./blog_data --index-dir ./blog_data/rag_index

# Build từ dữ liệu orangepi có sẵn
python rag_app.py --build --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index
```

### Kiểm tra retrieval (không cần LLM)

```bash
python rag_app.py --retrieve-only --query "Orange Pi 5 dùng chip gì" --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index
```

## 7. Chạy giao diện web

```bash
# Dữ liệu orangepi.vn có sẵn
python web_app.py --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index --port 5000

# Dữ liệu blog riêng
python web_app.py --data-dir ./blog_data --index-dir ./blog_data/rag_index --port 5000

# Tuỳ chọn khác
python web_app.py --host 0.0.0.0 --port 8080 --debug
```

### Tuỳ chọn CLI

| Tuỳ chọn | Mặc định | Mô tả |
|---|---|---|
| `--host` | `0.0.0.0` | Địa chỉ bind |
| `--port` | `5000` | Cổng lắng nghe |
| `--data-dir` | `.` | Thư mục dữ liệu (chứa `chunks.jsonl`) |
| `--index-dir` | `./rag_index` | Thư mục FAISS index |
| `--debug` | `false` | Chế độ debug |

### Tính năng web

- **Quản lý phiên chat:** Tạo, xóa, chuyển đổi giữa các phiên
- **Lịch sử hội đồng:** Mỗi phiên lưu riêng, hỗ trợ ngữ cảnh 10 tin nhắn gần nhất
- **Hiển thị markdown:** Headings, code blocks, tables, blockquotes, links
- **Thời gian xử lý:** Hiển thị bên dưới mỗi câu trả lời
- **Nguồn trích dẫn:** Link đến bài viết gốc
- **Dark/Light mode:** Nhấn biểu tượng ở sidebar header
- **Topic guard:** Tự động từ chối câu hỏi ngoài phạm vi dữ liệu

## 8. Chế độ CLI

```bash
# Hỏi một câu
python rag_app.py --query "Orange Pi 5 dùng chip gì" --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index

# Chat interactive
python rag_app.py --interactive --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index

# Chỉ test retrieval (không gọi LLM)
python rag_app.py --retrieve-only --query "Home Assistant" --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index
```

### Tuỳ chọn CLI

| Tuỳ chọn | Mặc định | Mô tả |
|---|---|---|
| `--data-dir` | `.` | Thư mục dữ liệu |
| `--index-dir` | `./rag_index` | Thư mục FAISS index |
| `--build` | - | Build index từ chunks |
| `--query` | - | Câu hỏi (một lần) |
| `--interactive` | - | Chế độ chat interactive |
| `--retrieve-only` | - | Chỉ test retrieval, không gọi LLM |
| `--top-k` | `5` | Số chunks trả về |
| `--embed-model` | `paraphrase-multilingual-MiniLM-L12-v2` | Embedding model |
| `--llm-model` | `gpt-4o-mini` | Tên model LLM |
| `--llm-base-url` | `https://api.openai.com/v1` | Base URL API |

## 9. Cấu hình nâng cao

### Biến môi trường

| Biến | Mô tả | Mặc định |
|---|---|---|
| `LLM_API_KEY` | API key cho LLM | - |
| `LLM_BASE_URL` | Base URL API | `https://api.openai.com/v1` |
| `LLM_MODEL` | Model name | `gpt-4o-mini` |
| `FIRECRAWL_API_KEY` | API key cho Firecrawl | - |
| `RAG_DATA_DIR` | Thư mục dữ liệu | `.` |
| `RAG_INDEX_DIR` | Thư mục index | `./rag_index` |
| `RAG_TOP_K` | Số chunks retrieval | `5` |
| `RAG_MAX_HISTORY` | Số tin nhắn ngữ cảnh | `10` |
| `RAG_EMBED_MODEL` | Embedding model | `paraphrase-multilingual-MiniLM-L12-v2` |

### Thay đổi embedding model

```bash
# Dùng model khác
python rag_app.py --build --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index \
  --embed-model "sentence-transformers/all-MiniLM-L6-v2"
```

> **Lưu ý:** Khi thay đổi embedding model cần build lại index.

## 10. Xử lý sự cố

### Lỗi `ModuleNotFoundError: No module named 'torch'`

```bash
pip install torch
# Hoặc dùng bản CPU:
pip install -r requirements-cpu.txt
```

### Lỗi `FIRECRAWL_API_KEY is not set`

Đảm bảo file `.env` đã được tạo và điền đúng key. Chỉ cần thiết khi crawl dữ liệu mới.

### Lỗi `LLM_API_KEY is not set`

Đảm bảo file `.env` có `LLM_API_KEY=sk-...`. Nếu chỉ muốn test retrieval mà không cần LLM:

```bash
python rag_app.py --retrieve-only --query "câu hỏi" --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index
```

### Lỗi encoding trên Windows

Nếu gặp lỗi ký tự tiếng Việt, đảm bảo terminal dùng UTF-8:

```bash
chcp 65001
python web_app.py --data-dir ./orangepi_data --index-dir ./orangepi_data/rag_index --port 5000
```

### Web không load được

- Kiểm tra port chưa bị chiếm: `netstat -ano | findstr :5000`
- Thử port khác: `--port 8080`
- Bật debug mode: `--debug`

---

**Copyright © 2026 — Blog RAG Solution — TTAI Solutions Software**