orangepi-rag/HDSD.md

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

Mục lục

1. Yêu cầu hệ thống
2. Cài đặt
3. Cấu hình API
4. Sử dụng dữ liệu có sẵn
5. Crawl dữ liệu mới
6. Build index
7. Chạy giao diện web
8. Chế độ CLI
9. Cấu hình nâng cao
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

# 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

cp .env.example .env

Chỉnh sửa file .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

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

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)

# 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ù)

# 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:

[
  {
    "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:

# 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)

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

# 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

# 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

# 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'

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:

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:

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