orangepi-rag/README.md

# Blog RAG Toolkit

Bộ công cụ RAG (Retrieval-Augmented Generation) hoàn chỉnh: **crawl** blog, **trích xuất** từ khóa, **chia nhỏ** nội dung, **truy vấn** bằng LLM, và **giao diện web** để chat.

---

## Mục lục

1. [Cài đặt](#1-cài-đặt)
2. [Cấu hình API](#2-cấu-hình-api)
3. [Bước 1 — Crawl dữ liệu blog](#bước-1--crawl-dữ-liệu-blog)
4. [Bước 2 — Xây dựng chỉ mục & truy vấn](#bước-2--xây-dựng-chỉ-mục--truy-vấn)
5. [Bước 3 — Giao diện web](#bước-3--giao-diện-web)
6. [Tham khảo](#tham-khảo)

---

## 1. Cài đặt

```bash
git clone <repo-url>
cd orangepi-rag
pip install -r requirements.txt
```

**Yêu cầu:** Python 3.10+, tài khoản [Firecrawl](https://www.firecrawl.dev) (cho crawl), tài khoản LLM — OpenAI / Together.ai / Groq / Ollama (cho truy vấn).

---

## 2. Cấu hình API

Tạo file `.env` ở thư mục gốc dự án:

```bash
# ─── BẮT BUỘC cho crawl ───
FIRECRAWL_API_KEY=fc-...

# ─── BẮT BUỘC cho RAG query ───
OPENAI_API_KEY=sk-...

# ─── TÙY CHỌN ───
# Thay đổi LLM provider (mặc định: OpenAI)
# LLM_BASE_URL=https://api.together.xyz/v1
# LLM_MODEL=meta-llama/Llama-3-70b-chat-hf
```

> Lấy Firecrawl key tại: https://www.firecrawl.dev
> Lấy OpenAI key tại: https://platform.openai.com/api-keys

---

## Bước 1 — Crawl dữ liệu blog

### 1.1 Tạo file từ khóa

Tạo file `keywords.json` chứa các từ khóa cần trích xuất từ blog:

```json
[
  {
    "category": "hardware",
    "keywords": ["Raspberry Pi", "Orange Pi", "Arduino", "ESP32"]
  },
  {
    "category": "software",
    "keywords": ["Docker", "Ubuntu", "Home Assistant", "MQTT"]
  }
]
```

Xem file mẫu tại `keywords_example.json`.

### 1.2 Tìm sitemap URL

Blog WordPress thường có sitemap tại:
- `https://example.com/post-sitemap.xml` (Yoast SEO)
- `https://example.com/sitemap.xml` (generic)

### 1.3 Chạy crawl

```bash
# Test thử 5 bài viết
python crawl_blog.py \
  --sitemap https://example.com/post-sitemap.xml \
  --limit 5 \
  --out-dir ./blog_data

# Crawl toàn bộ blog
python crawl_blog.py \
  --sitemap https://example.com/post-sitemap.xml \
  --all \
  --keywords keywords.json \
  --out-dir ./blog_data

# Crawl với tùy chỉnh
python crawl_blog.py \
  --sitemap https://example.com/post-sitemap.xml \
  --all \
  --keywords keywords.json \
  --out-dir ./blog_data \
  --sleep 1.5 \
  --max-words 500 \
  --overlap-words 80 \
  --language vi
```

### 1.4 Kết quả

Sau khi crawl xong, thư mục `blog_data/` sẽ chứa:

```
blog_data/
├── articles.jsonl        # Mỗi dòng = 1 bài viết (title, text, keywords, ...)
├── chunks.jsonl          # Mỗi dòng = 1 đoạn nhỏ (~650 từ) cho embedding
├── keywords.json         # File từ khóa đã dùng
├── urls.json             # Danh sách URL tìm được từ sitemap
├── raw/<slug>.json       # Response gốc từ Firecrawl
├── markdown/<slug>.md    # Markdown đã làm sạch
├── errors.jsonl          # Các URL lỗi
└── summary.json          # Tổng kết crawl
```

### 1.5 Tham số đầy đủ

| Tham số | Mặc định | Mô tả |
|---------|----------|-------|
| `--sitemap` | (bắt buộc) | URL sitemap |
| `--out-dir` | `./blog_data` | Thư mục output |
| `--keywords` | `<out-dir>/keywords.json` | File từ khóa JSON |
| `--limit N` | 5 | Crawl N bài đầu tiên |
| `--all` | — | Crawl toàn bộ |
| `--sleep SEC` | 1.0 | Nghỉ giữa mỗi request (giây) |
| `--force` | — | Crawl lại kể cả đã có cache |
| `--max-words N` | 650 | Số từ tối đa mỗi chunk |
| `--overlap-words N` | 100 | Số từ overlap giữa các chunk |
| `--language` | `en` | Mã ngôn ngữ mặc định |

---

## Bước 2 — Xây dựng chỉ mục & truy vấn

### 2.1 Xây dựng chỉ mục FAISS

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

Kết quả:

```
rag_index/
├── faiss.index           # Chỉ mục vector FAISS
└── chunks.jsonl          # Bản sao chunks cho retrieval
```

### 2.2 Truy vấn đơn lẻ

```bash
python rag_app.py \
  --query "Cài Docker trên Raspberry Pi như thế nào?" \
  --data-dir ./blog_data \
  --index-dir ./rag_index
```

### 2.3 Chat interactive (terminal)

```bash
python rag_app.py \
  --interactive \
  --data-dir ./blog_data \
  --index-dir ./rag_index
```

Gõ câu hỏi, nhận câu trả lời. Nhấn `Ctrl+C` để thoát.

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

```bash
python rag_app.py \
  --query "Home Assistant" \
  --retrieve-only \
  --data-dir ./blog_data \
  --index-dir ./rag_index
```

Chỉ hiển thị các chunk liên quan nhất, không gọi LLM.

### 2.5 Tham số đầy đủ

| Tham số | Mặc định | Mô tả |
|---------|----------|-------|
| `--data-dir` | `.` | Thư mục chứa chunks.jsonl |
| `--index-dir` | `./rag_index` | Thư mục chỉ mục FAISS |
| `--build` | — | Xây dựng chỉ mục |
| `--query` | — | Câu hỏi cần trả lời |
| `--interactive` | — | Chế độ chat terminal |
| `--retrieve-only` | — | Chỉ test retrieval, không dùng LLM |
| `--top-k` | 5 | Số chunk trả về |
| `--embed-model` | `paraphrase-multilingual-MiniLM-L12-v2` | Mô hình embedding |
| `--llm-model` | `gpt-4o-mini` | Tên mô hình LLM |
| `--llm-base-url` | `https://api.openai.com/v1` | URL API LLM |

---

## Bước 3 — Giao diện web

### 3.1 Khởi động server

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

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

### 3.2 Sử dụng

1. Nhấn **+** để tạo phiên chat mới
2. Gõ câu hỏi vào ô nhập, nhấn **Enter** để gửi
3. Xem câu trả lời + nguồn bài viết
4. Tạo nhiều phiên để hỏi nhiều chủ đề khác nhau
5. Xóa lịch sử hoặc xóa phiên bằng nút trên header

### 3.3 Tính năng

| Tính năng | Mô tả |
|-----------|-------|
| **Quản lý phiên** | Tạo, chuyển đổi, xóa nhiều phiên chat |
| **Lịch sử chat** | Lưu vào SQLite, giữ lại khi reload trang |
| **Nhớ ngữ cảnh** | 10 tin nhắn cuối được đưa vào prompt để giữ context |
| **Tránh lạc đề** | LLM được hướng dẫn chỉ trả lời trong phạm vi dữ liệu |
| **Trích nguồn** | Mỗi câu trả lời có link đến bài viết gốc |
| **Responsive** | Giao diện thích ứng desktop và mobile |

### 3.4 Tham số

| Tham số | Mặc định | Mô tả |
|---------|----------|-------|
| `--host` | `0.0.0.0` | Host để bind |
| `--port` | `5000` | Port |
| `--debug` | — | Chế độ debug |
| `--data-dir` | `.` | Thư mục dữ liệu |
| `--index-dir` | `./rag_index` | Thư mục chỉ mục |

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

```bash
# Trong file .env
RAG_DATA_DIR=./blog_data
RAG_INDEX_DIR=./rag_index
RAG_LLM_MODEL=gpt-4o-mini
RAG_LLM_BASE_URL=https://api.openai.com/v1
RAG_TOP_K=5
RAG_MAX_HISTORY=10          # Số tin nhắn giữ context
```

### 3.6 API endpoints

| Method | Path | Mô tả |
|--------|------|-------|
| `GET` | `/api/sessions` | Danh sách phiên |
| `POST` | `/api/sessions` | Tạo phiên mới |
| `DELETE` | `/api/sessions/<id>` | Xóa phiên |
| `GET` | `/api/sessions/<id>/messages` | Lịch sử tin nhắn |
| `POST` | `/api/sessions/<id>/messages` | Gửi tin nhắn, nhận câu trả lời |
| `POST` | `/api/sessions/<id>/clear` | Xóa lịch sử phiên |
| `GET` | `/api/stats` | Thống kê hệ thống |

---

## Tham khảo

### Cấu trúc thư mục hoàn chỉnh

```
orangepi-rag/
├── .env                     # API keys (FIRECRAWL, OPENAI)
├── requirements.txt         # Python dependencies
├── crawl_blog.py            # Crawler tổng quát
├── crawl_orangepi_blog.py   # Crawler orangepi.vn
├── rag_app.py               # RAG query (CLI)
├── web_app.py               # Giao diện web (Flask)
├── keywords_example.json    # Mẫu file từ khóa
├── templates/
│   └── index.html           # HTML template
├── static/
│   ├── style.css            # CSS
│   └── app.js               # JavaScript
├── blog_data/               # Dữ liệu crawl được
│   ├── articles.jsonl
│   ├── chunks.jsonl
│   ├── keywords.json
│   ├── urls.json
│   ├── raw/
│   ├── markdown/
│   ├── errors.jsonl
│   └── summary.json
├── rag_index/               # Chỉ mục FAISS
│   ├── faiss.index
│   └── chunks.jsonl
└── rag_chat.db              # SQLite chat history
```

### Lưu ý khi dùng LLM provider khác

```bash
# Together.ai
LLM_BASE_URL=https://api.together.xyz/v1
LLM_MODEL=meta-llama/Llama-3-70b-chat-hf
OPENAI_API_KEY=...

# Groq
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_MODEL=llama-3.1-70b-versatile
OPENAI_API_KEY=...

# Ollama (chạy local)
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3
OPENAI_API_KEY=ollama
```