{"id":23444850,"url":"https://github.com/tutortoise/face-validation-service","last_synced_at":"2025-06-13T09:09:23.243Z","repository":{"id":264376711,"uuid":"886276398","full_name":"Tutortoise/face-validation-service","owner":"Tutortoise","description":"Profile Picture Moderation for Tutortoise","archived":false,"fork":false,"pushed_at":"2024-12-11T02:14:24.000Z","size":56800,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-30T09:58:00.471Z","etag":null,"topics":["onnx","yolov11-face"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tutortoise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-10T16:44:59.000Z","updated_at":"2025-05-28T23:37:51.000Z","dependencies_parsed_at":"2025-04-09T23:38:52.712Z","dependency_job_id":null,"html_url":"https://github.com/Tutortoise/face-validation-service","commit_stats":null,"previous_names":["tutortoise/face-validation-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Tutortoise/face-validation-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tutortoise%2Fface-validation-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tutortoise%2Fface-validation-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tutortoise%2Fface-validation-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tutortoise%2Fface-validation-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tutortoise","download_url":"https://codeload.github.com/Tutortoise/face-validation-service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tutortoise%2Fface-validation-service/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259616383,"owners_count":22884884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["onnx","yolov11-face"],"created_at":"2024-12-23T19:19:22.792Z","updated_at":"2025-06-13T09:09:23.215Z","avatar_url":"https://github.com/Tutortoise.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face Validation Service\n\n![](./service_architecture.jpg)\n\nA high-performance face detection and validation service built in Go that uses ONNX Runtime for inference. The service can detect and validate single/multiple faces in images with optimized processing using SIMD instructions.\n\n## Features\n\n- Fast face detection using YOLOv11n model (IR version 9)\n- SIMD-optimized image preprocessing (AVX-512, AVX2, SSE4.1)\n- Concurrent processing with efficient memory management\n- Model session pooling for improved performance\n- Support for multiple input formats (JSON, multipart/form-data, raw)\n- Health monitoring and metrics endpoints\n- Docker support with multi-stage builds\n- Graceful shutdown handling\n\n## Tech Stack\n\n- Go 1.22+\n- ONNX Runtime 1.20.0\n- YOLOv11n neural network model\n- SIMD optimizations (AVX-512, AVX2, SSE4.1)\n- Docker\n\n## Architecture\n\n### Core Components\n\n1. **Detection Engine**\n\n   - ONNX model inference\n   - SIMD-optimized image preprocessing\n   - Bounding box processing\n   - Clustering algorithm for multiple detections\n\n2. **Session Management**\n\n   - Thread-safe model session pool\n   - Automatic session health checks\n   - Configurable pool size and timeouts\n\n3. **Image Processing Pipeline**\n   - Image decoding\n   - Resizing\n   - Channel processing\n   - SIMD-accelerated preprocessing\n\n### Performance Optimizations\n\n- SIMD instructions for faster image processing\n- Concurrent channel processing\n- Memory pooling and reuse\n- Efficient bounding box clustering\n- Session pooling to reduce model loading overhead\n\n## API Endpoints\n\n### POST /validate-face\n\nValidates faces in the provided image.\n\n**Supported Input Formats:**\n\n- JSON with base64 encoded image\n- Multipart form-data\n- Raw image data\n\n**Response:**\n\n```json\n{\n    \"is_valid\": boolean,\n    \"face_count\": integer,\n    \"message\": string\n}\n```\n\n### GET /health\n\nHealth check endpoint.\n\n### GET /metrics\n\nReturns pool metrics and performance statistics.\n\n## Configuration\n\nEnvironment Variables:\n\n- `PORT`: Server port (default: 8080)\n- `DEBUG`: Enable debug logging\n- `MODEL_OUTPUT_CHANNELS`: Model output channels\n- `MODEL_OUTPUT_GRID_SIZE`: Model output grid size\n- `GOMAXPROCS`: Go runtime thread limit\n- `GOMEMLIMIT`: Go runtime memory limit\n\n## Installation\n\n### Using Docker\n\n```bash\n# Build the image\ndocker build -t face-validation-service .\n\n# Run the container\ndocker run -p 8080:8080 face-validation-service\n```\n\n### Manual Installation\n\nRequirements:\n\n- Go 1.22+\n- ONNX Runtime 1.20.0\n- C compiler (for CGO)\n\n```bash\n# Clone the repository\ngit clone https://github.com/Tutortoise/face-validation-service\n\n# Build the service\ncd face-validation-service/web\ngo build -o server\n\n# Run the service\n./server\n```\n\n## Performance Considerations\n\n- Uses SIMD instructions when available\n- Implements memory pooling to reduce GC pressure\n- Concurrent processing of image channels\n- Session pooling for better resource utilization\n- Efficient clustering algorithm for multiple face detection\n\n## Monitoring and Metrics\n\nThe service provides monitoring endpoints for:\n\n- Session pool statistics\n- Processing times\n- Resource usage\n- Error rates\n- Health status\n\n## Error Handling\n\nThe service implements comprehensive error handling for:\n\n- Invalid input formats\n- Image decoding failures\n- Model inference errors\n- Resource exhaustion\n- Timeout scenarios\n\n## Development\n\n### Project Structure\n\n```\nface-validation-service/\n├── web/\n│   ├── clustering/      # Clustering algorithms\n│   ├── detections/      # Face detection logic\n│   ├── lib/            # ONNX Runtime libraries\n│   ├── models/         # Data models\n│   ├── onnx_model/     # Neural network model\n│   ├── main.go         # Main application\n│   └── pool.go         # Session pool implementation\n└── Dockerfile\n```\n\n### Building for Development\n\n```bash\n# Run tests\ngo test ./...\n\n# Build with debug info\ngo build -gcflags=\"all=-N -l\" -o server\n\n# Run with debug logging\nDEBUG=true ./server\n```\n\n## Model Training\n\nThe face detection model was trained using two datasets to ensure accurate detection of human faces while eliminating false positives:\n\n1. **Main Face Detection Dataset**\n\n   - Source: [Face Detection Dataset](https://www.kaggle.com/datasets/fareselmenshawii/face-detection-dataset/data) from Kaggle\n   - Purpose: Primary training data for human face detection\n   - Features:\n     - High-quality human face images\n     - Various poses and lighting conditions\n     - Different age groups and ethnicities\n\n2. **Anime Face Dataset (Negative Examples)**\n   - Source: [Annotated Anime Faces Dataset](https://www.kaggle.com/datasets/andy8744/annotated-anime-faces-dataset)\n   - Purpose: Used as negative examples to reduce false positives\n   - Features:\n     - Anime and cartoon-style faces\n     - Helps model discriminate between real human faces and illustrated faces\n     - Improves model's specificity for human face detection\n\n### Training Process\n\n1. **Data Preparation**\n\n   - Combined both datasets with appropriate labeling\n   - Human faces labeled as positive examples\n   - Anime faces labeled as negative examples\n   - Applied data augmentation techniques\n\n2. **Model Architecture**\n\n   - Based on YOLOv11n with IR version 9\n   - Optimized for 256x256 input resolution\n   - Modified to handle binary classification (human face vs. non-human face)\n\n3. **Training Configuration**\n   - Trained on Kaggle's GPU environment\n   - Used transfer learning from pre-trained weights\n   - Implemented custom loss function to balance precision and recall\n   - Employed hard negative mining to improve discrimination capability\n\nThis dual-dataset approach ensures the model:\n\n- Accurately detects human faces\n- Minimizes false positives from animated or illustrated faces\n- Provides robust performance in real-world applications\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftutortoise%2Fface-validation-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftutortoise%2Fface-validation-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftutortoise%2Fface-validation-service/lists"}