PDF_RAG_GUIDE.md

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

## Tổng Quan

Hệ thống ChatbotRAG hiện đã hỗ trợ **tải lên và index PDF** để chatbot có thể trả lời câu hỏi dựa trên nội dung trong PDF. Điều này rất hữu ích cho:
- Hướng dẫn sử dụng sản phẩm
- Tài liệu FAQ
- Chính sách, quy định
- Tài liệu kỹ thuật

## Cách Thức Hoạt Động

1. **Upload PDF** → Hệ thống parse PDF thành text
2. **Chunking** → Text được chia thành các chunks (mặc định: 500 words/chunk, overlap 50 words)
3. **Embedding** → Mỗi chunk được convert thành vector embedding
4. **Indexing** → Lưu vào Qdrant + MongoDB
5. **Chat** → Chatbot tìm kiếm chunks liên quan và trả lời câu hỏi

## Cách 1: Upload PDF Qua API

### Endpoint: `POST /upload-pdf`

**Request:**
```bash
curl -X POST "http://localhost:8000/upload-pdf" \
  -F "file=@huong_dan_su_dung.pdf" \
  -F "title=Hướng dẫn sử dụng ChatbotRAG" \
  -F "description=Tài liệu hướng dẫn đầy đủ về ChatbotRAG" \
  -F "category=user_guide"
```

**Python:**
```python
import requests

with open('huong_dan_su_dung.pdf', 'rb') as f:
    files = {'file': f}
    data = {
        'title': 'Hướng dẫn sử dụng ChatbotRAG',
        'description': 'Tài liệu hướng dẫn đầy đủ',
        'category': 'user_guide'
    }

    response = requests.post(
        'http://localhost:8000/upload-pdf',
        files=files,
        data=data
    )

    print(response.json())
```

**Response:**
```json
{
  "success": true,
  "document_id": "pdf_20251029_143022",
  "filename": "huong_dan_su_dung.pdf",
  "chunks_indexed": 45,
  "message": "PDF 'huong_dan_su_dung.pdf' đã được index thành công với 45 chunks"
}
```

### Tham Số:
- `file` (required): File PDF
- `document_id` (optional): ID tùy chỉnh, mặc định auto-generate
- `title` (optional): Tiêu đề tài liệu
- `description` (optional): Mô tả
- `category` (optional): Danh mục (user_guide, faq, policy, etc.)

## Cách 2: Batch Index Nhiều PDFs

Nếu bạn có nhiều PDF files, sử dụng script batch:

```bash
# Index tất cả PDFs trong thư mục
python batch_index_pdfs.py ./docs/user_guides

# Với category tùy chỉnh
python batch_index_pdfs.py ./docs/policies --category=policy

# Force reindex (ghi đè nếu đã có)
python batch_index_pdfs.py ./docs/faq --category=faq --force
```

Script sẽ tự động:
- Scan tất cả file .pdf trong thư mục
- Index từng file với metadata phù hợp
- Skip những file đã index (trừ khi dùng --force)
- Hiển thị progress và summary

## Quản Lý PDF Documents

### Xem Danh Sách PDFs

```bash
curl http://localhost:8000/documents/pdf
```

**Response:**
```json
{
  "documents": [
    {
      "document_id": "pdf_user_guide",
      "type": "pdf",
      "filename": "huong_dan_su_dung.pdf",
      "num_chunks": 45,
      "metadata": {
        "title": "Hướng dẫn sử dụng",
        "category": "user_guide"
      }
    }
  ],
  "total": 1
}
```

### Xóa PDF Document

```bash
# Xóa document và tất cả chunks của nó
curl -X DELETE http://localhost:8000/documents/pdf/pdf_user_guide
```

## Chat Với PDF Content

Sau khi index PDF, bạn có thể chat như bình thường:

```python
import requests

response = requests.post('http://localhost:8000/chat', json={
    'message': 'Làm sao để upload PDF vào ChatbotRAG?',
    'use_rag': True,
    'use_advanced_rag': True,
    'top_k': 5,
    'hf_token': 'your_hf_token'
})

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

# Xem sources
for ctx in result['context_used']:
    print(f"- Page {ctx['metadata']['page']}: {ctx['metadata']['text'][:100]}...")
```

Chatbot sẽ tự động tìm kiếm trong PDF và trả lời dựa trên nội dung đã index.

## Tạo PDF Hướng Dẫn Sử Dụng

### Template Nội Dung

Dưới đây là cấu trúc đề xuất cho PDF hướng dẫn ChatbotRAG:

```
HƯỚNG DẪN SỬ DỤNG CHATBOTRAG

1. GIỚI THIỆU
   - ChatbotRAG là gì?
   - Tính năng chính
   - Use cases

2. BẮT ĐẦU NHANH
   2.1. Cài đặt
   2.2. Khởi động server
   2.3. Truy cập API

3. INDEX DỮ LIỆU
   3.1. Index text đơn giản
   3.2. Index với images
   3.3. Index nhiều texts và images cùng lúc
   3.4. Upload PDF

4. TÌM KIẾM
   4.1. Search bằng text
   4.2. Search bằng image
   4.3. Hybrid search

5. CHAT VỚI CHATBOT
   5.1. Chat cơ bản
   5.2. Chat với RAG
   5.3. Advanced RAG options
   5.4. Tùy chỉnh LLM parameters

6. QUẢN LÝ DOCUMENTS
   6.1. Xem danh sách documents
   6.2. Xóa documents
   6.3. Quản lý PDF files

7. CÂU HỎI THƯỜNG GẶP (FAQ)
   - Làm sao để upload PDF?
   - Chatbot không tìm thấy thông tin?
   - Làm sao để cải thiện độ chính xác?
   - Token limit là bao nhiêu?

8. API REFERENCE
   - POST /index
   - POST /search
   - POST /chat
   - POST /upload-pdf
   - GET /documents/pdf
```

