chatbot_guide_template.md

# Hướng Dẫn Sử Dụng ChatbotRAG

*Version 2.0 - Tháng 10, 2025*

---

## 1. Giới Thiệu

### ChatbotRAG là gì?

ChatbotRAG là hệ thống chatbot thông minh sử dụng công nghệ RAG (Retrieval-Augmented Generation) để trả lời câu hỏi dựa trên cơ sở dữ liệu kiến thức của bạn.

### Tính năng chính

- **Multimodal Search**: Tìm kiếm bằng text và hình ảnh
- **Advanced RAG**: Query expansion, reranking, context compression
- **PDF Support**: Upload PDF và chat về nội dung trong PDF
- **Multiple Inputs**: Index nhiều texts và images cùng lúc (tối đa 10 mỗi loại)
- **Chat History**: Lưu lịch sử chat để theo dõi

---

## 2. Bắt Đầu Nhanh

### Bước 1: Khởi động server

```bash
cd ChatbotRAG
python main.py
```

Server sẽ chạy tại: `http://localhost:8000`

### Bước 2: Truy cập API Documentation

Mở trình duyệt và truy cập:
- API Docs: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

### Bước 3: Test với câu hỏi đơn giản

```bash
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Xin chào, bạn là ai?"}'
```

---

## 3. Index Dữ Liệu

### 3.1. Index Text Đơn Giản

```bash
curl -X POST "http://localhost:8000/index" \
  -F "id=doc1" \
  -F "texts=Đây là text nội dung 1" \
  -F "texts=Đây là text nội dung 2"
```

### 3.2. Index Với Images

```bash
curl -X POST "http://localhost:8000/index" \
  -F "id=event123" \
  -F "texts=Sự kiện âm nhạc tại Hà Nội" \
  -F "images=@poster1.jpg" \
  -F "images=@poster2.jpg"
```

**Lưu ý**: Tối đa 10 texts và 10 images mỗi request.

### 3.3. Upload PDF

Để upload tài liệu PDF vào hệ thống:

```bash
curl -X POST "http://localhost:8000/upload-pdf" \
  -F "file=@user_guide.pdf" \
  -F "title=Hướng dẫn sử dụng" \
  -F "category=user_guide"
```

Sau khi upload, chatbot có thể trả lời câu hỏi về nội dung trong PDF.

---

## 4. Tìm Kiếm Dữ Liệu

### 4.1. Search Bằng Text

```bash
curl -X POST "http://localhost:8000/search/text" \
  -F "text=sự kiện âm nhạc" \
  -F "limit=5"
```

### 4.2. Search Bằng Image

```bash
curl -X POST "http://localhost:8000/search/image" \
  -F "image=@query_image.jpg" \
  -F "limit=5"
```

### 4.3. Hybrid Search (Text + Image)

```bash
curl -X POST "http://localhost:8000/search" \
  -F "text=festival music" \
  -F "image=@query.jpg" \
  -F "text_weight=0.6" \
  -F "image_weight=0.4"
```

---

## 5. Chat Với Chatbot

### 5.1. Chat Cơ Bản (Không RAG)

```python
import requests

response = requests.post('http://localhost:8000/chat', json={
    'message': 'Xin chào!',
    'use_rag': False,
    'hf_token': 'your_huggingface_token'
})

print(response.json()['response'])
```

### 5.2. Chat Với RAG (Recommended)

```python
response = requests.post('http://localhost:8000/chat', json={
    'message': 'Festival âm nhạc diễn ra khi nào?',
    'use_rag': True,
    'use_advanced_rag': True,
    'top_k': 5,
    'hf_token': 'your_token'
})

result = response.json()
print("Answer:", result['response'])
print("Sources:", result['context_used'])
```

### 5.3. Advanced RAG Options

```python
response = requests.post('http://localhost:8000/chat', json={
    'message': 'Câu hỏi của bạn',
    'use_rag': True,
    'use_advanced_rag': True,

    # Advanced RAG settings
    'use_query_expansion': True,    # Mở rộng câu hỏi
    'use_reranking': True,          # Rerank kết quả
    'use_compression': True,        # Nén context
    'score_threshold': 0.5,         # Ngưỡng relevance (0-1)
    'top_k': 5,                     # Số documents retrieve

    # LLM settings
    'max_tokens': 512,
    'temperature': 0.7,
    'hf_token': 'your_token'
})
```

---

## 6. Quản Lý Documents

### 6.1. Xem Danh Sách Documents

```bash
# Xem stats collection
curl http://localhost:8000/stats

# Xem PDFs
curl http://localhost:8000/documents/pdf
```

### 6.2. Get Document By ID

```bash
curl http://localhost:8000/document/doc123
```

### 6.3. Xóa Document

```bash
curl -X DELETE http://localhost:8000/delete/doc123
```

### 6.4. Xóa PDF Document

```bash
curl -X DELETE http://localhost:8000/documents/pdf/pdf_20251029_143022
```

---

## 7. Câu Hỏi Thường Gặp (FAQ)

### Q1: Làm sao để upload PDF vào hệ thống?

