|
Download README.md from StillWorking/sentinel-face-recognition: direct link, hf CLI and curl.
- Browser
- Download file 6.95 kB
-
https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/README.md
- Command line
-
hf download hf://StillWorking/sentinel-face-recognition/README.md
-
curl -L -o README.md https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/README.md
6.95 kB
| language: | |
| - en | |
| license: mit | |
| tags: | |
| - face-recognition | |
| - computer-vision | |
| - celeba | |
| - faiss | |
| - semantic-search | |
| - gemini-ai | |
| datasets: | |
| - celeba | |
| # Sentinel Face Recognition - Complete AI Infrastructure | |
| A comprehensive computer vision system for celebrity face recognition with semantic search capabilities, built with Python, FastAPI, and Gemini AI. | |
| ## π― Overview | |
| Sentinel is an end-to-end face recognition pipeline featuring: | |
| - **Real-time face detection** using MTCNN | |
| - **High-accuracy face embedding** using AdaFace | |
| - **Semantic search** through 200K+ celebrity faces using FAISS | |
| - **AI-powered analysis** with Gemini integration | |
| - **Production-ready REST API** built with FastAPI | |
| - **Interactive web UI** built with React + TypeScript | |
| ## π¦ What's Included | |
| ### Backend (Python) | |
| ``` | |
| β Face detection & recognition | |
| β FAISS vector search | |
| β Gemini AI integration | |
| β REST API with Swagger docs | |
| β Rate limiting & security | |
| β Comprehensive test suite | |
| ``` | |
| ### Frontend (React) | |
| ``` | |
| β Interactive web interface | |
| β Real-time face analysis | |
| β Search & discovery | |
| β Responsive design | |
| β Error handling | |
| ``` | |
| ### Dataset & Models | |
| ``` | |
| β CelebA dataset (200K+ images, 1.35 GB) | |
| β AdaFace IR50 pre-trained weights | |
| β MTCNN face detection models | |
| β Pre-built FAISS index | |
| β Metadata & attributes CSV | |
| ``` | |
| ## π Quick Start | |
| ### Installation | |
| ```bash | |
| # Clone repository | |
| git clone https://huggingface.co/StillWorking/sentinel-face-recognition | |
| cd sentinel-face-recognition | |
| # Install Git LFS and pull large files | |
| git lfs install | |
| git lfs pull | |
| # Setup backend | |
| cd backend | |
| python -m venv venv | |
| source venv/bin/activate # On Windows: venv\Scripts\activate | |
| pip install -r ../requirements.txt | |
| # Configure API key | |
| cp .env.example .env | |
| # Edit .env and add your Gemini API key from https://aistudio.google.com/app/apikey | |
| # Run backend | |
| python main.py | |
| # API available at http://localhost:8000 | |
| # Docs at http://localhost:8000/docs | |
| ``` | |
| ### In another terminal - Frontend | |
| ```bash | |
| cd frontend | |
| npm install | |
| npm run dev | |
| # Frontend at http://localhost:5173 | |
| ``` | |
| ## π API Endpoints | |
| | Endpoint | Method | Description | | |
| |----------|--------|-------------| | |
| | `/health` | GET | Health check | | |
| | `/api/v1/analyze-frame` | POST | Detect & identify faces in image | | |
| | `/api/v1/search` | POST | Semantic search for similar faces | | |
| | `/api/v1/generate-person` | POST | Generate faces using AI | | |
| | `/api/v1/index-status` | GET | Check index information | | |
| **Example Usage:** | |
| ```python | |
| import requests | |
| # Analyze a face | |
| with open('photo.jpg', 'rb') as f: | |
| response = requests.post( | |
| 'http://localhost:8000/api/v1/analyze-frame', | |
| files={'file': f} | |
| ) | |
| print(response.json()) | |
| ``` | |
| ## ποΈ Project Structure | |
| ``` | |
| sentinel-face-recognition/ | |
| βββ backend/ | |
| β βββ api/ # FastAPI routes | |
| β βββ core/ # ML logic | |
| β βββ models_cache/ # Pre-trained models | |
| β β βββ adaface/ # AdaFace model files | |
| β β βββ embeddings.pkl # Pre-computed embeddings | |
| β βββ index_artifacts/ # FAISS index & metadata | |
| β βββ tests/ # Test suite | |
| β βββ main.py # FastAPI app | |
| βββ frontend/ # React application | |
| βββ Data/ # CelebA dataset (Git LFS) | |
| β βββ img_align_celeba/ # 200K+ face images | |
| β βββ list_attr_celeba.csv # Attributes | |
| βββ deploy/ # Nginx config | |
| ``` | |
| ## βοΈ Configuration | |
| Create `.env` file: | |
| ```env | |
| # Gemini API (required) | |
| GEMINI_API_KEY=your_key_here | |
| GEMINI_MODEL=gemini-2.5-flash | |
| # Hardware | |
| TORCH_DEVICE=cuda # or 'cpu' | |
| # Face detection | |
| MTCNN_MIN_FACE_SIZE=20 | |
| DETECTION_CONFIDENCE=0.6 | |
| MATCH_SIMILARITY_THRESHOLD=0.50 | |
| # API Security | |
| SENTINEL_API_KEY= # Leave empty for open access | |
| RATE_LIMIT_PER_MINUTE=60 | |
| # CORS | |
| CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173 | |
| ``` | |
| ## π Dataset Details | |
| **CelebA Dataset:** | |
| - **Size:** 1.35 GB (compressed) | |
| - **Images:** 202,599 aligned face images | |
| - **Attributes:** 40 binary attribute annotations | |
| - **Resolution:** 178 Γ 218 pixels | |
| - **Format:** JPEG | |
| - **Ready to use:** Yes, pre-processed | |
| ## π€ Model Information | |
| ### AdaFace (IR50) | |
| - State-of-the-art face recognition | |
| - 512-dimensional embeddings | |
| - Trained on MS1MV2 dataset | |
| - High accuracy on wild faces | |
| - Fast inference | |
| ### MTCNN | |
| - Multi-task Cascaded Convolutional Networks | |
| - Reliable multi-scale face detection | |
| - Handles rotations and occlusions | |
| - Pre-trained weights included | |
| ## π§ͺ Testing | |
| ```bash | |
| cd backend | |
| pytest tests/ -v | |
| ``` | |
| ## π Performance | |
| - **Face Detection:** ~50-100ms per image | |
| - **Face Embedding:** ~20-40ms per face | |
| - **Vector Search:** <5ms for 200K faces | |
| - **GPU Memory:** ~4GB (VRAM) | |
| - **CPU Fallback:** Supported (slower) | |
| ## π Security | |
| - API key authentication support | |
| - Rate limiting per client | |
| - CORS protection | |
| - Secure credential handling | |
| - Input validation on all endpoints | |
| - See `SECURITY.md` for details | |
| ## π Documentation | |
| - **API Docs:** http://localhost:8000/docs | |
| - **Security Guide:** See `SECURITY.md` | |
| - **Design Document:** See `design.md` | |
| - **Audit Report:** See `SENTINEL_AUDIT_FINDINGS.md` | |
| ## π οΈ Building Index | |
| To rebuild the FAISS index: | |
| ```bash | |
| cd backend | |
| python build_index.py | |
| ``` | |
| ## β οΈ Known Limitations | |
| - GPU recommended for real-time performance | |
| - CelebA contains western-centric celebrity data | |
| - Model trained on aligned faces (preprocessing needed for wild faces) | |
| - Rate limited for public API access | |
| ## π Deployment | |
| For production deployment, see `deploy/nginx.conf.example` for reverse proxy setup. | |
| ## π€ Contributing | |
| 1. Clone the repository | |
| 2. Create a feature branch | |
| 3. Make your changes | |
| 4. Run tests: `pytest tests/ -v` | |
| 5. Commit and push | |
| 6. Submit pull request | |
| ## π License | |
| MIT License - See LICENSE file for details | |
| ## π Citation | |
| If you use this project, please cite: | |
| ```bibtex | |
| @software{sentinel2026, | |
| title={Sentinel Face Recognition}, | |
| author={StillWorking}, | |
| year={2026}, | |
| url={https://huggingface.co/StillWorking/sentinel-face-recognition} | |
| } | |
| ``` | |
| ## π Acknowledgments | |
| - **CelebA Dataset:** Liu et al., 2015 | |
| - **AdaFace:** Hu et al., ICCV 2023 | |
| - **MTCNN:** Zhang et al., 2016 | |
| - **FAISS:** Meta AI Research | |
| - **FastAPI:** SebastiΓ‘n RamΓrez | |
| - **React:** Facebook | |
| ## π Support & Issues | |
| - π Check documentation files first | |
| - π Review test suite for usage examples | |
| - π¬ Comment on repository issues | |
| - π Visit: https://huggingface.co/StillWorking/sentinel-face-recognition | |
| --- | |
| **Status:** β Production Ready | |
| **Last Updated:** November 10, 2026 | |
| **Python Version:** 3.9+ | |
| **License:** MIT | |
| --- | |
| ### Quick Download | |
| ```bash | |
| git clone https://huggingface.co/StillWorking/sentinel-face-recognition | |
| cd sentinel-face-recognition | |
| git lfs pull | |
| ``` | |
| Start exploring! π | |