Дополнительная информация#

Описание OneShotLiveness#

Технология Liveness позволяет обнаруживать атаки на биометрическое предъявление. Такая атака означает ситуацию, когда злоумышленник пытается использовать видео или фото другого человека для того, чтобы обойти систему распознавания и получить доступ к личным данным этого человека.

Для оценки Liveness в LUNA PLATFORM, используется эстиматор LUNA SDK OneShotLiveness.

Атаки на биометрическое предъявление бывают следующих основных видов:

Атака с использованием распечатанного фото. Используются одно или несколько изображений другого человека.
Атака с воспроизведением видео. Используется видеоряд с другим человеком.
Атака с распечатанной бумажной маской. Злоумышленник закрывает свое лицо изображением лица другого человека, вырезанным из фото.
Атака с 3D-маской. Злоумышленник надевает 3D-маску с изображением лица другого человека.

Для Liveness доступна возможность лицензировать количество выполненных транзакций. Также можно выбрать между безлимитной лицензией и лицензией с ограниченным числом транзакций (Максимально в ключе может быть задано 16 777 215 транзакций). После исчерпания лимита транзакций будет невозможно использовать оценку Liveness в запросах. На запросы не использующие Liveness или с отключённой оценкой Liveness исчерпание лимита не влияет, они продолжают работать в обычном режиме.

Результаты проверки Liveness#

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

Liveness probability (вероятностная оценка Liveness) [0..1]. Здесь 1 означает реального человека, 0 — подмена. Этот параметр показывает вероятность того, что на изображении присутствует живой человек, то есть это не атака на биометрическое предъявление. В целом, расчетная вероятность должна превышать порог Liveness.
Prediction (вердикт). На основе вышеперечисленных данных LUNA PLATFORM выдаёт следующие вердикты:
0 (spoof). Проверка выявила, что человек не является реальным.
1 (real). Проверка выявила, что человек является реальным.

Запросы для проверки Liveness#

Liveness используется в следующих ресурсах:

События можно фильтровать по результатам оценки Liveness в ресурсах "handlers/{handler_id}\/events" и "/verifiers/{verifier_id}\/verifications", т.е. можно исключить результаты "spoof" или "real" из обработки изображений.

Фильтрация по результатам оценки Liveness доступна в следующих сценариях:

при выполнении операций сравнения;
при выполнении задач;
при отправке данных через веб-сокет.

Можно также задать параметр оценки Liveness при создании и сохранении событий вручную в ресурсе "handlers/{handler_id}\/events/raw".

Для многократно загружаемых изображений можно агрегировать результаты по результатам оценки Liveness для получения более точных данных.

Требования Liveness#

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

Параметры	Требования
Минимальное разрешение для мобильных устройств	720x960 пикселей
Максимальное разрешение для мобильных устройств	1080x1920 пикселей
Минимальное разрешение для веб-камер	1280x720 пикселей
Максимальное разрешение для веб-камер	1920x1080 пикселей
Сжатие	Нет
Биометрический образец	Нет
Обрезка изображения	Нет
Наложение эффектов	Нет
Маска	Нет
Количество лиц в кадре	1
Ширина bbox детекции лица	Более 200 пикселей
Отступ от краев кадра	Более 10 пикселей
Положение головы	от -20 до +20 градусов для наклона головы, рыскания и крена
Качество изображения	Лицо в кадре не должно быть переэкспонировано (light), недоэкспонировано (dark) или размыто (blur).
См. раздел "Качество изображения" для подробной информации по пороговым значениям качества изображения.

Порог Liveness#

Для корректировки оценки Liveness используется порог Liveness.

Порог Liveness — порог, ниже которого система будет считать результат атакой на биометрическое предъявление ("spoof"). Данный порог задается в настройке "real_threshold" из секции "LUNA_REMOTE_SDK_LIVENESS_ESTIMATOR_SETTINGS" сервиса Configurator. Значение порога по умолчанию — 0.5 (50%).

Для изображений, полученных с мобильных устройств, рекомендуется задавать порог 0.5. Для изображений, полученных с веб-камеры, рекомендуется задавать порог 0.364. При этом значении порога получаются приблизительно равные результаты по точности работы алгоритма.

Изменение порога на ресурсах «/handlers» и «/verifiers»#

В ресурсах "/handlers" и "/verifiers" есть один дополнительный параметр — "liveness_threshold", который задаёт порог Liveness threshold

Задание данного параметра переопределяет значение настройки "real_threshold" из секции "LUNA_REMOTE_SDK_LIVENESS_ESTIMATOR_SETTINGS" сервиса Configurator.

Изменение порога на ресурсах «/liveness», «/sdk» и «/videosdk»#

Для ресурсов "/liveness", "/sdk" и "/videosdk" нет дополнительных параметров для переопределения порога. Порог задается в настройке "real_threshold" из секции "LUNA_REMOTE_SDK_LIVENESS_ESTIMATOR_SETTINGS" сервиса Configurator.

Видеоаналитика#

В LUNA PLATFORM доступна возможность выполнения видеоаналитики с помощью двух способов:

ресурса "/videosdk" с включенным сервисом Video Agent
группы ресурсов "/streams" с включенными сервисами Video Agent и Video Manager (далее - функционал потоков для видеоанализа).

Основные возможности ресурса "/videosdk":

обработка одного видеофайла в один момент времени
обработка видеофайлов в фоновом режиме
выполнение аналитик подсчета количества людей и отслеживания людей
выдача информации только в теле ответа на запрос

Основные возможности группы ресурсов "/streams", реализующих функционал потоков:

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

В данном разделе описываются базовые понятия видеоаналики. См. подробное описание работы с группой ресурсов "/streams" в разделе "Функционал потоков для видеоанализа".

Важно! Обобщенное событие никак не связано с событиями, генерируемыми по обработчикам.

Поскольку оба способа преследуют разные цели, то для них может быть свой набор определенных параметров и значений. Например, при использовании функционала потоков доступна возможность задать момент генерации события (в начале трека, в конце трека, периодически), тогда как в ресурсе "videosdk" такой возможности нет. Особенности наличия тех или иных параметров приведены в соответствующих разделах ниже.

Важно! На данный момент функционал видеоаналитики находится в статусе бета-тестирования. Входные и выходные схемы могут быть изменены в будущих релизах без поддержки обратной совместимости.

Видеоаналитика — это набор функций, которые обрабатывают кадр за кадром и оценивают полезные данные.

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

При необходимости можно повернуть видео или видеопоток перед его обработкой на угол 90, 180 или 270 градусов.

В процессе выполнения видеоаналитики генерируется определенное количество событий по некоторым правилам, где каждое событие имеет начало и конец. События содержат специфическую информацию конкретной видеоаналитики. В ответе также содержится базовая метаинформация о видео (количество кадров, частота кадров, длительность видео).

Настройки обработки видео, такие как количество рабочих процессов декодера, тип процессора для декодирования видео, временная директория для хранения видео пр., можно задать в группе настроек "LUNA_VIDEO_AGENT_VIDEO_SETTINGS".

Видеоаналитика подсчета количества людей#

Трек начинается тогда, когда на последнем кадре из указанного количества подряд идущих кадров (параметр "probe_count") появляется указанное число людей (параметр "people_count_threshold"). Например, если минимальное количество людей равно 10, а количество подряд идущих кадров равно 3, то в случае наличия на 3 кадрах 10 человек начнется трек с 3го кадра. Если на 2 кадрах 10 человек, а на 3 кадре 9 человек, то трек не начнется.

По умолчанию обрабатываются каждые 10 кадров. При необходимости можно настроить частоту обработки кадров с помощью параметра "rate" (например, обрабатывать каждые 3 секунды или каждые 3 кадра).

Логика генерации событий видеоаналитики отличается для запросов "videosdk" и сервисов видеоаналитики.

При выполнении аналитики с помощью ресурса "videosdk", количество событий будет равно количеству треков.

При выполнении видеоаналитики с помощью сервиса Video Agent, события видеоаналитики можно генерировать в следующих случаях (политика "event_policy"):

когда трек начинается ("trigger" > "start")
когда трек заканчивается ("trigger" > "end")
периодически пока трек существует ("trigger" > "period" и "interval")

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

В теле запросов можно задать параметр "targets", принимающий следующие значения:

"coordinates" — вычисление координат людей
"overview" — получение изображения с максимальным количеством людей и включение сохранения изображений. При необходимости можно детально настроить качество, формат и максимальный размер сохраняемого изображения с помощью группы параметров "image_retain_policy".

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

Для такой видеоаналитики также доступна возможность настроить область интереса ROI или область интереса DROI на кадре (координаты "x", "y", ширина, высота, единицы измерения — проценты или координаты). Принцип работы области интереса ROI аналогичен FaceStream.

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

"event_id" — идентификатор события
"track_id" — идентификатор трека, связывающий события, генерируемые в рамках одного непрерывного наблюдения
"people_count" — максимальное количество людей, обнаруженное на обработанном сегменте видео
"video_segment" — информация о сегменте видео (время начала события, время конца события, номер первого кадра, номер последнего кадра)
"frames_estimations" (только ресурс "videosdk") — массив с информацией об оценках на каждом кадре, содержащий следующую информацию:
- координаты людей
- время, соответствующее кадру
- количество людей
"overview" — информация о кадре на видео, где было найдено больше всего людей:
- изображение
- время, соответствующее кадру
- координаты людей

Видеоаналитика отслеживания людей#

В случае видеоаналитики отслеживания людей, трек — объект, содержащий информацию о положении одного человека на последовательности кадров. Трек создается тогда, когда на последнем кадре из указанного количества подряд идущих кадров (параметр "probe_count") появляется детекция лица, тела или тела с лицом (зависит от типа детектора в параметре "detector_type"). Треков может быть столько, сколько людей было обнаружено на кадре.

При выполнении видеоаналитики с помощью запроса "videosdk" для одного трека может быть только одно событие.

Например, если "probe_count" = "3" и на двух подряд идущих кадрах есть детекции, а на третьем нет, то трек и событие не начнутся. Если в какой-то момент отслеживания человека на двух подряд идущих кадрах были детекции, а на третьем кадре детекция отсутствует, то трек и событие закончатся.

При выполнении видеоаналитики с помощью расширенного функционала потоков, события видеоаналитики можно генерировать в следующих случаях (политика "event_policy"):

когда трек начинается ("trigger" > "start")
когда трек заканчивается ("trigger" > "end")
периодически пока трек существует ("trigger" > "period" и "interval")

Во время отслеживания человека доступна возможность выполнить оценку атрибутов лиц, тел, изображения, оценки Deepfake и OneShotLiveness (только ресурс "videosdk"), а также получить изображение, в котором была лучшая детекция. Перечень оценок задается в параметре "targets" и отличается в зависимости от способа выполнения аналитики ("videosdk" или расширенного функционала потоков). Оценка может быть выполнена по одному лучшему снимку из трека или по нескольким (параметр "face_samples"/"body_samples" > "count"). При необходимости можно фильтровать лучшие снимки по параметрам "score", "head_pitch", "head_roll", "head_yaw".

При необходимости можно включить повторную идентификацию тела (ReID). Функция ReID используется для повышения точности отслеживания путем объединения различных треков одного человека.

Для такой видеоаналитики также доступна возможность настроить область интереса ROI или область интереса DROI на кадре (координаты "x", "y", ширина, высота, единицы измерения — проценты или координаты). Принцип работы области интереса ROI аналогичен FaceStream.

В каждом событии видеоаналитики отслеживания людей содержится следующая информация:

"event_id" — идентификатор события видеоаналитики
"track_id" — идентификатор трека, связывающий события, генерируемые в рамках одного непрерывного наблюдения
"people_count" — максимальное количество людей, обнаруженное на обработанном сегменте видео
"video_segment" — информация о сегменте видео (время начала события, время конца события, номер первого кадра, номер последнего кадра)
"frames_estimations" — массив с информацией об оценках на каждом кадре, содержащий следующую информацию:
- номер кадра
- время, соответствующее кадру
- количество людей
"overview" — информация о кадре на видео, где было найдено больше всего людей:
- изображение
- время, соответствующее кадру
- координаты людей

При использовании расширенного функционала потоков, в каждом событии также отображается идентификатор потока и местоположение, задаваемое в запросе на создание потока.

Важно! В зависимости от длительности, разрешения и частоты кадров в секунду (fps) видео, выполнение видеоаналитики отслеживания людей с использованием ресурса "/videosdk" может занимать больше времени. В связи с этим, может потребоваться увеличить значения временных интервалов, которые регулируют таймауты HTTP-запросов. Для этого потребуется выполнить следующие действия: - перейти в интерфейс сервиса Configurator http://<your_server_ip_adress>:5070/; - ввести в поле "Setting name" значение "LUNA_REMOTE_SDK_TIMEOUTS" и нажать "Apply Filters"; - в Value задать значения "request": 320, "connect": 20, "sock_connect": 10, "sock_read": 320.

roi#

ROI задаёт область интереса в которой происходит оценка.

Указанная прямоугольная область вырезается из кадра и именно это изображение в дальнейшем обрабатывает LUNA PLATFORM.

Правильное использование параметра "roi" существенно повышает производительность видеоанализа.

Область интереса ROI на исходном кадре задается параметрами "x", "y", "width", "height" и "mode", где:

"x" и "y" – координаты верхней левой точки области интереса ROI;
"width" и "height" — ширина и высота обрабатываемой области кадра;
"mode" – режим указания "x", "y", "width" и "height". Доступно два режима:
"abs" — параметры "x", "y", "width" и "height" задаются в пикселях;
"percent" — параметры "x", "y", "width" и "height" задаются в процентах от текущего размера кадра.

Если поле "mode" не указывается в теле запроса, то будет использовано значение "abs".

При значениях ширины и высоты, равных "0", областью интереса считается весь кадр.

Система координат на изображении задается аналогично рисунку ниже.

Ниже приведен пример расчета ROI в процентах:

droi#

DROI задаёт область интереса относительно исходного кадра. Если ROI предназначен для оптимизации эстимации соответствующих свойств, то DROI работает как фильтр после выполненной эстимации и предназначен для реализации бизнес-логики. Можно использовать DROI как вместе с ROI, так и отдельно. Например, если после обработки по области ROI количество людей на кадре было равно N, то после выполнения дополнительной фильтрации по области DROI количество людей на кадре может быть уменьшено до M.

Область интереса DROI на исходном кадре задается следующими параметрами:

"area" — геометрия области интереса. Параметр представлен в виде массива полигонов. Каждый полигон представлен массивом объектов, где каждый объект содержит координаты вершины полигона (x и y). Так, например, можно задать треугольную область интереса.
"mode" – режим указания "x", "y". Доступно два режима:
"abs" — параметры "x", "y" задаются в пикселях;
"percent" — параметры "x", "y" задаются в процентах от текущего размера
"form" — формат области интереса. Может принимать значения: "common" - общий формат и "wkt" (Well-known text) - текстовый формат представления геометрических объектов.

Обработка видео в фоновом режиме#

Чтобы запустить анализ видео на основе указанных параметров аналитики в фоновом режиме необходимо выполнить запрос к ресурсу /videosdk с включенным параметром deferred_task, при этом будет выдан task_id для отслеживания её статуса.

Отследить статус задачи и получить URL-адрес результата (в случае успешного завершения) по task_id можно с помощью запроса get task.

За регулирование максимального количества одновременно выполняемых задач в фоновом режиме одним агентом отвечает параметр max_active_tasks в настройке LUNA_VIDEO_AGENT_SETTINGS. По умолчанию установлено значение 2. Созданные задачи будут выполняться в порядке очереди, если количество активных задач достигнет указанного лимита.

Функционал потоков для видеоанализа#

Сервис Video Manager реализует расширенный функционал работы с видеоаналитиками. Он позволяет создавать отдельные сущности потоки, содержащие всю информацию об обрабатываемом видеофайле или видеопотоке и видеоаналитике, которую нужно будет выполнить, а также позволяет гибко управлять потоками.

Функционал потоков основан на взаимодействии трех ключевых компонентов: аналитик, агента и сервиса Video Manager.

Примечание. Для возможности создания потоков требуется лицензируемая функция, определяющая максимально допустимое одновременное количество потоков, обрабатываемых сервисом Video Agent. Сервис Video Manager проверяет наличие лицензии каждый раз при создании потока, а также проверяет отчеты (если они есть) для определения количества обрабатываемых потоков сервисом Video Agent. См. подробную информацию о лицензируемых функциях в разделе "Сервис Licenses".

Аналитика

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

Агент

Агент — это компонент, который реализует алгоритмы видеоаналитики. Он принимает потоки, выполняет заданную аналитику и отправляет результаты через механизм Callback'ов.

В качестве агента по умолчанию используется сервис Video Agent, однако при необходимости можно написать собственного агента. См. пример кода в руководстве разработчика сервиса Video Manager.

