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

2.1 Подготовка: загрузка образов и создание Kubernetes кластера

2.1.1 Подготовка

Скачайте и распакуйте дистрибутив платформы на машину, где планируется выполнить установку. Для этого можно воспользоваться командой:

curl --output platform.zip ссылка на дистрибутив

В curl-запросе необходимо указать ссылку на дистрибутив платформы (zip-файл). Ссылка на папку, в которой размещен дистрибутив и сопроводительная документация в формате pdf, будет указана в электронном письме.

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

Комплект установки OMNI Platform:

• ./cli.sh - точка входа для запуска команд.
• ./cfg - папка с конфигурационными файлами платформы.

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

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

Загрузите в локальный registry продуктовые образы из архива:

./cli.sh generic load-images

Загрузите в локальный registry инфраструктурные образы из архива:

./cli.sh smc load-images

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

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

2.1.3.1 Базовая конфигурация

Ввод переменных окружения

Откройте следующие файлы конфигурации, используя текстовый редактор, установите значения переменных и сохраните изменения в файлах.

примечание

Значения, указываемые через точку в yaml файлах, отражают вложенность.

Файл конфигурации	Переменные
./cfg/smc.settings.cfg	apiserver_advertise_address - адрес для kube-apiserver, обычно используется внутренний IP-адрес машины. external_ip_address - адрес для ingess-controller, необходимо указать внешний IP-адрес машины.
./cfg/license-server.settings.cfg	license_key - лицензионный ключ. Как правило, ключ отправляется в сопроводительном письме с дистрибутивом. При отсутствии ключа обратитесь к вашему менеджеру по продажам. Для пробного периода ключ не требуется. license_server_address - адрес лицензионного сервера.
./cfg/platform.secrets.json	license-secret - установите лицензионный ключ и адрес лицензионного сервера вместо license_server_address. docker-registry - установите значения, если используется внешний docker-registry. rabbit-secret - имя пользователя и пароль для доступа к брокеру сообщений, используется для внутреннего взаимодействия сервисов OMNI Platform. Задайте произвольное имя, состоящее из латинских букв, без пробелов и пароль, состоящий из латинских букв и цифр, без пробелов. postgres-root-credentials - имя пользователя и пароль для root пользователя в базе данных. platform-service-key - секретный ключ, необходимый для внутреннего взаимодействия сервисов OMNI Platform. platform-user-secret - учетные данные (адрес электронной почты и пароль), которые будут использоваться для доступа в OMNI Platform. При первом развертывании пользователи будут созданы автоматически. Указываемый адрес электронной почты должен состоять из цифр, латинских букв и символов. platform-email-secret - параметры SMTP-сервера. Чтобы отключить отправку писем, оставьте данные поля пустыми.
./cfg/platform.values.yaml	backend.query_limit - ограничение количества возвращаемых элементов в API запросах для получения сущностей системы. Увеличение данного лимита не рекомендуется, т.к. время выполнения API запроса может увеличиться в несколько раз. Также, обратите внимание, что увеличение лимитов приведет к ухудшению работы системы. backend.index_update_period - значение в секундах, описывающее через какое время добавленный профиль появится в поисковом индексе. По умолчанию установлено значение 60 секунд. Если требуется увеличить скорость обновления поискового индекса, следует уменьшить значение. backend.enable_profile_autogeneration - Автосоздание профилей для приходящих активностей с OMNI Agent. Необходимо учитывать, что при включении данной опции будет увеличенный расход ресурсов лицензии (размер базы данных). Для включения функции установить значение 1. processing.use_cuda - отвечает за использование видеокарты в сервисе обработки. 0 - отключить, 1 - включить. ingress.rules.gateway.host - доменное имя, используется в ingress для маршрутизации запросов на сервисы Kubernetes. postgres.enable - выключите, если используете свой сервер базы данных. Примечание: необходимо поменять значения для postgres-root-credentials в файле ./cfg/platform.secrets.json и значения для postgres.host и postgres.port в текущем файле.

