README.md

metadata

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

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

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

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:

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

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

   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:

   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:

   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: /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!