Версия: 1.2.0

3. Инструкция по развертыванию

3.1 Подготовка к развертыванию

3.1.1 Подготовка

Переместите файл лицензии face_sdk.lic в папку setup распакованного дистрибутива Image API.

Дальнейшие команды следует выполнять относительно директории setup.

3.1.2 Конфигурация

Название файла конфигурации	Описание
./cfg/image-api.values.yaml	Файл конфигурации развертывания экземпляра Image API
./cfg/package.settings.cfg	Файл конфигурации зависимостей для установки Kubernetes-кластера
./cfg/smc.settings.cfg	Файл конфигурации Kubernetes-кластера

1. Откройте файл ./cfg/smc.settings.cfg, используя текстовый редактор, и установите значения следующих переменных:

apiserver_advertise_address - внутренний IP-адрес машины, на которой выполняется развертывание.
external_ip_address - публичный IP-адрес машины, на который будет настраиваться DNS.

примечание

При отсутствии публичного IP-адреса используйте внутренний IP-адрес.

2. Откройте файл ./cfg/image-api.values.yaml, используя текстовый редактор, и установите значения следующих переменных:

ingress.host - доменное имя, используется в ingress для маршрутизации запросов на сервисы Kubernetes.

IP-адрес для доменного имени <ingress.host> должен быть сконфигурирован на DNS-сервере.

3.1.3 Установка зависимостей

Если в системе отсутствует Docker, Kubernetes, Helm выполните следующую команду:

$ ./cli.sh package install

3.1.4 Загрузка образов

Загрузите в локальный registry docker-образы image-api:

$ ./cli.sh image-api load-images

Загрузите в локальный registry docker-образы smc:

$ ./cli.sh smc load-images

Загрузка образов может длиться около пяти минут.

3.1.5 Установка и настройка кластера

Запустите команду для создания и настройки кластера:

$ ./cli.sh smc install

Эта команда выполняет следующие действия:

Настройка docker и сети хоста
Установка кластера
Установка ingress-controller
Установка flannel

Для использования GPU необходимо установить nvidia-device-plugin командой:

$ ./cli.sh smc nvidia install 

Для использования Horizontal Pod Autoscaler необходимо установить metric-server командой:

$ ./cli.sh smc metric-server install

Запустите следующую команду для создания секретов image-api в кластере:

$ ./cli.sh image-api install-secrets

3.1.6 Проверка работоспособности кластера

После инициализации главного узла убедитесь, что он готов к работе. Для проверки выполните следующую команду:

$ kubectl get nodes

В результате в терминале будет отображен следующий вывод:

NAME          STATUS      ROLES                   AGE     VERSION
master-node   Ready       control-plane,master    1d     v1.23.8

3.2 Развертывание

3.2.1 Настройка файла конфигурации (опционально)

При необходимости перед установкой Image API в кластер можно указать значения для следующих полей в файле конфигурации ./cfg/image-api.values.yaml:

Название поля	Описание
image_pull_policy	Регулирует политику загрузки из registry образов контейнера для развертывания экземпляра деплоймента Image API. Доступны следующие значения поля: Always - kubelet (агент узлов в Kubernetes) выполняет загрузку образа из registry. Never - загрузка образа из registry не предусмотрена. Если образ уже присутствует локально, kubelet попытается выполнить запуск контейнера, в противном случае, произойдет сбой загрузки. IfNotPresent - образ загружается только в случае, если отсутствует локально.
processing.capturer_config	В значении поля указывается название файла конфигурации выбранного детектора лиц. В Image API используются детекторы лиц из Face SDK - набора библиотек для разработки решений по распознаванию лиц. В текущей версии Image API доступны на выбор два детектора: ULD и REFA. Детектор ULD позволяет выполнять детекцию лиц разного размера, в том числе лиц в масках (скорость детекции выше чем у REFA). Детектор REFA обеспечивает детекцию лиц с наибольшим покрытием углов поворота и наклона головы и максимальным качеством, включая детекцию лиц в масках (качество детекции выше чем у ULD). В качестве значений для поля можно указать следующие файлы конфигурации детекторов: common_capturer_uld_fda.xml (Файл конфигурации детектора ULD) common_capturer_refa_fda_a.xml (Файл конфигурации детектора REFA) Более подробно о файлах конфигурации смотрите в документации 3DiVi Face SDK.
processing.recognizer_config	В значении поля указывается название файла конфигурации рекогнайзера лиц. Image API использует набор рекогнайзеров из Face SDK. В каждом рекогнайзере применяется определенный метод распознавания. Всего в Face SDK предусмотрено несколько методов распознавания, отличающихся по характеристикам качества распознавания и времени работы. Для Image API можно указать следующие файлы конфигурации рекогнайзеров: method11v1000_recognizer.xml method12v30_recognizer.xml method12v50_recognizer.xml method12v100_recognizer.xml method12v1000_recognizer.xml Более подробно о рекогнайзерах, методах идентификации и файлах конфигурации рекогнайзеров смотрите в документации 3DiVi Face SDK.
processing.enable_use_avx2	Использование набора команд AVX2 позволяет ускорить работу рекогнайзеров.
*processing.services.[].use_cuda**	Определяет использование видеокарты сервисом. Доступно в сервисе face-detector-template-extractor.
*processing.services.[].replicas**	Значение реплик сервиса.
processing.downscale_rawsamples	При включенном поле все сэмплы уменьшаются до предпочтительного размера в целях уменьшения потребления памяти, при этом происходит снижение производительности. Рекомендуется оставить поле отключенным.
processing.enable_ingress	Включить проксирование на сервисы image-api через ingress.
processing.enable_resource_management	Включить использования управления ресурсами под (pods) в кластере.
processing.enable_hpa	Включить Horizontal Pod Autoscaler для деплойментов. Необходим установленный metric-server.
processing.enable_node_selector	Активировать использование обозначенных nodeSelector’ов в подах (pods). Необходимые лейблы должны быть назначены нодам кластера с помощью команды: `kubectl label nodes <node_name> type=<type>` "type": "processing" - нода для вычислений "type": "generic" - обычная нода