Сервис Video Agent предоставляет следующие аналитики:

Video Manager

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

См. подробную информацию о взаимодействии сервиса Video Manager и агента в разделе "Взаимодействие Video Manager и агента".

Базовый принцип работы выглядит следующим образом:

Пользователь выполняет запрос на создание потока с помощью запроса "create stream".
Сервис Video Manager направляет поток агенту, способному обработать все аналитики, переданные в запросе.
Агент обрабатывает поток и отправляет статус обработки и возможные ошибки сервису Video Manager.
Агент отправляет результаты обработки в соответствии с выбранным типом Callback'ов (см. раздел "Отправка и сохранение результатов аналитики").

Также можно получить результаты обработки, выполнив запрос stream events ws handshake, позволяющий установить веб-сокет соединение для получения результатов обработки конкретного потока в реальном времени с помощью указания "stream_id".

Пользователь также может пересоздавать поток, получать статус обработки потока, останавливать и запускать поток и др. См. подробную информацию в группе запросов streams спецификации OpenAPI.

См. подробную информацию о том как пользователь использует сервисы видеоаналитики в разделе "Взаимодействие пользователя и Video Manager".

См. раздел "Быстрое начало по созданию потока" ниже для изучения базовых шагов по созданию потока.

См. подробную информацию в разделе "Взаимодействие Video Manager и агента".

Отправка и сохранение результатов аналитики#

Агент может отправлять результаты обработки через механизм Callback'ов с типами:

"http", предварительно настроив сервер для приема сообщений
"luna-ws-notification", предварительно установив веб-сокет соединение
"luna-event"

Типы "http" и "luna-ws-notification" являются стандартными. См. раздел "Отправка событий в сторонний сервис".

Если используются веб-сокеты, то сервис Sender должен быть включен в настройке "ADDITIONAL_SERVICE_USAGE" и должно быть установлено соединение с сервисом Sender (см. запрос "ws handshake for general events").

Тип "luna-event" предназначен для сохранения событий в базу данных Events с использованием механизма обобщенных событий. Получить такие события можно с помощью запросов "get general events" и "get general event", указав в качестве фильтра полученный идентификатор "stream_id".

Также можно получать результаты эстимации (не события) в режиме реального времени с помощью запроса "stream events ws handshake". Так, например, если выполняется аналитика количества людей, то можно получать координаты людей в тот момент, когда они появляются на кадре.

При создании потока можно настроить отправку уведомлений об изменениях статуса обработки потока с помощью параметра notification_policy. Для отправки уведомлений доступны два типа callback'ов:
- http — уведомления отправляются на указанный URL-адрес;
- telegram — уведомления отправляются в Telegram-чат. Для этого требуется указать идентификатор чата chat_id, и токен авторизации token для Telegram.

См. запрос create stream.

Аналитики#

С точки зрения сервиса Video Manager, аналитика представляет собой объект, содержащий имя, неизвестный набор параметров и, при необходимости, описание и документацию. Аналитику создает либо агент, либо администратор, отправляя запрос "create analytic" в сервис Video Manager.

В сервисе Video Agent доступно две аналитики - people_count и human_tracking. Аналитики автоматически регистрируется при запуске сервиса Video Agent.

Video Manager распределяет потоки по агентам, в том числе опираясь на знание того, какой агент готов сделать ту или иную аналитику. Когда агент или администратор создает аналитику, он может указать набор параметров, которые будут использоваться при запуске аналитики. Однако при создании запроса на обработку потока пользователь может указать и другие параметры, которые будут использоваться в рамках этой аналитики (используя параметр "analytics" > "parameters" запроса "create stream").

Примечание. Важно учитывать, что минимальные системные требования указаны исключительно для распознавания лиц и тел без учёта задач видеоаналитики (отслеживание людей, подсчёт количества людей и др.). Ресурсы, необходимые для выполнения этих аналитик, рассчитываются индивидуально в зависимости от используемой аналитики.

Подробная информация о доступных параметрах и их описаниях различна для каждой аналитики. Она доступна в документации соответствующей аналитики и может быть получена в ответ на запрос "get analytics".

Взаимодействие пользователя и Video Manager#

Для выполнения аналитики потока пользователь должен создать поток, указав желаемую аналитику.

Для создания потока необходимо сделать запрос "create stream". Для пересоздания потока необходимо сделать запрос "put stream", в этом случае будут использованы новые данные потока, а версия потока будет увеличена на 1.

После появления нового потока он переходит в статус "pending".

Когда поток обрабатывается одним из доступных агентов (см. раздел "Распределение потоков"), он будет иметь статус "in_progress".

Пока происходит обработка потока, агент отправляет обратную связь сервису Video Manager, который создает логи, которые может получить пользователь, выполнив запрос "get streams logs".

Обработку потока можно остановить:

по запросу пользователя (запрос "patch stream" с параметром "action" = "stop"). В таком случае статус потока будет "stop".
по запросу пользователя (запрос "remove stream"). В таком случае поток будет удален.
когда поток закончится. В таком случае статус потока будет "done".
при возникновении фатальной ошибки. В таком случае статус потока будет "failure".

Во всех случаях, за исключением ручного удаления логов с помощью запроса "delete stream logs", логи потоков будут доступны после выполнения запроса "get streams logs".

Во всех случаях, за исключением удаления потока с помощью запроса "remove stream", данные потока будут доступны после выполнения запроса "get stream".

Взаимодействие Video Manager и агента#

Взаимодействие сервиса Video Manager и агента описано ниже:

Агент или администратор должен зарегистрировать в сервисе Video Manager аналитику с которой агент умеет работать, выполнив запрос к ресурсу /1/analytic сервиса Video Manager.
При старте агент должен выполнить запрос к ресурсу /1/agent сервиса Video Manager на регистрацию самого себя. В данном запросе указываются следующие параметры:
- имя агента (обязательно)
- максимальное количество потоков, которое может обрабатывать агент (обязательно)
- набор аналитик, с которыми может работать агент (обязательно)
- описание агента
В ответе на запрос агент получит уникальный идентификатор "agent_id".
Агент периодически должен выполнять запросы к ресурсу /1/agent/{agent_id}/streams сервиса Video Manager для получения/остановки потока на обработку.

Как только агент получил поток на обработку, сервис Video Manager запускает счетчик потоков, обрабатываемых данным агентом.

Обратите внимание, что если агент не сделает такой запрос вовремя, статус агента будет помечен как "not_ready" и агент будет исключен из списка агентов, которые могут обрабатывать потоки (подробности см. в разделе "Управление статусом агента в случае отсутствия запроса агента").
Во время обработки, агент должен отправлять обратную связь о статусе обработки потока к ресурсу /1/agent/{agent_id}/streams/feedback.

Отчет содержит идентификатор потока, его статус, ошибку, версию потока и время генерации отчета. После отправки отчета пользователь может получить логи обработки с помощью запроса "get streams logs".

Обратите внимание, что пользовательский агент должен вышеописанные действия. См. пример кода в разделе "Agent interaction" в руководстве разработчика сервиса Video Manager.

Сервис Video Agent автоматически выполняет вышеописанные действия.

Потоки#

Потоки создает пользователь с помощью запроса "create stream".

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

"type" - тип источника: видеофайл или видеопоток
"reference" - адрес источника
"rotation" - угол поворота кадра камеры
"downloadable" - определяет необходимость предварительного скачивания видеофайла перед его обработкой

Предварительная загрузка необходима для:
- Успешного декодирования видеофайлов. Для некоторых файлов могут возникнуть ошибки декодирования, если файлы не будут предварительно сохранены.
- Длительных процессов обработки. Если обработка видео занимает значительное время, хранение предотвращает проблемы, связанные с разрывом соединения.
Обратите внимание, что иногда политики безопасности запрещают сохранение видеофайлов. В таких случаях предварительное скачивание может быть не применимо.
"timestamp_source" - определяет, откуда будут браться временные метки для видеоанализа.

Доступны следующие значения:
- "pts" - Использует временные метки видео, если они существуют, для точного отображения времени воспроизведения. Метки не всегда могут быть корректными (см. ниже).
- "server" - Применяет серверное время для видеопотока, что гарантирует единообразие и синхронизацию с другими событиями.
- "frame_rate" - Применяет частоту кадров для видеофайлов, что помогает приблизительно определить временные метки.
- "auto" (по умолчанию) - Автоматически выбирает источник времени, сначала проверяя временные метки ("pts"), а затем переключаясь на серверное время ("server") или частоту кадров ("frame_rate"), если метки некорректны.
Корректные метки для видеофайла означают, что временные метки (PTS) должны быть близки к нулю, то есть время от начала видео до метки должно быть относительно небольшим (абсолютное значение не должно превышать 10^5 секунд).

Корректные метки для видеопотока означают, что время видеопотока отличается от времени сервера менее чем на 1 день.
"pts" > "start_time" - смещение для временных меток видео (PTS)

Указание смещения позволяет синхронизировать начало обработки видео с конкретным моментом времени. Это может быть полезно, например, если видео обрабатывается частями и необходимо, чтобы временные метки новых частей продолжали последовательность с предыдущих. Таким образом, при нарезке большого видео на маленькие фрагменты, временные метки будут отображаться так, как если бы обрабатывалось одно целое видео.

Формат потоков, поддерживаемый сервисом Video Agent#

Сервис Video Agent может обрабатывать потоки в различных форматах. Если формат потока не соответствует поддерживаемым, возникает ошибка. При этом ведется запись логов и поток считается неудачным. В общем, сервис Video Agent поддерживает обработку всех потоков, которые могут быть обработаны с использованием ffmpeg, но существует известное ограничение на формат пикселей. Сервис Video Agent поддерживает следующие форматы пикселей: BGR, BGR_32F, NV12, P10, P12, RGB, RGB_32F, RGB_32F_PLANAR, RGB_PLANAR, YCBCR, YUV420, YUV420_10bit, YUV422, YUV444, YUV444_10bit.

Если поток имеет формат, который не поддерживается, его можно перекодировать, например, с помощью ffmpeg:

ffmpeg -rtsp_transport tcp -i <входной_поток> -rtsp_transport tcp -pix_fmt yuv420p -c:v copy -f rtsp <выходной_поток>

Важно! Описание выше распространяется только на сервис Video Agent. Если у пользователя собственный агент, то пользователь самостоятельно настраивает формат обработки потоков.

Статусы потока#

Поток может иметь следующие статусы:

"pending" — поток взят в работу, но пока не найдено ни одного агента. Такой статус может быть сразу после создания, пересоздания потока и во время автоматического перезапуска
"in_progress" — поток обрабатывается агентом
"done" — поток полностью обработан
"restart" — сервер перезапустил обработку потока с помощью автоматического перезапуска
"failure" — от агента был получен отчет об ошибке обработки потока
"cancel" — обработка потока была отменена, т.к. поток был удален из сервиса Video Manager
"stop" — поток был остановлен с помощью запроса "patch stream"

Жизненный цикл потока#

Жизненный цикл потока представлен ниже:

Поток создается с помощью запроса "create stream". Статус изменяется на "pending"
Агент принимает поток для обработки. Статус изменяется на "in_progress".
Опционально. Выполняется остановка/продолжение обработки потока:
- Выполняется запрос "patch stream" с параметром "action" = "stop". Статус изменяется на "stop"
- Выполняется запрос "patch stream" с параметром "action" = "resume". Статус изменяется на "pending" до того момента, как очередной агент не возьмет поток в обработку. При этом статус изменится на "in_progress"
Окончание обработки:
- Окончание потока. Агент останавливает обработку и отправляет обратную связь сервису Video Manager. Статус изменяется на "done".
- Поток удаляется с помощью запроса "remove stream".
- Обработка заканчивается из-за ошибки, которую отправляет агент в обратной связи. Статус потока меняется на "failure".

Автоматический перезапуск потоков#

Возможность автоматического перезапуска потоков актуальна только для потоков со статусом "failure". Параметры автоматического перезапуска (возможность перезапуска, максимальное количество попыток перезапуска, задержка между попытками) задаются пользователем для каждого потока в разделе "autorestart" запроса "create stream". Параметры и статус автоматического перезапуска можно получить с помощью запроса "get stream".

Ниже перечислены статусы автоматического перезапуска:

"disabled" — автоматический перезапуск отключен пользователем (отключен параметр "restart")
"enabled" — автоматический перезапуск включен, но в данный момент не активен поскольку поток не находится в статуса "failure"
"in_progress" — автоматический перезапуск в процессе
"failed" — превышено допустимое количество попыток автоматического перезапуска и ни одна попытка не увенчалась успехом

Распределение потоков#

Сервис Video Manager распределяет потоки, предоставленные пользователями агентам, следующим образом:

выбирает все потоки, которые требуют обработки (обработке подлежат только потоки со статусом "pending"). См. раздел "Статусы потока" для более подробной информации.
выбирает все доступные агенты, количество потоков обработки которых в текущем режиме не достигает максимального количества потоков, доступных для одновременной обработки агентом. См. раздел "Взаимодействие Video Manager и агента" для более подробной информации.
в порядке очередности создания потоков выбирает агента для каждого потока, удовлетворяющего следующим условиям:
- агент может обрабатывать аналитику, указанную для потока
- есть свободный слот для потока (агент предоставляет параметр max_stream_count - максимальное количество потоков, доступных ему для одновременной обработки, поэтому количество одновременных потоков для агента не может превышать это число)
вносит необходимые записи в базу данных для ответа на запрос агента в соответствии с предыдущей логикой
агент получает 2 типа потоков через запрос "get agent streams" — потоки, которые необходимо обработать, и потоки, обработка которых должна быть остановлена. Поток, однажды упомянутый в ответе на запрос, как поток, обработка которого должна быть начата, больше не будет упоминаться в ответах на этот запрос до тех пор, пока его обработку не потребуется остановить. То же самое относится и к потокам, обработку которых необходимо остановить — они больше не будут упоминаться в ответах на этот запрос до тех пор, пока их обработку не потребуется начать снова.

Описанная процедура будет выполняться как периодическая фоновая задача главного экземпляра. Период выполнения можно настроить с помощью параметра luna_video_manager_streams_agent_search_interval. Рекомендуется проконсультироваться со специалистами VisionLabs перед изменением данного параметра.

Процесс перезапуска потоков#

Ниже описан процесс обработки потоков с включенным автоматическим перезапуском. Описанные действия будут выполняться как периодическая фоновая задача главного экземпляра сервиса Video Manager, период выполнения можно настроить с помощью параметра luna_video_manager_streams_autorestarter_interval. Рекомендуется проконсультироваться со специалистами VisionLabs перед изменением данного параметра.

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

статус потока изменяется сначала на "restart", а затем на "pending";
счетчик попыток автоматической перезагрузки "current_attempt" увеличивается на 1;
запись времени последней попытки "last_attempt_time" обновляется, чтобы отразить актуальное время.

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

статус потока должен находиться в состоянии "failure";
должен быть включен автоматический перезапуск потока (параметр "restart");
значение текущей попытки автоматической перезагрузки "current_attempt" должно быть равно "null" или меньше, чем максимальное число попыток "attempt_count";
время последней попытки автоматической перезагрузки "last_attempt_time" должно быть равно "null" или разница между текущим временем и временем последней попытки должна быть больше или равна задержке "delay".

Если соблюдаются условия ниже, то произойдет сбой автоматического перезапуска потока (прекращение попыток перезапуска):

статус потока находится в состоянии "failure";
статус автоматического перезапуска потока находится в состоянии "in_progress";
значение текущей попытки автоматической перезагрузки "current_attempt" равно значению максимального числа попыток "attempt_count".

Если соблюдаются условия ниже, то произойдет завершение работы автоматического перезапуска потока:

статус потока не равен статусу "failure";
статус автоматической перезагрузки потока находится в состоянии "in_progress";
время последней попытки автоматической перезагрузки "last_attempt_time" равно "null" или разница между текущим временем и временем последней попытки больше или равна задержке "delay".

Группировка потоков#

Потоки можно группировать. Группировка призвана объединять потоки с множеством камер в логические группы. Например, можно группировать потоки по территориальному признаку.

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

Группа создается с помощью запроса "create group". Для создания группы нужно указать обязательный параметр "group_name". При необходимости можно указать описание группы.

Поток может быть привязан к группе с помощью параметров "group_name" или "group_id" во время создания потока (запрос "create stream").

Если поток был привязан к группе, то при запросе "get stream" или "get streams" группа будет отражена в поле "groups".