### Tạo PDF Từ Markdown

Bạn có thể tạo PDF từ Markdown bằng nhiều tools:

**1. Pandoc (Recommended):**
```bash
pandoc guide.md -o guide.pdf --pdf-engine=xelatex
```

**2. Online Tools:**
- https://www.markdowntopdf.com/
- https://md2pdf.netlify.app/

**3. VS Code Extension:**
- Install "Markdown PDF" extension
- Right-click file .md → "Markdown PDF: Export (pdf)"

### Ví Dụ Markdown Content

Tạo file `chatbot_guide.md`:

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

## 1. Upload PDF

Để upload PDF vào hệ thống:

### Bước 1: Chuẩn bị file PDF
- File phải có định dạng .pdf
- Nội dung nên rõ ràng, có cấu trúc

### Bước 2: Upload qua API

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

### Bước 3: Kiểm tra
Sau khi upload, hệ thống sẽ trả về số chunks đã được index.

## 2. Chat Với Chatbot

Sau khi upload PDF, bạn có thể hỏi chatbot:

**Ví dụ:**
- "Làm sao để upload PDF?"
- "Các bước tạo event là gì?"
- "Tính năng nào trong hệ thống?"

Chatbot sẽ tìm kiếm trong PDF và trả lời dựa trên nội dung đã index.

## 3. FAQ

### Câu hỏi 1: Upload PDF tối đa bao nhiêu trang?
Không giới hạn, nhưng PDF càng lớn thì thời gian index càng lâu.

### Câu hỏi 2: Có thể upload nhiều PDFs không?
Có, bạn có thể upload nhiều PDFs. Mỗi PDF sẽ có document_id riêng.

### Câu hỏi 3: Làm sao để xóa PDF đã upload?
Sử dụng endpoint DELETE /documents/pdf/{document_id}
```

Sau đó convert sang PDF:
```bash
pandoc chatbot_guide.md -o chatbot_guide.pdf
```

## Best Practices

### 1. Cấu Trúc PDF
- ✓ Có tiêu đề rõ ràng
- ✓ Chia sections/chapters
- ✓ Sử dụng bullet points
- ✓ Tránh quá nhiều hình ảnh phức tạp (text extraction khó)

### 2. Nội Dung
- ✓ Viết câu ngắn gọn, dễ hiểu
- ✓ Mỗi section tập trung 1 chủ đề
- ✓ Có ví dụ cụ thể
- ✗ Tránh văn xuôi dài, khó tách câu

### 3. Metadata
- Luôn đặt `title` rõ ràng
- Sử dụng `category` để phân loại
- Thêm `description` cho dễ quản lý

### 4. Chunking
Mặc định:
- Chunk size: 500 words
- Overlap: 50 words

Có thể tùy chỉnh trong `pdf_parser.py`:
```python
parser = PDFParser(
    chunk_size=500,      # Tăng nếu muốn context dài hơn
    chunk_overlap=50,    # Tăng để giữ context tốt hơn
    min_chunk_size=50    # Min words cho 1 chunk
)
```

## Troubleshooting

### Lỗi: "Error reading PDF"
- Kiểm tra file PDF có bị corrupt không
- Thử mở bằng PDF reader để verify
- Convert lại PDF nếu cần

### Lỗi: "No text extracted"
- PDF có thể là scanned images (không có text layer)
- Cần OCR trước khi index (dùng tools như Tesseract)

### Chatbot không tìm thấy thông tin
- Kiểm tra `score_threshold` - thử giảm xuống (e.g., 0.3)
- Tăng `top_k` để retrieve nhiều documents hơn
- Rephrase câu hỏi

### Chunks quá ngắn/dài
- Điều chỉnh `chunk_size` trong `pdf_parser.py`
- Reindex PDF với settings mới

## Complete Example

```python
# 1. Upload PDF
import requests

with open('user_guide.pdf', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/upload-pdf',
        files={'file': f},
        data={
            'title': 'Hướng dẫn sử dụng',
            'category': 'user_guide'
        }
    )

doc_id = response.json()['document_id']
print(f"Uploaded: {doc_id}")

# 2. List PDFs
response = requests.get('http://localhost:8000/documents/pdf')
print(response.json())

# 3. Chat
response = requests.post('http://localhost:8000/chat', json={
    'message': 'Làm sao để tạo event mới?',
    'use_rag': True,
    'use_advanced_rag': True,
    'hf_token': 'your_token'
})

print("Answer:", response.json()['response'])

# 4. Delete PDF (if needed)
response = requests.delete(f'http://localhost:8000/documents/pdf/{doc_id}')
print(response.json())
```

## Next Steps

1. **Tạo PDF hướng dẫn của bạn** với nội dung về hệ thống của bạn
2. **Upload PDF** vào hệ thống
3. **Test chatbot** - hỏi các câu hỏi về nội dung trong PDF
4. **Fine-tune** - điều chỉnh parameters nếu cần
5. **Add more PDFs** - thêm FAQs, policies, etc.

## Support

Nếu có vấn đề, check:
- Server logs để xem errors
- MongoDB để xem documents đã được lưu chưa
- Qdrant collection để verify chunks đã được index

## Conclusion

Hệ thống PDF RAG giúp chatbot của bạn trả lời câu hỏi dựa trên tài liệu có sẵn, không cần train lại model. Bạn chỉ cần:
1. Upload PDF
2. Chat như bình thường
3. Chatbot sẽ tìm kiếm và trả lời dựa trên PDF content

Đơn giản và hiệu quả!