Spaces:
Runtime error
Runtime error
| 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! | |