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:

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:

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:

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

# 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

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

Response:

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

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

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

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:

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

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:

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

# 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ả!