С помощью запроса patch streams in group можно привести все потоки группы в желаемое состояние (запуск/остановка). Изменения применяются только к тем потокам, которые находятся в отличном от целевого состоянии. Например, если необходимо запустить все потоки в группе, но некоторые из них уже запущены, то операция будет применена только к тем потокам, которые находятся в состоянии stop. Потоки, которые уже находятся в целевом состоянии (например, уже запущены pending), не будут изменены. Если в группе есть хотя бы один поток, который можно перевести в новое состояние (например, из stop в pending), запрос будет выполнен. Однако, если ни один поток нельзя изменить (например, все стримы уже находятся в целевом состоянии или их состояние нельзя изменить по другим причинам), будет возвращена ошибка с кодом 44015 и описанием Unable to patch streams. No streams suitable for patching.

Управлять удалением внутри группы можно с помощью следующих запросов:

remove all streams in the group позволяет удалить все потоки из группы, без удаления самой группы;
remove group выполняет удаление в зависимости от выставленного параметра with_streams:
- при значении 0 (по умолчанию) удаляется только группа, а потоки остаются без изменений;
- при значении 1 удаляются как группа, так и все связанные с ней потоки.

Работа с несколькими экземплярами#

Каждый экземпляр сервиса Video Manager может обслуживать ограниченное количество пользовательских запросов, а каждый агент может анализировать ограниченное количество потоков, поэтому эти сервисы можно масштабировать таким образом, чтобы каждый сервис Video Manager имел доступ к одной и той же базе данных и каждый агент имеет доступ к одному из экземпляров сервиса Video Manager.

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

Эти процессы должны выполняться только одним экземпляром, чтобы избежать состояния гонки, когда несколько экземпляров пытаются одновременно выполнять одни и те же задачи, что может привести к некорректной работе системы.

Выбор главного экземпляра#

Для выбора главного экземпляра каждый экземпляр сервиса пытается получить блокировку базы данных, обновляя поле в таблице single_process_lock. Если экземпляру удается получить блокировку, он объявляется главным экземпляром и сохраняет это состояние, регулярно отправляя в базу данных сигнал "heartbeat". Этот сигнал позволяет другим экземплярам знать, что главный экземпляр активен и выполняет свои задачи. Если сигнал "heartbeat" от главного экземпляра перестает поступать, это означает, что главный экземпляр больше не активен, и любой другой экземпляр может попытаться стать новым главным экземпляром, получив блокировку базы данных.

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

Обработка потоков в случае не появления обратной связи#

Процесс обработки видеопотоков подразумевает получение обратной связи для каждого потока, находящегося в состоянии "in_progress". Сервис Video Manager периодически проверяет время последнего получения обратной связи по каждому потоку. Если обратная связь не была получена в установленное время, статус потока изменится на "restart", что означает попытку заново начать обработку потока. Затем статус потока сразу изменяется на "pending", чтобы поставить его в очередь на обработку.

Проверка условий для обновления статуса потоков выполняется как периодическое фоновое задание главным экземпляром. Период выполнения можно настроить с помощью параметра luna_video_manager_stream_status_obsoleting_interval. Потоки будут считаться устаревшими, если время последнего получения обратной связи превышает установленный период, который настраивается с помощью параметра luna_video_manager_stream_status_obsoleting_period.

Рекомендуется проконсультироваться со специалистами VisionLabs перед изменением данных параметров.

Управление статусом агента в случае отсутствия запроса агента#

Взаимодействие с агентами подразумевает периодические запросы к сервису Video Manager (см. раздел "Взаимодействие Video Manager и агента"). Сервис Video Manager периодически проверяет время последнего запроса агентов на обработку потоков, и если это время было слишком давно, статус агента изменяется на "not_ready", что означает исключение агента из очереди распределения потоков.

Если такой агент позже сделает запрос на обработку потоков, его статус будет обновлен на "ready", и агент будет добавлен в список агентов, которые могут обрабатывать потоки.

Проверка условий для обработки потоков в случае отсутствия запроса агента выполняется как периодическое фоновое задание главным экземпляром. Период выполнения можно настроить с помощью параметра luna_video_manager_agent_status_obsoleting_interval. Агенты будут считаться не готовыми, если последний запрос от агента не был получен вовремя, что можно настроить с помощью параметра luna_video_manager_agent_status_obsoleting_period.

Рекомендуется проконсультироваться со специалистами VisionLabs перед изменением данных параметров.

Быстрое начало по созданию потока#

В данном примере будут описаны базовые действия для создания потока, его обработки и просмотра результатов обработки. В качестве агента будет использоваться сервис Video Agent.

1) Подготовьте тело запроса "create stream".

Секция "analytics" > "parameters" отличается для каждого типа аналитики. Узнать параметры конкретной аналитики можно с помощью соответствующих спецификаций в комплекте поставки по пути docs/ReferenceManuals или на сайте с онлайн-документацией.

Онлайн-документация:

Также можно получить документацию аналитики с помощью запроса "get analytic documentation", указав идентификатор аналитики, который можно получить с помощью запроса "get analytics". Запрос "get analytic documentation" подразумевает обращение к ресурсу /6/analytics/{analytic_id}/docs. Рекомендуется открывать данный ресурс в браузере или указывать заголовок "Accept" = "text/html" для корректного отображения HTML-документации.

Содержимое параметров аналитики необходимо добавить в тело запроса "create stream".

Например, можно создать следующее тело запроса для аналитики people_count:

{
    "name": "name_example",
    "description": "description_example",
    "data": {
        "type": "videofile",
        "reference": "https://example.com/humantracking.mp4",
        "rotation": 0
    },
    "location": {
        "city": "Moscow",
        "area": "Central",
        "district": "Basmanny",
        "street": "Podsosensky lane",
        "house_number": "23 bldg.3",
        "geo_position": {
            "longitude": 36.616,
            "latitude": 55.752
        }
    },
    "autorestart": {
        "restart": 0,
        "attempt_count": 10,
        "delay": 60
    },
    "analytics": [
        {
            "analytic_name": "people_count",
            "parameters": {
                "parameters": {
                    "probe_count": 2,
                    "image_retain_policy": {
                        "mimetype": "PNG"
                    }
                },
                "callbacks": [
                    {
                        "type": "luna-event",
                    }
                ],
                "targets": [
                    "coordinates",
                    "overview"
                ]
            }
        }
    ]
}

Сохраните полученный идентификатор "stream_id".

2) Выполните запрос "get general events" или "get general event" с приминением фильтра по "stream_id".

Фильтры#

В LUNA PLATFORM доступна возможность фильтровать объекты по определенным правилам. Например, можно сравнивать лица только из определенного списка или получать события за какой-либо промежуток времени.

Как правило фильтры расположены в поле "filters" различных запросов.

Фильтры по операторам сравнения#

Для некоторых фильтров доступно указание операторов сравнения с помощью суффикса "__operator". Оператор используется как для временных фильтров (с какой-то даты, за какое-то время), так и для обычных фильтров (за какой-то возраст человека, за перечень идентификаторов в лексикографическом порядке).

__lt

Фильтр "less than" используется для поиска значений меньше заданного. Например, при использовании фильтра "create_time__lt": "2022-08-11T09:11:41.674Z" в запросе "get events" будут возвращены события с временем создания, предшествующим указанной дате и времени, т.е. события созданные до 11 августа 2022 года, 09:11:41.674 по времени UTC.

__lte

Фильтр "less than or equal to" используется для поиска значений меньше или равных заданному. Например, при использовании фильтра "face_id__lte": "2046d39b-410d-481e-b9de-ede6a0c7367f" в фильтрах запроса "matching faces" для кандидатов, будут возвращены только те кандидаты, чьи идентификаторы начинаются с "2046d39b-410d-481e-b9de-ede6a0c7367f" или меньше этого значения в лексикографическом порядке.

__gte

Фильтр "greater than or equal to" используется для поиска значений больше или равных заданному. Например, при использовании фильтра "similarity__gte": "0.9" в политике "storage_policy" > "face_sample_policy" > "filters" > "match" запроса "create handler" можно настроить правило сохранения биометрического образца лица в БД Faces только в том случае, если политика "matching_policy" определила, что схожесть кандидата с эталоном больше или равна "0.9".

Фильтры now-time#

Для временных фильтров "create_time", "insert_time" и "end_time" доступен формат задания времени относительно текущего времени (формат "now-time"). Например, при создании расписания для задачи Garbage collection можно указать фильтр "create_time__lt": "now-30d", что позволит удалить все объекты кроме тех, что создавались за последние 30 дней.

Необходимо помнить, что:

при создании расписания, текущее время будет отсчитываться не от создания расписания, а от создания задачи расписанием в соответствии с cron-выражением;
при генерации события по обработчику в котором указан фильтр "now-time" (например в политике "matching_policy" > "candidates"), текущее время будет отсчитываться от момента генерации события.

Для использования времени относительно генерации события можно задавать политики непосредственно в запросе на генерацию события с помощью схемы "multipart/form-data" или с помощью задачи Estimator с созданием нового обработчика.

В этом формате время задаётся по следующему шаблону 'now-(\d+)[smhdwMy]', где "[d+]" — число, "[smhdwMy]" — необходимый период: m (минуты), h (часы), d (дни), w (недели), M (месяцы), y (годы).

Пользовательские интерфейсы#

Веб-сервис LUNA CLEMENTINE 2.0#

Для выполнения основных запросов LP для создания объектов и выполнения операций сравнения может использоваться веб-сервис LUNA CLEMENTINE 2.0.

Данный сервис не поставляется вместе с LUNA PLATFORM 5, его необходимо скачивать и настраивать отдельно.

Интерфейсы сервисов Backport 3 и Backport 4#

В LUNA PLATFORM 5 доступны интерфейсы для взаимодействия с API LP 4 и LP 3. Интерфейсы предназначены только для тех пользователей, которые предпочли не переходить на новую версию API LUNA PLATFORM 5. Они не включают в себя большинство функций, доступных в LP 5, и никогда не будут включать.

Сервис	Описание	Данные для входа по умолчанию	Порт по умолчанию
Backport 4	Интерфейс для работы с API LP 4	-	4200
Backport 3	Интерфейс для работы с API LP 3	Для входа в интерфейс требуется создать аккаунт на вкладке Sign Up.	4100

Прочие интерфейсы#

Данные интерфейсы нужны для упрощения работы с сервисами LUNA PLATFORM.

Сервис	Описание	Данные для входа по умолчанию	Порт по умолчанию
Configurator	Интерфейс для работы с настройками LUNA PLATFORM. Позволяет в одном месте настроить параметры всех сервисов. Особенно удобен, если включена автоперезагрузка сервисов после обновления настроек.	-	5070
Admin	Интерфейс для выполнения административных задач LUNA PLATFORM: создание аккаунтов через GUI, запуск и контроль выполнения длинных задач (задача Garbage collection task и задача Additional extraction).	root@visionlabs.ai/root	5010
InfluxDB	Интерфейс позволяет просматривать данные мониторинга сервисов LUNA PLATFORM.	luna/password	8086
Grafana (LUNA Dashboards)	Интерфейс для визуализации данных мониторинга LUNA PLATFORM, хранящихся в InfluxDB. Для него написаны дашборды для визуализации и фильтрации информации. Также можно использовать систему агрегации логов Grafana Loki.	admin/admin	3000

Отключаемые сервисы#

Некоторые неиспользуемые основные сервисы можно отключить. При отключении сервиса, его основные функции не будут работать. Так, например, если отключить сервис Tasks, то при попытке выполнить задачу будет возвращена ошибка или если отключить сервис Sender и использовать обработчик с политикой "notification_policy", то это также приведет к ошибке.

В итоге все ресурсы, которые требуют наличия отключенного сервиса будут возвращать ошибки вида <Service_name> service is disabled с кодом ответа 403.

Если в процессе работы LUNA PLATFORM произойдет сбой в работе какого-либо сервиса или он будет вручную остановлен, то работа зависимых сервисов завершится ошибкой. Например, при остановке сервиса Licenses, в логах сервиса Faces будет отображена следующая ошибка:

[0000001 2023-08-11 13:00:51.042000] ERROR: luna-faces 1690887528,00000000-0000-4000-a000-000000000001: Check connection to Luna Licenses : GET:http://127.0.0.1:5120/version:Cannot connect to host 127.0.0.1:5120 ssl:default [Connection refused]

Соответствующая ошибка будет возвращена при попытке сделать запрос, который зависит от проблемного сервиса.

Затем работа сервисов, зависимых от сервиса Faces, также будет завершена аналогичной ошибкой.

Проверить зависимость сервисов друг от друга можно с помощью диаграммы взаимодействия или можно найти настройку вида "service_name_ADDRESS" в настройках сервиса, для которого требуется определить зависимые сервисы. Например, в настройках сервиса Faces есть настройка "LUNA_LICENSES_ADDRESS", отвечающая за соединение с сервисом Licenses, а в настройках сервиса Admin есть настройка "LUNA_FACES_ADDRESS", отвечающая за соединение с сервисом Faces.

Отключение сервиса Configurator#

Сервис Configurator отключается посредством остановки контейнера.

При отключении сервиса Configurator, остальные сервисы будут использовать конфигурационные файлы config.conf, расположенные в директории srv/<service_name>/configs соответствующего контейнера.

Процесс отключения сервисов#

откройте пользовательский интерфейс Configurator http://<configurator_server_ip>:5070;
введите название настройки "ADDITIONAL_SERVICE_USAGE" в поле "Setting name" и нажмите "Apply Filters";
установите значение для необходимого сервиса "false";
сохраните изменения, нажав кнопку "Save".

Последствия отключения сервиса Image Store#

При отключении сервиса Image Store, существуют некоторые особенности, перечисленные ниже:

объекты типа images, objects, samples и политики сохранения биометрических образцов в обработчиках/верификаторах будут недоступны.
пропадет возможность использования всех задач, кроме задач Garbage Collection, Linker и Estimator, однако для этих задач есть ряд ограничений:
- Garbage Collection, Estimator, Linker: результаты задач/подзадач не будут сохраняться
- Garbage Collection, Estimator, Linker: после завершения подзадачи, статус задачи будет обновлен на Done и идентификатор результата задачи будет равен None
- Garbage Collection: удаление биометрических образцов станет недоступным
Если сервис Image Store отключается после того, как были сгенерированы события с включенной политикой "image_origin_policy", то при использовании задачи Garbage Collection и параметра remove_image_origins, сервис Tasks будет по-прежнему пытаться удалять исходные изображения, имеющие внешний URL-адрес.

Последствия отключения сервиса Image Store для Backport 3#

В сервисе Backport 3 доступна настройка "BACKPORT3_ENABLE_PORTRAITS", позволяющая отключить возможность использования портретов, но оставить возможность использования остального функционала сервиса Image Store. Если использование сервиса Image Store отключено в настройке "ADDITIONAL_SERVICES_USAGE", то вышеописанная настройка также должна быть отключена.

При отключении сервиса Image Store, БО и портреты станут недоступны, как и ресурсы "get portrait" и "get portrait thumbnail".

Последствия отключения сервиса Remote SDK#

При отключении сервиса Remote SDK:

будет недоступен весь функционал, связанный с нейронными сетями, а именно: обнаружение лиц и тел на изображениях, оценка параметров изображений, а также извлечение базовых атрибутов и биометрического шаблона;
будет отсутствовать возможность работы с задачей Additional extraction, а задача Estimator будет работать только в том случае, если обработчик, который используется этой задачей, не требует сервиса Remote SDK.

Последствия отключения сервиса Handlers#

При отключении сервиса Handlers:

запуск сервиса API приведет к отсутствию возможности использования следующих запросов:
- "detect faces";
- "extract attributes";
- "estimator task";
- все запросы на ресурс "/handlers";
- все запросы на ресурс "/verifiers".
запуск сервиса Tasks приведет к отсутствию возможности выполнения задач "Additional extraction" и "Estimator";
запуск сервиса Admin приведет к отсутствию возможности выполнения задачи "Additional extraction";

Последствия отключения сервиса Faces#

При отключении сервиса Faces:

работа с лицами, атрибутами и списками станет недоступна;
политика "storage_policy" > "face_policy" (и, соответственно, "link_to_lists_policy") обработчика/верификатора станет недоступна;
станет невозможно указывать лица в качестве кандидатов для сравнения в политике "match_policy" обработчика;
будет отсутствовать возможность работы с задачей Linker, а задачи Clustering, Reporter, Exporter, Cross-matching, Garbage Collection, Additional extraction и ROC-curve calculating во всех сервисах не смогут работать с лицами и атрибутами.

Последствия отключения сервиса Python Matcher#

Для обеспечения возможности выполнения запросов на матчинг требуется, чтобы хотя бы один из сервисов, Python Matcher или Python Matcher Proxy, оставался включенным; если же оба сервиса будут отключены одновременно, это приведёт к следующим последствиям:

станет невозможно использовать политику сравнения "match_policy" обработчика;
будет отсутствовать возможность выполнять запросы к ресурсу "/matcher";
создание задач Clustering, ROC-curve calculating и Cross-matching будет недоступно.