Настройка Docker для использования GPU (опционально)

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

Для установки nvidia-container-runtime в качестве низкоуровневой среды выполнения по умолчанию, добавьте следующие строки в файл конфигурации, который находится по адресу /etc/docker/daemon.json:

"default-runtime": "nvidia",
"runtimes": {
    "nvidia": {
        "path": "/usr/bin/nvidia-container-runtime",
        "runtimeArgs": []
    }
}

Применение конфигурации

Перезапустите docker-service, выполнив следующую команду:

sudo systemctl restart docker

2.1.3.2 Расширенная конфигурация

Изменение конфигурации элементов системы

предупреждение

Значения для каждого из параметров указаны по умолчанию. Изменять значения параметров рекомендуется только в случае явной необходимости.

Файл ./cfg/platform.values.yaml:

• backend.activity_ttl - Время хранения активностей в базе данных. Значение задается в секундах. Например, 2592000 секунд (30 дней)
• backend.sample_ttl - Время хранения сэмплов в базе данных. Значение задается в секундах. Например, 2592000 секунд (30 дней)

Изменение метода распознавания лиц

OMNI Platform использует методы распознавания лиц из набора библиотек Face SDK. Под методом имеется в виду версия модели распознавания лиц. По умолчанию в OMNI Platform установлен метод 12v1000. Для более быстрой работы вы можете переключиться на метод 12v100, однако при этом снизится точность распознавания.

Смена метода во время установки платформы

На этапе заполнения файлов конфигурации откройте файл ./cfg/platform.values.yaml и замените метод в полях generic.recognizer, backend.default_template_version, processing.recognizer_methods. Далее откройте файл ./cfg/image-api.values.yaml и замените метод в полях face-detector-template-extractor.configs.recognizer.name и verify-matcher.configs.recognizer.name.

Смена метода на работающей платформе

1. Остановите платформу

./cli.sh platform uninstall

2. Остановите сервисы image-api

./cli.sh image-api uninstall

3. Удалите базу данных платформы

./cli.sh platform db-reset

4. Откройте файл ./cfg/platform.values.yaml и замените метод в полях generic.recognizer, backend.default_template_version, processing.recognizer_methods. Далее откройте файл ./cfg/image-api.values.yaml и замените метод в полях face-detector-template-extractor.configs.recognizer.name и verify-matcher.configs.recognizer.name.

5. Запустите установку сервисов image-api

./cli.sh image-api install

6. Запустите платформу

./cli.sh platform install

примечание

На данный момент отсутствует возможность переключить метод для платформы с уже созданной базой данных. Если вы все же решили поменять метод распознавания, в таком случае базу данных нужно будет создать заново.

Настройка порога score

Параметр score показывает степень схожести лиц от 0 (0%) до 1 (100%). Высокая степень схожести означает, что два биометрических шаблона принадлежат одному и тому же человеку. Пороговое значение по умолчанию - 0.85.

Изменить порог score на OMNI Platform можно через API-запрос updateWorkspaceConfig, где в качестве аргументов указываются два пороговых значения: activityScoreThreshold (Требуемый score для привязки активности к профилю) и notificationScoreThreshold (Требуемый score для создания оповещений для профиля) (См. подробнее в п. 2.11.4 руководства по интеграции).

подсказка

Убедитесь, что пороги score, указанные для OMNI Agent и OMNI Platform совпадают. В противном случае, часть активностей, сформированных из переданных процессов OMNI Agent, не будет привязана к соответствующему профилю, а значит и оповещения для таких активностей приходить не будут.

Например:

• score, указанный на стороне OMNI Agent = 0.7
• score, указанный на OMNI Platform = 0.85

В этом случае активности, сформированные из процессов OMNI Agent со значением score в диапазоне [0.7, 0.85), не будут прикреплены к соответствующему профилю, оповещения по ним также не появятся.

