them web app va README

2026-06-12 22:13:19 +07:00
parent abddb932aa
commit c512d60160
8 changed files with 1216 additions and 155 deletions
@@ -1,215 +1,326 @@
 # Blog RAG Toolkit

-A complete RAG (Retrieval-Augmented Generation) pipeline: **crawl** any blog, **extract** keywords, **chunk** content, and **query** with an LLM.
+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.

-## Components
+---

-| File | Purpose |
-|------|---------|
-| `crawl_blog.py` | Generic blog crawler (sitemap + Firecrawl) |
-| `crawl_orangepi_blog.py` | OrangePi.vn-specific crawler |
-| `rag_app.py` | RAG query application (FAISS + LLM) |
-| `keywords_example.json` | Sample keyword dictionary |
+## Mục lục

-## Quick Start
+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. Install
+---
+
+## 1. Cài đặt

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

-### 2. Set API key
-
-```bash
-export FIRECRAWL_API_KEY="fc-..."
-# or put in .env file:
-echo "FIRECRAWL_API_KEY=fc-..." > .env
-```
-
-### 3. Crawl a blog
-
-```bash
-# Crawl 5 articles from any WordPress blog
-python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --limit 5
-
-# Crawl all articles with custom keywords
-python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --all --keywords keywords.json
-
-# Output to custom directory
-python crawl_blog.py --sitemap https://example.com/post-sitemap.xml --all --out-dir ./my_blog_data
-```
-
-### 4. Build index & query
-
-```bash
-# Build FAISS index
-python rag_app.py --build --data-dir ./my_blog_data --index-dir ./my_index
-
-# Query (requires OPENAI_API_KEY)
-export OPENAI_API_KEY="sk-..."
-python rag_app.py --query "How to install Docker?" --data-dir ./my_blog_data --index-dir ./my_index
-
-# Interactive chat
-python rag_app.py --interactive --data-dir ./my_blog_data --index-dir ./my_index
-```
+**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).

 ---

-## crawl_blog.py — Generic Blog Crawler
+## 2. Cấu hình API

-Crawls any blog that exposes a sitemap (WordPress, Yoast, etc.).
-
-### Usage
+Tạo file `.env` ở thư mục gốc dự án:

 ```bash
-python crawl_blog.py --sitemap <SITEMAP_URL> [options]
+# ─── 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
 ```

-### Options
-
-| Argument | Default | Description |
-|----------|---------|-------------|
-| `--sitemap` | (required) | Sitemap URL |
-| `--out-dir` | `./blog_data` | Output directory |
-| `--keywords` | `<out-dir>/keywords.json` | Keywords JSON path |
-| `--limit N` | 5 | Process first N articles |
-| `--all` | — | Process all articles |
-| `--sleep SEC` | 1.0 | Delay between Firecrawl calls |
-| `--force` | — | Re-scrape cached articles |
-| `--max-words N` | 650 | Target words per chunk |
-| `--overlap-words N` | 100 | Overlap words between chunks |
-| `--language` | `en` | Default language code |
-
-### Output files
-
-| File | Description |
-|------|-------------|
-| `articles.jsonl` | Article records with keyword mentions |
-| `chunks.jsonl` | Chunked content for embedding |
-| `keywords.json` | Keyword dictionary used |
-| `urls.json` | Discovered URLs |
-| `raw/<slug>.json` | Raw Firecrawl responses |
-| `markdown/<slug>.md` | Cleaned markdown |
-| `errors.jsonl` | Failed URLs |
-| `summary.json` | Crawl summary |
+> Lấy Firecrawl key tại: https://www.firecrawl.dev
+> Lấy OpenAI key tại: https://platform.openai.com/api-keys

 ---

-## keywords.json — Keyword Dictionary
+## Bước 1 — Crawl dữ liệu blog

-Defines keywords to extract from crawled content. Supports categorized or flat format.
+### 1.1 Tạo file từ khóa

