# InsightFace-REST
This repository aims to provide convenient, easy deployable and scalable
REST API for InsightFace face detection and recognition pipeline using
FastAPI for serving and NVIDIA TensorRT for optimized inference.
Code is heavily based on API
[code](https://github.com/deepinsight/insightface/tree/master/python-package)
in official DeepInsight InsightFace
[repository](https://github.com/deepinsight/insightface).
This repository provides source code for building face recognition REST
API and converting models to ONNX and TensorRT using Docker.
![Draw detections example](misc/images/draw_detections.jpg)
## Key features:
- Ready for deployment on NVIDIA GPU enabled systems using Docker and
nvidia-docker2.
- Automatic model download at startup (using Google Drive).
- Up to 3x performance boost over MXNet inference with help of TensorRT
optimizations, FP16 inference and batch inference of detected faces
with ArcFace model.
- Support for older Retinaface detectors and MXNet based ArcFace models,
as well as newer `SCRFD` detectors and PyTorch based recognition models (`glintr100`,`w600k_r50`, `w600k_mbf`).
- Up to 2x faster `SCRFD` postprocessing implementation.
- Batch inference supported both for recognition and detection models
(currently `SCRFD` family only)
- Inference on CPU with ONNX-Runtime.
## Contents
[List of supported models](#list-of-supported-models)
- [Detection](#detection)
- [Recognition](#recognition)
- [Other](#other)
[Prerequesites](#prerequesites)
[Running with Docker](#running-with-docker)
[API usage](#api-usage)
- [/extract](#extract-endpoint)
[Work in progress](#work-in-progress)
[Known issues](#known-issues)
[Changelog](#changelog)
## List of supported models:
### Detection:
| Model | Auto download | Batch inference | Detection (ms) | Inference (ms) | GPU-Util (%) | Source | ONNX File |
|-----------------------|:-------------:|:---------------:|:--------------:|:--------------:|:------------:|:----------------------------|:------------:|
| retinaface_r50_v1 | Yes* | | 12.3 | 8.4 | 26 | [official package][1] | [link][dl1] |
| retinaface_mnet025_v1 | Yes* | | 8.6 | 4.6 | 17 | [official package][1] | [link][dl2] |
| retinaface_mnet025_v2 | Yes* | | 8.8 | 4.9 | 17 | [official package][1] | [link][dl3] |
| mnet_cov2 | Yes* | | 8.7 | 4.6 | 18 | [mnet_cov2][2] | [link][dl4] |
| centerface | Yes | | 10.6 | 3.5 | 19 | [Star-Clouds/CenterFace][3] | [link][dl5] |
| scrfd_10g_bnkps | Yes* | Yes | 3.3 | 2 | 16 | [SCRFD][4] | [link][dl6] |
| scrfd_2.5g_bnkps | Yes* | Yes | 2.2 | 1.1 | 13 | [SCRFD][4] | [link][dl7] |
| scrfd_500m_bnkps | Yes* | Yes | 1.9 | 0.8 | 13 | [SCRFD][4] | [link][dl15] |
| scrfd_10g_gnkps | Yes* | Yes | 3.3 | 2.2 | 17 | [SCRFD][4]** | [link][dl16] |
| scrfd_2.5g_gnkps | Yes* | Yes | 2.3 | 1.2 | 14 | [SCRFD][4]** | [link][dl17] |
| scrfd_500m_gnkps | Yes* | Yes | 2.1 | 1.3 | 14 | [SCRFD][4]** | [link][dl18] |
| yolov5s-face | Yes* | Yes | | | | [yolov5-face][10] | [link][dl23] |
| yolov5m-face | Yes* | Yes | | | | [yolov5-face][10] | [link][dl24] |
| yolov5l-face | Yes* | Yes | | | | [yolov5-face][10] | [link][dl25] |
> Note: Performance metrics measured on NVIDIA RTX2080 SUPER + Intel Core i7-5820K (3.3Ghz * 6 cores) for
> `api/src/test_images/lumia.jpg` with `force_fp16=True`, `det_batch_size=1` and `max_size=640,640`.
>
> Detection time include inference, pre- and postprocessing, but does not include image reading, decoding and resizing.
> Note 2: SCRFD family models requires input image shape dividable by 32, i.e 640x640, 1024x768.
### Recognition:
| Model | Auto download | Batch inference | Inference b=1 (ms) | Inference b=64 (ms) | Source | ONNX File |
|------------------------|:-------------:|:---------------:|:------------------:|:-------------------:|:-----------------------|:------------:|
| arcface_r100_v1 | Yes* | Yes | 2.6 | 54.8 | [official package][1] | [link][dl8] |
| r100-arcface-msfdrop75 | No | Yes | - | - | [SubCenter-ArcFace][5] | None |
| r50-arcface-msfdrop75 | No | Yes | - | - | [SubCenter-ArcFace][5] | None |
| glint360k_r100FC_1.0 | No | Yes | - | - | [Partial-FC][6] | None |
| glint360k_r100FC_0.1 | No | Yes | - | - | [Partial-FC][6] | None |
| glintr100 | Yes* | Yes | 2.6 | 54.7 | [official package][1] | [link][dl13] |
| w600k_r50 | Yes* | Yes | 1.9 | 33.2 | [official package][1] | [link][dl21] |
| w600k_mbf | Yes* | Yes | 0.7 | 9.9 | [official package][1] | [link][dl22] |
### Other:
| Model | Auto download | Inference code | Source | ONNX File |
|------------------|:-------------:|:--------------:|:----------------------------|:------------:|
| genderage_v1 | Yes* | Yes | [official package][1] | [link][dl14] |
| mask_detector | Yes* | Yes | [Face-Mask-Detection][8] | [link][dl19] |
| mask_detector112 | Yes* | Yes | [Face-Mask-Detection][8]*** | [link][dl20] |
| 2d106det | No | No | [coordinateReg][9] | None |
`*` - Models will be downloaded from Google Drive, which might be inaccessible in some regions like China.
`**` - custom models retrained for this repo. Original SCRFD models have bug
([deepinsight/insightface#1518](https://github.com/deepinsight/insightface/issues/1518)) with
detecting large faces occupying >40% of image. These models are retrained with Group Normalization instead of
Batch Normalization, which fixes bug, though at cost of some accuracy.
Models accuracy on WiderFace benchmark:
| Model | Easy | Medium | Hard |
|:--------------------|:-------:|:----------:|:-----:|
| scrfd_10g_gnkps | 95.51 | 94.12 | 82.14 |
| scrfd_2.5g_gnkps | 93.57 | 91.70 | 76.08 |
| scrfd_500m_gnkps | 88.70 | 86.11 | 63.57 |
`***` - custom model retrained for 112x112 input size to remove excessive resize operations and
improve performance.
[1]: https://github.com/deepinsight/insightface/tree/master/python-package
[2]: https://github.com/deepinsight/insightface/tree/master/detection/RetinaFaceAntiCov
[3]: https://github.com/Star-Clouds/CenterFace
[4]: https://github.com/deepinsight/insightface/tree/master/detection/scrfd
[5]: https://github.com/deepinsight/insightface/tree/master/recognition/SubCenter-ArcF