Последствия отключения сервиса Events#

При отключении сервиса Events:

можно будет создать обработчик с политикой сохранения события, однако само событие будет невозможно сгенерировать;
все запросы к ресурсу "/events" не будут работать;
запросы к ресурсам "/handlers/{handler_id}/events", "/handlers/{handler_id}/events/raw" не будут работать;
параметр "event_id" в запросе "create face" не будет работать;
сравнение по событиям-кандидатам будет недоступно;
фильтры по событиям в задачах будут недоступны;
использование запроса "ws handshake" не будет иметь смысла.

Последствия отключения сервиса Tasks#

При отключении сервиса Tasks:

все запросы к ресурсу "/tasks" (группы параметров "task processing", "task info", "task errors") не будут работать;
использование задач во всех сервисах будет недоступным.

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

Последствия отключения сервиса Sender#

При отключении сервиса Sender:

запрос "ws handshake" не будет работать;
политика "notification_policy" в обработчике не будет работать.

Отключение дополнительных сервисов#

Дополнительные сервисы также могут быть отключены, если ранее были включены.

Если сервис Python Matcher Proxy ранее использовался, то его отключение приведет к невозможности использования плагинов сравнения или модуля LIM.

Если сервис Lambda ранее использовался, то его отключение приведет к невозможности отправки запросов к ресурсам "/lambdas" и работе с созданной lambda.

Если сервисы Backport 3 или Backport 4 ранее использовались, то их отключение приведет к невозможности обработки запросов LUNA PLATFORM 3/4 с помощью LUNA PLATFORM 5.

Включение сервисов Backport 3, Backport 4, User Interface 3 и User Interface 4 регулируется только запуском соответствующих контейнеров. В настройках "ADDITIONAL_SERVICE_USAGE" нет параметров, включающих данные сервисы.

Шифрование биометрических шаблонов#

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

Примечание. Шифрование добавляет дополнительные вычислительные затраты, что приводит к замедлению процессов, таких как сравнение по базе, сравнение с использованием LUNA Index Module и синхронизация кеша в Cached Matcher.

В результате шифрования биометрические шаблоны хранятся в зашифрованном виде в базах данных Events, Faces или Attributes и в том же виде передаются во внешние системы. Соответственно, если включено шифрование, то на запросы, которые возвращают биометрический шаблон, будет получен именно зашифрованный биометрический шаблон.

Важно! LUNA PLATFORM не предназначена для одновременного использования зашифрованных и незашифрованных биометрических шаблонов. В случае обнаружения обоих видов биометрических шаблонов, сервис Python Matcher не запустится, выдав ошибку "Check is failed, encryption hash is not unique". Поэтому, при включении шифрования, необходимо остановить сервисы, ограничив тем самым все запросы, перевести все биометрические шаблоны на новую версию шифрования и только потом заново запускать сервисы. Крайне рекомендуется выполнения бекапа БД перед манипуляциями с шифрованием.

Примечание. Плагины для сравнения также необходимо обновить в соответствии с логикой шифрования. LUNA Index Module поддерживает работу с зашифрованными биометрическими шаблонами.

Формат зашифрованных биометрических шаблонов#

Зашифрованные биометрические шаблоны имеют следующий формат: <encrypted_descriptor><tag><nonce><hash>.

encrypted_descriptor — Зашифрованный биометрический шаблон.
tag — Данные, используемые для аутентификации сообщения.
nonce — Инициализационный вектор для шифрования.
hash — Хэш-сумма ключа шифрования и алгоритма.

Включение и настройка шифрования#

Шифрование можно включить и настроить с помощью группы параметров DESCRIPTOR_ENCRYPTION.

Для включения шифрования необходимо установить параметр enabled в значение true. Это активирует шифрование биометрических шаблонов в системе. Параметр algorithm задает используемый алгоритм шифрования (по умолчанию aes256-gcm).

Параметры шифрования указываются в разделе params. Здесь необходимо указать источник ключа шифрования с помощью параметра source. Поддерживаются два типа источников: raw и vaultKV.

При использовании raw, ключ шифрования указывается напрямую в параметре key.
При использовании vaultKV, ключ шифрования необходимо получать из хранилища Hashicorp Vault. В этом случае параметр key должен содержать URL для получения ключа и токен аутентификации. Пример конфигурации для vaultKV:

{
    "enabled": true,
    "algorithm": "aes256-gcm",
    "params": {
        "source": "vaultKV",
        "key": {
            "url": "https://vault.example.com/v1/secret/data/encryption_key",
            "token": "s.XYZ12345"
        }
    }
}

Hashicorp Vault — это инструмент для управления секретами и защиты конфиденциальных данных, таких как ключи шифрования.

Содержимое хранилища ключей/значений Vault должно быть в следующем формате:

{
    "key": "...",
    "algorithm": "..."
}

Управление шифрованием биометрических шаблонов#

При необходимости можно добавить шифрование для уже существующих биометрических шаблонов, заменить существующее шифрование или выполнить дешифрование биометрических шаблонов в БД Faces, БД Attributes или БД Events.

Для этого необходимо выполнить миграцию биометрических шаблонов с помощью скрипта descriptors_encryption.py, расположенного в контейнерах сервисов Faces и Events, передав в качестве аргументов скрипта данные о БД Faces/Attributes/Events, и передав в качестве переменных окружения соответствующий ключ и алгоритм следующим образом:

docker run \
--env=OLD_ENCRYPTION_KEY=<your_old_encryption_key> \
--env=NEW_ENCRYPTION_KEY=<your_new_encryption_key> \
--env=ENCRYPTION_ALGORITHM=aes256-gcm \
--rm \
...
dockerhub.visionlabs.ru/luna/luna-faces:v.4.13.9 \
python3 ./base_scripts/descriptors_encryption.py --luna-config=http://127.0.0.1:5070/1 --LUNA_FACES_DB=<LUNA_FACES_DB_TAG> --DATABASE_NUMBER=<DATABASE_NUMBER_TAG> --LUNA_ATTRIBUTES_DB=<ATTRIBUTES_DB_TAG>

Важно! Скрипт необходимо выполнять когда сервис остановлен.

В зависимости от сценария (добавление/обновления/дешифрования), определенные переменные окружения могут не использоваться. Например, при добавлении шифрования к биометрическим шаблонам без шифрования, переменная OLD_ENCRYPTION_KEY не будет использоваться.

См. подробную информацию о скрипте миграции биометрических шаблонов в разделе "Управление шифрованием биометрических шаблонов" в руководствах по обновлению в разделе "Дополнительная информация".

Особенности работы с сервисами#

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

Автоориентация повернутого изображения#

Не рекомендуется отправлять повернутые изображения на LP, поскольку они не обрабатываются должным образом и их необходимо поворачивать. Существует два метода автоматической ориентации повернутого изображения – на основе данных EXIF изображения (параметр запроса) и с использованием алгоритмов LP (настройка Configurator). Оба метода автоматической ориентации изображения можно использовать вместе.

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

Автоориентация на основе данных EXIF#

Этот способ ориентации изображения выполняется в параметрах запроса с помощью параметра "use_exif_info". С его помощью можно включать или отключать автоматическую ориентацию изображения на основе EXIF данных.

Данный параметр доступен и включен по умолчанию в следующих ресурсах:

Параметр "use_exif_info" нельзя использовать с биометрическими образцами. Если задан параметр "warped_image" или задано соответствующее значение параметра "image_type", то параметр "use_exif_info" будет игнорироваться.

Автоориентация на основе настроек сервиса Configurator#

Этот метод ориентации изображения используется в сервисе Configurator с помощью настройки "LUNA_REMOTE_SDK_USE_AUTO_ROTATION". Если эта настройка включена и входное изображение повернуто на 90, 180 или 270 градусов, то LP поворачивает изображение под соответствующим углом. Если эта настройка включена, но входное изображение не повернуто, LP не будет поворачивать изображение.

Выполнение автоматической ориентации требует значительного количества ресурсов сервера.

Настройку "LUNA_REMOTE_SDK_USE_AUTO_ROTATION" нельзя использовать с биометрическими образцами. Если задан параметр "warped_image" или задано соответствующее значение параметра "image_type", то настройка "LUNA_REMOTE_SDK_USE_AUTO_ROTATION" будет игнорироваться.

Особенности сохранения исходных изображений#

URL-адрес исходного изображения можно сохранить в поле "image_origin" созданных событий при обработке запроса "/handlers/{handler_id}/events".

Для этого при создании обработчика необходимо указать параметр "store_image" в "image_origin_policy".

Затем необходимо задать изображение для обработки в запросе "generate events".

Если "use_external_references"=0 и URL-адрес внешнего изображения был передан в запросе "generate events", то это изображение будет сохранено в хранилище Image Store, а идентификатор сохраненного изображения будет добавлен в поле "image_origin" сгенерированного события.

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

Если "use_external_references"=1 и URL-адрес внешнего изображения был передан в запросе "generate events", то этот URL-адрес будет добавлен в поле "image_origin". Само изображение не будет сохранено в Image Store.
Если "use_external_references"=1 и биометрический образец был передан в запросе "generate events" и включен параметр "face_sample_policy > store_sample", URL-адрес биометрического образца в Image Store будет сохранен в поле "image_origin". Таким образом, можно избежать дублирования изображения. Если внешний URL-адрес слишком длинный (более 256 символов), сервис сохранит изображение в Image Store.

Также можно непосредственно указать URL-адрес исходного изображения, используя ресурс "/handlers/{handler_id}/events". Для этого необходимо использовать в запросе схему тела "application/json" или "multipart/form-data". URL-адрес необходимо указывать в поле "image_origin" запроса.

Если поле "image_origin" не пустое, предоставленный URL-адрес будет использоваться в созданном событии независимо от политики "image_origin_policy".

Изображение, указанное в поле "image_origin", не будет обрабатываться в запросе. Оно используется только как исходное изображение.

Нейросети#

С помощью нейронных сетей выполняется оценивание параметров лиц или тел и извлечение их биометрических шаблонов.

Существует два типа нейронных сетей — для выполнения оценивания и для извлечения БШ.

Нейросети для выполнения обнаружения и оценивания расположены в контейнерах сервисов Remote SDK и Video Agent в формате <estimation_name>_<architecture>.plan, где <estimation_name> — название нейронной сети, <architecture> используемая архитектура (cpu-avx2 или gpu). Такого рода нейросети называются детекторами и эстиматорами соответственно.

Нейросети для извлечения биометрических шаблонов расположены в контейнерах сервисов Remote SDK и Video Agent в формате cnn<model>_<architecture>.plan, где <model> — модель нейронной сети, <architecture> используемая архитектура (cpu-avx2 или gpu).

Для работы с нейросетью используется конфигурационный файл формата cnndescriptor_<model>.conf, где <model> — модель нейронной сети. Конфигурационные файлы для всех нейросетей также расположены в контейнерах сервисов Remote SDK и Video Agent.

Далее будет описана информация только для нейронных сетей для извлечения биометрических шаблонов.

Можно удалить какую-либо нейронную сеть из контейнера сервиса Remote SDK, если выключается использование некоторых эстиматоров или детекторов.

В текущей сборке LUNA PLATFORM поддержаны модели нейросетей для извлечения биометрических шаблонов:

Объект, из которого извлекается БШ	Модели нейронных сетей	Модель по умолчанию
Лицо	59, 60, 62, 65	62
Тело	108, 116	116

Размеры всех моделей нейронных сетей для извлечения биометрических шаблонов лиц приведены ниже:

Модель нейронной сети	Размер данных в формате Raw (байты)	Размер метаданных (байты)	Размер данных в формате SDK (Raw + метаданные)
54	512	8	520
56	512	8	520
57	512	8	520
58	512	8	520
59	512	8	520
60	512	8	520
62	512	8	520
65	512	8	520

Размеры всех моделей нейронных сетей для извлечения биометрических шаблонов тел приведены ниже:

Модель нейронной сети	Размер данных в формате Raw	Размер метаданных (байты)	Размер данных в формате SDK (Raw + метаданные)
102	2048	8	2056
103	2048	8	2056
104	2048	8	2056
105	512	8	520
106	512	8	520
107	512	8	520
108	512	8	520
116	512	8	520

См. подробную информацию о форматах БШ в разделе "Форматы биометрических шаблонов".

Нейросеть 105 является более новой версией нейросети 102.

Биометрические шаблоны, полученные с использованием разных моделей нейронной сети, не сопоставимы друг с другом. Поэтому необходимо повторно извлекать все БШ из существующих БО при использовании новой модели нейронной сети (см. раздел "Изменение используемой модели нейросети").

Можно хранить для одного лица или тела несколько БШ полученных для одного изображения с помощью разных нейронных сетей.

См. параметры "DEFAULT_FACE_DESCRIPTOR_VERSION" и "DEFAULT_HUMAN_DESCRIPTOR_VERSION" в сервисе Configurator для проверки текущих нейронных сетей для извлечения.

Перед любыми действиями с нейронными сетями необходимо проконсультироваться со специалистами VisionLabs.

Изменение используемой модели нейросети#

Изменение используемой модели нейросети требуется когда необходимо повысить качество распознавания лиц/тел или когда старые модели объявляются устаревшими и удаляются из контейнеров сервисов Remote SDK и Video Agent.

При изменении используемой модели нейросети необходимо:

для сохранения возможности использования старых БШ: повторно выполнить извлечение существующих биометрических шаблонов, чтобы БШ были извлечены с помощью новой модели нейросети. Повторное извлечение БШ реализовано в виде длительной задачи Additional extraction (см. "Запуск задачи Additional extraction");
задать новую модель нейросети в настройках LP (см. "Изменение модели нейросети в настройках").

Не следует менять модель нейросети по умолчанию в настройках LP до того, как операция повторного извлечения БШ будет завершена.

Можно как повышать модель нейросети, так и понижать. Для понижения модели нейросети необходимо выполнить аналогичные повышению действия.

Запуск задачи Additional extraction#

Задачу Additional extraction можно запустить одним из следующих способов:

с помощью запроса "additional extract" к сервису Admin;
с помощью пользовательского интерфейса сервиса Admin, по умолчанию расположенного по адресу http://<admin_server_ip>:5010.

В зависимости от способа нужно указать следующую информацию:

тип объекта: лица или события
цель извлечения: БШ лица, БШ тела или базовые атрибуты
новая версия нейронной сети (не применимо для базовых атрибутов)

См. подробную информацию в разделе "Задача Additional extraction".

Изменение модели нейросети в настройках#

Новая модель нейросети задается в настройках сервисов Remote SDK и Video Agent в сервисе Configurator:

Открыть пользовательский интерфейс Configurator http://<configurator_server_ip>:5070.
Установить требуемую нейросеть в параметре "DEFAULT_FACE_DESCRIPTOR_VERSION" (для лиц) или "DEFAULT_HUMAN_DESCRIPTOR_VERSION" (для тел).
Сохранить изменения, нажав кнопку "Save".
Подождать, пока настройка не будет применена во всех сервисах LP.

Использование модели нейросети не из поставки#

В данном разделе описывается процесс переноса нейросети не из поставки в контейнер Remote SDK или Video Agent. Это необходимо, если пользователь использует старую нейросеть из предыдущей версии LP и не хочет её менять при обновлении на новую версию LP.

Необходимо запросить архив с файлами нейросети от представителя VisionLabs. В архиве содержатся следующие файлы:

файл(ы) нейронной сети cnn<model>_<architecture>.plan, где <model> — модель нейронной сети, <architecture> используемая архитектура (cpu-avx2 и/или gpu).
конфигурационный файл cnndescriptor_<model>.conf, где <model> — модель нейронной сети.

Примечание. Далее приводится инструкция по переносу только одной модели нейронной сети с архитектурой cpu-avx2 или gpu.
Однако, чтобы в дальнейшем избежать возможных ошибок, связанных с используемой архитектурой, необходимо выполнить перенос двух файлов нейронной сети в контейнер.

После скачивания архива с нейронной сетью и архива с её конфигурацией необходимо выполнить следующие действия:

распаковать архив
присвоить права нейросетям
скопировать нейросети и их конфигурацию в запущенный контейнер Remote SDK или Video Agent
убедиться, что в конфигурациях сервисов используется необходимая модель нейросети (см. раздел "Изменение модели нейросети в настройках")

Перенос нейронных сетей в контейнер Remote SDK или Video Agent может быть выполнен двумя способами:

Копирование с помощью команды docker cp. В этом случае нейронная сеть и конфигурационный файл копируются в контейнер. Однако данные не сохраняются при перезапуске контейнера. Если контейнер будет перезапущен, команду потребуется выполнить повторно.
Монтирование с использованием volume. Этот способ предполагает монтирование нейронной сети и конфигурационного файла. Данные сохраняются между перезапусками контейнера и могут быть синхронизированы между хост-системой и контейнером.

