310 lines
9.1 KiB
Markdown
310 lines
9.1 KiB
Markdown
# 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**
|