3.2.2 Установка

Запустите скрипт для установки Image API в кластер:

$ ./cli.sh image-api install

Для получения статуса работы развертывания выполните команду:

$ kubectl get pods

В терминал будет выведен список под (pods - экземпляров деплоймента), их статус, количество перезапусков и время с момента создания.

Пример вывода:

NAME                                                READY    STATUS     RESTARTS   AGE
image-api-age-estimator-dep-5bf7889dcd-jm46h         1/1     Running        0      1h
image-api-body-detector-dep-6778495696-4zkpm         1/1     Running        0      1h
image-api-emotion-estimator-dep-7c8cdd7c6b-z4vlv     1/1     Running        0      1h
image-api-face-detector-face-fitter-dep-5fb48dcb5…   1/1     Running        0      1h
image-api-gateway-dep-65d4846c59-g2nfj               1/1     Running        0      1h
image-api-gender-estimator-dep-86b9457f9b-2464q      1/1     Running        0      1h
image-api-face-detector-liveness-estimator-dep-7bd…  1/1     Running        0      1h
image-api-mask-estimator-dep-76b958b84b-w7pss        1/1     Running        0      1h
image-api-quality-assessment-estimator-dep-fbf8bc4…  1/1     Running        0      1h
image-api-face-detector-template-extractor-dep-5758… 1/1     Running        0      1h
image-api-verify-matcher-dep-6d66dc4948-lx8j7        1/1     Running        0      1h

примечание

Наличие у всех под (pods) статуса Running означает, что все контейнеры успешно запущены.

Ниже приведено краткое описание деплойментов:

image-api-gateway-dep: обратный прокси-сервер, отвечает за единый доступ к сервисам обработки;
image-api-face-detector-face-fitter-dep: детекция лица и вычисление антропометрических точек лица и углов поворота головы;
image-api-body-detector-dep: детекции тела;
image-api-emotion-estimator-dep: оценка эмоций;
image-api-age-estimator-dep: оценка возраста;
image-api-gender-estimator-dep: оценка пола;
image-api-face-detector-liveness-estimator-dep: оценка принадлежности лица на изображении реальному человеку (liveness);
image-api--mask-estimator-dep: оценка наличия/отсутствия медицинской маски на лице человека;
image-api-quality–assessment-estimator-dep: оценка качества изображения;
image-api-verify-matcher-dep: сравнение двух биометрических шаблонов;
image-api-template-extractor-dep: извлечение биометрического шаблона лица с изображения.

3.2.3 Настройка модулей

Модуль - это вариант реализации конкретного сервиса Image API. Например, для сервиса face-detector-liveness-estimator доступны три модуля на выбор:

liveness-anti-spoofing
quality-liveness-anti-spoofing
face-detector-liveness-estimator

Модули liveness-anti-spoofing и face-detector-liveness-estimator отличаются друг от друга алгоритмами определения liveness. В модуле quality-liveness-anti-spoofing дополнительно перед расчётом liveness выполняется оценка качества изображения, при этом порог качества (threshold) (значение по умолчанию - 30) позволяет исключить из пайплайна обработки изображения с недостаточным качеством.