Ниже приведены примеры команд для переноса нейронных сетей в контейнер Remote SDK или Video Agent.

Распаковка нейросетей#

Откройте директорию с архивами и распакуйте их.

unzip <archive_name>.zip

Присвойте права нейросетям#

chown -R 1001:0 <archive_name>/cnn<model>_<architecture>.plan

Далее, в зависимости от выбранного способа переноса нейронных сетей в контейнер Remote SDK или Video Agent, выберите "Копирование файлов в контейнер" либо "Монтирование файлов в контейнер".

Копирование файлов в контейнер#

Скопируйте требуемую нейросеть и ее конфигурационный файл в контейнер Remote SDK или Video Agent с помощью следующих команд.

docker cp <archive_name>/cnn<model>_<architecture>.plan <container_name>:/srv/fsdk/data/

docker cp <archive_name>/cnndescriptor_<model>.conf <container_name>:/srv/fsdk/data/

<container_name> — имя запущенного контейнера: luna-remote-sdk или luna-video-agent. Это имя может отличаться в разных инсталляциях.

Проверьте, что требуемая модель требуемого устройства (CPU и/или GPU) была успешно загружена:

docker exec -t <container_name> ls /srv/fsdk/data/

Монтирование файлов в контейнер#

Файл с нейросетью монтируется с помощью следующего аргумента при старте контейнера:

-v <file_path>:<container_file_path> \

где <file_path> - путь до файла на хосте, а <container_file_path> - путь к файлу в контейнере.

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

docker run \
...
-v /var/lib/luna/plans/cnndescriptor_65.conf:/srv/fsdk/data/cnndescriptor_65.conf \
-v /var/lib/luna/plans/cnn65b_gpu.plan:/srv/fsdk/data/cnn65b_gpu.plan \
-v /var/lib/luna/plans/cnn65b_cpu-avx2.plan:/srv/fsdk/data/cnn65b_cpu-avx2.plan \
...

Проверьте, что требуемая модель требуемого устройства (CPU и/или GPU) была успешно загружена:

docker exec -t <container_name> ls /srv/fsdk/data/

Логирование информации#

В LUNA PLATFORM существует два способа вывода логов:

стандартный вывод логов (stdout);
вывод логов в файл.

Настройки вывода логов задаются в настройках каждого сервиса в секции <SERVICE_NAME>_LOGGER.

По умолчанию логи выводятся только в стандартный вывод.

Посмотреть логи сервиса через стандартный вывод можно с помощью команды docker logs <service_name>.

Рекомендуется настроить внешнюю систему для сбора и хранения логов. В данном руководстве не приводится пример настройки внешней системы для настройки логов.

При необходимости можно использовать оба способа вывода логов.

При включении сохранения логов в файл в контейнере, в качестве пути по умолчанию используется путь srv/logs для каждого контейнера. Логи сохраняются в формате <service_name>_<type_of_logs>.txt, где:

<service_name> — имя сервиса, например, luna-faces
<types_of_logs> — тип выводимых логов — "ERROR", "INFO", "WARNING", "DEBUG"

Возможно создать до 6 файлов каждого типа. Для каждого типа выводимых логов в настройках сервиса Configurator можно назначить максимальный размер (параметр "max_log_file_size" в секции <SERVICE_NAME>_LOGGER). Так, например, для типа "INFO" может быть создано 6 файлов по 1024 Мб. Для остальных типов принцип работы аналогичен. Таким образом, если максимальное значение "max_log_file_size" равно 1024 Мб, то общее количество памяти, занимаемой логами в контейнере не может превышать 6*4*1024=24576 Мб. После окончания оставшегося места в последнем файле, будет осуществлена перезапись первого файла. Если необходимо снизить количество занимаемой логами памяти, то необходимо уменьшить значение параметра "max_log_file_size".

Можно синхронизировать папку с логами сервиса с локальной папкой на сервере с помощью команды -v /tmp/logs/<service_name>:/srv/logs \ при запуске контейнера. Для этого предварительно нужно создать соответствущую директорию на сервере и присвоить ей необходимые права.

Без присвоения прав монтируемой папке сервис будет выдавать соответствующую ошибку.

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

Проверка изображений#

LUNA PLATFORM позволяет произвести различные проверки изображений фронтального типа. Проверка может быть выполнена как с помощью порогов, соответствующих стандарту ISO/IEC 19794-5:2011, так и с помощью ручного ввода порогов и выбора необходимых проверок.

Результаты проверок не сохраняются в БД, они возвращаются только в ответе.

Проверки на соответствие ISO/IEC 19794-5:2011 выполняются с помощью ресурса "/iso" (см. подробное описание в разделе "Проверка изображений на соответствие стандарту ISO/IEC 19794-5:2011" ниже).

Проверки с ручным указанием условий выполняются с помощью группы проверок "face_quality", политики "detect_policy", ресурсов "/handlers" и "/verifiers" (см. подробное описание в разделе "Проверка изображений по заданным условиям" ниже).

Возможность выполнения таких проверок регулируется специальным параметром в файле лицензии.

Результат выполнения всех проверок определяется параметром "status", где:

"0" — какая-либо из проверок не была пройдена
"1" — все проверки были пройдены

Напротив каждой проверки также отображается её результат (параметр "result").

Можно включить проверку для нескольких лиц на фотоизображении с помощью параметра "multiface_policy". Проверки выполняются для каждой детекции лица, найденного на фото. Результаты проверок не агрегируются.

Для некоторых проверок должны быть выполнены определенные требования. Например, чтобы получить корректные результаты статуса бровей, необходимо чтобы углы наклона головы находились в определенном диапазоне и размер лица по ширине был не менее 80 пикс. Требования для проверок перечислены в разделе "Оцениваемые данные". В случае невыполнения каких-либо требований при проверке определенного параметра, результаты проверки этого параметра могут быть некорректными.

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

Проверка положения головы по вертикали/горизонтали (параметры head_horizontal_center, head_vertical_center)
Проверка вертикального/горизонтального размеров головы (параметры head_width, head_height)
Проверка расстояния между центрами глаз (параметр eye_distance)
Проверки ширины/высоты лица (параметры indent_upper, intent_lower, intent_right, intent_left)
Проверки отступов от краёв фото (параметры indent_upper, intent_lower, intent_right, intent_left)
Проверка равномерности освещения по стандарту ICAO (параметр illumination_uniformity)
Проверка динамического диапазона (параметр dynamic_range)
Проверка фона (параметры background_lightness, background_uniformity)

Набор проверок для "face_quality" и ресурса "/iso" отличается (cм. различие проверок в разделе "Таблица сравнения доступных проверок").

Проверка изображений на соответствие стандарту ISO/IEC 19794-5:2011#

Такая проверка выполняется с помощью ресурса "/iso".

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

Порядок возвращаемых ответов после обработки соответствует порядку передаваемых фотоизображений.

В запросе можно дополнительно включить извлечение EXIF данных фотоизображения.

Для каждой проверки заданы пороги, соответствующие требованиям ISO. Значение порогов для каждой проверки приведено в примере ответа на запрос "/iso" в документации OpenAPI.

Некоторые проверки объединяются под одно требование ISO. Например, для успешного прохождения проверки статуса глаз необходимо, чтобы статусы левого и правого глаза принимали значение "open".

В ответе на запрос ресурс возвращает:

Вердикт о прохождении проверок, который равен 1, если все проверки успешны.
Результаты выполнения каждой из проверок. Это позволяет определить, какая именно проверка не была пройдена. Возвращаются следующие значения:
- Название проверки.
- Полученное после выполнения проверки значение.
- Заданный по умолчанию порог. Пороги заданы в системе в соответствием с требованиями стандарта ISO/IEC 19794-5:2011 и не изменяются пользователем.
- Результат этой проверки. При прохождении порогов возвращается 1.
Координаты найденного лица.

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

Кроме ресурса "/iso" доступна возможность выполнить проверку на соответствие стандартам ISO/IEC 19794-5:2011 и ICAO в ресурсе "/detector" (параметр "estimate_face_quality"). Принцип выполнения проверок аналогичен вышеописанному, однако в данном ресурсе доступны дополнительные проверки из группы проверок "face_quality".

Проверка изображений по заданным условиям#

Такая проверка выполняется с помощью группы проверок "face_quality", политики "detect_policy", ресурсов "/handlers" и "/verifiers".

Принцип работы схож с проверкой на соответствие стандарту ISO, однако пользователь вправе сам решать какие проверки необходимо выполнять и какие пороги задавать.

Для включения проверок необходимо указать значение "1" в поле "estimate" для "face_quality". По умолчанию проверка изображений отключена. Для отключения определённой проверки требуется выставить "0" в поле "estimate" для этой проверки. По умолчанию все проверки включены и будут выполнены при включении "face_quality".

В зависимости от типа проверки можно указать минимальное и максимальное значения порога или допустимые значения для этой проверки. Для этого используется поле "threshold". Если минимальный или максимальный порог не задан, то в качестве незаданного порога автоматически будет выбрано минимальное или максимальное допустимое значение. Если максимальное значение неограниченно (например, ">=0"), то в теле ответа события в поле "max" вернется значение "null". Если оба порога не заданы — проверка выполнится по стандартным порогам, установленным в группе параметров "FACE_QUALITY_SETTINGS" в сервисе Configurator или в теле запроса "face_quality". Если порог указан в теле запроса "face_quality", то это переопределяет стандартные пороги, заданные в группе параметров "FACE_QUALITY_SETTINGS".

Стандартные пороги подобраны специалистами VisionLabs для получения оптимальных результатов. Данные пороги могут отличаться в зависимости от условий съемки, оборудования и т.д.

При задании порогов для проверок "Качество изображения" и "Положение головы" рекомендуется принимать во внимание стандартные пороги, предустановленные в настройках системы. Например, для проверки изображения на размытость (параметр "blurriness_quality"), рекомендуется задавать порог в диапазоне [0.57...0.65]. При задании порога вне данного диапазона результаты могут быть непредсказуемыми. При выборе углов положения головы нужно обращать внимание на рекомендуемые максимальные пороги для проведения оценки в кооперативном и некоорперативном режимах. Информация об этих порогах приведена в соответствующих главах руководства администратора.

Рекомендуется рассматривать результаты проверок состояния рта ("mouth_smiling", "mouth_occluded", "mouth_open", "smile_properties") совместно друг с другом. Так, например, если проверка выявила, что лицо чем-то перекрыто, то остальные результаты проверки рта не будут полезны.

Доступна возможность включения фильтрации по результатам проверок (параметр "filter"). Если одна из проверок "face_quality" для определённой детекции завершится неудачей, то будут возвращены результаты и причина фильтрации. Для данной детекции не будут выполняться дальнейшие политики.

Кроме того, в группе проверок "face_quality" доступны некоторые проверки, которые отсутствуют в проверке изображений на соответствие стандарту (см. ниже).

Таблица сравнения доступных проверок#

Для ресурса "/iso" и группы проверок "face_quality" ресурсов "/handlers" и "/verifiers" доступны следующие проверки:

Описание проверок	Наименование проверок	Ресурсы "/iso"	"face_quality"
Проверка качества изображения	illumination_quality, specularity_quality, blurriness_quality, dark_quality, light_quality	+	+
Проверка фона	background_lightness, background_uniformity	+	+
Проверка равномерности освещения по стандарту ICAO	illumination_uniformity	-	+
Проверка положения головы	head_yaw, head_pitch, head_roll	+	+
Проверка направления взгляда	gaze_yaw, gaze_pitch	+	+
Проверка атрибутов рта	mouth_smiling, mouth_occluded, mouth_open	+	+
Проверка состояния улыбки	smile_properties (none, smile_lips, smile_teeth)	+	+*
Проверка состояния очков	glasses	+	+
Проверка атрибутов глаз	left_eye (open, occluded, closed), right_eye (open, occluded, closed)	+	+
Проверка расстояния между центрами глаз	eye_distance	+	+
Проверка естественности освещения	natural_light (0, 1)	+	+
Проверка бочкообразной дисторсии (эффект Fisheye)	radial_distortion (0, 1)	+	+
Проверка эффекта красных глаз	red_eyes (0, 1)	+	+
Проверка состояния бровей	eyebrows_state (neutral, raised, squinting, frowning)	+	+*
Проверка наличия и типа головного убора	headwear_type (none, baseball_cap, beanie, peaked_cap, shawl, hat_with_ear_flaps, helmet, hood, hat, other)	+	+*
Проверка положения головы по вертикали/горизонтали	head_horizontal_center, head_vertical_center	+	+
Проверка вертикального/горизонтального размеров головы	head_width, head_height	+	+
Проверка формата изображения	image_format	+	+
Проверка типа цвета по лицу	face_color_type (color, grayscale, infrared)	+	+
Проверка положения плеч	shoulders_position	+	+
Проверка размера изображения	image_size	-	+
Проверки отступов от краёв фото	indent_upper, intent_lower, intent_right, intent_left	-	+
Проверки ширины/высоты изображения	image_width, image_height	-	+
Проверка соотношения сторон изображения	aspect_ratio	-	+
Проверки ширины/высоты лица	face_width, face_height	-	+
Проверка динамического диапазона	dynamic_range	-	+
Перекрытие лица	face_occlusion, lower_face_occlusion, forehead_occlusion, nose_occlusion	-	+

* Для данных проверок можно указывать несколько параметров.

Проверки работоспособности сервисов (health checks)#

Для проверок работоспособности сервисов предназначен ресурс "/healthcheck". Ресурс может использоваться для активной проверки состояния сервиса, а именно, может ли сервис выполнять свои функции в полном объёме или нет. Проверяется возможность подключения данного сервиса к сервисам LP и БД, от которых он зависит.

Возможно настроить периодическую проверку ресурса с использованием HAProxy, NGINX или иной системы. Это позволит определить, что сервис недоступен, и принять решение о его отключении из контура или перезапуске.

С помощью опции "include_luna_services" можно включать и отключать проверку health check для сервисов LUNA PLATFORM, от которых зависит данный сервис. Если опция включена, то отправляются дополнительные запросы на ресурсы "/healthcheck" этих сервисов. Опция "include_luna_services" отключается, чтобы не выполнять рекурсивную проверку одних и тех же сервисов. Например, когда сразу несколько сервисов, от которых зависит данный сервис, будут отправлять запросы в сервис Faces и тем самым увеличивать нагрузку на него.

При успешном выполнении проверки health check возвращается только время выполнения подключения в поле "execution_time".

При недоступности одного или нескольких сервисов возвращается ошибка с кодом 502 "Unhealthy". В теле ответа перечисляются компоненты, статусы проверок и возникшие ошибки. Код ошибки 500 в ответе не обязательно означает проблему в работе сервиса. Долгий запрос может завершиться с ошибкой из-за превышения таймаутов, повышенной нагрузки на сервер, проблем в сети или по иным причинам.

При выполнении запроса на ресурс "/healthcheck" рекомендуется выставлять таймаут в несколько секунд. Если запрос не успевает отработать, это признак того, что при работе системы возникли проблемы.

См. описание ресурса "/healthcheck" в спецификации OpenAPI требуемого сервиса LUNA PLATFORM.

Для проверки работоспособности сервисов также доступен запрос "get health (redirect)", позволяющий не указывать версию API в запросе.

Загрузка изображений из папки#

Скрипт "folder_uploader.py" загружает изображения из указанной папки и обрабатывает загруженные изображения в соответствии с заранее прописанными параметрами.

Основная информация о скрипте#

Скрипт "folder_uploader.py" можно использовать для загрузки изображений только с помощью сервиса API.

Нельзя задать адрес и порт Backport 4 для использования этого скрипта. Можно использовать данные, загруженные в LP 5 API в запросах Backport 4.

Нельзя использовать скрипт "folder_uploader.py" для загрузки данных в сервис Backport 3, т.к. созданные для Backport 3 объекты отличаются (например, объект "person" не создается скриптом).

Использование скрипта#

Порядок работы скрипта:

Поиск изображений допустимого типа (форматы: '.jpg', '.jpeg', '.png', '.bmp', '.ppm', '.tif', '.tiff'; цветовая модель: RGB, CMYK) в указанной папке (источнике).
Запуск асинхронной обработки изображения в соответствии с заданными параметрами (см. раздел "Запуск скрипта").

Процесс обработки изображения:

Обнаружение лиц и создание биометрических образцов.
Извлечение атрибутов.
Создание лиц и прикрепление их к списку.
Добавление записи в файл логов.

Если изображение было загружено успешно, будет добавлена следующая запись в {start_upload_time}_success_log.txt: success load logfile. Структура записи следующая:

    {
    "image name": ..., 
    "face id": [...]
    }.