-### Categorized format (recommended)
+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", "Arduino", "ESP32"]
+    "keywords": ["Raspberry Pi", "Orange Pi", "Arduino", "ESP32"]
  },
  {
    "category": "software",
-    "keywords": ["Docker", "Ubuntu", "Home Assistant"]
+    "keywords": ["Docker", "Ubuntu", "Home Assistant", "MQTT"]
  }
 ]
 ```

-### Flat format
+Xem file mẫu tại `keywords_example.json`.

-```json
-["Raspberry Pi", "Docker", "Home Assistant", "MQTT"]
+### 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
 ```

-See `keywords_example.json` for a complete template.
+### 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 |

 ---

-## rag_app.py — RAG Query Application
+## Bước 2 — Xây dựng chỉ mục & truy vấn

-FAISS-based vector search + LLM generation.
-
-### Usage
+### 2.1 Xây dựng chỉ mục FAISS

 ```bash
-# Build index (one-time)
-python rag_app.py --build --data-dir ./blog_data --index-dir ./index
-
-# Single query
-python rag_app.py --query "Câu hỏi của bạn" --data-dir ./blog_data --index-dir ./index
-
-# Interactive chat
-python rag_app.py --interactive --data-dir ./blog_data --index-dir ./index
-
-# Test retrieval only (no LLM needed)
-python rag_app.py --query "test" --retrieve-only --data-dir ./blog_data --index-dir ./index
+python rag_app.py \
+  --build \
+  --data-dir ./blog_data \
+  --index-dir ./rag_index
 ```

-### Options
+Kết quả:

-| Argument | Default | Description |
-|----------|---------|-------------|
-| `--data-dir` | `.` | Directory with chunks.jsonl |
-| `--index-dir` | `./rag_index` | FAISS index directory |
-| `--build` | — | Build index from chunks |
-| `--query` | — | Query to answer |
-| `--interactive` | — | Interactive chat mode |
-| `--retrieve-only` | — | Test retrieval without LLM |
-| `--top-k` | 5 | Number of chunks to retrieve |
-| `--embed-model` | `paraphrase-multilingual-MiniLM-L12-v2` | Embedding model |
-| `--llm-model` | `gpt-4o-mini` | LLM model name |
-| `--llm-base-url` | `https://api.openai.com/v1` | LLM API base URL |
+```
+rag_index/
+├── faiss.index           # Chỉ mục vector FAISS
+└── chunks.jsonl          # Bản sao chunks cho retrieval
+```

-### LLM API configuration
-
-Set in `.env`:
+### 2.2 Truy vấn đơn lẻ

 ```bash
-OPENAI_API_KEY=sk-...
-# Or for other providers:
-# LLM_BASE_URL=https://api.together.xyz/v1
-# LLM_MODEL=meta-llama/Llama-3-70b-chat-hf
+python rag_app.py \
+  --query "Cài Docker trên Raspberry Pi như thế nào?" \
+  --data-dir ./blog_data \
+  --index-dir ./rag_index
 ```

-Compatible with any OpenAI-format API: OpenAI, Together.ai, Groq, Ollama, etc.
+### 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 |

 ---

-## crawl_orangepi_blog.py — OrangePi-specific Crawler
+## Bước 3 — Giao diện web

-Specialized crawler for orangepi.vn with Orange Pi model detection.
+### 3.1 Khởi động server

 ```bash
-python crawl_orangepi_blog.py --limit 5
-python crawl_orangepi_blog.py --all
+python web_app.py \
+  --data-dir ./blog_data \
+  --index-dir ./rag_index \
+  --port 5000
 ```

-Uses `orangepi_models.json` for product mention detection (36 Orange Pi models with aliases).
+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 |

 ---

-## Architecture
+## Tham khảo
+
+### Cấu trúc thư mục hoàn chỉnh

 ```
-Blog (sitemap)
-    │
-    ▼
-crawl_blog.py ──► Firecrawl API ──► articles.jsonl
-    │                                  chunks.jsonl
-    │                                  keywords.json
-    │                                  raw/*.json
-    │                                  markdown/*.md
-    ▼
-rag_app.py
-    │
-    ├──► SentenceTransformer (embeddings)
-    ├──► FAISS (vector index)
-    └──► LLM API (generation)
-            │
-            ▼
-        Answer + sources
+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
 ```

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

-Data sourced from respective blogs. Check each site for content usage terms.
+```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
+```