Для смены модуля найдите в файле ./cfg/image-api.values.yaml конфиг интересующего сервиса в processing.services и поменяйте в нем значение поля module.

Пример конфига сервиса quality-assessment-estimator:

quality-assessment-estimator:
      …………
      module: quality-assessment-estimator
      …………

Перечень доступных модулей для каждого сервиса Image API:

Сервис	Модули
face-detector-face-fitter	face-detector-face-fitter - стандартный модуль
body-detector	body-detector - стандартный модуль
age-estimator	age-estimator - стандартный модуль
emotion-estimator	emotion-estimator - стандартный модуль
gender-estimator	gender-estimator - стандартный модуль
mask-estimator	mask-estimator - стандартный модуль
face-detector-liveness-estimator	face-detector-liveness-estimator - стандартный модуль liveness-anti-spoofing - более медленный, но более точный модуль quality-liveness-anti-spoofing - модуль liveness-anti-spoofing с дополнительной проверкой качества перед вычислением liveness
verify-matcher	verify-matcher - стандартный модуль
face-detector-template-extractor	face-detector-template-extractor - стандартный модуль
quality-assessment-estimator	quality-assessment-estimator - стандартный модуль

3.2.4 Масштабирование

В случае, когда нагрузка возрастает, для стабилизации работы Image API предусмотрено масштабирование описанных в пункте 3.2.2 деплойментов в ручном режиме:

Для масштабирования установленного релиза необходимо выполнить следующую команду:

$ kubectl scale deployment <deployment_name> --replicas <count>

где <deployment_name> - наименование деплоймента (например, face-detector-dep), а <count> - количество реплик деплоймента (pods).

Для сохранения состояния масштабирования необходимо установить значение replicas под ключом интересующего сервиса в processing.services в файле ./cfg/image-api.values.yaml и перезапустить развертывание командой:

$ ./cli.sh image-api install

3.2.5 Настройка DNS

Для обеспечения доступа DNS сервер вашей сети должен содержать запись о том, что домен <host> доступен по адресу <external_ip_address>. Значения переменных можно получить из файлов ./cfg/smc.settings.cfg и ./cfg/image-api.values.yaml, заполненных в пункте 3.1.2. Чтобы выполнить данную конфигурацию, обратитесь к администратору вашей сети.

Для целей тестирования можно указать IP-адрес и домен в файле /etc/hosts на Linux или C:\Windows\System32\drivers\etc\hosts на Windows. Для этого добавьте в конец данного файла новую строку вида <external_ip_address> <host>, подставив значения соответствующих переменных, и сохраните файл. Обратите внимание, что для редактирования файла hosts необходимо обладать правами администратора.

Для использования Image API с той же машины, где выполнено развертывание, можно воспользоваться скриптом, который автоматически добавит необходимую запись в файл /etc/hosts.

$ echo "<external_ip_address> <host>" | sudo tee -a /etc/hosts

3.2.6 Проверка работы

Для проверки работы выполните команду ниже:

$ ./cli.sh image-api test - http://<host>

Вывод теста должен иметь следующий вид:

face-detector-face-fitter ✓
age-estimator ✓
emotion-estimator ✓
gender-estimator ✓
face-detector-liveness-estimator ✓
mask-estimator ✓
quality-assessment-estimator ✓
face-detector-template-extractor ✓
body-detector ✓
face-detector-template-extractor ✓
face-detector-template-extractor ✓
verify-matcher ✓

3.2.7 Удаление

Для удаления Image API выполните следующую команду:

$ ./cli.sh image-api uninstall

3.3 Лицензирование

3.3.1 Установка лицензии

Распакуйте дистрибутив Image API и переместите файл лицензии face_sdk.lic (файл прикреплен к электронному письму) в папку setup.

3.3.2 Обновление лицензии

Переустановите секреты.

$ ./cli.sh image-api install-secrets

Удалите релиз из кластера.

$ ./cli.sh image-api uninstall

Установите релиз в кластер.

$ ./cli.sh image-api install

3.1 Подготовка к развертыванию​

3.1.1 Подготовка​

3.1.2 Конфигурация​

3.1.3 Установка зависимостей​

3.1.4 Загрузка образов​

3.1.5 Установка и настройка кластера​

3.1.6 Проверка работоспособности кластера​

3.2 Развертывание​

3.2.1 Настройка файла конфигурации (опционально)​

3.2.2 Установка​

3.2.3 Настройка модулей​

3.2.4 Масштабирование​

3.2.5 Настройка DNS​

3.2.6 Проверка работы​

3.2.7 Удаление​

3.3 Лицензирование​

3.3.1 Установка лицензии​

3.3.2 Обновление лицензии​