Important information to get started with the Face SDK.
- Worker Model
- Interactions with Licensing Service
- Connect to Licensing Service via HTTP Proxy
- Proxy Guard
By default, the web service starts with one worker. Each worker processes requests in a single-threaded mode that means that it can process only one request at a time. So, if you submit many requests at once, they queue up and are processed one by one.
To improve the throughput performance, you can launch more workers according to the planned load. The web service can spawn multiple workers under one service instance. You may set the workers number based on the hardware limitation you have.
Also, you can use N web server instances with multiple workers under the load balancer to increase the performance even more.
Each worker in our license model counts as an instance. So, a setup of 3 machines with 2 workers on each requires a license with 6 instances.
For transaction-based licenses, the number of workers is not limited, only the number of the process requests counts.
Interactions with Licensing Service
When working with an online license, the web service contacts the licensing service at https://lic.regulaforensics.com via encrypted communication and sends requests for validation.
The licensing service is created to manage the license keys, and this is its only purpose. The web service is customer-hosted, on-prem, and all personal data remains on the customer's servers and is not being communicated back to Regula.
On the start of a worker, the licensing service is contacted, and a registration request is sent. If the license is valid, the worker runs. Otherwise, it fails.
In case the online license is transaction-based, each time the functionality is used, the web service contacts the licensing service with a POST request. This request consists of the license id, transaction id, session id, client ip, transaction scenario, product type and version used, and the timestamp. If the license is valid for this kind of request, the request gets logged, the 'OK' response is provided, and the SDK returns the processing results.
In case the online license is instance/worker-based, heartbeats are monitored instead. Every hour the web service sends a heartbeat request to the licensing service providing the following information: license id, session id, client ip, product type and version used, and the timestamp. If the license is valid and the response is 'OK', the web service continues to perform. If the response is 'FAIL', the Error message appears.
Heartbeats continue and as soon as the license becomes valid again, the operation of the web service restores automatically. In case there is no Internet connection when the request is sent, the result is 'TIMEOUT'.
Connect to Licensing Service via HTTP Proxy
If you host the SDK in an isolated private environment, you can specify an HTTP proxy via the
HTTPS_PROXY env variable. The proxy will be used by the web service to connect to the licensing service.
Do not specify any protocol prefix in the proxy URL. Instead of
If you use your own TSL certs, place them in the
/etc/ssl/certs folder in Linux and docker envs.
The Regula Face SDK is not a general HTTP web server that handles hundreds of requests per second. Typical processing takes up to a few seconds, so we can call it CPU intensive. Considering that a typical instance has 1-4 workers, we need to carefully manage workers' time.
One of the main sources of wasting worker's processing time is a slow clients problem. When the web service receives a request from a client with a slow internet connection, this request goes to a free worker. The worker will be bottlenecked by the speed of the client connection, and it will be blocked until the slow client finishes sending a large ID image. Being blocked means that this worker process can't handle any other request in the meantime, it’s just there, idle, waiting to receive the entire request, so it can start really processing it.
We strongly recommend using the Face SDK behind a proxy server. Although there are many HTTP proxies available, we strongly advise that you use Nginx. If you choose another proxy server, you need to make sure that it buffers slow clients.
Typical Load Balancers from cloud providers, such as ELB/ALB from aws, do not buffer slow clients. So, you still need to use some proxy server between LB and the Face SDK.
The recommended machine settings are 1CPU and 3Gb RAM per worker.
For using the docker or Linux instances, you will need an online license. Internet connection is a mandatory requirement for an online license, thus the instance with a pre-installed service must have internet access at least to the https://lic.regulaforensics.com/ URL.
A.B.C.D is composed of:
A.Bfor the Regula SDK version
Cfor the neural network version
Dfor the service wrapper version
For example, a version 3.0.310.2 should be interpreted as follows:
3.0is the Regula SDK version
310is the current neural network version
2is the web service wrapper version