Introduction

FaceAI aims to create rich, leading, and practical Ai Face tools that help users train better models and apply them into practice.

his 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 in official DeepInsight InsightFace repository.

This repository provides source code for building face recognition REST API and converting models to ONNX and TensorRT using Docker.

Key features:

• Ready for deployment on NVIDIA GPU enabled systems using Docker and nvidia-docker2.
• Fully automatic model bootstrapping, including downloading and MXnet->ONNX->TensorRT conversion of official DeepInsight InsightFace models.
• Up to 3x performance boost over MXNet inference with help of TensorRT optimizations, FP16 inference and batch inference of detected faces with ArcFace model.
• Inference on CPU with ONNX-Runtime.

Contents

List of supported models

• Detection
• Recognition
• Other

Prerequesites

Running with Docker

API usage

• /extract

Work in progress

Known issues

Changelog

List of supported models:

Detection:

Model	Auto download	Inference code	Source	ONNX File
retinaface_r50_v1	Yes	Yes	official package	link
retinaface_mnet025_v1	Yes	Yes	official package	link
retinaface_mnet025_v2	Yes	Yes	official package	link
mnet_cov2	Yes*	Yes	mnet_cov2	link
centerface	Yes	Yes	Star-Clouds/CenterFace	link
scrfd_10g_bnkps	Yes*	Yes	SCRFD	link
scrfd_2.5g_bnkps	Yes*	Yes	SCRFD	link
scrfd_500m_bnkps	Yes*	Yes	SCRFD	link
scrfd_10g_gnkps	Yes*	Yes	SCRFD**	link
scrfd_2.5g_gnkps	Yes*	Yes	SCRFD**	link
scrfd_500m_gnkps	Yes*	Yes	SCRFD**	link

Note: SCRFD family models requires input image shape dividable by 32, i.e 640x640, 1024x768.

Recognition:

Model	Auto download	Inference code	Source	ONNX File
arcface_r100_v1	Yes*	Yes	official package	link
r100-arcface-msfdrop75	No	Yes	SubCenter-ArcFace	None
r50-arcface-msfdrop75	No	Yes	SubCenter-ArcFace	None
glint360k_r100FC_1.0	No	Yes	Partial-FC	None
glint360k_r100FC_0.1	No	Yes	Partial-FC	None
glintr100	Yes*	Yes	official package	link

Other:

Model	Auto download	Inference code	Source	ONNX File
genderage_v1	Yes*	Yes	official package	link
2d106det	No	No	coordinateReg	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) 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

Requirements:

1. Docker
2. Nvidia-container-toolkit
3. Nvidia GPU drivers (465.x.x and above)

Running with Docker:

1. Clone repo.
2. Execute deploy_trt.sh from repo's root.
3. Go to http://localhost:9997 to access documentation and try API

If you have multiple GPU's with enough GPU memory you can try running multiple containers by editing n_gpu and n_workers parameters in deploy_trt.sh.

Also if you want to test API in non-GPU environment you can run service with deploy_cpu.sh script. In this case ONNXRuntime will be used as inference backend.

API usage:

This documentation might be outdated, please referer
to builtin API documentation for latest version

/extract endpoint

Extract endpoint accepts list of images and return faces bounding boxes with corresponding embeddings.

API accept JSON in following format:

{
  "images":{
      "data":[
          base64_encoded_image1,  
          base64_encoded_image2
      ]
  },
  "max_size":[640,480]
}

Where max_size is maximum image dimension, images with dimensions greater than max_size will be downsized to provided value.

If max_size is set to 0, image won't be resized.

To call API from Python you can use following sample code:

import os
import json
import base64
import requests

def file2base64(path):
    with open(path, mode='rb') as fl:
        encoded = base64.b64encode(fl.read()).decode('ascii')
        return encoded


def extract_vecs(ims,max_size=[640,480]):
    target = [file2base64(im) for im in ims]
    req = {"images": {"data": target},"max_size":max_size}
    resp = requests.post('http://localhost:9997/extract', json=req)
    data = resp.json()
    return data
    
images_path = 'src/api/test_images'
images = os.path.listdir(images_path)
data = extract_vecs(images)

Response is in following format:

[
    [
        {"vec": [0.322431242,0.53545632,], "det": 0, "prob": 0.999, "bbox": [100,100,200,200]},
        {"vec": [0.235334567,-0.2342546,], "det": 1, "prob": 0.998, "bbox": [200,200,300,300]},
    ],
    [
        {"vec": [0.322431242,0.53545632,], "det": 0, "prob": 0.999, "bbox": [100,100,200,200]},
        {"vec": [0.235334567,-0.2342546,], "det": 1, "prob": 0.998, "bbox": [200,200,300,300]},
    ]
]

First level is list in order the images were sent, second level are faces detected per each image as dictionary containing face embedding, bounding box, detection probability and detection number.

Work in progress:

• Add examples of indexing and searching faces (powered by Milvus).
• Add Triton Inference Server as execution backend

Known issues:

• When glintr100 recognition model is used genderage model returns wrong predictions.

Visualization

Tutorials

• Installation
• Quick Start
• Community
• License
• Contribution

Face Detection Algorithm

FaceAI open source text detection algorithms list:

• MTCNN(paper)
• RetinaFace(paper)

Model	Backbone	Easy	Medium	Hard	Download link
RetinaFace	ResNet50	96.5%	95.6%	90.4%	Download link
RetinaFace	MobileNet0.25	88.67%	84.83%	82.5%	Download link

Face Recognition Algorithm

FaceAI open-source face recognition algorithms list:

• FaceNet(paper)
• InsightFace(ArcFace)(paper)

Model	Backbone	LFW Accuracy	Module combination	Download link
FaceNet	InceptionV3	99.65%	Inception-ResNet-v1	Download link
InsightFace	ResNet100	99.77%	LResNet100E-IR,ArcFace@ms1m-refine-v2	Download link

Community

Scan the QR code below with your wechat and completing the questionnaire, you can access to offical technical exchange group.

License

This project is released under Apache 2.0 license

Contribution

We welcome all the contributions to FaceAI and appreciate for your feedback very much.