Для настройки порога score для OMNI Agent см. раздел 5.5 в руководстве пользователя OMNI Agent.

Настройка liveness

В OMNI Platform реализовано три liveness-модуля:

• 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) позволяет исключить из пайплайна обработки изображения с недостаточным качеством.

Для переключения модуля liveness установите интересующий модуль в файле конфигурации ./cfg/image-api.values.yaml в поле processing.services.face-detector-liveness-estimator.modul.

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

примечание

Если у вас уже есть развернутый кластер, перейдите к пункту 2.3.1

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

./cli.sh platform db-create-mountpoint
./cli.sh smc install
./cli.sh platform install-secrets

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

• Создание точки монтирования базы данных
• Инициализация кластера
• Установка секретов

примечание

Для использования GPU в кластере установите NVIDIA device plugin командой:

./cli.sh smc nvidia install

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

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

kubectl get nodes

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

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

Для проверки всех элементов кластера запустите следующую команду:

kubectl get all --all-namespaces

2.2 Настройка лицензирования

2.2.1 Активация пробного периода

Важно:

• требуется подключение к сети Интернет;
• не допускается запуск OMNI Platform на виртуальной машине.

Активация пробного периода происходит при первом запуске OMNI Platform.

2.2.2 Установка сервера лицензий

Перед установкой откройте файл license-server.settings.cfg и задайте IP адрес машины, на которой будет установлен сервер лицензий, в переменной license_server_address. Запустите команду для установки и запуска сервера лицензий. Если license_server_address не равен адресу хоста машины, где происходит развертывание, он будет установлен через sshpass.

./cli.sh license-server install

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

./cli.sh license-server start

Проверьте, что сервер лицензий находится в статусе running, выполнив следующую команду:

./cli.sh license-server status

Пример вывода в консоль:

