.. _architecture:
*************************************
Architecture
*************************************
Though you mostly interact with FindFace through its web interface, be sure to take a minute to learn the FindFace architecture. This knowledge is essential for the FindFace deployment, integration, maintenance, and troubleshooting.
.. rubric:: In this chapter:
.. contents::
:local:
Architectural Elements
===============================
FindFace consists of the following fundamental architectural elements:
* FindFace core, a cutting-edge AI-based face recognition technology that can be used as a separate product `FindFace Enterprise Server `_.
* FindFace, which is a turnkey application module for FindFace Enterprise Server.
Architecture scheme
------------------------
|architecture_en|
.. |architecture_en| image:: /_static/architecture.png
.. |architecture_ru| image:: /_static/architecture_ru.png
FindFace Core
-------------------------
The FindFace core includes the following components:
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| Component | Ports in use | Description | Vendor |
+===========================+==============+======================================================================================+============================================+
| findface-extraction-api | 18666 | Service that uses neural networks to detect a face in an image and extract a | NtechLab own deployment |
| | | face biometric sample (feature vector). It also performs recognition of face | |
| | | attributes such as gender, age, emotions, beard, glasses, face mask, and others, | |
| | | and silhouette recognition (if configured). CPU- or GPU-acceleration. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-sf-api | 18411 | Service that implements HTTP API for face detection and face recognition. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-tarantool-server | 32001, | Service that provides interaction between the ``findface-sf-api`` service and the | |
| | shard ports | biometric database (database that stores face biometric samples) | |
| | (default | powered by Tarantool. | |
| | 330xx, 81xx) | | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-upload | 3333 | NginX-based web server used as a storage for original images, thumbnails and | |
| | | normalized face images. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-facerouter | 18820 | Service used to define processing directives for detected faces. In FindFace | |
| | | Security, its functions are performed by ``findface-security`` | |
| | | (see :ref:`application-module`). If necessary, you can still deploy and | |
| | | enable this component for integration purposes (see :ref:`Plugins`). | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-video-manager | 18810, | Service, part of the video face detection module, that is used for managing the | |
| | 18811 | video face detection functionality, configuring the video face detector | |
| | | settings and specifying the list of to-be-processed video streams. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-video-worker | 18999 | Service, part of the video face detection module, that recognizes a face in the video| |
| | | and posts its normalized image, full frame and metadata (such as the camera ID and | |
| | | detection time) to the ``findface-facerouter`` service for further processing | |
| | | according to given directives. Provides :ref:`face liveness detection ` | |
| | | if enabled. CPU- or GPU-acceleration. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+ |
| findface-ntls | 443 | License server which interfaces with the NtechLab Global License Server or a USB | |
| | (TCP), | dongle to verify the :ref:`license ` of your FindFace | |
| | 3133, | instance. | |
| | 3185 | | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| Tarantool | Shard ports | Third-party software which implements the biometric database that stores extracted | `Tarantool `_ |
| | (default | biometric samples (feature vectors) and face identification events. The system data, | |
| | 330xx, 81xx) | dossiers, user accounts, and camera settings are stored in PostgreSQL | |
| | | (part of the FindFace application module). | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| etcd | 2379 | Third-party software that implements a distributed key-value store for | `etcd `_ |
| | | ``findface-video-manager``. Used as a coordination service in the distributed | |
| | | system, providing the video face detector with fault tolerance. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| NginX | 80; | Third-party software which implements the system web interfaces. | `nginx `_ |
| | SSL: 8002, | | |
| | 8003, 443, | | |
| | 80 | | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
| memcached | 11211 | Third-party software which implements a distributed memory caching system. | `memcached `_ |
| | | Used by ``findface-extraction-api`` as a temporary storage for extracted face | |
| | | biometric samples before they are written to the biometric database powered by | |
| | | Tarantool. | |
+---------------------------+--------------+--------------------------------------------------------------------------------------+--------------------------------------------+
.. _application-module:
FindFace Application Module
---------------------------------------------
The FindFace application module includes the following components:
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
| Component | Ports in use | Description | Vendor |
+=======================+==============+=======================================================================================+============================================+
| findface-security | Configurable | Component that serves as a gateway to the FindFace core. | NtechLab own deployment |
| | | Provides interaction between the FindFace Core and the web interface, the system | |
| | | functioning as a whole, HTTP and web socket, biometric monitoring, event | |
| | | notifications, episodes, webhooks, and counters. | |
| | | Includes the following internal services: NTLS checker, Counter manager, Webhooks | |
| | | manager, Persons clusterizator, Event episodes manager, and Video archive queue | |
| | | manager. The last four can be enabled and disabled via the | |
| | | ``/etc/findface-security/config.py`` configuration file. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+ |
| findface-security-ui | Configurable | Main web interface that is used to interact with FindFace. | |
| | | Allows you to work with face identification events, search for | |
| | | faces, manage cameras, users, dossiers, and watch lists, collect real-time | |
| | | statistics, and many more. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+ |
| findface-counter | 18300 | Service used for face deduplication. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+ |
| findface-liveness-api | 18301 | Besides the embedded functionality provided by ``findface-video-worker``, face | |
| | | liveness detection can also be harnessed as a standalone service | |
| | | ``findface-liveness-api``. The service takes a specific number of frames from a video | |
| | | fragment and returns the best quality face, and decimal liveness result averaged | |
| | | across the taken frames. The service is also used for authentication based on facial | |
| | | recognition. See :ref:`liveness-api` and :ref:`authentication`. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
| PostgreSQL | 5432 | Third-party software which implements the main system database that stores | `PostgreSQL `_ |
| | | detailed and categorized dossiers on particular persons, | |
| | | as well as data for internal use such as user accounts and camera settings. | |
| | | The face biometric data and face identification events are stored in Tarantool | |
| | | (part of the FindFace core). | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
| Pgbouncer | 5439 | Third-party software, a lightweight connection pooler for PostgreSQL. Optional, | `PgBouncer `_ |
| | | used to increase the database performance under high load. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
| Redis | 6379 | Third-party software which implements a message broker inside ``findface-security``. | `Redis `_ |
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
| Django | 5439 | Third-party software which implements a web framework for the FindFace | `Django `_ |
| | | web interface. | |
+-----------------------+--------------+---------------------------------------------------------------------------------------+--------------------------------------------+
.. seealso::
:ref:`components`
Single- and Multi-Host Deployment
==================================
You can deploy FindFace on a single host or in a cluster environment. If you opt for the latter, we offer you one of the following deployment schemes:
* Deploy FindFace standalone and distribute additional ``findface-video-worker`` components across multiple hosts.
* Distribute the FindFace components across multiple hosts. If necessary, set up load balancing.
See :ref:`cluster-installation` for details.
CPU- and GPU-acceleration
==========================================
The ``findface-extraction-api`` and ``findface-video-worker`` services can be either CPU- or GPU-based. During installation from the developer-friendly :ref:`installer `, you will have an opportunity to choose the acceleration type you need.
If you opt to install FindFace from the :ref:`repository package `, deploy the ``findface-extraction-api`` and ``findface-video-worker-cpu`` packages on a CPU-based server, and the ``findface-extraction-api-gpu`` and/or ``findface-video-worker-gpu`` packages on a GPU-based server.
.. important::
Refer to :ref:`requirements` when choosing hardware configuration.
.. important::
If the resolution of a camera(s) in use is more than 1280x720px, it is strongly recommended to use the GPU-accelerated package ``findface-video-worker-gpu``.
.. note::
The :ref:`liveness detector ` is much slower on CPU than on GPU.