README.md

---
title: FaceID AI Service
emoji: 👤
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# 🚀 FaceID AI Model Service (Docker & HuggingFace Spaces)

Dịch vụ AI nhận diện khuôn mặt đóng gói độc lập dưới dạng Docker Container, chạy bằng **Flask + Gunicorn + InsightFace**, sẵn sàng để deploy lên **HuggingFace Spaces** hoặc các nền tảng Container (Docker, AWS ECS, Google Cloud Run).

> [!NOTE]
> Thư mục này được thiết kế tự chứa (Self-contained) hoàn chỉnh, chỉ tập trung vào **AI Model Service**, không ảnh hưởng đến Frontend hay Backend chính của ứng dụng.

---

## 📂 Cấu trúc dịch vụ đóng gói
```text
ai_service_docker/
├── Dockerfile                  # Build image tối ưu, tải sẵn model buffalo_l lúc build
├── docker-compose.yml          # Hỗ trợ chạy & test nhanh dưới local
├── .dockerignore               # Loại bỏ các file rác, virtualenv và local DB
├── .env.example                # File cấu hình mẫu
├── requirements.txt            # Thư viện Python (đã đổi sang opencv-python-headless & thêm gunicorn)
├── app.py                      # File entry point chạy WSGI (đã cấu hình startup tại module level)
├── config.py                   # Cấu hình biến môi trường (default PORT=7860 cho HuggingFace)
├── face_model/                 # InsightFace Model Analyzer & RAM Cache
├── storage/                    # Storage Layer kết nối MongoDB & Supabase
├── api/                        # RESTful API Endpoints (18 routes)
└── utils/                      # Helper xử lý ảnh
```

---

## 🛠️ Hướng dẫn Chạy & Test Local

### 1. Chuẩn bị file `.env`
Sao chép `.env.example` thành `.env` bên trong thư mục `ai_service_docker/` và điền đầy đủ các cấu hình thực tế của bạn (MongoDB URI, Supabase URI):
```bash
cp .env.example .env
```

### 2. Khởi chạy bằng Docker Compose (Khuyến nghị)
Docker Compose được cấu hình ánh xạ port `8000` của máy bạn vào port `7860` của container để bạn có thể test bình thường như chạy không có Docker:
```bash
# Từ thư mục gốc dự án hoặc thư mục ai_service_docker/
docker compose up --build -d
```
*   **API URL (Local):** `http://localhost:8000/api/health`
*   **Xem logs container:** `docker compose logs -f`
*   **Dừng container:** `docker compose down`

### 3. Khởi chạy bằng Docker CLI (Thủ công)
Nếu không dùng Compose:
```bash
# Build image
docker build -t faceid-ai-service .

# Run container (truyền file .env)
docker run -p 8000:7860 --env-file .env --name faceid-ai-service-run faceid-ai-service
```

---

## ☁️ Hướng dẫn Deploy lên HuggingFace Spaces

HuggingFace Spaces hỗ trợ chạy Dockerfile trực tiếp một cách miễn phí. Dưới đây là 2 cách để deploy:

### Cách 1: Git Push trực tiếp vào Space (Dễ và Khuyến nghị)

1. Truy cập [HuggingFace Spaces](https://huggingface.co/spaces) và nhấn **Create new Space**.
2. Thiết lập thông số:
   * **Space name**: Tùy chọn (ví dụ: `faceid-ai-service`)
   * **License**: open-source (tùy chọn)
   * **SDK**: Chọn **Docker** (Thay vì Streamlit/Gradio)
   * **Docker template**: Chọn **Blank**
   * **Space hardware**: Chọn **CPU basic** (Miễn phí) hoặc nâng cấp GPU nếu muốn.
3. Clone Space repository vừa tạo về máy cục bộ của bạn:
   ```bash
   git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
   ```
4. Copy toàn bộ các file bên trong thư mục `ai_service_docker/` (bao gồm `Dockerfile`, `app.py`, `face_model/`, v.v.) dán vào thư mục Space vừa clone.
5. Commit và Push lên HuggingFace:
   ```bash
   git add .
   git commit -m "Deploy FaceID AI Service via Docker"
   git push origin main
   ```
6. HuggingFace sẽ tự động nhận diện phần **YAML metadata** ở đầu file `README.md` này, tiến hành build Dockerfile (tải trước model `buffalo_l` mất khoảng 2-3 phút) và kích hoạt dịch vụ chạy trên port `7860`.

---

### Cách 2: Deploy từ Docker Hub / Private Registry

Nếu bạn muốn build image trên máy mình hoặc qua GitHub Actions rồi đẩy lên Registry trước:

1. Đăng nhập Docker Hub và Build / Push image:
   ```bash
   docker build -t <your-dockerhub-username>/faceid-ai-service:latest .
   docker push <your-dockerhub-username>/faceid-ai-service:latest
   ```
2. Trên Space của HuggingFace, thay vì chọn Blank Docker, bạn có thể chỉnh sửa `README.md` của Space trên giao diện web để thêm thuộc tính `app_port` và `docker` kéo trực tiếp từ registry:
   ```yaml
   ---
   title: FaceID AI Service
   sdk: docker
   docker_image: <your-dockerhub-username>/faceid-ai-service:latest
   app_port: 7860
   ---
   ```

---

## 🔑 Cấu hình Biến môi trường (Secrets) trên HuggingFace

Để bảo mật thông tin kết nối Cơ sở dữ liệu (MongoDB, Supabase), **TUYỆT ĐỐI KHÔNG** push file `.env` lên HuggingFace. Thay vào đó, hãy dùng **Variables and Secrets**:

1. Vào Space của bạn trên HuggingFace -> Chọn tab **Settings**.
2. Kéo xuống mục **Variables and Secrets** -> Click **New secret**.
3. Thêm các key quan trọng sau:
   * `MONGO_URI`: Đường dẫn kết nối MongoDB Atlas của bạn.
   * `SUPABASE_DB_URI`: Đường dẫn kết nối Supabase PostgreSQL của bạn.
4. (Tùy chọn) Thêm **Variables** nếu muốn ghi đè cấu hình mặc định:
   * `SIMILARITY_THRESHOLD`: Ví dụ `0.45`
   * `CORS_ORIGINS`: Ví dụ `*` hoặc domain frontend của bạn.

Sau khi cập nhật Secrets, Space sẽ tự động rebuild/restart để nhận cấu hình mới. Dịch vụ AI của bạn sẽ hoạt động hoàn toàn bảo mật và tự động!