floatingserver.service - Floating License Server
    Loaded: loaded (/etc/systemd/system/floatingserver.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2022-12-20 12:25:54 +05; 1min 48s ago

Убедитесь, что сервер лицензий доступен. Для этого перейдите по адресу http://<license_server_address>:8090 в вашем браузере, на странице должна отобразиться форма входа.

2.2.3 Онлайн активация лицензии

Перед активацией убедитесь, что в key (файл ./cfg/license-server.settings.cfg) записан лицензионный ключ.

Запустите команду активации лицензии:

./cli.sh license-server activate

Пример вывода в консоль при успешной активации лицензии:

[2022-12-20 12:25:53+05:00] INF Activating license key...
[2022-12-20 12:25:54+05:00] INF License activated successfully!

2.2.4 Офлайн активация лицензии

Перед активацией убедитесь, что в поле license_key (в файле ./cfg/license-server.settings.cfg) записан лицензионный ключ.

примечание

Для оффлайн активации установите “1” в поле enable_offline_activation в файле license-server.settings.cfg.

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

./cli.sh license-server generate-offline

В результате выполнения команды в директории setup должен появиться файл request-offline.dat.

Отправьте сгенерированный файл запроса request-offline.dat на почту support-platform@3divi.com. В ответном письме будет отправлен файл лицензии.

Поместите полученный лицензионный файл в папку setup.

Откройте файл конфигурации license-server.settings.cfg и заполните значение переменной license_offline_activation_file именем файла лицензии и его расширением, если присутствует, через точку.

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

./cli.sh license-server activate

Пример вывода в консоль при успешной активации лицензии:

[2022-09-08 01:30:36+05:00] INF Offline activating license key...
[2022-09-08 01:30:36+05:00] INF License activated successfully!

2.2.5 Проверка статуса лицензии после активации

Выполните команду для получения статуса лицензии:

./cli.sh license-server status-license

Пример вывода в консоль:

Activation Status: OK
License key: YOUR-LICENSE-KEY
Days Left To Expiration: 100

примечание

Сравните результат вывода команды с данными вашей лицензии. Days Left To Expiration=14 означает, что автоматически активировалась триальная лицензия. В этом случае повторите шаги по активации.

2.3 Развертывание платформы

2.3.1 Запуск развертывания

Для распознавания лиц OMNI Platform использует сервисы Image API, которые необходимо установить перед установкой платформы с помощью команды:

./cli.sh image-api install

Запустите установку платформы:

./cli.sh platform install

Для отслеживания процесса развертывания откройте ещё одну вкладку терминала и введите следующую команду:

watch 'kubectl get pods'

Наличие у всех pods статуса Running означает, что платформа запущена.

примечание

После запуска проверьте статус лицензии. Если полученные данные не соответствуют действительности, вставьте ключ лицензии в поля license_key (в файле ./cfg/license-server.settings.cfg) и license-secret.key (в файле ./cfg/platform.secrets.json) и выполните все действия из пункта 7.5.

2.3.2 Настройка DNS

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

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

./cli.sh generic add-dns - <external_ip_address> <domain>

2.3.3 Описание элементов развернутой системы

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

kubectl get pods

В консоль будет выведен список сервисов, их статус, количество перезапусков и время с момента создания сервиса. Пример вывода:

NAME                                                        READY          STATUS         RESTARTS         AGE
image-api-age-estimator-dep-c66c8f575-zb84s                  1/1           Running         0               24h
image-api-body-detector-dep-5588d96ddc-lnrrx                 1/1           Running         0               24h
image-api-emotion-estimator-dep-b6c947ff-mz7cw               1/1           Running         0               24h
image-api-face-detector-face-fitter-dep-                     1/1           Running         0               24h
image-api-face-detector-liveness-estimator-dep-              2/2           Running         0               24h
image-api-face-detector-template-extractor-dep-              1/1           Running         0               24h
image-api-gender-estimator-dep-7948d8cf85-4hk2q              1/1           Running         0               24h
image-api-mask-estimator-dep-5ccfcc8cb9-sjnqz                1/1           Running         0               24h
image-api-quality-assessment-estimator-dep-                  1/1           Running         0               24h
image-api-verify-matcher-dep-6b8f5b4d6f-jjqr4                1/1           Running         0               24h
platform-activity-matcher-dep-8697574c9b-xvh5z               2/2           Running         0               24h
platform-agent-sync-dep-899c9ddc8-7qcvj                      1/1           Running         0               24h
platform-backend-dep-685675d648-ngcrj                        1/1           Running         0               24h
platform-event-service-dep-5fcd66f999-24jjg                  1/1           Running         0               24h
platform-gateway-dep-f4cd7db78-h86jz                         1/1           Running         0               24h
platform-licensing-dep-84d78745d6-2flk2                      1/1           Running         0               24h
platform-matcher-dep-6495447f45-5hdsp                        1/1           Running         0               24h
platform-memcached-dep-64d9d7f6f7-b5bpd                      1/1           Running         0               24h
platform-postgres-dep-67c5b75b84-fm8wr                       1/1           Running         0               23h
platform-processing-dep-7fdf8699b5-682sn                     1/1           Running         0               24h
platform-quality-dep-76995ff9c7-kwsz7                        1/1           Running         0               24h
platform-rabbit-dep-69cd659f8c-sbnk2                         1/1           Running         0               24h
platform-redis-dep-694df659f-9vhrh                           1/1           Running         0               24h

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

• platform-activity-matcher-dep - сервис используется для поиска людей по активностям;
• image-api-age-estimator-dep - сервис используется для оценки возраста человека по изображению лица;
• platform-agent-sync-dep - сервис отвечает за синхронизацию данных о профилях с OMNI Agent;
• platform-backend-dep - основной контейнер платформы, отвечает за работу большей части API;
• image-api-body-detector-dep - сервис предназначен для детекции силуэтов на изображении;
• platform-rabbit-dep - сервис RabbitMQ, используется для работы асинхронной очереди задач;
• platform-cache-dep - сервис Memcached, используется для кэширования данных;
• platform-postgres-dep - экземпляр СУБД PostgreSQL, хранит всю информацию платформы;
• image-api-emotion-estimator-dep - сервис используется для оценки эмоций человека по изображению лица;
• image-api-face-detector-face-fitter-dep - сервис используется для детекции лиц и определения антропометрических точек лица и углов поворота головы;
• image-api-face-detector-liveness-estimator-dep - сервис используется для детекции лиц и оценки принадлежности лица на изображении реальному человеку;
• image-api-face-detector-template-extractor-dep - сервис предназначен для детекции лиц и извлечения биометрического шаблона лица;
• platform-gateway-dep - cервис nginx, отвечает за доступ к платформе и за работу веб-интерфейса платформы;
• image-api-gender-estimator-dep - сервис используется для оценки пола человека по изображению лица;
• platform-licensing-dep - сервис, ограничивающий работу платформы согласно параметрам лицензии;
• image-api-mask-estimator-dep - сервис позволяет определить наличие/отсутствие медицинской маски на лице человека;
• platform-matcher-dep - сервис используется для поиска людей по профилям;
• platform-processing-dep - сервис аккумулирует результаты работы сервисов-обработчиков (age-estimator-dep, emotion-estimator-dep, gender-estimator-dep,face-detector-face-fitter-dep, mask-estimator-dep
• image-api-quality-assessment-estimator-dep - сервис предназначен для оценки качества изображения лица;
• platform-quality-dep - сервис отвечает за расчет качества изображения (является устаревшим, используется для обратной совместимости);
• platform-redis-dep - сервис Redis, используется для работы WebSockets;
• image-api-verify-matcher-dep - сервис отвечает за сравнение двух лиц с изображений.
• platform-event-service-dep - сервис используется для обработки событий, приходящих с OMNI Agent.

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

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

• platform-processing-dep
• image-api-face-detector-liveness-estimator-dep
• image-api-age-estimator
• image-api-gender-estimator
• image-api-mask-estimator
• image-api-emotion-estimator
• image-api-face-detector-template-extractor-dep

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

kubectl scale deployment <SERVICE_NAME> --replicas <COUNT>

где <SERVICE_NAME> - наименование сервиса (например, gateway-dep), а <COUNT> - количество экземпляров сервиса.

примечание

При использовании GPU ускорения сервис platform-processing-dep поддерживает только один экземпляр, а значит для его масштабирования необходимо иметь N доступных видеоускорителей в кластере. При отсутствии нескольких GPU, можно увеличить утилизацию, изменив параметр processing.workers в файле ./cfg/platform.values.yaml.

Для поддержания нагрузки в A запросов/сек, направленной на обработку изображений, на сервере с физическим количеством ядер ЦП равным B следует установить значение реплик каждого из указанных сервисов по формуле min(A, B).

Для сохранения параметров масштабирования откройте файлы ./cfg/platform.values.yaml и ./cfg/image-api.values.yaml, найдите поле replicas в блоке сервиса и укажите новые значения реплик.

При следующих установках платформы и image-api сервисы будут автоматически масштабироваться до указанных значений.

подсказка

При увеличении запросов поиска по изображению увеличьте число реплик сервиса image-api-face-detector-template-extractor-dep. Также можно увеличить количество потоков, которые используются для вычисления биометрического шаблона (Более подробно см. в пункте 7.6).

При увеличении запросов на детекцию, создание профилей и создание сэмплов увеличьте число реплик сервисов:

• platform-processing-dep
• image-api-face-detector-liveness-estimator-dep
• image-api-age-estimator
• image-api-gender-estimator
• image-api-mask-estimator
• image-api-emotion-estimator