---
title: EGoV Chatbot
emoji: 💻
colorFrom: red
colorTo: blue
sdk: docker
pinned: false
license: mit
---

# EGoV Chatbot 💻

EGoV Chatbot là một ứng dụng **chatbot tra cứu thủ tục hành chính** sử dụng dữ liệu từ Hugging Face Hub và cơ chế **hybrid search** (semantic + keyword).  
Dự án này được triển khai dưới dạng **Hugging Face Space** với backend **Flask** và **Docker SDK**.

---

## 🚀 Tính năng chính
- **Tra cứu thủ tục hành chính** với dữ liệu có sẵn.
- **Hybrid Search**: kết hợp tìm kiếm từ khóa (BM25) và tìm kiếm vector (Sentence Transformers).
- **REST API Endpoint**: `/chat` để nhận câu hỏi và trả về câu trả lời.
- **Tích hợp Hugging Face Hub**: tải dữ liệu và model trực tiếp từ HF Hub bằng token.

---

## 📂 Cấu trúc dự án
```
├── app.py               # Flask backend chính
├── requirements.txt     # Danh sách thư viện cần cài đặt
├── Dockerfile           # Docker build cho Space
├── id_to_record.pkl     # File mapping id -> dữ liệu thủ tục
├── toan_bo_du_lieu_final.json            # Dữ liệu gốc (tùy chọn)
└── README.md            # File này
```

---

## 🔑 Biến môi trường yêu cầu
Trước khi chạy, cần cung cấp biến môi trường:
- `HF_TOKEN`: Token Hugging Face của bạn (để tải dữ liệu/model từ Hub).

Trong Hugging Face Space, đặt token trong mục **"Settings > Secrets"**.

---

## 🐳 Chạy bằng Docker (cục bộ)
```bash
docker build -t egov-chatbot .
docker run -p 7860:7860 -e HF_TOKEN=your_hf_token egov-chatbot
```
Sau đó truy cập:
[http://localhost:7860/chat?query=Thủ tục làm CCCD](http://localhost:7860/chat?query=Thủ%20tục%20làm%20CCCD)

---

## 📡 API Endpoint
- **`POST /chat`**
  - **Body**: `{ "query": "Câu hỏi của bạn" }`
  - **Response**: `{ "answer": "Câu trả lời từ chatbot" }`

Ví dụ:
```bash
curl -X POST http://localhost:7860/chat \
    -H "Content-Type: application/json" \
    -d '{"query": "Thủ tục cấp giấy khai sinh"}'
```

---

## 📝 Giấy phép
Dự án sử dụng giấy phép **MIT** – tự do sử dụng và tùy biến.

---

## 📖 Tham khảo
- [Hugging Face Hub](https://huggingface.co/)
- [Sentence Transformers](https://www.sbert.net/)
- [BM25 Ranker](https://github.com/castorini/pyserini)