**A:** Sử dụng endpoint `/upload-pdf`:

```bash
curl -X POST "http://localhost:8000/upload-pdf" \
  -F "file=@your_file.pdf" \
  -F "title=Tên tài liệu"
```

### Q2: Chatbot không tìm thấy thông tin phù hợp?

**A:** Thử các cách sau:
1. Giảm `score_threshold` xuống (0.3 - 0.5)
2. Tăng `top_k` lên (5-10)
3. Sử dụng `use_advanced_rag=True`
4. Rephrase câu hỏi rõ ràng hơn

### Q3: Làm sao để cải thiện độ chính xác của chatbot?

**A:**
- Bật Advanced RAG: `use_advanced_rag=True`
- Bật tất cả RAG features: `use_reranking=True`, `use_compression=True`
- Index nhiều documents với nội dung chi tiết
- Sử dụng metadata phù hợp khi index

### Q4: Token limit của LLM là bao nhiêu?

**A:** Mặc định `max_tokens=512`. Bạn có thể tăng lên trong request:

```python
{
    'message': 'Your question',
    'max_tokens': 1024,  # Tăng lên
    'hf_token': 'your_token'
}
```

### Q5: Có thể upload bao nhiêu texts/images cùng lúc?

**A:** Tối đa **10 texts** và **10 images** mỗi request tại endpoint `/index`.

### Q6: Chatbot có support tiếng Việt không?

**A:** Có! Hệ thống sử dụng Jina CLIP v2 hỗ trợ đa ngôn ngữ, bao gồm tiếng Việt.

### Q7: Làm sao để xem lịch sử chat?

**A:**
```bash
curl "http://localhost:8000/history?limit=10&skip=0"
```

### Q8: PDF của tôi có nhiều hình ảnh, có vấn đề gì không?

**A:** Hệ thống hiện chỉ extract text từ PDF. Hình ảnh trong PDF chưa được xử lý. Nếu cần xử lý hình ảnh trong PDF, có thể integrate RAG-Anything sau.

---

## 8. API Reference

### Endpoints Chính

| Endpoint | Method | Mô tả |
|----------|--------|-------|
| `/` | GET | Health check & API docs |
| `/index` | POST | Index texts + images (tối đa 10 mỗi loại) |
| `/search` | POST | Hybrid search (text + image) |
| `/search/text` | POST | Search chỉ bằng text |
| `/search/image` | POST | Search chỉ bằng image |
| `/chat` | POST | Chat với RAG |
| `/documents` | POST | Add text document |
| `/upload-pdf` | POST | Upload và index PDF |
| `/documents/pdf` | GET | List PDFs |
| `/documents/pdf/{id}` | DELETE | Delete PDF |
| `/history` | GET | Get chat history |
| `/stats` | GET | Collection statistics |

### Request Examples

**Index with multiple texts:**
```json
POST /index
{
  "id": "doc123",
  "texts": ["Text 1", "Text 2", "Text 3"]
}
```

**Chat with Advanced RAG:**
```json
POST /chat
{
  "message": "Your question",
  "use_rag": true,
  "use_advanced_rag": true,
  "use_reranking": true,
  "top_k": 5,
  "score_threshold": 0.5,
  "hf_token": "hf_xxxxx"
}
```

---

## 9. Best Practices

### Index Dữ Liệu
✓ Chia nhỏ nội dung thành các chunks có nghĩa
✓ Thêm metadata đầy đủ (title, category, source)
✓ Sử dụng texts array cho multiple paragraphs
✗ Tránh index text quá dài trong 1 chunk

### Chat
✓ Bật Advanced RAG cho câu hỏi phức tạp
✓ Điều chỉnh `top_k` và `score_threshold` phù hợp
✓ Sử dụng `temperature` thấp (0.3-0.5) cho câu trả lời factual
✗ Tránh đặt `score_threshold` quá cao (>0.8)

### PDF
✓ PDF có text layer (không phải scanned image)
✓ Cấu trúc rõ ràng với headings, paragraphs
✓ Nội dung ngắn gọn, dễ hiểu
✗ Tránh PDF quá nhiều hình ảnh phức tạp

---

## 10. Troubleshooting

### Server không khởi động
- Kiểm tra dependencies: `pip install -r requirements.txt`
- Kiểm tra MongoDB connection string
- Kiểm tra Qdrant service

### Upload PDF lỗi
- Verify file là PDF hợp lệ
- Check file không bị corrupt
- Thử convert lại PDF nếu cần

### Chatbot không trả lời đúng
- Kiểm tra documents đã được index chưa: `/stats`
- Thử giảm `score_threshold`
- Bật Advanced RAG options
- Check LLM token (Hugging Face)

### Out of memory
- Giảm `chunk_size` trong PDF parser
- Giảm `top_k` trong chat request
- Index ít documents hơn mỗi lần

---

## 11. Liên Hệ & Support

Nếu có thắc mắc hoặc vấn đề:
- Check server logs
- Review API documentation tại `/docs`
- Xem GitHub issues

---

**Happy Chatting! 🤖**