При возникновении ошибок на каком-либо этапе обработки скрипта обработка изображения прерывается и добавляется запись в лог-файл с ошибками {start_upload_time}_error_log.txt: error. Структура записи следующая:

    {
    "image name": ..., 
    "error": ...
    }

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

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

Крайне рекомендуется создать виртуальное окружение для установки зависимостей python.

Небходимо установить пакеты Python (версия 3.7 и более поздние) перед запуском установки. Эти пакеты не поставляются в пакете дистрибутива, их установка не описана в данном руководстве:

python3.7
python3.7-devel

Установите gcc.

yum -y install gcc

Откройте директорию со скриптом.

cd /var/lib/luna/current/extras/utils/folder_uploader

Создайте виртуальное окружение.

python3.7 -m venv venv

Активируйте виртуальное окружение.

source venv/bin/activate

Установите библиотеку tqdm.

pip3.7 install tqdm

Установите библиотеки luna3.

pip3.7 install ../luna3*.whl

Отключите виртуальное окружение.

deactivate

Запуск скрипта#

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

python3.7 folder_uploader.py --account_id 6d071cca-fda5-4a03-84d5-5bea65904480 --source "Images/" --warped 0 --descriptor 1 --origin http://127.0.0.1:5000 --avatar 1  --list_id 0dde5158-e643-45a6-8a4d-ad42448a913b --name_as_userdata 1

Убедитесь в том, что параметр --descriptor установлен на 1, чтобы биометрические шаблоны создавались.

Версия API установлена в значение "6" по умолчанию, её нельзя изменить с помощью аргументов командной строки.

--source "Images/" — "Images/" — папка с изображениями, расположенными рядом со скриптом "folder_uploader.py". Можно также задать полный путь к директории

--list_id 0dde5158-e643-45a6-8a4d-ad42448a913b — задание существующего списка

--account_id 6d071cca-fda5-4a03-84d5-5bea65904480 — задание требуемого ID аккаунта

--origin http://127.0.0.1:5000 — задание текущего адреса и порта сервиса API

См. help для более подробной информации о доступных аргументах скрипта:

python3.7 folder_uploader.py --help

Аргументы командной строки:

account_id: ID аккаунта, используемый в запросах в LUNA PLATFORM (требуется)
source: директория с изображениями для загрузки (требуется)
warped: является ли изображение биометрическим образцом (0,1) (требуется)
descriptor: извлекать ли биометрический шаблон (0,1); по умолчанию — 0
origin: адрес API; по умолчанию — "http://127.0.0.1:5000"
avatar: использовать ли биометрический образец как аватар (0,1); по умолчанию — 0
list_id: ID списка, к которому прикрепляются лица (новый список LUNA будет создан, если list_id не задан и list_linked=1); по умолчанию — None
list_linked: прикреплять ли лица к списку (0,1); по умолчанию — 1
list_userdata: пользовательские данные для списка, к которому прикрепляются лица (для нового списка); по умолчанию — None
pitch_threshold: максимальный угол головы вверх/вниз [0..180];
roll_threshold: максимальный угол отклонения головы вправо/влево [0..180];
yaw_threshold: максимальный угол поворота головы вправо/влево [0..180];
multi_face_allowed: разрешено ли обнаружение нескольких лиц на одном изображении (0,1); по умолчанию — 0
get_major_detection: выбрать ли основное обнаружение лица посредством "манхеттенского расстояния" на одном изображении (0,1); по умолчанию — 0
basic_attr: извлекать ли базовые атрибуты (0,1); по умолчанию — 1
score_threshold: пороговое значение качества биометрического шаблона (0..1); по умолчанию — 0
name_as_userdata: использовать ли имя изображения в качестве пользовательских данных (0,1); по умолчанию — 0
concurrency: число параллельной обработки изображений; по умолчанию — 10

Клиентская библиотека#

Основная информация#

Архив с клиентской библиотекой для LUNA PLATFORM 5 поставляется в пакете дистрибутива: /var/lib/luna/current/extras/utils/luna3-*.whl

Данная библиотека Python является HTTP клиентом для всех сервисов LUNA PLATFORM.

В документе /var/lib/luna/current/docs/ReferenceManuals/APIReferenceManual.html можно найти примеры использования библиотеки.

В примере показан запрос на сравнение лиц. Библиотека luna3 используется для создания запроса. См. "matcher" > "matching faces" в "APIReferenceManual.html":

# This example is written using luna3 library {#this-example-is-written-using-luna3-library}

from luna3.common.http_objs import BinaryImage
from luna3.lunavl.httpclient import LunaHttpClient
from luna3.python_matcher.match_objects import FaceFilters
from luna3.python_matcher.match_objects import Reference
from luna3.python_matcher.match_objects import Candidates

luna3client = LunaHttpClient(
    accountId="8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a",
    origin="http://127.0.0.1:5000",
)

# create sample {#create-sample}
sampleId = luna3client.saveSample(
    image=BinaryImage("image.jpg"),
    raiseError=True,
).json["sample_id"]

attributeId = luna3client.extractAttrFromSample(
    sampleIds=[
        sampleId,
    ],
    raiseError=True,
).json[0]["attribute_id"]

# create face {#create-face}
faceId = luna3client.createFace(
    attributeId=attributeId,
    raiseError=True,
).json["face_id"]

# match {#match}
candidates = Candidates(
    FaceFilters(
        faceIds=[
            faceId,
        ]
    ),
    limit=3,
    threshold=0.5,
)
reference = Reference("face", faceId)

response = luna3client.matchFaces(
    candidates=[candidates], references=[reference],
    raiseError=True,
)

print(response.statusCode)
print(response.json)

Пример установки библиотеки#

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

Данную библиотеку Python можно использовать на Windows, Linux, MacOS.

Установите пакеты Python (версия 3.7 и позже) перед началом установки. Эти пакеты не поставляются в пакете дистрибутива, их установка не описана в данном руководстве:

python3.7
python3.7-devel

Установите gcc.

yum -y install gcc

Перейдите в директорию со скриптом, например, folder_uploader.py

cd /var/lib/luna/current/extras/utils/folder_uploader

Создайте виртуальное окружение.

python3.7 -m venv venv

Активируйте виртуальное окружение.

source venv/bin/activate

Установите библиотеки luna3.

pip3.7 install ../luna3*.whl

Деактивируйте виртуальное окружение.

deactivate

Плагины#

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

Файлы с базовыми абстрактными классами находятся в папке .plugins/plugins_meta конкретного сервиса.

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

Доступно три типа плагинов:

Плагины событий
Фоновые плагины
Плагины сравнения

Плагины событий#

Первый тип запускается при выполнении события. Плагин должен реализовывать функцию обратного вызова. Эта функция вызывается для каждого события соответствующего типа. Набор типов событий определяется разработчиками сервиса. Для сервиса Remote SDK доступны два подтипа плагинов событий:

Мониторинг события
Отправка события

Для других сервисов доступен только мониторинг события.

Примеры плагина события приведены в документе "PythonMatcherDevelopmentManual".

Фоновые плагины#

Второй тип плагинов предназначен для фоновой работы. Фоновый плагин может реализовывать:

индивидуальный запрос на конкретный ресурс (route),
фоновый мониторинг ресурсов сервисов,
совместную работу плагина событий и фонового плагина (группирование точек мониторинга),
подключение к другим источникам данных (Redis, RabbitMQ) и обработка их данных.

Примеры фонового плагина приведены в документе "PythonMatcherDevelopmentManual".

Плагины сравнения#

Третий тип плагинов позволяет значительно ускорить выполнение запросов на сравнение.

Важно, что плагины не предоставляются как готовое решение для матчинга. Требуется дополнительно реализовать логику, необходимую для решения конкретных бизнес-задач.

Плагины сравнения активируются в сервисе Python Matcher Proxy. Данный сервис не устанавливается по умолчанию. Следует запустить его для работы плагинов. См. команду запуска Python Matcher Proxy в разделе "Использование Python Matcher с Python Matcher Proxy" руководства по установке LUNA PLATFORM.

При обычном сценарии работы LUNA PLATFORM с использованием Python Matcher Proxy все запросы на сравнение, обрабатываемые сервисом Python Matcher Proxy, перенаправляются на сервис Python Matcher. В этом случае обработка запросов на сравнение может идти медленнее по нескольким причинам:

из-за большого объема данных и невозможности ускорить запрос любыми изменениями конфигурации базы данных;
из-за способа хранения данных — биометрический шаблон и идентификатор объекта (face_id/event_id) хранятся в разных таблицах базы данных. Фильтры, указанные в запросе на сравнение, также могут быть представлены в отдельной таблице базы данных, что замедляет обработку запроса;
из-за внутренних ограничений базы данных.

С помощью плагинов сравнения можно отделить некоторые группы запросов и ускорить их обработку, в том числе путем передачи данных в другое хранилище с опредленным способом хранения данных, которое делает возможным выполнять сравнение быстрее, чем со способом по умолчанию (см. "Источники данных плагина").

Примеры:

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

В этом случае можно скопировать необходимых данные для кандидатов матчинга в другое хранилище данных, отличное от хранилища данных по умолчанию, и создать плагин сравнения, который будет сравнивать только указанные эталоны с этими кандидатами, а не с любыми другими объектами.

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

В этом случае можно дублировать все event_id и их биометрические шаблоны тел в отдельное хранилище данных, отличное от хранилища данных по умолчанию, и создать плагин сравнения, который будет сравнивать указанный эталон с этими кандидатами, а не с другими объектами.

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

Можно использовать встроенные плагины сравнения или создать пользовательские плагины сравнения.

Доступно три примера встроенных плагина сравнения:

плагин "Thin event", использующийся для быстрого сравнения лиц с упрощенными событиями;
плагин "Thin face", использующийся для быстрого сравнения лиц с упрощенными лицами;
плагин "Cached Matcher", использующийся для быстрого сравнения лиц по большим спискам.

Thin event

Плагин использует собственную таблицу в базе данных "luna_events".

Ниже приведены несколько особенностей, которые ускоряют сравнение с помощью плагина по сравнению со способом по умолчанию:

база данных "Thin event" содержит меньше полей данных;
база данных "Thin event" хранит "event_id" и БШ лица в одной таблице;
база данных "Thin event" хранит возраст, пол и некоторые другие фильтры в одной таблице.

Thin face

Плагин использует собственную таблицу в базе данных "luna_faces" с тремя обязательными столбцами ("face_id", "descriptor", "descriptor_version") и рядом дополнительных, которые можно настроить: "account_id", "lists", "create_time", "external_id", "user_data", "event_id", "avatar".

Cached Matcher

Сопоставление лиц по списку — трудоемкий процесс, поэтому для повышения производительности с помощью плагина реализованы следующие методы:

для сравнения кандидатов и ссылок используется отдельный сервис "LUNA-CACHED-MATCHER";
данные для кандидата ("list_id", "face_id", "descriptor:) хранятся в кеше памяти. Это обеспечивает быстрый доступ к данным;
данные разбиты по горизонтали на сегменты (в качестве сегмента используется сервис "LUNA-CACHED-MATCHER"), что обеспечивает быстрый поиск совпадающих результатов.

См. подробное описание встроенных плагинов и инструкцию по написанию пользовательских плагинов в документе "PythonMatcherDevelopmentManual" в комплекте поставки.

Общее описание работы плагина#

Каждый запрос на сравнение представлен в виде всех возможных комбинаций кандидатов и эталонов, затем каждая такая комбинация обрабатывается как отдельный подзапрос следующим образом (дополнительный подзапрос означает комбинацию эталонов и кандидатов):

Получение сложности подзапроса (см. "Затраты ресурсов на сравнение").
Выбор способа обработки подзапроса: с помощью плагина сравнения или сервиса Python Matcher.
- Если на предыдущем шаге был выбран сервис Python Matcher, он обработает подзапрос и вернет ответ сервису Python Matcher Proxy.
- Если на предыдущем шаге был выбран плагин сравнения, то он обработает подзапрос. Если подзапрос успешно обработан, ответ возвращается в сервис Python Matcher Proxy. Если подзапрос не был успешно обработан, будет совершена попытка обработки в сервисе Python Matcher.
Если запрос был успешно обработан плагином сравнения, но у него нет доступа ко всем полям объекта, указанным в позапросе в поле "target" для сравнения, то сервис Python Matcher Proxy получит эти данные перед следующим шагом.
Сервис Python Matcher Proxy собирает результаты от всех подзапросов, сортирует их в правильном порядке, и выдает ответ пользователю.

Рабочий процесс плагина сравнения показан ниже:

Сложность запроса на сравнение#

Matching cost — это число с плавающей запятой, определяющее сложность запроса на сравнение с использованием плагина. Определение сложности сравнения необходимо для выбора наилучшего способа обработки запроса на сравнение: с помощью сервиса Python Matcher или с помощью одного или нескольких плагинов.

Значение сложности запроса на сравнение для сервиса Python Matcher равно 100. Если существует несколько плагинов, то соответствующее значение сложности будет рассчитано для каждого плагина. Будет использоваться плагин сравнения с наименьшим значением сложности, если его сложность ниже, чем сложность запроса для сервиса Python Matcher. Все запросы со сложностью более 100 будут обрабатываться в сервисе Python Matcher. Если плагинов сравнения нет, то для обработки запроса будет использоваться сервис Python Matcher.

Поля target, выступающие в качестве сравнения#

Сервис Python Matcher имеет доступ ко всем данным сущностей сравнения, поэтому он может обрабатывать запросы на сравнение со всеми полями target. В свою очередь, плагины сравнения могут не иметь доступа к данным, указанным в поле target запроса. В этом случае сервис Python Matcher Proxy дополнит ответ плагина сравнения отсутствующими данными о полях target, например:

ответ на сравнение содержит следующие поля target: face_id , user_data и similarity, а выбранный плагин сравнения не имеет доступа к полю user_data, тогда:
- плагин сравнения сравнивает эталон с указанными face_id и возвращает результат сравнения сервису Python Matcher Proxy, который содержит только пары face_id и similarity.
- для каждого кандидата на сравнение в результате сервис Python Matcher Proxy получит user_data из основной базы данных по face_id и объединит face_id и similarity с user_data.
- плагин сравнения вернет пользователю расширенный ответ с указанными полями target и ключевым полем face_id в качестве target. Эта механика требует, чтобы плагин поддерживал соответствующий идентификатор объекта в качестве target. Если плагин не поддерживает идентификатор сущности в качестве target, такой запрос не будет отправлен этому плагину.
ответ на сравнение содержит следующие поля target: age и gender, а выбранный плагин сравнения имеет доступ только к полям event_id , descriptor и age.
- плагин сравнения сравнивает эталон и возвращает соответствующий ответ в сервис Python Matcher Proxy, который содержит только пары event_id , age и similarity.
- для каждого кандидата на сравнение в результате сервис Python Matcher Proxy получит gender из основной базы данных по event_id и объединит event_id с age, а также после этого удалит ненужные event_id и similarity из ответа.
- плагин сравнения вернет пользователю расширенный ответ с указанными полями target и ключевым полем event_id в качестве target. Эта механика требует, чтобы плагин поддерживал соответствующий идентификатор объекта в качестве target. Если плагин не поддерживает идентификатор сущности в качестве target, такой запрос не будет отправлен этому плагину.

Источники данных плагина#

Для ускорения обработки запроса каждый плагин сравнения может использовать отдельный источник данных вместо источника по умолчанию (базы данных Events, Faces или Attributes (см. раздел "Описание баз данных")), например использовать отдельную базу данных, новую таблицу в существующей базе данных, кеш в памяти и т.д.

Более подробную информацию о плагинах сравнения см. в документе "PythonMatcherDevelopmentManual".

Использование плагинов#

Ручное добавление плагинов в директорию#

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

Чтобы использовать плагин вместе с сервисом в Docker-контейнере, необходимо выполнить два шага:

Добавить файл плагина в контейнер.
Указать использование плагина в настройках контейнера.

При запуске контейнера необходимо переслать файл плагина в папку с плагинами конкретного сервиса. Например, для сервиса Remote SDK это будет папка /srv/luna_remote_sdk/plugins.

Сделать это можно любым удобным способом. Например, при запуске сервиса можно смонтировать папку с плагинами в каталог нужного сервиса (см. команды запуска сервиса в руководстве по установке):

Необходимо добавить следующий том, если все необходимые плагины для сервиса хранятся в директории "/var/lib/luna/remote_sdk/plugins":

-v /var/lib/luna/remote_sdk/plugins:/srv/luna_remote_sdk/plugins/ \

Данная команда приведена для случая ручного запуска сервиса.

Затем нужно добавить имя/имена файла в настройку "LUNA_REMOTE_SDK_ACTIVE_PLUGINS" в сервисе Configurator.

[   
   "plugin_1",
   "plugin_2",
   "plugin_3"   
]

Список должен содержать имена файлов без расширения (.py).

После выполнения этих шагов LP будет автоматически использовать плагин(ы).

Дополнительную информацию о настройках для конкретного сервиса можно найти в руководстве разработчика сервиса API.

Создание нового Docker-контейнера с помощью плагина#

Создавать новый Docker-контейнер с помощью плагина можно, когда для использования плагина требуются дополнительные зависимости или когда для производственного использования требуется контейнер с плагином.

Необходимо создать свой Docker-контейнер на основе базового контейнера сервиса.

Нужно добавить "Dockerfile" со следующей структурой в CI:

FROM dockerhub.visionlabs.ru/luna/luna-remote-sdk:v.0.16.1
USER root
...
USER luna

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

USER root — изменение прав пользователя на root для выполнения следующих действий. После изменения прав должны быть перечислены команды для добавления плагина и его зависимости. Они не приводятся в данном руководстве. См. документацию Docker.

USER luna — после выполнения всех команд пользователь должен быть снова изменен на "luna".

Нужно добавить имя файла плагина в настройку "LUNA_REMOTE_SDK_ACTIVE_PLUGINS" в сервисе Configurator.

Доступны следующие возможности:

Обновление настройки вручную в сервисе Configurator в соответствии с вышеописанным способом.
Создание файла дампа с настройками плагина LP и добавление его в сервис Configurator после запуска.

Пример файла дампа с настройками плагина Remote SDK приведен ниже.

{
    "settings":[
        {
            "value": [   
                        "plugin_1",
                        "plugin_2",
                        "plugin_3"   
                     ],
            "description": "list active plugins",
            "name": "LUNA_REMOTE_SDK_ACTIVE_PLUGINS",
            "tags": []
        },
    ]
}

Затем файл применяется с помощью нижеописанной команды. Например, файл хранится в "/var/lib/luna/". Имя файла дампа — "luna_remote_sdk_plugin.json".

docker run \
-v /var/lib/luna/luna_remote_sdk_plugin.json:/srv/luna_configurator/used_limitations/luna_remote_sdk_plugin.json \
--network=host \
--rm \
--entrypoint=python3 \
dockerhub.visionlabs.ru/luna/luna-configurator:v.2.2.85 \
./base_scripts/db_create.py --dump-file /srv/luna_configurator/used_limitations/luna_remote_sdk_plugin.json

Мониторинг#

В LUNA PLATFORM есть несколько методов мониторинга:

Отправка данных в InfluxDB (включен по умолчанию)
Экспорт метрик в формате Prometheus через ресурс /metrics (отключен по умолчанию)

Отправка данных в InfluxDB#

Начиная с версии 5.5.0, в LUNA PLATFORM предоставляется возможность использовать InfluxDB версии 2.

При необходимости можно выполнить миграцию с версии 1 на версию 2 с помощью встроенных инструментов. См. документацию InfluxDB

Для работы с InfluxDB необходимо зарегистрироваться с помощью логина и пароля и указать имя бакета, имя организации и токен. Все эти данные задаются при запуске контейнера InfluxDB с помощью переменных окружения.

Для использования мониторинга необходимо в настройках каждого сервиса задать для полей bucket, organization, token точно такие же данные, которые указывались при запуске контейнера InfluxDB. Так, например, если при запуске контейнера InfluxDB использовались следующие настройки...:

-e DOCKER_INFLUXDB_INIT_BUCKET=luna_monitoring \
-e DOCKER_INFLUXDB_INIT_USERNAME=luna \
-e DOCKER_INFLUXDB_INIT_PASSWORD=password \
-e DOCKER_INFLUXDB_INIT_ORG=luna \
-e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=kofqt4Pfqjn6o \

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

"influxdb": {
    "organization": "luna",
    "token": "kofqt4Pfqjn6o",
    "bucket": "luna_monitoring",

По умолчанию значения для переменных окружения контейнера и значения настроек сервисов совпадают. Это означает, что если LUNA PLATFORM запускается с помощью руководства по установке или скрипта Docker Compose, то мониторинг будет автоматически включен.

Логин и пароль используются для доступа к пользовательскому интерфейсу InfluxDB.

Также доступна возможность запуска InfluxDB на отдельном сервере. Адрес сервера с InfluxDB необходимо указать в параметрах host и port в настройках сервисов.

См. остальные настройки для InfluxDB на примере сервиса API в разделе "LUNA_MONITORING".

Отправляемые данные#

Мониторинг возможен для двух типов событий: запрос (все запросы) и ошибка (только неудавшиеся запросы).

Каждое событие — это точка временного ряда. Для сервиса API точка представлена с использованием следующих данных:

тип события (запросы или ошибки)
отметка времени начала запроса
теги
поля

Для других сервисов набор типов событий может отличаться. Например, сервис Remote SDK также собирает данные об использовании SDK, выполненных оценках и лицензировании.

Тег — это индексированные данные в хранилище. Он представлен в виде словаря, где

keys — имена тегов (строка),
values — строка, целое число или число с плавающей запятой.

Поле представляет собой неиндексированные данные в хранилище. Оно представлено в виде словаря, где

keys — имена полей (строка),
values — строка, целое число или число с плавающей запятой.

Ниже приведен пример тегов и полей для сервиса API. Нижеперечисленные теги уникальны для каждого сервиса. Информацию о мониторинге конкретного сервиса можно найти в соответствующей документации разработчика:

Сохранение данных для запросов запускается при каждом запросе. Каждая точка содержит данные о соответствующем запросе (время выполнения и т.д.).

теги

Имя тега	Описание
service	сервис, всегда "luna-api"
account_id	идентификатор аккаунта или пусто
route	объединение метода запроса и ресурса запроса (POST:/extractor)
status_code	HTTP статус код ответа

поля

Имя поля	Описание
request_id	идентификатор запроса
execution_time	время выполнения запроса

Сохранение данных для ошибок запускается при сбое запроса. Каждая точка содержит error_code ошибки LUNA.

теги

Имя тега	Описание
request_id	идентификатор запроса,всегда "luna-api"
account_id	идентификатор аккаунта или пусто
route	объединение метода запроса и ресурса запроса (POST:/extractor)
status_code	HTTP статус код ответа
error_code	код ошибки LUNA PLATFORM

поля

Имя поля	Описание
request_id	идентификатор запроса

Каждый обработчик может добавлять дополнительные теги или поля. Например, обработчик ресурса "/handlers/{handler_id}/events" добавляет тег handler_id.

Просмотр данных мониторинга#

Для просмотра данных мониторинга можно использовать пользовательский интерфейс InfluxDB.

перейдите в пользовательский интерфейс InfluxDB <server_ip>:<influx_port>. Порт по умолчанию — 8086. Данные для входа по умолчанию — luna/password.
выберите вкладку Explore
выберите способ отображения информации в выпадающем списке (график, гистограмма, таблица и пр.)
выберите бакет внизу страницы. По умолчанию — luna_monitoring
отфильтруйте необходимые данные
нажмите "Submit".

Также InfluxDB версии 2 позволяет визуализировать данные мониторинга с помощью инструмента "LUNA Dashboards (Grafana)".

Подсчет статистики выполненных запросов и оценок#

LUNA PLATFORM подсчитывает количество выполненных запросов и оценок за месяц по данным мониторинга если включен сбор статистики. Сбор статистики работает только при включенном мониторинге и установленной InfluxDB версии 2.0.8 и более поздних версий.

Для получения статистики следует использовать запрос на ресурс "/luna_sys_info" или перейти в GUI сервиса Admin на вкладку "help" и нажать "Get LUNA PLATFORM system info". Необходимая информация содержится в секции "stats".

В этой секции содержатся два поля — "estimators_stats" и "routes_stats".

Первое поле содержит список выполненных оценок. Для каждой оценки отображается три поля:

name — наименование выполненной оценки (например, estimate_emotions)
count — суммарное количество выполненных оценок одного типа
month — месяц, за который был произведен подсчет (например, 2021-09)

Второе поле содержит список сервисов, к которым выполнялись запросы. Для каждого сервиса отображается пять полей:

service — наименование сервиса (например, luna-api)
route — метод и запрос (например, GET:/version)
month — месяц, за который был произведен подсчет
errors — количество запросов, выполненных с конкретной ошибкой (например, [ { "count": 1, "error_code": "12012" } ] )
request_stats — количество успешно выполненных запросов (например, [ { "count": 1, "status_code": "200" } ])

Информация является обезличенной и содержит только количественные данные.

Статистика подсчитывается в InfluxDB на основе данных из бакета "luna_monitoring" и хранится в бакете "luna_monitoring_aggregated". Бакеты создаются в InfluxDB. Не следует удалять данные из данного бакета, иначе будет невозможно получить статистику.

Статистика подсчитывается раз в сутки, поэтому не отображается сразу после запуска LP.

Задачи для подсчёта статистики можно найти в GUI InfluxDB на вкладке "Tasks". Там можно вручную запустить их выполнение.

Для включения данного функционала следует выполнить команду python3 ./base_scripts/influx2_cli.py create_usage_task --luna-config http://127.0.0.1:5070/1 после запуска сервиса Admin (см. руководство по установке). Команда автоматически создаёт необходимый бакет "luna_monitoring_aggregated". Если данная команда не выполнена, то в ответе "/luna_sys_info" не будет отображаться статистика.

При необходимости можно отключить сбор статистики, удалив или отключив соответствующие задачи на вкладке "Tasks" в GUI InfluxDB.

Экспорт метрик в формате Prometheus#

Каждый сервис LUNA PLATFORM может собирать и сохранять метрики в формате Prometheus в виде данных временных рядов, которые можно использовать для отслеживания поведения сервиса. Метрики могут быть интегрированы в систему мониторинга Prometheus для отслеживания производительности. См. официальную документацию Prometheus для подробной информации.

По умолчанию сбор метрик отключен. Сбор метрик включается в группе параметров "LUNA_SERVICE_METRICS".

Обратите внимание, что все данные метрик сбрасываются при завершении работы сервиса.

Тип метрик#

Доступно два типа метрик:

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

Кумулятивная гистограмма — это отображение, которое подсчитывает совокупное количество наблюдений во всех интервалах до указанного интервала. См. описание в Wikipedia.

Доступны следующие метрики типа счетчики:

request_count_total — общее количество запросов
errors_count_total — общее количество ошибок

Каждый из них имеет как минимум два лейбла для сортировки:

status_code (или error_code для метрик ошибок)
path — путь, состоящий из метода запроса и маршрута конечной точки

Лейблы представляют собой ключевые пары, состоящие из имени и значения, которые присваиваются метрикам.

При необходимости можно добавить пользовательские типы лейблов, указав пару label_name=label_value в параметре "extra_labels".

Обратите внимание, что пара label_name=label_value будет добавлена к каждому сервису LUNA PLATFORM.

Специальный менеджер распределяет все запросы, проходящие через сервис, среди счетчиков, используя эти метки. Это обеспечивает, что два успешных запроса, отправленных на разные конечные точки или на одну конечную точку, но с разными кодами состояния, будут доставлены к различным метрикам.

Неудачные запросы распределяются по метрикам request_count_total и request_errors_total.

Метрика requests типа кумулятивные гистограммы отслеживает длительность запросов к сервису. Для гистограммы определяются следующие интервалы (бакеты), в которые попадают измерения:

0.0001
0.00025
0.0005
0.001
0.0025
0.005
0.01
0.025
0.05
0.075
0.1
0.25
0.5
0.75
1.0
2.5
5.0
7.5
10.0
Inf

Таким образом диапазон времени запроса может быть разбит на несколько интервалов, начиная от очень быстрых запросов (0.0001 секунды) до очень долгих (Inf - бесконечность). У гистограмм также есть метки для классификации данных, такие как status_code для статуса запроса или route для указания маршрута запроса.

Примеры

Если отправить один запрос в ресурс /healthcheck, за которым последуют три запроса в ресурс /docs/spec, один из которых будет перенаправлен (код состояния ответа 301), то при выполнении запроса к ресурсу /metrics, в теле ответа будет выдан следующий результат:

# HELP request_count_total Counter of requests
# TYPE request_count_total counter
request_count_total{path="GET:/docs/spec",status_code="200"} 2.0
request_count_total{path="GET:/docs/spec",status_code="301"} 1.0
request_count_total{path="GET:/healthcheck",status_code="200"} 1.0

Если отправить один неверный POST-запрос к ресурсу /handlers, то при выполнении запроса к ресурсу /metrics, в теле ответа будет выдан следующий результат:

# HELP request_count_total Counter of requests
# TYPE request_count_total counter
request_count_total{path="POST:/handlers",status_code="401"} 1.0
# HELP request_errors_total Counter of request errors
# TYPE request_errors_total counter
request_errors_total{error_code="12010",path="POST:/handlers"} 1.0
# HELP requests Histogram of request time metrics
# TYPE requests histogram
requests_sum{route="GET:/docs/spec",status_code="200"} 0.003174567842297907
requests_bucket{le="0.0001",route="GET:/docs/spec",status_code="200"} 0.0
requests_bucket{le="0.00025",route="GET:/docs/spec",status_code="200"} 0.0
requests_bucket{le="0.0005",route="GET:/docs/spec",status_code="200"} 0.0
requests_bucket{le="0.001",route="GET:/docs/spec",status_code="200"} 1.0
...
requests_count{route="GET:/docs/spec",status_code="200"} 2.0
requests_sum{route="GET:/docs/spec",status_code="301"} 0.002381476051209132

Настройка сбора метрик для Prometheus#

Prometheus необходимо настроить на сбор метрик LUNA PLATFORM.

Пример конфигурации Prometheus для сбора метрик сервисов LP:

 - job_name: "luna-api"
    static_configs:
      - targets: ["127.0.0.1:5000"]
  ...

  - job_name: "luna-configurator"
    static_configs:
      - targets: ["127.0.0.1:5070"]

См. пример запуска Prometheus в официальной документации.

В сервисе LUNA Dashboards уже созданы дашборды Prometheus.

LUNA Dashboards#

Инструмент LUNA Dashboards предназначен для визуализации данных мониторинга. LUNA Dashboards на основе веб-приложения Grafana создает набор дашбордов для анализа состояния отдельных сервисов, а также пару обобщенных дашбордов, которые можно использовать для оценки состояния системы.

Для использования веб-интерфейса Grafana нужно перейти по адресу "http://IP_ADDRESS:3000".

Дашборд сервиса API при запуске тестирования

В Grafana конфигурирует источник данных, благодаря которому веб-приложение может связываться с базой данных Influx, в которую попадают данные мониторинга.

Инструмент LUNA Dashboard может быть полезен:

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

После установки дашбордов (см. ниже) в веб-интерфейсе Grafana становится доступен каталог "luna_platform_5", который содержит следующие дашборды:

Luna Platform Heatmap,
Luna Platform Summary,
Дашборды отдельных сервисов.

Luna Platform Heatmap позволяет оценить нагрузку на систему без конкретного ресурса. В статистике вы можете оценить время активности системы в определенное время.

Luna Platform Summary позволяет получать статистику по запросам для всех сервисов в одном месте, а также оценивать графики по RPS (Request Per Seconds).

Dashboards for individual services позволяет получать информацию о запросах по отдельным ресурсам, ошибкам и статус кодам для каждого сервиса. В таком дашборде будут отображаться не данные о загрузке, а искусственно сгенерированные данные в выбранном временном интервале.

Для использования дашбордов Grafana требуется следующее ПО:

InfluxDB 2.0 (в настоящее время используется версия 2.0.8-alpine)
Grafana (в настоящее время используется версия 8.5.20)

InfluxDB и Grafana уже включены в состав дистрибутива. При необходимости можно использовать собственную инсталляцию Grafana или установить ее вручную.

Ручная установка LUNA Dashboards#

Примечание. Ниже описаны действия для ручной установки LUNA Dashboards. Дашборды можно также автоматически запустить с помощью специальной команды в разделе "Визуализация мониторинга и логов с помощью Grafana" в руководстве по установке.

Установка плагина

Помимо встроенных плагинов Grafana, дашборды также используют плагин piechart. Использовать инструмент grafana-cli для установки piechart-panel можно с помощью следующей команды:

grafana-cli plugins install grafana-piechart-panel

При необходимости можно использовать архив "grafana-piechart-panel.zip" в "/var/lib/luna/current/extras/utils/".

Для применения плагина требуется перезапуск:

sudo service grafana-server restart

Запуск дашбордов

Дашборды можно запускать вручную или с помощью специального контейнера Grafana с дашбордами — luna-dashboards:

Запуск с использованием специального контейнера Grafana с дашбордами описан в руководстве по установке.
Запуск вручную описан далее в этом документе.

Установите Grafana. Пример команды приведен ниже:

docker run \
--restart=always \
--detach=true \
--network=host \
--name=grafana \
-v /etc/localtime:/etc/localtime:ro \
-e "GF_INSTALL_PLUGINS=grafana-piechart-panel" \
dockerhub.visionlabs.ru/luna/grafana:8.5.20

При необходимости в переменной окружения "GF_INSTALL_PLUGINS" можно указать путь до архива "/var/lib/luna/current/extras/utils/grafana-piechart-panel.zip".

Скрипты для установки плагинов Grafana можно найти в "/var/lib/luna/current/extras/utils/".

Перед запуском следующего скрипта необходимо установить Python версии 3.7 или новее. Данный пакет не входит в состав дистрибутива, и его установка в данном руководстве не описывается.

Перейдите в каталог luna dashboards.

cd /var/lib/luna/current/extras/utils/luna-dashboards_linux_rel_v.*

Создайте виртуальную среду.

python3.7 -m venv venv

Активируйте виртуальную среду.

source venv/bin/activate

Установите файл luna dashboards.

pip install luna_dashboards-*-py3-none-any.whl

Перейдите в следующий каталог.

cd luna_dashboards

Папка "luna_dashboards" содержит файл конфигурации "config.conf", который включает настройки для Grafana, InfluxDB и периодов мониторинга. По умолчанию файл уже включает настройки по умолчанию, но при необходимости их можно изменить с помощью команды "vi config.conf".

Запустите следующий скрипт для создания дашбордов.

python create_dashboards.py

Отключите виртуальную среду.

deactivate

Для использования веб-интерфейса Grafana нужно перейти по адресу "http://IP_ADDRESS:3000", при условии, что контейнеры Grafana и InfluxDB были запущены.

В левом верхнем углу нужно нажать кнопку "General", затем развернуть папку "luna_platform_5" и выбрать необходимый дашборд.

Grafana Loki#

Grafana Loki — система агрегации логов, позволяющая гибко работать с логами LUNA PLATFORM в Grafana.

С помощью Grafana Loki можно выполнять следующие задачи:

сбор логов LUNA PLATFORM
поиск по логам LUNA PLATFORM
визуализация логов
извлечение числовых метрик из логов
другие

См. подробную информацию о возможностях Grafana Loki в официальной документации: https://grafana.com/oss/loki/.

Grafana Loki включена в состав дистрибутива LUNA PLATFORM.

Для запуска Grafana Loki требуется следующее ПО:

запущенная Grafana с настроенным источник данных Loki в Grafana (см. раздел "LUNA Dashboards")
запущенный агент доставки логов Promtail (см. раздел "Promtail" ниже)

Таким образом, для работы с логами LUNA PLATFORM в Grafana выполняется следующая цепочка действий:

Команды запуска Grafana и Promtail приведены в руководстве по установке. В контейнере Grafana из дистрибутива LUNA PLATFORM уже настроен источник данных Loki.

Также можно запустить Grafana и Promtail с помощью выполнения дополнительного скрипта Docker Compose после выполнения основного скрипта Docker Compose (см. документ "Развертывание с помощью Docker Compose").

Promtail#

Для доставки логов LUNA PLATFORM в Grafana Loki используется специально настроенный агент Promtail. Как и Grafana Loki, агент Promtail включен в состав дистрибутива LUNA PLATFORM.

В комплекте поставки LUNA PLATFORM доступен настроенный файл конфигурации Promtail, предоставляющий возможность фильтрации по следующим меткам:

уровень логирования LP
сервисы LP
URI
статус коды LP

Некоторые дополнительные метки (например, версия сервиса LP) также могут быть указаны с помощью аргумента client.external-labels в команде запуска Promtail.

В Grafana Loki также настроено вторичное поле (см. derived field в официальной документации) для поиска по определенному идентификатору запроса (Request ID) в логах.

Базы данных#

Ручное создание баз данных сервисов в PostgreSQL#

В этом разделе описаны команды, необходимые для настройки внешнего PostgreSQL для работы с сервисами LP. Внешний означает, что уже есть рабочая БД и её необходимо использовать с LP.

Команды для Oracle не приведены в данной документации.

Необходимо указать внешнюю базу данных в конфигурациях сервисов LP.

Для сервисов Faces и Events необходимо добавить дополнительные функции VLMatch в используемую базу данных. Сначала библиотеку VLMatch нужно скомпилировать и перенести в PostgreSQL, а затем добавить функцию VLMatch в базы данных Events и Faces. См. разделы "Компиляция VLMatch для PostgreSQL", "Добавление функции VLMatch для БД Faces в PostgreSQL" и "Добавление функции VLMatch для БД Events в PostgreSQL" для подробной информации.

Создание пользователя PostgreSQL#

Создайте пользователя базы данных.

runuser -u postgres -- psql -c 'create role luna;'

Присвойте пользователю пароль.

runuser -u postgres -- psql -c "ALTER USER luna WITH PASSWORD 'luna';"

Создание базы данных Configurator#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Configurator.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_configurator;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_configurator TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Accounts#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Accounts.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_accounts;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_accounts TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Handlers#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Handlers.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_handlers;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_handlers TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Backport 3#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Backport 3.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_backport3;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_backport3 TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Faces#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Faces.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_faces;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_faces TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Events#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Events.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_events;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_events TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Tasks#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Tasks.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_tasks;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_tasks TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Lambda#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Lambda.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_lambda;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_lambda TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Создание базы данных Video Manager#

Предполагается, что пользователь базы данных уже создан.

Создайте базу данных для сервиса Video Manager.

runuser -u postgres -- psql -c 'CREATE DATABASE luna_video_manager;'

Присвойте привилегии пользователю базы данных.

runuser -u postgres -- psql -c 'GRANT ALL PRIVILEGES ON DATABASE luna_video_manager TO luna;'

Разрешите пользователю авторизацию в базе данных.

runuser -u postgres -- psql -c 'ALTER ROLE luna WITH LOGIN;'

Компиляция VLMatch в PostgreSQL#

Примечание. В следующей инструкции описана установка для PostgreSQL 16.

Все файлы, требуемые для компиляции расширения, заданного пользователем (UDx), в VLMatch, можно найти в следующей директории:

/var/lib/luna/current/extras/VLMatch/postgres/

Для компиляции функции VLMatch UDx необходимо:

установить репозиторий RPM:

dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

установить PostgreSQL:

dnf install postgresql16-server

установить окружение для разработки:

dnf install postgresql16-devel

установить пакет gcc:

dnf install gcc-c++

установить CMAKE. Необходима версия 3.5 или выше.
открыть скрипт make.sh в текстовом редакторе. Он включает в себя пути к используемой на данный момент версии PostgreSQL. Измените следующие значения (при необходимости):

SDK_HOME задает путь к домашней директории PostgreSQL. По умолчанию это /usr/pgsql-16/include/server;

LIB_ROOT задает путь к библиотечной корневой директории PostgreSQL. По умолчанию это /usr/pgsql-16/lib.

Откройте директорию скрипта make.sh и запустите его:

cd /var/lib/luna/current/extras/VLMatch/postgres/

chmod +x make.sh

./make.sh

Перенесите сгенерированный файл VLMatchSource.so в любое удобное место если PostgreSQL работает вне контейнера или в директорию /srv в контейнер PostgreSQL.

Путь до библиотеки указывается во время создания функции в БД (см. ниже).

Добавление функции VLMatch для БД Faces в PostgreSQL#

Сервис Faces требует добавления дополнительной функции VLMatch к используемой базе данных. LUNA PLATFORM не может выполнять вычисления по сравнению биометрических шаблонов без этой функции.

Библиотека VLMatch компилируется для конкретной версии базы данных.

Не используйте библиотеку, созданную для другой версии базы данных. Например, библиотеку, созданную для PostgreSQL версии 12 нельзя использовать для PostgreSQL версии 16.

В данном разделе описывается создание функции для PostgreSQL. Библиотека VLMatch должна быть скомпилирована и перенесена в PostgreSQL. См. раздел "Компиляция VLMatch для PostgreSQL".

Добавление функции VLMatch в базу данных Faces#

Функцию VLMatch необходимо применить в базу данных PostgreSQL.

Определите функцию в базе данных Faces:

sudo -u postgres -h 127.0.0.1 -- psql -d luna_faces -c "CREATE FUNCTION VLMatch(bytea, bytea, int) RETURNS float8 AS '/srv/VLMatchSource.so', 'VLMatch' LANGUAGE C PARALLEL SAFE;"

Важно! Здесь /srv/VLMatchSource.so - полный путь до скомпилированной библиотеки. Необходимо заменить путь на актуальный.

Протестируйте функцию, отправив следующий запрос в базу данных сервиса:

sudo -u postgres -h 127.0.0.1 -- psql -d luna_faces -c "SELECT VLMatch('\x1234567890123456789012345678901234567890123456789012345678901234'::bytea, '\x0123456789012345678901234567890123456789012345678901234567890123'::bytea, 32);"

База данных должна вернуть результат "0.4765625".

Добавление функции VLMatch для БД Events в PostgreSQL#

Сервис Events требует добавления дополнительной функции VLMatch к используемой базе данных. LUNA PLATFORM не может выполнять вычисления по сравнению биометрических шаблонов без этой функции.

Библиотека VLMatch компилируется для конкретной версии базы данных.

Не используйте библиотеку, созданную для другой версии базы данных. Например, библиотеку, созданную для PostgreSQL версии 12 нельзя использовать для PostgreSQL версии 16.

В данном разделе описывается создание функции для PostgreSQL. Библиотека VLMatch должна быть скомпилирована и перенесена в PostgreSQL. См. раздел "Компиляция VLMatch для PostgreSQL".

Добавление функции VLMatch в базу данных Events#

Функцию VLMatch необходимо применить в базе данных PostgreSQL.

Определите функцию в базе данных Events.

sudo -u postgres -h 127.0.0.1 -- psql -d luna_events -c "CREATE FUNCTION VLMatch(bytea, bytea, int) RETURNS float8 AS 'VLMatchSource.so', 'VLMatch' LANGUAGE C PARALLEL SAFE;"

Протестируйте функцию.

sudo -u postgres -h 127.0.0.1 -- psql -d luna_events -c "SELECT VLMatch('\x1234567890123456789012345678901234567890123456789012345678901234'::bytea, '\x0123456789012345678901234567890123456789012345678901234567890123'::bytea, 32);"

База данных должна вернуть результат "0.4765625".

VLMatch для Oracle#

Примечание. В следующей инструкции описана установка для Oracle 21c.

Все файлы, требуемые для компиляции расширения, заданного пользователем (UDx), в VLMatch, можно найти в следующей директории:

/var/lib/luna/current/extras/VLMatch/oracle

Для компиляции функции VLMatch UDx необходимо:

Установить требуемое окружение, см. требования:

sudo yum install gcc g++

Поменяйте переменную SDK_HOME — oracle sdk root (по умолчанию $ORACLE_HOME/bin, проверьте, что переменная окружения $ORACLE_HOME задана) в makefile.

vi /var/lib/luna/current/extras/VLMatch/oracle/make.sh

Откройте директорию и запустите файл "make.sh".

cd /var/lib/luna/current/extras/VLMatch/oracle

chmod +x make.sh

./make.sh

Определите библиотеку и функцию внутри базы данных (из консоли базы данных):

CREATE OR REPLACE LIBRARY VLMatchSource AS '$ORACLE_HOME/bin/VLMatchSource.so';
CREATE OR REPLACE FUNCTION VLMatch(descriptorFst IN RAW, descriptorSnd IN RAW, length IN BINARY_INTEGER)
   RETURN BINARY_FLOAT 
AS
   LANGUAGE C
   LIBRARY VLMatchSource
   NAME "VLMatch"
   PARAMETERS (descriptorFst BY REFERENCE, descriptorSnd BY REFERENCE, length UNSIGNED SHORT, RETURN FLOAT);

Протестируйте функцию посредством вызова (из консоли базы данных):

SELECT VLMatch(HEXTORAW('1234567890123456789012345678901234567890123456789012345678901234'), HEXTORAW('0123456789012345678901234567890123456789012345678901234567890123'), 32) FROM DUAL;

Результат должен быть равен "0.4765625".

Перенесите сгенерированный файл VLMatchSource.so в любое удобное место если Oracle работает вне контейнера или в директорию /srv в контейнер Oracle.

Путь до библиотеки указывается во время создания функции в БД (см. ниже).

Сбор информации для технической поддержки#

Для эффективного и оперативного решения проблем, технической поддержке VisionLabs необходимо предоставить логи сервисов LUNA PLATFORM и дополнительную информацию о статусе сторонних сервисов, состоянии лицензии, настройках LUNA PLATFORM и пр.

Соберите нижеописанные данные и отправьте их специалистам VisionLabs.

Сбор логов сервисов#

В LUNA PLATFORM существует два способа вывода логов:

стандартный вывод логов (stdout);
вывод логов в файл.

Настройки вывода логов задаются в настройках каждого сервиса в секции <SERVICE_NAME>_LOGGER.

По умолчанию логи выводятся только в стандартный вывод.

Для более подробной информации о системе логирования LUNA PLATFORM см. раздел "Логирование информации" в руководстве администратора.

Соберите логи всех сервисов. Например, можно собрать логи за последние 10 минут для всех сервисов с помощью нижеописанных команд.

docker logs --since 10m luna-licenses > luna-licenses_log.txt
docker logs --since 10m luna-faces > luna-faces_log.txt
docker logs --since 10m luna-image-store > luna-image-store_log.txt
docker logs --since 10m luna-accounts > luna-accounts_log.txt
docker logs --since 10m luna-tasks > luna-tasks_log.txt
docker logs --since 10m luna-events > luna-events_log.txt
docker logs --since 10m luna-sender > luna-sender_log.txt
docker logs --since 10m luna-admin > luna-admin_log.txt
docker logs --since 10m luna-remote-sdk > luna-remote-sdk_log.txt
docker logs --since 10m luna-handlers > luna-handlers_log.txt
docker logs --since 10m luna-lambda > luna-lambda_log.txt
docker logs --since 10m luna-python-matcher > luna-python-matcher_log.txt
docker logs --since 10m luna-backport3 > luna-backport3_log.txt
docker logs --since 10m luna-backport4 > luna-backport4_log.txt

Сбор дополнительной информации#

Необходимо собрать следующую дополнительную информацию:

Версия LUNA PLATFORM.

Версию LUNA PLATFORM содержится в названии архива с комплектом поставки. Также можно узнать актуальную версию перейдя на страницу http://your_server_ip_adress:5000/version в браузере.
Статус лицензии в зависимости от вендора:
- HASP — информация со страниц http://your_server_ip_adress:1947/_int_/features.html и http://your_server_ip_adress:1947/_int/devices.html
- Guardant — информация со страниц http://your_server_ip_adress:3189/#/dongles/list и http://your_server_ip_adress:3189/#/sessions
Актуальные настройки LUNA PLATFORM.

Актуальные настройки можно получить перейдя на страницу http://your_server_ip_adress:5010/4/luna_sys_info, указав логин и пароль от аккаунта. Логин и пароль по умолчанию — root@visionlabs.ai/root. После ввода пароля будет скачан файл в формате json, который нужно передать в техническую поддержку.
Статус сторонних сервисов:
- Docker: systemctl status docker
- aksusbd: systemctl status aksusbd
- grdcontrol: systemctl status grdcontrol
Статус контейнеров LUNA PLATFORM.

Можно получить список всех контейнеров с помощью команды docker ps -a.
Список открытых портов.

Можно вывести список открытых портов с помощью команды ss -ltn.
Список реестров в конфигурации Docker, к которым можно подключаться без использования защищенного соединения.

Список реестров можно получить с помощью команды cat /etc/docker/*.
Правила файрволла.

Правила файрволла можно получить с помощью команды iptables-save.
Общая информация о системе:
- Информация о процессоре: lscpu
- Использование памяти: free -h; lsmem
- Использование дискового пространства: df -h
Окружение и тип сервера:

Укажите, в каком окружении работает система (тестовое, продуктивное) и является ли сервер виртуальным или физическим.

Модель нейронной сети	Размер данных в формате Raw (байты)	Размер метаданных (байты)	Размер данных в формате SDK (Raw + метаданные)
54	512	8	520
56	512	8	520
57	512	8	520
58	512	8	520
59	512	8	520
60	512	8	520
62	512	8	520
65	512	8	520

Модель нейронной сети	Размер данных в формате Raw (байты)	Размер метаданных (байты)	Размер данных в формате SDK (Raw + метаданные)
54	512	8	520
56	512	8	520
57	512	8	520
58	512	8	520
59	512	8	520
60	512	8	520
62	512	8	520
65	512	8	520

Модель нейронной сети	Размер данных в формате Raw (байты)	Размер метаданных (байты)	Размер данных в формате SDK (Raw + метаданные)
54	512	8	520
56	512	8	520
57	512	8	520
58	512	8	520
59	512	8	520
60	512	8	520
62	512	8	520
65	512	8	520