Глоссарий#

Введение#

LUNA PLATFORM — это автоматизированная система распознавания лиц и тел. LUNA PLATFORM предназначена для решения следующих задач:

• Обработка и анализ изображений:
  • обнаружение лиц и тел на фотографиях;
  • оценка базовых атрибутов (возраст, пол, расовая принадлежность) и параметров лиц, тел и изображений (эмоции, верхняя одежда, соотношение сторон изображения и др.);
  • проверка изображений на соответствие стандарту ISO/IEC 19794-5:2011 и по нестандартным условиям.
  • определение атак на биометрическое предъявление (проверка Liveness) и анализ изображений на предмет использования технологии Deepfake.
• Поиск схожих лиц в базе данных (1 к 1, 1 ко многим и M к N);
• Хранение получаемых биометрических шаблонов лиц/тел в базах данных;
• Обработка и анализ видеофайлов или видеопотоков для решения различных аналитических задач, таких как: подсчет людей, отслеживание людей на кадре, обнаружение драк и др.;
• Создание списков для поиска;
• Сбор статистики;
• Гибкое управление запросами для соответствия требованиям обработки пользовательских данных.

Некоторые из вышеперечисленных функций лицензируются отдельно. См. раздел "Информация о лицензии".

Общие сведения#

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

Сервисы#

LP состоит из нескольких сервисов. Сообщение между ними происходит посредством HTTP-запросов: сервис получает запрос и возвращает ответ. Некоторые сервисы также взаимодействуют друг с другом через Redis или веб-сокеты.

Информацию об архитектуре LUNA PLATFORM 5 можно найти в разделе "Взаимодействие сервисов".

Все сервисы можно разделить на основные и дополнительные. С помощью основных сервисов обеспечивается оптимальная работа LP. Использование всех основных сервисов включено по умолчанию в настройках сервиса API. При необходимости некоторые основные сервисы можно отключить (см. раздел "Отключаемые сервисы").

У большинства сервисов имеется собственная база данных или файловое хранилище.

Основные сервисы#

Дополнительные сервисы#

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

Ниже представлена схема взаимодействия основных и дополнительных сервисов.

Данная схема не описывает линии связи между сервисами. Для полного описания взаимодействия основных сервисов см. раздел "Взаимодействие сервисов".

Сторонние сервисы#

Существует несколько сторонних сервисов, обычно используемых с LP.

Описание этих сервисов не приведено в данном документе. См. соответствующую документацию, предоставляемую поставщиками сервисов.

Система авторизации#

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

Аккаунты

Аккаунт необходим для разграничения областей видимости объектов для конкретного пользователя. Каждый созданный аккаунт имеет свой собственный уникальный идентификатор "account_id". Все данные аккаунтов сохраняются в БД сервиса Accounts под этим идентификатором.

Аккаунт можно создать с помощью POST запроса "create account" к сервису API, либо с помощью запроса "register account" к сервису Admin, либо с помощью пользовательского интерфейса Admin. При создании аккаунта необходимо указать следующие данные: login (email), password и account type (тип аккаунта).

Тип аккаунта определяет, какие данные доступны пользователю. Существует три типа аккаунтов:

• user — тип аккаунта, с помощью которого можно создавать объекты и использовать только данные своего аккаунта.
• advanced_user — тип аккаунта, для которого доступны права, аналогичные "user", а также есть доступ к данным всех аккаунтов. Доступ к данным других аккаунтов означает возможность получать данные (запросы GET), проверять их наличие (запросы HEAD) и выполнять запросы на сравнение по данным других аккаунтов.
• admin — тип аккаунта, для которого доступны права, аналогичные "advanced_user", а также есть доступ к сервису Admin

С помощью заголовка "Luna-Account-Id" в запросе "create account" можно задать желаемый идентификатор аккаунта.

Токены

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

Токен и все его разрешения сохраняются в БД и привязываются к аккаунту по параметру "account_id".

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

• expiration_time – время окончания действия токена в формате RFC 3339. Можно указать бесконечное время действия токена с помощью значения "null"
• permissions – разрешения, которые доступны пользователю
• visibility_area – видимость токеном данных других аккаунтов

Типы авторизации для доступа к ресурсам

В LUNA PLATFORM доступны следующие способы авторизации:

• BasicAuth. Авторизация по логину и паролю (задаются во время создания аккаунта).
• BearerAuth. Авторизация по JWT токену (выдается после создания токена).

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

См. подробную информацию о системе авторизации LUNA PLATFORM 5 в разделе "Аккаунты, токены и способы авторизации".

Подходы при работе#

В LUNA PLATFORM есть три основных операции:

1․ Детекция — процесс распознавания лица или тела на фотографии и нормализация изображения (создание биометрического образца) для дальнейшей работы. На этапе детекции также происходит эстимация (оценивание) параметров лица или тела, т.е. оценивание эмоций, направления взгляда, верхней одежды и др.

2․ Экстракция — процесс извлечения пола и возраста по изображению лица и извлечения набора уникальных свойств лица или тела (биометрических шаблонов) по биометрическому образцу для выполнения дальнейшего сравнения.

3․ Матчинг — процесс сравнения биометрических шаблонов.

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

Существует два основных подхода при выполнении вышеописанных операций.

Параллельное выполнение запросов#

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

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

• с помощью запроса "create handler" создается обработчик, содержащий в себе информацию о правилах обработки изображения;
• в запросе "generate events" указывается полученный идентификатор обработчика, прикрепляется обрабатываемое изображение и генерируется событие, содержащее в себе информацию, полученную с помощью обработки правил обработчика.

Таким образом, при генерации события одновременно выполняется детекция, эстимация, экстракция, матчинг, сохранение в БД и прочее.

Примеры распространенных сценариев использования обработчиков:

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

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

Преимущества подхода:

• все правила в одном месте; можно легко отредактировать существующий обработчик или создать новый для новой задачи. Следовательно, нет необходимости создавать и настраивать несколько разных запросов для выполнения базовых операций с изображениями;
• гибкое управление сохранением объектов в базы данных, настройка фильтров сохранения;
• возможность работы с пакетами изображений, расположенных в ZIP-архиве, на FTP-сервере, в S3-подобном хранилище и др.;
• возможность отправки уведомлений через веб-сокеты;
• сбор статистики.

Классический вариант использования такого подхода — в паре с модулем FaceStream. FaceStream анализирует видеопоток и отправляет лучшие изображения с видеопотока в LUNA PLATFORM на дальнейшую обработку. С помощью указанного обработчика, LUNA PLATFORM обрабатывает изображения по указанным правилам и сохраняет объекты в указанные базы данных.

Последовательное выполнение запросов#

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

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

• нормализация изображения, а также детекция и эстимация лица с помощью запроса "detect faces";
• извлечение пола, возраста и биометрического шаблона по нормализованному изображению с помощью запроса "extract attributes";
• создание лица с помощью запроса "create face";
• сравнение биометрических шаблонов лиц с помощью запроса "matching faces".

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

Данный подход рекомендован к использованию:

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

Детекция#

LP выполняет поиск всех лиц и/или тел на каждом входящем фотоизображении.

Детекция выполняется с помощью нейронных сетей, расположенных в контейнере Remote SDK.

Подробная информация о нейронных сетях описана в разделе "Нейросети".

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

Требования к формату исходного изображения#

Изображения должны отправляться только в разрешенных форматах. Формат изображения указывается в заголовке "Content-Type".

Поддерживаются следующие форматы изображений: JPG, PNG, BMP, PORTABLE PIXMAP, TIFF. Каждый формат имеет свои преимущества и предназначен для определенных задач.

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

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

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

LUNA PLATFORM 5 поддерживает многие цветовые модели (например, RGB, RGBA, CMYK, HSV и др.), однако при обработке изображения, все они преобразуются в цветовую модель RGB.

Изображение также может может быть перекодировано в формат Base64.

Дополнительная информация об исходных изображениях приведена в разделе "Исходные изображения".

Процесс детекции и эстимации лиц#

Ниже представлен порядок детекции лица на изображении:

Основные шаги при детекции изображений лиц:

• Обнаружение лица. Определяется ограничивающий прямоугольник лица (высота, ширина, координаты "X" и "Y") и пять контрольных точек лица.
• Нормализация. Изображение центрируется определенным образом и обрезается до размера 250x250 пикс., необходимого для дальнейшей работы. Таким образом, все обрабатываемые изображения выглядят одинаково. Например, левый глаз всегда находится в рамке, определяемой некоторыми координатами. Такое нормализованное изображение называется биометрическим образцом. Сам биометрический образец сохраняется в хранилище Image Store. После создания биометрического образца, ему присваивается специальный идентификатор "sample_id", который используется для дальнейшей обработки изображения.

Всем создаваемым объектам в LUNA PLATFORM присваиваются идентификаторы. Биометрический образец — "sample_id", лицо — "face_id", событие — "event_id" и т.д. Идентификаторы являются основным способом передачи данных между запросами и сервисами.

Подробная информация о биометрических образцах приведена в разделе «Объект «Биометрический образец».

• Эстимация. Оцениваются следующие параметры лица:
  • направление взгляда (углы поворота для обоих глаз);
  • положение головы (наклон вперед, в сторону, поворот);
  • шестьдесят восемь контрольных точек. Количество контрольных точек зависит от того, какие параметры лица подлежат оцениванию;
  • качество изображения (свет, тень, размытость, освещенность и зеркальность);
  • атрибуты рта (перекрытие, наличие улыбки);
  • наличие маски (медицинская или тканевая маска на лице, маска отсутствует, рот перекрыт);
  • эмоции (гнев, отвращение, страх, счастье, нейтральность, грусть, удивление);
  • другие (см. раздел "Параметры лиц").

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

Процесс детекции и эстимации тел#

Ниже представлен порядок детекции тела на изображении:

Основные шаги при детекции изображений тел:

• Обнаружение тела. Определяется ограничивающий прямоугольник тела (высота, ширина, координаты "X" и "Y").
• Нормализация. Изображение центрируется определенным образом и обрезается до размера 128x250 пикс., необходимого для дальнейшей работы (в остальном принцип работы аналогичен процессу нормализации лица).
• Эстимация. Оцениваются следующие параметры тела:
  • верхняя часть тела (наличие и цвет головного убора, цвет верхней одежды);
  • длина рукавов (длинные рукава, короткие рукава, неизвестно);
  • нижняя часть тела (тип нижней одежды — брюки, шорты, юбка, неизвестно; цвет нижней одежды, наличие и цвет обуви);
  • аксессуары;
  • другие (см. раздел "Параметры тел").

Взаимодействие сервисов при выполнении детекции#

Ниже приведена схема взаимодействия сервисов при выполнении детекции.

Запросы на выполнение детекции#

Ниже приведены основные запросы, где можно выполнить обнаружение лица или тела на изображении.

Запросы "create handler" и "generate events"#

Данные запросы используются при подходе "Параллельное выполнение запросов".

• Запрос "create handler":

• Запрос "generate events":

В запросе доступно использование схемы "multipart/form-data". Использование схемы позволяет отправить несколько изображений одновременно, указать дополнительную информацию для события и пр. См. дополнительную информацию в разделе "Использование схемы "multipart/form-data" при генерации события".

Запрос "detect faces"#

Запрос "detect faces" используется при подходе "Последовательное выполнение запросов". Данный запрос не может быть использован для изображения тела.

В запросе можно отправить изображение или указать URL-адрес изображения. Можно использовать схему "multipart/form-data" для отправки нескольких изображений в запросе. Каждое из отправленных изображений должно иметь уникальное имя. Заголовок "Content-Disposition" должен содержать фактическое имя файла.

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

• координаты "x" и "y" верхнего левого угла,
• высота,
• ширина.

Запрос "sdk"#

Запрос "sdk" также позволяет выполнить детекцию лица или тела на исходном изображении. В отличие от других запросов, его данные не могут быть использованы в дальнейшнем. См. подробную информацию в разделе "Ресурс sdk".

Запросы на выполнение эстимации#

Эстимация параметров лиц и тел выполняется совместно с детекцией. Чаще всего, параметры для оценивания имеют название вида estimate_<estimation_name>. Например, estimate_glasses.

В разделе "Оцениваемые данные" приведен перечень всех возможных параметров, которые можно оценить в LUNA PLATFORM 5.

Результаты детекции#

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

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

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

Данная информация дополняется в зависимости от включенных параметров эстимации лиц/тел.

Больше об детекции лиц, тел и сервисе Remote SDK можно прочитать в разделе "Сервис Remote SDK".

Доверенные детекции#

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

Работа с доверенными детекциями доступна в следующих запросах:

• "detect faces"
• "sdk"
• "iso"
• "generate events"
• "perform verification"
• "generate stream events (beta)"

Необходимо выполнить следующие действия:

1․ Включить режим указания доверенной детекции. Это можно сделать с помощью схемы "application/json" с параметром "trusted_detections" или с помощью схемы "multipart/form-data" с заголовком "X-Luna-Trusted-Detections".

2․ Передать координаты доверенной детекции ("x", "y", "width", "height") в параметрах "face_bounding_boxes" или "body_bounding_boxes".

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

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

Экстракция#

В LUNA PLATFORM под словом "экстракция" понимается:

• извлечение биометрических шаблонов и базовых атрибутов (пол, возраст, этническая принадлежность) лиц;
• извлечение биометрических шаблонов тел.

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

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

Восстановить исходное изображение лица или тела из БШ невозможно по соображениям безопасности персональных данных.

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

Биометрический шаблон извлекается с помощью нейронной сети, расположенной в контейнере Remote SDK.

При необходимости можно зашифровать биометрический шаблон для обеспечения дополнительной безопасности. См. раздел "Шифрование биометрических шаблонов" для более подробной информации.

Подробная информация о нейронных сетях описана в разделе "Нейросети".

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

Процесс экстракции#

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

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

Ниже представлен порядок выполнения экстракции:

• в большинстве запросов на извлечение, биометрический шаблон записывается в базу данных, не выдаваясь в теле ответа (см. "Запросы на извлечение биометрических шаблонов").

Особенности извлечения данных из лиц#

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

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

Агрегированный БШ можно получить из изображений, но не из уже созданных БШ.

Подробная информация об агрегации описана в разделе "Агрегирование".

Временные атрибуты#

После извлечения атрибутов с помощью соответствующих запросов (см. "Запросы на извлечение данных"), полученные данные сохраняются в БД Redis в качестве временных атрибутов.

Временные атрибуты имеют TTL (время существования) и удаляются из базы данных по истечении указанного периода. В запросе можно указать период от 1 до 86400 секунд. По умолчанию TTL составляет 5 минут.

Можно получить информацию о временном атрибуте по его идентификатору, пока не истечет его TTL.

Для того, чтобы сохранить атрибуты в базу данных, необходимо создать объект лицо, привязав к нему атрибуты. Лицо создается либо отдельным запросом после извлечения атрибутов (лицо сохраняется в БД Faces), либо во время генерации события (лицо сохраняется в БД Faces или в БД Events). Можно создать несколько лиц и объединить их в список, который можно использовать при сравнении.

См. подробную информацию в разделах «Объект «Лицо» и «Объект «Список».

Хранить атрибуты можно во внешней базе данных и использовать их в LP только тогда, когда требуется. См. раздел "Создание объектов с использованием внешних данных".

Подробная информация об атрибутах приведена в разделе «Объект «Атрибут».

Особенности извлечения данных из тел#

Для тел не существует атрибутов. Вся информация о телах может быть сохранена только как объект событие. Соответственно, извлеченные данные не сохраняются в базу данных Redis. Информация о телах может быть сохранена только в базу данных сервиса Events при включении соответствующего параметра.

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

Взаимодействие сервисов при выполнении экстракции#

Ниже приведена схема взаимодействия сервисов при выполнении экстракции.

Запросы на выполнение экстракции#

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

Запросы "create handler" и "generate events"#

Данные запросы используются при подходе "Параллельное выполнение запросов".

• Запрос "create handler":

• Запрос "generate events":

В запросе доступно использование схемы "multipart/form-data". Использование схемы позволяет отправить несколько изображений одновременно, указать дополнительную информацию для события и пр. См. дополнительную информацию в разделе "Использование схемы "multipart/form-data" при генерации события".

Запрос "extract attributes"#

Запрос "extract attributes" используется при подходе "Последовательное выполнение запросов". Данный запрос не может быть использован для биометрического образца тела.

Для сохранения информации в БД Faces, нужно привязать атрибуты к лицу с помощью запроса "create face". В противном случае, по истечению TTL временные атрибуты лица будут удалены из базы данных Redis. Невозможно сохранить лицо в базу данных Events, используя комбинацию запросов "extract attributes" + "create face". Для этого нужно воспользоваться подходом "Параллельное выполнение запросов" (см. выше).

Запрос "sdk"#

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

Результаты извлечения#

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

• идентификатор временного атрибута лица (не возвращается если в обработчике выключен параметр "store_attribute" политики "attribute_policy")
• адрес до сохраненного в БД Redis временного атрибута лица (не возвращается если в обработчике выключен параметр "store_attribute" политики "attribute_policy")
• базовые атрибуты лица
• качество БШ лица/тела
• набор идентификаторов биометрических образцов по которым было выполнено извлечение

Матчинг#

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

Сравнение выполняется с помощью сервиса Python Matcher. В ответе на сравнение выдается степень схожести, значение которой лежит в интервале от 0 до 1. Высокая степень схожести означает, что два БШ принадлежат одному и тому же человеку.

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

Исходники сравниваемых объектов представлены в виде эталонов (объектов, подлежащих сравнению) и кандидатов (набора объектов, с которыми производится сравнение). Каждый эталон сопоставляется с каждым из заданных кандидатов.

Сравнение не может быть выполнено при отсутствии БШ для любого из сравниваемых лиц.

Можно выбрать следующие объекты в качестве эталонов и кандидатов.

Эталоны:

• Атрибуты
• Лица
• Внешние ID лиц и событий
• События (лицо или тело)
• ID треков событий
• Биометрические шаблоны

Кандидаты:

• Лица
• События (лицо или тело)
• Атрибуты
• Биометрические шаблоны

Эталоны указываются с помощью ID соответствующих объектов. Если задается несуществующий эталон (например, указан несуществующий ID в поле "event_id" или "face_id"), возвращается соответствующая ошибка.

Кандидаты указываются с помощью фильтров. Результаты сравнения возвращаются для тех кандидатов, которые соответствуют заданным фильтрам. Если таковых не обнаружено (например, указан несуществующий ID в поле "event_ids" или "face_ids"), не будет ни результата сравнения, ни ошибки. То есть поле результата будет пустым.

Процесс выполнения матчинга#

Ниже представлен процесс выполнения матчинга с использованием лиц в качестве кандидатов и эталонов:

• Биометрические шаблоны можно также передать напрямую с помощью запроса "raw matching".

Взаимодействие сервисов при выполнении матчинга#

Ниже приведена схема взаимодействия сервисов при выполнении матчинга.

См. дополнительные сценарии взаимодействия сервисов при выполнении сравения в разделе "Диаграммы сравнения".

Фильтрация результатов матчинга#

Результаты матчинга можно фильтровать. Для фильтрации нужно указать соответствующие параметры запроса.

Ниже приведены некоторые примеры фильтров событий и лиц.

Для фильтрации событий можно:

• Указать камеру (поле «source») и период (поля «create_time__gte» и «create_time__lt» или «end_time__gte» и «end_time__lt»);
• Указать теги (поле "tags") для событий в качестве фильтров и выполнить сравнение для событий с помощью одних этих тегов;
• Указать географическую зону и выполнить сравнение с помощью событий, созданных только в этой зоне. Можно указать конкретную локацию (город, район, улица, дом) или область, заданную географическими координатами.

Для фильтрации лиц можно:

• Указать список внешних ID лиц для выполнения сравнения по ним;
• Указать список ID и выполнять сравнение по нему.

См. запросы "matching faces", "human body matching" и политику "match_policy" запроса "generate events" в справочном руководстве сервиса API для более подробной информации обо всех доступных фильтрах.

Запросы на матчинг#

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

Запросы "create handler" и "generate events"#

Данные запросы используются при подходе "Параллельное выполнение запросов".

• Запрос "create handler":

• Запрос "generate events":

В запросе доступно использование схемы "multipart/form-data". Использование схемы позволяет отправить несколько изображений одновременно, указать дополнительную информацию для события и пр. См. дополнительную информацию в разделе "Использование схемы "multipart/form-data" при генерации события".

Запросы "matching faces" и "matching bodies"#

Запросы "matching faces" и "matching bodies" используются при подходе "Последовательное выполнение запросов".

Запрос "raw matching"#

Можно задавать в качестве эталонов и кандидатов биометрические шаблоны в форматах SDK, Raw и XPK-файлах с помощью запроса "raw matching".

Все данные по БШ предоставляются посредством запроса, таким образом можно использовать этот запрос при необходимости производить сравнение БШ, не хранимых в базах данных LUNA PLATFORM.

В LUNA PLATFORM есть возможность извлечь биометрический шаблон в формате SDK (см. раздел "Форматы биометрических шаблонов").

Результаты матчинга#

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

• информация о эталоне
• информация о кандидате
• степень схожести каждого кандидата с эталоном
• отфильтрованные кандидаты

Для более подробной информации о сервисах сравнения БШ см. раздел "Сервисы сравнения".

Верификация#

Можно использовать ресурс "/verifiers" для создания специального обработчика для верификации. Он включает несколько политик для обработки входных изображений. См. подробную информацию о верификаторе в разделе "Описание верификаторов".

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

Сравнение большого набора биометрических шаблонов#

Иногда требуется сравнивать очень большое количество кандидатов. При классическом сравнении методом последовательного перебора большого количества биометрических шаблонов с помощью сервиса Python Matcher, невозможно получить малую задержку при высоком количестве запросов в секунду. Поэтому требуется использовать методы аппроксимации, реализованные в дополнительном модуле LUNA Index Module, которые обменивают некоторую точность на высокую скорость. Эти методы ускоряют сравнение за счет построения индекса, содержащего данные предварительной обработки.

LUNA Index Module лицензируется отдельно и поставляется по запросу к VisionLabs. Поставка модуля содержит всю необходимую документацию и скрипт Docker Compose.

Сохраняемые данные и объекты LP#

В этом разделе описываются данные, сохраняемые в LUNA PLATFORM 5.

Эта информация может быть полезна при использовании LUNA PLATFORM 5 в соответствии с правовой системой Европейского Союза и Общими положениями о защите (GDPR).

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

Обратите внимание, что комбинации данных LUNA PLATFORM могут быть расценены в соответствии с законом как персональные данные, даже если отдельные поля данных не содержат персональных данных. Например, объект лицо, содержащий параметр "user_data" и БШ, может считаться персональными данными.

Объекты и данные сохраняются в LP при выполнении определённых запросов. Поэтому следует отключать сохранение ненужных данных при выполнении этих запросов.

Рекомендуется ознакомиться с этим разделом, прежде чем принимать решение о том, какие данные следует получать и хранить в LUNA PLATFORM.

В этом документе рассматривается использование ресурсов, приведенных в спецификации OpenAPI, и создание только объектов LUNA PLATFORM 5. Данные, созданные с помощью сервисов Backport 3 и Backport 4, в этом разделе не рассматриваются.

Исходные изображения#

Фотоизображения являются основными источниками данных для LP. Они необходимы для создания биометрических образцов и проверки Liveness.

Можно отправить в LP сами изображения или URL-адреса изображений.

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

Не рекомендуется отправлять повернутые изображения в LP, поскольку они будут обработаны неверно и потребуется выполнить их поворот. Изображение можно повернуть, используя внутренние механизмы LP, двумя способами:

• включить параметр автоориентации "use_exif_info" по данным EXIF, имеющимся в параметрах запроса;
• включить настройку автоориентации "LUNA_REMOTE_SDK_USE_AUTO_ROTATION" в настройках сервиса Configurator.

Более подробная информация о работе с повернутыми изображениями приведена в разделе Особенности работы с сервисами.

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

Использование исходных изображений#

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

• "/sdk";
• "/detector";
• "/handlers/{handler_id}/events";
• "/verifiers/{verifier_id}/verifications";
• "/liveness".

Сохранение исходных изображений#

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

Исходные изображения можно сохранять в LP:

• используя POST запрос к ресурсу "/images".
• используя POST запрос к ресурсу "/handlers/{handler_id}/events". Исходные изображения сохраняются, если включён параметр "store_image" для "image_origin_policy" в "storage_policy" во время создания обработчика с помощью ресурса "/handlers".

Исходные изображения хранятся в бакете "visionlabs-image-origin" сервиса Image Store.

Сохранение метаданных с изображением

В ресурсе "/images" вместе с изображением можно сохранять пользовательские метаданные, используя заголовок X-Luna-Meta-<user_defined_key> со значением <user_defined_value>. В бакете исходных изображений хранилища Image Store, метаданные сохраняются в отдельный файл <image_id>.meta.json, который расположен рядом с исходным изображением.

В ответе на запрос на получение изображения (запрос "get image") нужно указать заголовок with_meta=1 для получения метаданных изображения в заголовке ответа.

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

Удаление исходных изображений#

Исходные изображения хранятся в бакете в течение неограниченного времени.

Исходные изображения можно удалить из бакета следующим образом:

• с помощью запроса DELETE к ресурсу "/images/{image_id}",
• вручную, удалив соответствующие файлы из бакета.

Объект «Биометрический образец»#

Использование биометрического образца#

Для лица и тела создаются отдельные биометрические образцы.

БО необходимы:

• для оценки базовых атрибутов.
• для оценки параметров лица, тела и изображения.
• для извлечения БШ для лиц и тел.
• при изменении версии нейросети БШ.

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

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

БО хранятся в бакетах хранилища Image Store неограниченное время.

БО хранятся в следующих бакетах:

• "visionlabs-samples" – бакет для БО лиц.
• "visionlabs-bodies-samples" – бакет для БО тел.

Пути к бакетам указываются в параметрах "bucket" в разделах "LUNA_IMAGE_STORE_FACES_SAMPLES_ADDRESS" и "LUNA_IMAGE_STORE_BODIES_SAMPLES_ADDRESS" в сервисе Configurator.

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

Создание и сохранение биометрических образцов#

БО создаются при обнаружении лица и/или тела на изображении. Они создаются при выполнении следующих запросов:

• запроса POST к ресурсу "/detector". БО создаются и сохраняются в неявной форме. Пользователь не влияет на их создание.
• запроса POST к ресурсу "/handlers/{handler_id}/events". Исходные изображения сохраняются при активации параметра "store_sample" для "face_sample_policy" и "body_sample_policy" в "storage_policy" во время создания обработчика с помощью ресурса "/handlers".
• запроса POST к ресурсу "/verifiers/{verifier_id}/verifications". БО сохраняются при активации параметра "store_sample" для "face_sample_policy" в "storage_policy" при создании верификатора с помощью ресурса "/verifiers". БО тела не сохраняются с помощью этого ресурса.

Сохранение внешних биометрических образцов

БО можно передать непосредственно в LP из внешнего программного обеспечения VisionLabs (например, FaceStream). Программное обеспечение самостоятельно создает биометрический образец из исходного изображения.

Можно вручную сохранить внешние БО в LP (внешний БО должен быть передан в запросе) с помощью следующих запросов:

• С помощью POST запроса к ресурсу "/samples/{sample_type}".
• Если установлен параметр "warped_image" в POST запросе к ресурсу "/detector".
• Если для параметра "image_type" установлено значение "1" (БО лица) или «2» (БО тела) в параметрах POST запроса к ресурсу "/handlers/{handler_id}/events". Для «face_sample_policy» и "body_sample_policy" из "storage_policy" должен активироваться параметр "store_sample".

Отключение сохранения биометрических образцов#

Отключение сохранения БО при выполнении запроса к ресурсу "/detector" невозможно. Созданные БО можно удалить вручную после выполнения запроса.

В ресурсе "/handlers" предусмотрен параметр "storage_policy", с помощью которого можно отключить сохранение:

• БО лиц. Необходимо установить "face_sample_policy" > "store_sample" на "0".
• БО тел. Необходимо установить "body_sample_policy" > "store_sample" на "0".

В ресурсе "/verifiers" предусмотрен параметр "storage_policy", с помощью которого можно отключить сохранение БО лиц. Необходимо установить "face_sample_policy" > "store_sample" на "0".

Удаление биометрических образцов#

Можно воспользоваться следующими способами удаления БО лица или тела:

• Выполнить запрос DELETE к ресурсу "/samples/faces{sample_id}", чтобы удалить БО лица по его идентификатору.
• Выполнить запрос DELETE к ресурсу "/samples/bodies{sample_id}", чтобы удалить БО тела по его идентификатору.
• Вручную удалить из бакета необходимые БО лица или тела.

Получение информации о биометрических образцах#

Биометрический образец лица или тела можно получить по его идентификатору.

• Выполнить запрос GET к ресурсу "/samples/faces/{sample_id}", чтобы получить БО лица по его идентификатору.
• Выполнить запрос GET к ресурсу "/samples/bodies/{sample_id}", чтобы получить БО тела по его идентификатору.

При удалении БО лица или тела система выдает ошибку при выполнении GET запроса.

Биометрический шаблон#

Базовое описание и применение биометрических шаблонов описано в разделе "Экстракция" выше.

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

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

Объект «Атрибут»#

Данный объект предназначен только для работы с лицами.

Перед прочтением рекомендуется ознакомиться с разделом "Экстракция".

Атрибуты – это временные объекты, которые включают в себя базовые атрибуты и биометрические шаблоны лица. Эти данные можно получить после обработки БО.

Базовые атрибуты содержат следующие личные данные:

• возраст. Возраст определяется в годах.

• пол. Предполагаемый пол: 0 — женский, 1 — мужской.

• этническая принадлежность. Предполагаемая этническая принадлежность.

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

БШ не считается персональными данными. С его помощью невозможно восстановить исходное лицо.

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

Объект "Атрибут" может использоваться в следующих случаях:

• при сравнении с помощью атрибутов. Оно может быть выполнено с использованием:

• ресурса "/matcher/faces",

• ресурса "/tasks/cross_match",
• ресурса "/verifiers/{verifier_id}/verifications".

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

• для создания ROC-кривых с помощью ресурса "/tasks/roc" (см. раздел "Задача ROC-curve calculating"),

• для сохранения данных существующего атрибута для лица с помощью ресурса "/faces".

Это не единственный способ сохранить БШ и базовые атрибуты лица. Можно использовать ресурс "/handlers/{handler_id}/events" для создания лица и прикрепления к нему извлечённого БШ и базовых атрибутов.

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

Создание и сохранение атрибутов#

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

• "/extractor",

Необходимо включить параметры запроса "extract_basic_attributes" и "extract_descriptor", чтобы извлечь соответствующие данные. Атрибуты сохраняются в неявной форме после выполнения запроса.

• "/handlers/{handler_id}/events",

Параметры "extract_basic_attributes", "extract_face_descriptor" и "extract_body_descriptor" включаются в обработчике для извлечения соответствующих данных. Необходимо включить опцию в обработчике для хранения атрибутов: "storage_policy" > "attribute_policy" > "store_attribute".

• "/verifiers/{verifier_id}/verifications".

Параметр "extract_basic_attributes" следует активировать в верификаторе для извлечения соответствующих данных. Необходимо активировать опцию "storage_policy" > "attribute_policy" > "store_attribute" в верификаторе для хранения атрибутов.

Атрибуты можно создать с использованием внешних БШ и внешних базовых атрибутов с помощью следующего ресурса:

• "/attributes".

Время существования атрибутов#

У атрибутов есть время существования (TTL). По истечении TTL атрибуты автоматически удаляются. Поэтому нет необходимости удалять атрибуты вручную.

Значение TTL по умолчанию можно задать в параметре "default_ttl" в сервисе Configurator. Максимальное значение TTL можно задать в параметре в сервисе Configurator.

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

• "/extractor" в параметре "ttl".
• "/handlers" в "storage_policy" > "attribute_storage" в параметре "ttl"

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

Можно отключить извлечение базовых атрибутов, установив значение параметра "extract_basic_attributes" равным "0" в следующих ресурсах:

• "/extractor"
• "/handlers"
• "/verifiers"

Можно отключить извлечение БШ, установив значение параметра "extract_descriptor" равным "0" в следующих ресурсах:

• "/extractor"
• "/handlers"

Отключение сохранения атрибутов#

Можно отключить параметр "storage_policy" > "attribute_policy" > "store_attribute" в ресурсе "/handlers" для отключения сохранения атрибутов. При использовании этого обработчика для ресурса "/handlers/{handler_id}/events" атрибуты не сохраняются даже в течение указанного периода TTL.

Можно отключить параметр "storage_policy" > "attribute_policy" > "store_attribute" в ресурсе "/verifiers" для отключения сохранения атрибутов. При использовании этого верификатора для ресурса "/verifiers/{verifier_id}/verifications", атрибуты не сохраняются даже в течение указанного периода TTL.

Удаление атрибутов#

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

Для удаление атрибутов по их идентификатору необходимо выполнить запрос DELETE к ресурсу "/attributes/{attribute_id}".

Получение информации об атрибутах#

Можно получить информацию о существующих временных атрибутах до истечения времени существования. Для этого необходимо:

• Выполнить запрос GET к ресурсу "/attributes/{attribute_id}", чтобы получить информацию о временном атрибуте по его идентификатору.
• Выполнить запрос GET к ресурсу "/attributes", чтобы получить информацию о ранее созданных атрибутах по их идентификаторам.
• Выполнить запрос GET к ресурсу "/attributes/{attribute_id}/samples", чтобы получить информацию обо всех биометрических образцах временных атрибутов по идентификатору атрибута.

Если время существования TTL какого-либо атрибута не истекло, выдаются данные атрибута. В противном случае данные для этого атрибута в ответе не выдаются.

Объект «Лицо»#

Лица – это изменяемые объекты, содержащие информацию об одном человеке.

В объекте "Лицо" хранятся следующие общие данные:

• Биометрический шаблон ("descriptor")
• Базовые атрибуты ("basic_attributes")
• Аватар ("avatar")
• Данные пользователя ("user_data")
• Внешний идентификатор ("external_id")
• Идентификатор события ("event_id")
• Идентификатор биометрического образца ("sample_id")
• Идентификатор списка ("list_id")
• Идентификатор учетной записи ("account_id")

См. раздел "Описание базы данных Faces" для получения дополнительной информации об объекте "Лицо" и данных, хранящихся в нем.

Данные атрибутов могут храниться в лице. Данные базовых атрибутов, данные БШ и информация о БО сохраняются в базе данных Faces и связаны с объектом "лицо".

При удалении лица, данные связанных атрибутов также удаляются.

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

Одно лицо нельзя связать с несколькими БШ.

• Базовые атрибуты: Базовые атрибуты могут использоваться для отображения информации в пользовательском интерфейсе.

Объект "Лицо" также может содержать идентификаторы биометрических образцов, используемых для создания атрибутов.

Описание общих полей событий:

• "user_data". Это поле может содержать любую информацию о человеке.

• "avatar". Аватар – это визуальное представление лица, которое можно использовать в пользовательском интерфейсе.

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

• "external_id". Внешний идентификатор лица.

Можно использовать внешний идентификатор для работы с внешними системами.

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

По запросу "faces" > "get faces" можно посмотреть все лица с одинаковым внешним идентификатором.

• "event_id". В этом поле может содержаться идентификатор события, в результате которого появилось это лицо.

• "list_id". В этом поле может содержаться идентификатор списка, с которым связано лицо.

Лицо можно связать с одним или несколькими списками.

• "account_id" – идентификатор учетной записи, которой принадлежит лицо.

• "sample_id" – идентификатор биометрического образца. К лицу можно привязать один или несколько БО. Это должны быть БО, используемые для извлечения атрибутов. Все БО должны принадлежать одному человеку. БШ невозможно будет обновить до новой версии нейросети, если для лица не будут сохранены БО.

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

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

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

Если в системе нет сохраненных лиц, следующие операции с лицами невозможны:

• Сравнение по лицам и спискам, если лица указаны в качестве кандидатов или эталонов в запросе к ресурсу "/matcher/faces".
• Сравнение по лицам и спискам, когда лица указаны в качестве кандидатов в политике сравнения к ресурсу "/handlers".
• Задачи Cross-matching, когда лица указываются в качестве кандидатов или эталонов в запросе к ресурсу "/tasks/cross_match".
• Задачи Clustering, если лица заданы как фильтры для кластеризации в запросе к ресурсу "/tasks/clustering".
• Запросы на верификацию, если идентификаторы лиц задаются в параметрах запроса в запросе к ресурсу "/verifiers/{verifier_id}/verifications".
• Задачи ROC-curve calculation (ресурс "/tasks/roc").

Создание и сохранение лиц#

Лица могут быть созданы с помощью следующих запросов:

• "create face"

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

• путем указания идентификатора временного атрибута;
• путем указания БШ и базовых атрибутов (с БО или без них);
• путем указания БШ (с БО или без них);
• путем указания базовых атрибутов (с БО или без них);

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

• "generate events". В используемом обработчике должен быть активирован параметр "storage_policy" > "face_policy" > "store_face".

Запросы для работы с лицами#

Ниже приведены запросы для работы с лицами:

Объект «Список»#

Список – это объект, в котором могут находиться лица, относящиеся к одной категории, например, клиенты или сотрудники.

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

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

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

В списки можно добавлять только лица.

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

Запросы для работы со списками#

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

Объект «Событие»#

События используются при подходе "Параллельное выполнение запросов".

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

В отличие от лиц, события невозможно изменить после создания. Единственным исключением является БШ, прикреплённый к событию. Он может быть обновлён на новую версию нейронной сети.

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

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

Событие может быть связано с БШ, хранящимся в базе данных Events.

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

В объекте "Событие" хранятся следующие основные данные:

• "source". В этом поле может быть указан источник, из которого было получено лицо или тело человека. Значение указывается при выполнении запроса "generate events".

• "location". В этой группе параметров приведена информация о месте, где произошло событие. Значения указываются при выполнении запроса "generate events". В эту группу входят следующие поля:

• "city"

• "area"
• "district"
• "street"
• "house_number"

• "geo_position" – широта и долгота.

• "tag". Это поле содержит тег (или несколько тегов), применяемый при выполнении "conditional_tags_policy". Теги можно указать при выполнении запроса "create handler" или "generate events".

• "emotion". В этом поле отображается преобладающая эмоция, оцениваемая для лица. При необходимости можно отключить параметр "estimate_emotions" в ресурсе "/handlers" или "create verifier".
• "insert_time". В этом поле содержится время, когда лицо появилось в видеопотоке. Эти данные обычно предоставляются внешними системами.
• "top_similar_object_id". В этом поле содержится идентификатор наиболее похожего объекта.
• "top_similar_external_id". В этом поле содержится внешний идентификатор наиболее похожего кандидата (события или лица), с которым выполняется сравнение лица.
• "top_matching_candidates_label". В этом поле содержится метка, применяемая при выполнении "match_policy". Метки задаются в этой политике в ресурсе "/handlers".
• "face_id". События содержат идентификатор лица, появившегося в результате события.
• "list_id". События содержат идентификатор списка, с которым связано созданное лицо.
• "external_id". Этот внешний идентификатор указывается для лица, созданного при обработке запроса события. Значение указывается при выполнении запроса "generate events".
• "user_data". Это поле может содержать любую пользовательскую информацию. Указываются данные пользователя для лица, созданного при обработке запроса события. Значение указывается при выполнении запроса "generate events".
• базовые атрибуты "age", "gender" и "ethnic_group" можно сохранить в событии. Извлечение базовых атрибутов задается в "extract_policy" ресурса "/handlers".
• БШ лица и тела. События могут использоваться для операций сравнения, поскольку они содержат БШ.
• информация о лицах, телах и событиях, используемых для сравнения с событиями.
• информация о результатах обнаружения лиц и тел людей, включая:
• идентификаторы созданных биометрических образцов.
• информация об ограничивающих прямоугольниках обнаруженных лиц/тел.
• "detect_time" – время обнаружения события лица/тела. Значение выдается от внешней системы.
• "image_origin" – URL исходного изображения, на котором было обнаружено лицо/тело.

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

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

Агрегирование атрибутов для событий

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

В соответствии с указанными настройками на входных изображениях обнаруживаются лица и тела. Если включено обнаружение лиц и должна быть выполнена агрегация БШ, то единый БШ создаётся на основе всех найденных лиц. Такая же логика используется и для создания агрегированного БШ тел. Кроме того, агрегируются базовые атрибуты, полученные значения определения Liveness, масок, эмоций, верхняя и нижняя части тела и аксессуары тела.

Вся информация об обнаруженном лице/теле и предполагаемых свойствах выдается в ответе отдельно для каждого изображения. При сохранении события в БД заносится агрегированные результаты. Информация о детекции лица/тела добавляется в базу данных Events в виде отдельной записи для каждого изображения из запроса.

При выполнении агрегации изображения в запросе к ресурсу "/handlers/{handler_id}/events" должны содержать только одно лицо/тело и это лицо/тело должны принадлежать одному и тому же человеку.

Использование событий#

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

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

События предоставляют следующие возможности:

• Сравнение по событиям

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

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

• Уведомления через веб-сокеты

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

См. раздел "Отправка уведомлений через сервис Sender".

• Сбор статистики

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

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

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

Дополнительную информацию по запросу "events" > "get statistics on events" см. в "APIReferenceManual.html".

• Пользовательские данные

В события можно добавлять пользовательскую информацию, которую в дальнейшем можно использовать для фильтрации событий. Информация передается в формате JSON и записывается в базу данных Events.

См. подробную информацию в разделе "Метаинформация события".

Создание и сохранение событий#

События создаются при выполнении запроса к ресурсу "/handlers/{handler_id}/events". Для параметра "event_policy" > "store_event" необходимо установить значение "1" при создании обработчика с использованием ресурса "/handlers".

Для создания и сохранения событий вручную используйте ресурс "/handles/{handler_id}/events/raw".

Формат сгенерированного события аналогичен формату, выдаваемому с помощью ресурса "/handlers/{handler_id}/events". Поля "event_id" и "url" не указываются при создании запроса. Они возвращаются в ответе после создания события.

Уведомления с использованием веб-сокетов отправляются при создании событий через ресурс "/handlers/{handler_id}/events".

Удаление событий#

События удаляются только с помощью задачи Garbage collection. Необходимо установить фильтры для удаления всех событий, соответствующих этим фильтрам.

Чтобы удалить событие, нужно отправить запрос POST к ресурсу "/tasks/gc".

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

Получение информации о событиях#

Можно получить информацию об имеющихся событих.

• С помощью запроса "events" > "get event" можно получить информацию о событии по его идентификатору.

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

• С помощью запроса "events" > "get events" можно получить информацию обо всех ранее созданных событиях в соответствии с установленными фильтрами. По умолчанию события фильтруются за последний месяц начиная с текущей даты. Если задан какой-либо из следующих фильтров, то фильтрация по умолчанию не будет использоваться.

• список идентификаторов событий (event_ids);

• нижнее пороговое значение идентификатора события (event_id__gte);
• верхнее пороговое значение идентификатора события (event_id__lt);
• нижнее пороговое значение времени создания (create_time__gte);
• верхнее пороговое значение времени создания (create_time__lt).

Использование схемы "multipart/form-data" при генерации события#

В запросе "generate events" можно отправить изображение, указать URL-адрес изображения или отправить "сырой" биометрический шаблон. Можно также использовать схему "multipart/form-data" для отправки нескольких изображений в запросе. Каждое из отправленных изображений должно иметь уникальное имя. Заголовок "Content-Disposition" должен содержать фактическое имя файла.

В запросе также можно указать следующие параметры с помощью схемы "multipart/form-data":

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

Все вышеперечисленная информация будет записана в событие при его генерации.

Объект «Обработчик»#

Обработчики используются при подходе "Параллельное выполнение запросов".

Обработчик – это объект, в котором хранятся точки входа для обработки изображений. Точки входа называются политиками. Они характеризуют процесс обработки изображения, следовательно, определяют сервисы LP, используемые для обработки. Обработчик создается с помощью запроса "create handler".

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

Политики обработчика

В таблице ниже представлены все существующие политики обработчиков. Каждая политика соответствует одному из сервисов LP, приведенных в столбце "Сервис".

Table: Политики обработчика

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

Все доступные политики описаны в справочном руководстве сервиса API.

Фильтрация выходных данных

Во многих политиках есть фильтры. Фильтры могут указываться как явно в поле "filters", так и в параметрах с названием вида "‹estimation›_states". Если фильтрация будет выполнена в первой политике, то это приведет к прекращению выполнения последующих политик, поскольку они выполняются последовательно. В таком случае событие не будет сохранено в БД, а отфильтрованные объекты отобразятся в подблоке "filtered_detections" в теле ответа запроса на генерацию события.

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

При использовании обработчиков можно:

• Указать параметры обнаружения лица/тела и предполагаемые параметры лица/тела (см. "Обработка исходного изображения и создание биометрических образцов").
• Активировать извлечение базовых атрибутов и БШ (см. "Извлечение биометрических шаблонов и создание атрибутов").
• Выполнить сравнение БШ (см. "Сравнение биометрических шаблонов") для получения результата сравнения и использования результата в качестве фильтров для политик.
• Настроить автоматическое создание лиц с помощью фильтров. Можно указать фильтры в соответствии с предполагаемыми базовыми атрибутами и результатами сравнения.
• Настроить автоматическое прикрепление созданных лиц к спискам на основании фильтров. Можно указать фильтры в соответствии с предполагаемыми базовыми атрибутами и результатами сравнения.
• Указать объекты, которые необходимо сохранить после обработки изображения.
• Настроить автоматическое добавление тегов к событию на основании фильтров. Можно указать фильтры в соответствии с предполагаемыми базовыми атрибутами и результатами сравнения.

Кроме того, доступна возможность обработки пакета изображений с помощью обработчика (см. "Задача Estimator").

Существует три типа обработчиков (параметр "handler_type"):

• статический
• динамический
• lambda

Статический обработчик#

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

Динамический обработчик#

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

Верификаторы могут быть только статическими.

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

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

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

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

Lambda обработчик#

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

Все запросы будут отправлены в обработчик lambda с использованием "lambda_id".

Если пользовательская Handlers-lambda поддерживает возможность генерации события, то формат тела запроса и ответа к ресурсам "/handlers/{handler_id}/events" или "/tasks/estimator" будет соответствовать спецификации OpenAPI. Если же Handlers-lambda не поддерживает возможность генерации события, то должен быть использован запрос к ресурсу "/lambdas/{lambda_id}/proxy" с соответствующей формой запроса.

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

См. подробную информацию в разделе "Сервис Lambda".

Запросы для работы с обработчиками#

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

Объект «Верификатор»#

Верификаторы используются при подходе "Параллельное выполнение запросов".

Сервис Handlers также обрабатывает запросы на создание верификаторов, необходимых для процесса верификации. Они создаются с помощью запроса "create verifier".

Верификатор содержит ограниченное количество политик обработчика — detect_policy, extract_policy и storage_policy.

В верификаторе можно задать "verification_threshold".

Созданный верификатор следует использовать при отправке запросов в:

• ресурс "/verifiers/{verifier_id}/verifications". Можно задать ID объектов, по которым должна производиться верификация.
• ресурс "/verifiers/{verifier_id}/raw". Можно задать биометрические шаблоны в чистом виде в качестве эталонов и кандидатов для сравнения. Т. к. обрабатываются БШ в чистом виде, "verification_threshold" — это основной параметр, используемый из указанного верификатора.

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

Запросы для работы с верификаторами#

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

Прочие объекты#

В сервисе Image Store можно хранить любые файлы в качестве объектов (например, видеофайл).

Загрузить файлы можно с помощью запроса "create objects". Байты файла должны быть указаны в теле запроса, а заголовок Content-Type должен содержать MIME-тип файла (например, video/mp4). Ответ на запрос "get object" содержит заголовок Content-Disposition. Этот заголовок содержит имя файла объекта вложения (например, video_1.mp4). Имя файла генерируется на основе object_id и MIME-типа.

Если MIME-тип файла не получилось определить, то расширение файла будет установлено как .bin.

Отправка уведомлений через сервис Sender#

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

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

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

Уведомление о новом событии отправляется сервисом Sender.

Для более подробной информации о работе сервиса Sender см. раздел "Сервис Sender".

Общие сведения сервиса Licenses#

Сервис Licenses предоставляет информацию об условиях лицензии сервисам LP.

См. раздел "Сервис Licenses" для более подробной информации.

Общие сведения сервиса Admin#

Сервис Admin обеспечивает инструменты для административных процедур.

Все запросы сервиса Admin описаны в спецификации OpenAPI сервиса Admin.

См. раздел "Сервис Admin" для более подробной информации о сервисе Admin.

Общие сведения сервиса Configurator#

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

См. раздел "Сервис Configurator" для более подробной информации о сервисе Configurator.

Общие сведения сервиса Tasks#

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

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

См. раздел "Сервис Tasks" для более подробной информации об обработке задач.

Задача Clustering

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

Можно задать фильтры для выбора обрабатываемых объектов.

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

См. запрос "task processing" > "clustering task" для получения более подробной информации о создании запроса на задачу Clustering.

См. раздел "Задача Clustering" для более подробной информации об этой задаче.

Задача Reporter

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

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

См. запрос "task processing" > "reporter task" для более подробной информации о создании запроса на задачу Reporter.

См. раздел "Задача Reporter" для более подробной информации об этой задаче.

Задача Exporter

Задача Exporter позволяет получать данные по событиям и/или лицам и экспортировать их из LP в CSV-файл.

В строках файла содержится информация о запрашиваемых объектах и соответствующие биометрические образцы (если их сохранение указано в запросе).

См. запрос "task processing" > "exporter task" для более подробной информации о создании запроса на выполнение задачи Exporter.

См. раздел "Задача Exporter" для более подробной информации об этой задаче.

Задача Cross-matching

Cross-matching (перекрестное сравнение) означает, что большое количество эталонов можно сравнить с большим количеством кандидатов. Таким образом, каждый эталон сравнивается с каждым кандидатом.

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

См. запрос "task processing" > "cross-matching task" в справочном руководстве сервиса API для более подробной информации о создании запроса на выполнение задачи Cross-matching.

См. раздел "Задача Cross-matching" для более подробной информации об этой задаче.

Задача Linker

Задача Linker позволяет:

• осуществлять привязку существующих лиц к спискам;
• создавать лица из существующих событий и привязывать их к спискам.

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

См. запрос "task processing" > "linker task" в справочном руководстве сервиса API для более подробной информации о создании запроса на выполнение задачи Linker.

См. раздел "Задача Linker" для более подробной информации об этой задаче.

Задача Estimator

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

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

Ресурс может принимать в обработку пять типов источников с изображениями:

• ZIP-архив
• S3-подобное хранилище
• Сетевой диск
• FTP-сервер
• Сетевая файловая система Samba

См. запрос "task processing" > "estimator task" в справочном руководстве сервиса API для более подробной информации о создании запроса на выполнение задачи Estimator.

См. раздел "Задача Estimator" для более подробной информации об этой задаче.

Backport#

В LP 5 сервисы Backport (ретроподдержка) — это механизм, позволяющий принимать запросы в формате предыдущих версий LP, но обрабатывать их в новой версии.

Ретроподдержка в LUNA PLATFORM 3 и LUNA PLATFORM 4 реализуется посредством сервисов Backport 3 и Backport 4 соответственно.

Ретроподдержка позволяет отправлять запросы, аналогичные запросам из LUNA PLATFORM 3 и LUNA PLATFORM 4, и получать отклик в требуемом формате.

При использовании ретроподдержки есть некоторые нюансы.

• Миграция данных в ретроподдержку достаточно сложная.

  Структуры баз данных LUNA PLATFORM 3 и LUNA PLATFORM 4 отличаются от структуры базы данных LUNA PLATFORM 5. Поэтому для переноса данных необходимо выполнить дополнительные шаги, и в процессе могут возникать ошибки.

• Ретроподдержка имеет много ограничений.

  Не вся логика из LP 3 и LP 4 может поддерживаться в ретроподдержке. Смотрите раздел "Ограничения при работе с сервисами Backport" для получения дополнительной информации.

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

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

Пример использования:

К примеру, есть интерфейсное приложение, отправляющее запросы в LUNA PLATFORM 3.

При использовании сервиса Backport 3 запросы в LP 3 принимаются сервисом, форматируются и отправляются в LUNA PLATFORM 5 в формате, соответствующем спецификации API. LP 5 обрабатывает этот запрос и отправляет отклик сервису Backport 3, который приводит все входные результаты к формату LP 3 и отправляет отклик.

Ограничения при работе с сервисами Backport#

Так как таблицы сохраненных данных и сами данные различны в разных версиях LP, существуют особенности и ограничения при выполнении запросов. Информация об этих особенностях и ограничениях представлена в разделах "Backport 3" и "Backport 4" данного документа.

Сервисы Backport и API в LP 5 можно использовать одновременно с соблюдением следующих ограничений:

• При использовании сервисов Backport рекомендуется использовать разные аккаунты для запросов в сервисы Backport и API в LUNA PLATFORM 5.

• Следует выполнять запросы администратора, которые не используют ID аккаунта, только напрямую в LUNA PLATFORM 5.

Ресурс sdk#

Ресурс sdk позволяет напрямую обращаться к сервису Remote SDK для обнаружения лиц и/или тел и оценки атрибутов входных изображений. После выполнения запроса полученные данные не сохраняются в базе данных и Image Store, и возвращаются только в ответе.

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

• оценивать наличие очков на изображении;
• оценивать Liveness;
• оценивать параметры лиц/тел;
• агрегировать параметры лица/тела;
• создавать биометрический образец лица и возвращать его биометрический шаблон в формате SDK, закодированном в Base64;
• создавать биометрический образец тела и возвращать его биометрический шаблон в формате SDK, закодированном в Base64;
• извлекать биометрические шаблоны лица и тела и возвращать их в ответе;
• устанавливать порог оценки качества биометрического шаблона для фильтрации изображений, не подходящих для дальнейшей обработки;
• фильтровать по наличию маски;
• другие.

Биометрический шаблон лица или тела в формате SDK, закодированного в Base64 можно использовать в запросах на сравнение "сырых" биометрических шаблонов.

Аккаунты, токены и способы авторизации#

Аккаунт#

Аккаунт необходим для разграничения областей видимости объектов для конкретного пользователя. Наличие аккаунта требуется для выполнения большинства запросов. Каждый созданный аккаунт имеет свой собственный уникальный идентификатор "account_id". Все данные аккаунтов сохраняются в БД сервиса Accounts под этим идентификатором.

Аккаунт можно создать с помощью POST запроса "create account" к сервису API, либо с помощью сервиса Admin. При создании аккаунта необходимо указать следующие данные: электронная почта (login), пароль (password) и тип аккаунта (account_type).

Тип аккаунта#

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

Существует три типа аккаунтов:

• user — тип аккаунта, с помощью которого можно создавать объекты и использовать только данные своего аккаунта.
• advanced_user — тип аккаунта, для которого доступны права, аналогичные "user", а также есть доступ к данным всех аккаунтов. Доступ к данным других аккаунтов означает возможность получать данные (запросы GET), проверять их наличие (запросы HEAD) и выполнять запросы на сравнение по данным других аккаунтов.
• admin — тип аккаунта, для которого доступны права, аналогичные "advanced_user", а также есть доступ к сервису Admin.

В сервисе API можно работать со всеми типами аккаунтов, но создать можно только аккаунты типа "advanced_user" и "user", в то время как в сервисе Admin можно создать все три типа.

По умолчанию в системе существует аккаунт типа "admin" и логином и паролем по умолчанию root@visionlabs.ai/root.

С помощью заголовка "Luna-Account-Id" в запросе "create account" можно задать желаемый идентификатор аккаунта. Также его необходимо использовать в случае, если необходимо сохранить возможность работы с данными, созданными в версиях LP до 5.30.0 с помощью указания идентификатора "account_id" в заголовке "Luna-Account-Id". Таким образом, использование данного параметра привяжет старый "account_id" к создаваемому аккаунту (см. подробную информацию о миграции в разделе "Миграция аккаунтов" в руководстве по обновлению LUNA PLATFORM).

В ответе на запрос на создание аккаунта выдается "account_id". После создания аккаунта можно использовать этот идентификатор для авторизации LunaAccountIdAuth или использовать авторизацию авторизацию BasicAuth (авторизация по по логину/паролю).

Токен#

Токен привязывается к существующему аккаунту с любым типом ("user", "advanced_user", "admin") и позволяет наложить расширенные ограничения на выполняемые запросы. Например, при создании токена можно дать пользователю разрешение только на создание и изменение всех списков и лиц, или можно запретить использование определенных обработчиков, указав их идентификатор.

Токен создается с помощью запроса "create token" к сервису API.

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

Нет необходимости в использовании и токена и аккаунта. При работе с токенами можно ограничить доступ к ресурсу "/accounts" с помощью внешних средств.

Для токена в любой момент можно выдать дополнительные ограничения с помощью запроса "replace token" или можно отозвать токен с помощью запроса "delete token". В этом случае токен будет удален из БД и больше не может быть использован для авторизации.

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

— expiration_time – время окончания действия токена в формате RFC 3339. Можно указать бесконечное время действия токена с помощью значения "null" — permissions – действия, которые может выполнять пользователь (см. "Разрешения, задаваемые в токене")

Для токена также возможно указать видимость токеном данных других аккаунтов с помощью параметра "visibility_area" (см. раздел "Просмотр данных других аккаунтов").

В ответе на запрос на создание токена выдается "token_id" и закодированный в Base64 JWT токен. После создания токена можно использовать полученный JWT токен для авторизации BearerAuth.

Разрешения, задаваемые в токене#

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

Пользовательские права предназначены для проксирования запросов LUNA Streams через LUNA API. В остальных случаях использование пользовательских прав не будет иметь эффекта. См. раздел "Проксирование запросов в LUNA Streams через LUNA API" в руководстве администратора FaceStream.

Ресурсы "/iso", "/sdk", "/liveness" и "/videosdk" по умолчанию не требуют никакой авторизации.

Значение [] означает отсутствие всех разрешений.

Разрешения "emit_events" и "verify" позволяют указать можно ли выполнять запросы к ресурсу "generate events" или "perform verification", а также поместить идентификаторы обработчиков или верификаторов в черный или белый списки. Если идентификаторы "handler_id" или "verifier_id" присутствуют в черном списке, то только их использование будет запрещено. Если же идентификаторы присутствуют в белом списке, то только их использование будет разрешено. Максимальное количество идентификаторов в списках — 100. При использовании разрешения "emit_events" у пользователя не должно быть прав "creation" и "modification" на использование обработчика.

Если выдано разрешение "emit_events", то во время генерации события будут созданы все необходимые объекты независимо от разрешений, задаваемых в токене. Например, разрешение типа "faces" регулирует работу с лицами только в запросах к ресурсам "faces/*", но не влияет на создание лица во время генерации события. Таким образом, при использовании обработчика с параметром "store_face" и отсутствии права "creation" для "faces", все равно будет создано лицо.

Если выдано разрешение "verify", то во время выполнения верификации будут созданы все необходимые объекты независимо от разрешений, задаваемых в токене. Например, разрешение типа "sample" не влияет на создание биометрического образца во время выполнения верификации. Таким образом, при использовании верификатора с параметром "store_sample" и отсутствии права "creation" для "samples", все равно будет создан биометрический образец.

При задании разрешений следует учитывать следующие особенности:

• тип "modification" означает выполнение PATCH и PUT запросов
• прикрепление/открепление к списку является разрешением типа "modification"
• удаление списка с включенной настройкой "with_faces" (запрос "delete lists") требует разрешения "face" > "deletion"
• прикрепление лица к списку в запросе на создания лица (запрос "create face") требует разрешения "list" > "modification"
• при выполнении сравнения необходимо иметь разрешение "matching" для соответствующих объектов (event, face, attribute)
• запросы на получение статистики по событиям (запрос "get statistics on events") требуют разрешения "event" > "view"
• разрешение "event" > "create" дает право только на создание события с помощью запроса "save event". Для генерации события необходимо воспользоваться разрешением "emit_events" (см. выше)
• разрешение "event" > "create" не распространяется на верификаторы

См. таблицу зависимости разрешений токенов от ресурсов сервиса API в руководстве разработчика.

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

Данные другого аккаунта могут быть просмотрены если:

• тип аккаунта установлен как "advanced_user" или "admin"
• при создании токена был указан параметр "visibility_area" = "all".

Для типа аккаунта "user" нельзя задать "visibility_area" = "all".

Если установлен тип аккаунта "advanced_user"/"admin" и создается токен с установленным параметром "visibility_area" = "account", то при авторизации по токену (BearerAuth) пропадет возможность смотреть данные других аккаунтов, однако при авторизации по логину/паролю (BasicAuth), такая возможность останется.

Если установлен тип аккаунта "advanced_user"/"admin" и создан токен с установленным параметром "visibility_area" = "all", а затем тип аккаунта изменяется на "user" (с помощью запроса "patch account"), то при попытке выполнить запрос на просмотр данных других аккаунтов с помощью токена будет выдана ошибка.

При использовании авторизации LunaAccountIdAuth область видимости регулируется с помощью заголовка "Luna-Account-Id", что означает, что видны только данные аккаунта, связанного с этим идентификатором.

Для верификаторов недоступна возможность использования области видимости данных всех аккаунтов. При значении параметра "visibility_area" = "all", будет видны данные только своего аккаунта.

Типы авторизации для доступа к ресурсам#

В LUNA PLATFORM доступно три типа авторизации:

• BasicAuth. Авторизация по логину и паролю (задаются во время создания аккаунта).
• BearerAuth. Авторизация по JWT токену (выдается после создания токена).
• LunaAccountIdAuth. Авторизация по заголовку "Luna-Account-Id", в котором указывается сгенерированный после создания аккаунта "account_id". Данный способ считается устаревшим и не рекомендуется к использованию.

Авторизация LunaAccountIdAuth может быть включена с помощью настройки "ALLOW_LUNA_ACCOUNT_AUTH_HEADER" в секции "OTHER" настроек сервиса API в Configurator (по умолчанию отключена).

В спецификации OpenAPI заголовок "Luna-Account-Id" помечен словом Deprecated.

Нет необходимости в использовании всех трех типов авторизации при выполнении запросов. Необходимо выбрать предпочтительный способ в зависимости от требуемых задач.

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

Проверка актуальности учетной записи#

С помощью ресурса "verify credentials" можно проверять существующие учетные записи по одному из типов:

• верификация логина/пароля. Если верификация успешна – вернется идентификатор аккаунта и его тип.
• верификация токена. Если верификация успешна, вернется тип аккаунта и все разрешения для токена.
• верификация идентификатора аккаунта. Если верификация успешна – вернется тип аккаунта.

Логирование информации об аккаунтах#

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

Если запрос был выполнен с авторизацией типа BasicAuth или LunaAccountIdAuth, то в логах будет выдано следующее сообщение:

Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db')

Если запрос был выполнен с авторизацией типа BearerAuth, то в логах будет выдано следующее сообщение:

Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db' token_id: 'd57e16f5-e243-47d2-aa85-8b200c12d86f')

Если запрос был выполнен без авторизации, то в логах будет выдано следующее сообщение:

Request invoked by user (account_id: null)

В логах сервиса Accounts дополнительно выводится информация о создании токенов конкретными пользователями:

User with account_id: '270531af-e52e-4538-9181-628d9900a0db' create token: 'd57e16f5-e243-47d2-aa85-8b200c12d86f'

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

Оцениваемые данные#

В данном разделе перечислены основные параметры лиц, тел и изображений, оцениваемые LUNA PLATFORM 5, и способы их получения.

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

1․ Извлечение пола и возраста из изображения лица. Пол и возраст принадлежат понятию базовые атрибуты.

Для извлечения базовых атрибутов по изображению лица используются ресурсы "/extractor", "/sdk" и политики "extract_policy" ресурсов "/handlers" и "/verifiers".

Для извлечения этих параметров с помощью ресурса "/extractor" необходимо предварительно создать биометрический образец изображения с помощью ресурса "/detector". В ответ на запрос к ресурсу "/extractor" будут выданы пол и возраст человека. Извлеченные данные имеют TTL (время существования) и удалятся из базы данных по истечении указанного периода.

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

При оценивании параметров с помощью ресурса "/sdk" нужно отправить исходное изображение в LUNA PLATFORM 5 и указать в параметрах запроса параметр "estimate_basic_attributes". В ответ на запрос будут получены пол и возраст человека. Данные параметры не будут сохранены в базу данных.

Для извлечения базовых атрибутов лица с помощью запросов "/handlers" и "/verifiers" необходимо использовать параметр "extract_basic_attributes" политики "extract_policy".

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

2․ Выполнение оценки параметров лица и изображения.

Для оценивания параметров используются различные ресурсы. В основном используются ресурсы "/detector", "/sdk", "/handlers" и "/verifiers".

При оценивании параметров с помощью ресурса "/detector" нужно отправить исходное изображение в LUNA PLATFORM 5 и указать в параметрах запроса оценивание необходимых параметров лица или изображения. В ответ на запрос будет создан биометрический образец лица и выданы указанные параметры. Оцененные параметры не будут сохранены в базу данных.

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

Для оценивания параметров с помощью ресурсов "/handlers" и "/verifiers" необходимо использовать политику "detect_policy" с указанием необходимых параметров.

3․ Выполнение оценки параметров тела.

Возможность выполнения оценки параметров тела регулируется особым параметром в лицензионном ключе LUNA PLATFORM 5.

Для оценивания параметров тела используются ресурсы "/sdk" и "/handlers". Использование данных ресурсов аналогично выполнению оценки параметров лица и изображения (см. выше).

4․ Выполнение проверки параметров лица и изображения на соответствие стандарту ISO/IEC 19794-5:2011 или по нестандартным условиям.

Возможность выполнения таких проверок регулируется особым параметром в лицензионном ключе LUNA PLATFORM 5.

Для выполнения проверки используются ресурсы "/iso", "/detector" (параметр "estimate_face_quality") и группа проверок "face_quality", политики "detect_policy", запросов "/handlers" и "/verifiers".

В ответах на запросы отображается общий результат прохождения всех проверок ("0" или "1"), а также результаты каждой проверки.

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

5․ Выполнение оценки Liveness.

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

6․ Выполнение оценки количества людей на изображении

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

Обратите внимание, что для получения результатов при отправке запросов к ресурсам "/handlers" или "/verifiers" необходимо сгенерировать событие и выполнить верификацию по заданным обработчикам. См. раздел Объект «Обработчик» для получения более подробной информации о работе с данными ресурсами.

Пол и возраст по изображению лица#

Данная оценка позволяет определить базовые атрибуты (пол и возраст человека) на изображении лица.

Подробная информация о базовых атрибутах приведена в разделе Объект «Атрибут».

Ресурсы, в которых выполняется оценка:

• "/extractor"

  Название оценки — "extract_basic_attributes".

• "/handlers"

  Название оценки — "policies" > "extract_policy" > "extract_basic_attributes".

• "/verifiers"

  Название оценки — "policies" > "extract_policy" > "extract_basic_attributes".

• "/sdk"

  Название оценки — "estimate_basic_attributes".

Параметры лиц#

Атрибуты глаз#

Данная оценка определяет следующие положения для каждого глаза:

• "open" (открытый);
• "closed" (закрытый);
• "occluded" (чем-то перекрыт).

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

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

В ресурсах "/iso", "/detector" (средство проверки изображения) и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_eyes_attributes".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_eyes_attributes".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_eyes_attributes".

• "/sdk"

  Название оценки — "estimate_eyes_attributes".

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

• "/iso" и "/detector" (см. разделы "7.2.3 Expression", пункт "a", "7.2.11 Visibility of pupils and irises" и "7.2.13 Eye patches" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "left_eye", "right_eye".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "left_eye", "right_eye".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Контрольные точки лица#

Существует две оценки контрольных точек лица:

• оценка по 5 контрольным точкам лица
• оценка по 68 контрольным точкам лица

Контрольные точки используются в различных целях, например, при создании биометрического образца, при извлечении биометрического шаблона и др. См. более подробное описание контрольных точек лица в документации SDK.

• "/detector"

  Название оценки — "detect_landmarks68".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "detect_landmarks68".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "detect_landmarks68".

• "/sdk"

  Название оценки — "estimate_landmarks5".

  Название оценки — "estimate_landmarks68".

Расстояние между центрами глаз#

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

Доступна возможность оценить расстояние между центрами глаз в пикселях. Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

• "/iso" и "/detector" (см. раздел "5.6.5 Eye and nostril centre Landmark Points" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "eye_distance".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "eye_distance".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Эффект «красных глаз»#

Данная оценка определяет наличие эффекта "красных глаз", где:

• "0" — на изображении лица нет эффекта "красных глаз";
• "1" — на изображении лица присутствует эффект "красных глаз".

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Требования к изображению:

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

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

В таблице ниже приведено требование к естественности освещения:

Ресурсы, в которых выполняется оценка:

Оценка эффекта "красных глаз" доступна только с помощью средств для проверки изображения:

• "/iso" и "/detector" (см. раздел "7.3.4 Unnatural colour" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "red_eyes".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "red_eyes".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Направление взгляда#

Данная оценка определяет направление взгляда. Направление взгляда определяется следующими параметрами:

• угол наклона взгляда вверх/вниз (pitch);
• угол поворота взгляда вправо/влево (yaw);

Положительное значение угла pitch означает направление взгляда вверх, а отрицательное значение — направление взгляда вниз.

Положительное значение угла yaw означает направление взгляда вправо, а отрицательное значение — направление взгляда влево.

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

В ресурсах "/iso" и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_gaze".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_gaze".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_gaze".

• "/sdk"

  Название оценки — "estimate_gaze".

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

• "/iso" и "/detector" (см. раздел "7.2.3 Expression" пункт "e" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "gaze_yaw", "gaze_pitch".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "gaze_yaw", "gaze_pitch".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Очки#

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

• "sun_glasses" (солнечные очки);
• "glasses" (обычные очки);
• "no_glasses" (очков нет).

В ресурсах "/iso" и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

• "/sdk"

  Название оценки — "estimate_glasses".

Определение состояния очков с помощью средств для проверки изображения:

• "/iso" и "/detector" (см. раздел "7.2.9 Eye glasses" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "glasses".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "glasses".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Брови#

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

• "neutral" — брови находятся в обычном положении;
• "raised" — брови подняты;
• "squinting" — глаза прищурены, брови опущены;
• "frowning" — брови нахмурены.

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

Требования к изображению:

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

В таблице ниже приведены требования к положению головы:

В таблице ниже приведено требование к ширине лица:

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.2.3 Expression", пункты "d", "f" и "g" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "eyebrows_state".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "eyebrows_state".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Атрибуты рта#

Данная оценка определяет вероятностную оценку для каждого нижеперечисленного параметра в диапазоне [0..1]:

• "opened" (рот открыт);
• "smile" (улыбка);
• "occluded" (рот чем-то перекрыт).

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

В ресурсах "/iso" и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_mouth_attributes".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_mouth_attributes".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_mouth_attributes".

• "/sdk"

  Название оценки — "estimate_mouth_attributes".

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

• "/iso" и "/detector" (см. раздел "7.2.3 Expression" пункты "a", "b" и "c" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "mouth_smiling", "mouth_occluded", "mouth_open".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "mouth_smiling", "mouth_occluded", "mouth_open".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Состояние улыбки#

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

• "none" — улыбки не найдено, поэтому дополнительные параметры не определяются
• "smile_lips" — обычная улыбка со сомкнутыми губами
• "smile_teeth" — улыбка с открытыми зубами

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

Требования к изображению:

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

В таблице ниже приведены требования к положению головы:

В таблице ниже приведено требование к ширине лица:

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.2.3 Expression" пункты "a", "b" и "c" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "smile_properties".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "smile_properties".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Качество изображения#

Данная оценка определяет вероятностную оценку для каждого нижеперечисленного параметра в диапазоне [0..1], где 0 соответствует низкому качеству, а 1 – высокому качеству:

• "dark" — степень того, что фото не затемнено;
• "light" — степень того, что фото не засвечено;
• "blurriness" — степень размытости;
• "illumination" — степень равномерности освещения. Чем меньше разница между светлыми и темными зонами лица, тем выше расчетное значение. Если освещение равномерно распределено по всему лицу, значение близится к "1".
• "specularity" — степень отсутствия бликов. Чем выше оценочное значение, тем меньше бликов и лучше качество изображения. Если оценочное значение низкое, значит на лице яркие блики.

В ресурсах "/iso" и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

Эти данные не сохраняются в базе данных и на основе этих данных не выполняется фильтрация изображений.

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

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

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

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_quality".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_quality".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_quality".

• "/sdk"

  Название оценки — "estimate_quality".

Определение качества изображения с помощью средств для проверки изображения:

• "/iso" и "/detector" (см. разделы "7.2.7 Subject and scene lighting", "7.3.2 Contrast and saturation", "7.3.3 Focus and depth of field", "7.2.8 Hot spots and specular reflections", "7.2.12 Lighting artefacts", "7.2.7 Subject and scene lighting" и "7.2.12 Lighting artefacts" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "illumination_quality", "specularity_quality", "blurriness_quality", "dark_quality", "light_quality".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "illumination_quality", "specularity_quality", "blurriness_quality", "dark_quality", "light_quality".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Равномерность освещения по стандарту ICAO#

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

Доступна возможность оценки равномерности освещения по требованиям, указанным в стандарте ICAO.

Также выполняется сравнение оцененного значения с порогом.

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

Определение равномерности освещения по стандарту ICAO доступно только с помощью средства для проверки изображения — группы проверок "/handlers" > "detect_policy" > "face_quality" ресурсов "/handlers" и "/verifiers".

Название проверки — "illumination_uniformity".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Фон изображения#

Яркость фона#

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

Данная оценка определяет степень яркости фона, где:

• [0...0.1] — черный фон
• [0.1...0.3] — темный фон
• [0.3...0.97] — светлый фон
• [0.97...1] — белый фон

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "B.2.9 Backgrounds" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "background_lightness".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "background_lightness".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Однородность фона#

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

Данная оценка позволяет определить степень однородности фона, где:

• "0" — фон неоднородный;
• "1" — фон однородный.

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "B.2.9 Backgrounds" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "background_uniformity".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "background_uniformity".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Динамический диапазон по стандарту ICAO#

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

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

Также выполняется сравнение оцененного значения с порогом.

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

• "/detector"

  Название проверки — "dynamic_range".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "dynamic_range".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Естественность освещения#

Данная оценка определяет естественное ли освещение на лице, где:

• "0" — освещение неестественное;
• "1" — освещение естественное.

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Требования к изображению:

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

В таблице ниже приведено требование к маске:

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

В таблице ниже приведено требование к очкам:

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.3.4 Unnatural colour" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "natural_light".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "natural_light".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Тип цвета изображения на основе лица#

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

• "color" — изображение цветное;
• "grayscale" — изображение черно-белое;
• "infrared" — изображение находится в ближнем инфракрасном диапазоне (near infrared).

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.4.4 Use of near infra-red cameras" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "face_color_type".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "face_color_type".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Положение головы#

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

• угол наклона головы вверх/вниз (pitch);
• угол отклонения головы вправо/влево (roll);
• угол поворота головы вправо/влево (yaw).

Значения углов определяются в диапазоне от "-180" до "180".

Положительное значение угла pitch означает направление наклона головы вверх, а отрицательное значение — направление наклона головы вниз.

Положительное значение угла roll означает направление отклонения головы вправо, а отрицательное значение — направление отклонения головы влево.

Положительное значение угла yaw означает направление поворота головы вправо, а отрицательное значение — направление поворота головы влево.

В ресурсах "/iso" и "detect_policy" > "face_quality" также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

В ресурсах "/detector", "/handlers", "/verifiers" и "/sdk" для порога задается значение от "0" до "180". Значение по умолчанию равно "180", что означает, что голова на изображении может быть повёрнута на любой угол от "-180" до "180". При установке любого другого значения (например, "30") все детекции с углом головы, который меньше или равен "-30" и больше или равен "30" будут отфильтрованы.

Для поля "face_quality" ресурсов "/handlers" и "/verifiers" задается минимальный и максимальный порог в отдельных полях.

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_head_pose".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_head_pose".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_head_pose".

• "/sdk"

  Название оценки — "estimate_head_pose".

Ниже представлены рекомендуемые пороги для проведения оценки в ресурсах "/detector", "/handlers", "/verifiers" and "/sdk".

Рекомендуемые максимальные пороги:

В таблице ниже приведены рекомендуемые максимальные пороги положения головы для проведения оценки в кооперативном режиме:

В таблице ниже приведены рекомендуемые максимальные пороги положения головы для проведения оценки в некооперативном режиме:

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

• "/iso" и "/detector" (см. раздел "7.2.2 Pose" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "head_roll", "head_pitch", "head_yaw".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "head_roll", "head_pitch", "head_yaw".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Положение лица по вертикали и горизонтали#

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

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

Также выполняется сравнение оцененных значений с порогами (в соответствии с ISO или нестандартными порогами).

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. разделы "8.3.2 Horizontally centred face" и "8.3.3 Vertical position of the face" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "head_horizontal_center", "head_vertical_center".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "head_horizontal_center", "head_vertical_center".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Ширина и высота головы (вертикальный и горизонтальный размеры)#

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

Данные оценки определяют вертикальный и горизонтальный размер головы относительно размера изображения. Также выполняется сравнение оцененных значений с порогами (в соответствии с ISO или нестандартными порогами).

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. разделы "8.3.4 Width of head" и "8.3.5 Length of head" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "head_width", "head_height".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "head_width", "head_height".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Ширина и высота лица#

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

Данные оценки определяют ширину и высоту лица в пикселях. Также выполняется сравнение оцененных значений с заданными порогами.

Ресурсы, в которых выполняется оценка:

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

• "/detector"

  Названия проверок — "face_width", "face_height".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "face_width", "face_height".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Отступы от краёв изображения#

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

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

Ресурсы, в которых выполняется оценка:

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

• "/detector"

  Названия проверок — "indent_upper", "indent_lower", "indent_right", "indent_left".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "indent_upper", "indent_lower", "indent_right", "indent_left".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Маска#

Данная оценка определяет вероятностную оценку для каждого нижеперечисленного параметра в диапазоне [0..1]:

• "medical_mask" (надета медицинская маска);
• "missing" (не надета медицинская маска);
• "occluded" (лицо закрыто другим предметом, помимо медицинской маски).

Также определяется наиболее вероятное состояние маски.

Помимо трёх основных состояний определяются следующие дополнительные состояния:

• "correct" — маска на лице, рот и нос закрыты маской
• "mouth" — маска закрывает только рот
• "clear" — на лице нет маски
• "chin" — маска находится под подбородком и не перекрывает зону от глаз до рта
• "partially" — лицо частично перекрыто, но не медицинской маской и не маской с полным перекрытием лица
• "full" — на лице присутствует маска, при которой полностью закрыто лицо, например, балаклава/лыжная маска

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

• состоянию "medical_mask" соответствует свойство "correct" или "mouth"
• состоянию "missing" соответствует свойство "clear" или "chin"
• состоянию "occluded" соответствует свойство "partially" или "full"

Для каждого из свойств возвращается вероятностная оценка в диапазоне [0..1].

Дополнительные свойства маски не записываются в БД и по ним не выполняется фильтрация.

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_mask".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_mask".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_mask".

• "/sdk"

  Название оценки — "estimate_mask".

Эмоции#

Данная оценка определяет вероятностную оценку для каждого нижеперечисленного параметра в диапазоне [0..1]:

• "anger" (злость);
• "disgust" (отвращение);
• "fear" (страх);
• "happiness" (счастье);
• "neutral" (нейтральность);
• "sadness" (грусть);
• "surprise" (удивление).

Также определяется наиболее вероятная эмоция.

Эмоции можно сохранить в объекте события при создании события.

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "estimate_emotions".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_emotions".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_emotions".

• "/sdk"

  Название оценки — "estimate_emotions".

Положение плеч#

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

• "non-parallel" (плечи не параллельны)
• "parallel" (плечи параллельны)
• "hidden" (плечи скрыты)

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.2.5 Shoulders" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "shoulders_position".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "shoulders_position".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Головной убор#

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

• "none" (нет головного убора)
• "baseball_cap" (кепка/бейсболка);
• "beanie" (шапка);
• "peaked_cap" (фуражка);
• "shawl" (платок);
• "hat_with_ear_flaps" (ушанка);
• "helmet" (шлем/каска);
• "hood" (капюшон);
• "hat" (шляпа);
• "other" (прочее).

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

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

Требования к изображению:

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

В таблице ниже приведены требования к положению головы:

В таблице ниже приведено требование к ширине лица:

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "B.2.7 Head coverings" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "headwear_type".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "headwear_type".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Бочкообразная дисторсия (эффект «Fisheye»)#

Данная оценка определяет наличие эффекта "Fisheye", где:

• "0" — на изображении не присутствует эффект "Fisheye";
• "1" — на изображении присутствует эффект "Fisheye".

Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Требования к изображению:

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

В таблице ниже приведены требования к положению головы:

В таблице ниже приведено требование к ширине лица:

Ресурсы, в которых выполняется оценка:

Определение эффекта "Fisheye" доступна только с помощью средств для проверки изображения:

• "/iso" и "/detector" (см. раздел "7.3.6 Radial distortion of the camera lens" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "radial_distortion". - "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "radial_distortion".

Допустимое значение прохождения проверки:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Перекрытие лица#

Эстиматор позволяет определить наличие перекрытия всего лица или его отдельных зон.

Эстиматор возвращает информацию о перекрытии:

• Всего лица
• Зоны лба
• Зоны глаз
• Зоны носа
• Зоны рта
• Нижней части лица

Пороги перекрытия

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

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

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

Пороги могут быть изменены в соответствии с бизнес задачами.

Примечание. Зона усов и бороды никогда не считаются перекрытием лица.

Фильтрация

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

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

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "estimate_face_occlusion".

  Проверки в рамках face_quality:

  • face_occlusion - перекрытие зоны лица;
  • lower_face_occlusion - перекрытие нижней части лица;
  • forehead_occlusion - перекрытие зоны лба;
  • nose_occlusion - перекрытие зоны носа.

• "/verifiers"

  Название оценки — "estimate_face_occlusion".

  Проверки в рамках face_quality.

• "/sdk"

  Название оценки — "estimate_face_occlusion".

Параметры изображений#

Формат изображения#

Данная оценка определяет формат входящего изображения ("JPEG", "JPEG2000" или "PNG"). Также выполняется сравнение оцененного значения с порогом (в соответствии с ISO или нестандартным порогом).

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. раздел "7.5 Format requirements for the Frontal Image Type" в стандарте ISO/IEC 19794-5:2011)

  Название проверки — "image_format".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "image_format".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Размер изображения#

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

Ресурсы, в которых выполняется оценка:

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

• "/detector"

  Название проверки — "image_size".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "image_size".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Ширина и высота изображения#

Данные оценки определяют ширину и высоту изображения в пикселях. Также выполняется сравнение оцененных значений с порогами (в соответствии с ISO или нестандартными порогами).

Ресурсы, в которых выполняется оценка:

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

• "/iso" и "/detector" (см. разделы "5.7.4 Width" и "5.7.5 Height" в стандарте ISO/IEC 19794-5:2011)

  Названия проверок — "image_height", "image_width".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Названия проверок — "image_height", "image_width".

Допустимые диапазоны прохождения проверок:

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Соотношение сторон изображения#

Данная оценка определяет пропорциональное отношение ширины изображения к высоте. Также выполняется сравнение оцененного значения с заданным порогом.

Ресурсы, в которых выполняется оценка:

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

• "/detector"

  Название проверки — "aspect_ratio".

• "detect_policy" > "face_quality" в ресурсах "/handlers" и "/verifiers"

  Название проверки — "aspect_ratio".

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

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

Для средства проверки изображения "face_quality" допустимое значение может быть задано вручную, однако это будет означать отклонение от стандарта.

Метаданные EXIF#

При включённой оценке EXIF все теги изображения анализируются, после чего выводятся их названия и значения. См. спецификацию JEITA CP-3451 EXIF для получения подробной информации. Возвращаются следующие данные:

• make;
• model;
• orientation;
• latitude;
• longitude;
• artist;
• software;
• dateTime;
• digitalZoomRatio;
• flash;
• uid.

Ресурсы, в которых выполняется оценка:

• "/detector"

  Название оценки — "extract_exif".

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "extract_exif".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "extract_exif".

• "/sdk"

  Название оценки — "use_exif_info".

Параметры тел#

Пол и возраст по изображению тела#

Данная оценка позволяет определить пол и возраст человека по изображению тела.

Определение пола и возраста по изображению тела является менее точным, чем по лицу.

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "body_attributes" > "estimate_basic_attributes".

• "/sdk"

  Название оценки — "estimate_body_basic_attributes".

Верхняя часть тела#

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

• "headwear" — головной убор (нет, есть, неизвестно), цвет головного убора (белый, черный, прочий, неизвестно);
• "sleeve" — рукава (длинные рукава, короткие рукава, неизвестно);
• "upper_clothing" — цвет верхней одежды (бежевый, чёрный, синий, коричневый, зеленый, серый, хаки, разноцветный, оранжевый, розовый, фиолетовый, красный, белый, желтый, неизвестно)

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "body_attributes" > "estimate_upper_body".

• "/sdk"

  Название оценки — "estimate_upper_body".

Нижняя часть тела#

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

• "lower_garment" — нижняя одежда (брюки, шорты, юбка, неизвестно), цвет нижней одежды (бежевый, чёрный, синий, коричневый, зеленый, серый, хаки, разноцветный, оранжевый, розовый, фиолетовый, красный, белый, желтый, неизвестно);
• "shoes" — цвет обуви (черный, белый, прочий, неизвестный);

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "body_attributes" > "estimate_lower_body".

• "/sdk"

  Название оценки — "estimate_lower_body".

Наличие рюкзака#

Данная оценка определяет наличие рюкзака на теле:

• "0" — на изображении тела нет рюкзака;
• "1" — на изображении тела есть рюкзак.

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "body_attributes" > "estimate_accessories".

• "/sdk"

  Название оценки — "estimate_accessories".

Face Image Modification#

Эстиматор Face Image Modification позволяет автоматически определять факт модификации/редактирования изображения по наличию характерных артефактов:

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

Система будет считать, что изображение было модифицировано, если полученная оценка (значение от 0 до 1) будет ниже установленного порога. Значение порога по умолчанию — 0.5 (50%).
При необходимости пороговое значение можно задать в настройке LUNA_REMOTE_SDK_IMAGE_MODIFICATION_ESTIMATOR_SETTINGS.estimator_settings.threshold сервиса Remote SDK.

Требования к изображению:

• минимальное разрешение 640 x 480 пикселей;
• наличие только одного лица на изображении.

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "face_quality" > "checks" > "image_modification".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "face_quality" > "checks" > "image_modification".

• "/sdk"

  Название оценки — "estimate_image_modification".

Liveness#

Примечание. Возможность выполнения такой оценки регулируется особым параметром в лицензионном ключе LUNA PLATFORM 5.

Технология Liveness позволяет обнаруживать атаки на биометрическое предъявление. Для оценки Liveness в LUNA PLATFORM, используется эстиматор LUNA SDK OneShotLiveness.

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

• "0" — человек не является реальным;
• "1" — человек является реальным;
• "2" — результат проверки неизвестен.

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_liveness".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_liveness".

• "/sdk"

  Название оценки — "estimate_liveness".

• "/videosdk"

  Оценка выполняется только для аналитики "human_tracking". В процессе анализа для каждого трека человека проводится оценка Liveness по кадрам, и в ответе возвращается агрегированный результат оценки.

  Название оценки — "analytics" > "targets" > "aggregated_liveness".

• "/liveness"

См. дополнительную информацию про Liveness в разделе "Описание OneShotLiveness".

Deepfake#

Примечание. Возможность выполнения такой оценки регулируется особым параметром в лицензионном ключе LUNA PLATFORM 5.

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

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

В результате оценки Deepfake могут вернуться следующие результаты:

• "prediction" = "fake" — человек не является реальным;
• "prediction" = "real" — человек является реальным;
• "score" = [0...1] — степень достоверности выполнения оценки.

При необходимости можно настроить обработчик так, чтобы фильтровать события по предполагаемому результату оценки Deepfake ("fake" или "real"). Для этого в теле запроса обработчика надо указать параметр "deepfake_states" со значением "0" (фильтровать по значению "fake") или "1" (фильтровать по значению "real"). Например, если параметр "deepfake_states" равен "1" (фильтровать по "real"), а эстиматор определил, что результат "fake", то в событии вернется пустое поле "events", а результаты проверки попадут в поле "filtered_detections".

В запросах "create handler" и "create verifier" доступна возможность задать порог "real_threshold" и режим работы "mode". В запросе "sdk" будут использованы значения данных параметров по умолчанию (см. ниже) без возможности явного указания.

Порог

С помощью порога "real_threshold" можно задать значение в диапазоне [0...1], ниже которого система будет считать, что человек не является реальным.

Например, если значение порога "real_threshold" = "0.5", а степень достоверности выполнения оценки "score" = "0.4", то в теле ответа будет выдан результат "prediction" = "fake". Если же значение порога "real_threshold" = "0.6", а степень достоверности выполнения оценки "score" = "0.7", то в теле ответа будет выдан результат "prediction" = "real".

Значение по умолчанию — "0.5".

Режимы работы

Режимы работы описаны в таблице ниже.

Требования к изображению

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

В таблице ниже приведены требования к разрешению изображения:

В таблице ниже приведены требования к положению головы:

В таблице ниже приведено требование к ширине лица:

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_deepfake".

• "/verifiers"

  Название оценки — "policies" > "detect_policy" > "estimate_deepfake".

• "/sdk"

  Название оценки — "estimate_deepfake".

• "/videosdk"

  Оценка выполняется только для аналитики "human_tracking". В процессе анализа для каждого трека человека проводится оценка Deepfake по кадрам, и в ответе возвращается агрегированный результат оценки.

  Название оценки — "analytics" > "targets" > "aggregated_deepfake".

Количество людей#

Примечание. Возможность выполнения такой оценки регулируется особым параметром в лицензионном ключе LUNA PLATFORM 5.

Данная оценка определяет количество людей на изображении.

Ресурсы, в которых выполняется оценка:

• "/handlers"

  Название оценки — "policies" > "detect_policy" > "estimate_people_count".

• "/sdk"

  Название оценки — "estimate_people_count".

При необходимости совместно с оценкой количества людей можно получить X и Y координаты людей с помощью параметра "people_count_coordinates" в ресурсе "/handlers" и параметра "people_coordinates" в ресурсе "/sdk".

Взаимодействие сервисов LP#

На схеме ниже для каждого сервиса указаны отдельные базы данных. Они приведены для наглядности. Не нужно запускать отдельный экземпляр БД для каждого сервиса. Можно запустить один экземпляр (например, PostgreSQL) и использовать его для хранения данных каждого из сервисов LP. У каждого сервиса будет своя таблица в этой базе данных.

См. раздел "Общие сведения" для подробной информации о базах данных, используемых сервисами LP.

Сервис API обеспечивает RESTful интерфейс для выполнения детекции лиц, извлечения и сравнения биометрических шаблонов.

Запросы отправляются в LP с помощью протокола HTTP. Стандартный механизм работы: внешний сервис отправляет запросы в LP, получает результаты и обрабатывает их в соответствии с заданными в запросе параметрами.

Всю информацию об основных запросах в API можно найти в спецификации OpenAPI.

Некоторые сервисы можно отключить (см. раздел "Общие сведения").

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

Основные операции (детекция, эстимация, извлечение, сравнение) выполняются нижеописанным образом.

Подход "Последовательное выполнение запросов":

• запрос "detect faces", в котором выполняется обнаружение лица, оценка параметров лица и создание биометрических образцов, отправляется из сервиса API в сервис Handlers (A1), а затем перенаправляются в сервис Remote SDK (H1);
• запрос "extract attributes", в котором выполняется извлечение временных атрибутов, отправляется из сервиса API в сервис Handlers (A1), а затем перенаправляется в сервис Remote SDK (H1);
• запрос "matching faces" отправляется из сервиса API в сервис Python Matcher (A6).

Подход "Параллельное выполнение запросов":

• запрос "create handler" с правилами детекции, эстимации, извлечения и матчинга лиц и тел отправляется из сервиса API в сервис Handlers (A1);
• запрос "generate events" отправляется из сервиса API в сервис Handlers (A1), а затем перенаправляется в сервис Remote SDK (H1)

Сервис API отправляет запросы в сервис Faces для создания/изменения новых лиц (запросы из секции "faces"), а также создания/изменения списков (запросы из секции "lists") (A2).

Сервис API получает информацию о текущих лицензионных условиях из сервиса Licenses (A3).

Сервис API отправляет биометрические образцы от внешних сервисов в сервис Image Store (запрос "save face/body sample") (A5).

Handlers создает новые обработчики и хранит их в базе данных Handlers (H2).

Также сервис перенаправляет запросы на детекцию и эстимацию в сервис Remote SDK (H1).

Сервис Handlers включается/отключается в настройке "ADDITIONAL_SERVICE_USAGE".

Remote SDK обрабатывает запросы на обнаружение лица/тела и создание атрибутов, оценивает параметры лиц/тел.

Сервис Remote SDK обрабатывает запрос на обнаружение лиц/тел и оценку параметров из сервиса Handlers (H1), отправляет результат обратно в Handlers (H1), который отправляет полученные биометрические образцы в сервис Image Store (H3).

Сервис Remote SDK обрабатывает запрос на создание атрибутов из сервиса Handlers (H1), запрашивая у сервиса Handlers существующие биометрические образцы, который тот запрашивает у сервиса Image Store (H3). Далее сервис Handlers отправляет созданные временные атрибуты в сервис Faces (H4), который хранит их в базе данных Redis (F1).

Запросы "/iso", "/sdk", "/liveness" выполняются напрямую к сервису Remote SDK (A9). В таком случае выполняется проверка лицензии с помощью взаимодействия с сервисом Licenses (RS1). Для возможности использования набора биометрических образцов, сервис Remote SDK взаимодействует с сервисом Image Store (RS2).

Image Store получает биометрические образцы из сервиса Remote SDK и хранит их на локальном накопителе или на S3-подобном облачном хранилище и предоставляет доступ к ним (Im1).

Сервис Image Store включается/отключается в настройке "ADDITIONAL_SERVICE_USAGE".

Faces отвечает за взаимодействие с базой данных Faces, которая хранит: лица, БШ лиц и списки (F2). Он дает доступ к сохраненным данным для сервисов API, Python Matcher и Tasks.

Faces также хранит созданные временные атрибуты в базе данных Redis (F1).

Каждый раз при создании нового лица, сервис Faces отправляет информацию о количестве созданных лиц с прикрепленными атрибутами в сервис Licenses (F3) (см. раздел "Максимальное количество лиц").

Events хранит и предоставляет информацию о событиях. После создания события сервис Events получает созданное событие из сервиса Handlers (H6) и хранит его в базе данных Events (Ev1).

Использование сервиса Events можно включать и отключать в файле конфигурации сервиса API.

Python Matcher используется для сравнения биометрических шаблонов. Запрос на сравнение может быть отправлен напрямую сервисом АPI (A6). Если в обработчике указана политика сравнения, то запрос на сравнение БШ поступит из сервиса Handlers (H7). Python Matcher отправляет запросы на сравнение в базу данных Faces (M3) или Events (M1). Эти базы данных сравнивают биометрические шаблоны и отправляют результаты сравнения.

Python Matcher также может получать временные атрибуты, требуемые для сравнения, из базы данных Redis (M2).

Доступна возможность дополнительно использовать сервис Python Matcher Proxy, который может перенаправлять запросы либо сервису Python Matcher, либо плагинам сравнения. Плагины сравнения позволяют значительно ускорить выполнение запросов на сравнение (см. раздел "Плагины сравнения"). Данный сервис не отображен на схеме, но имеет те же линии связи, что и сервис Python Matcher.

Admin. Пользователь может управлять аккаунтами и выполнять другие действия через пользовательский интерфейс сервиса Admin (Adm1). Соответствующие запросы отправляются в сервис Admin (Adm2).

Сервис Admin получает информацию об аккаунтах из сервиса Accounts (Adm3).

Сервис Admin отправляет запросы в сервис Tasks (Adm4). Эти задачи выполняются для всех данных БД, а не только для отдельного ID аккаунта.

Сервис Admin получает информацию о текущих лицензионных условиях из сервиса Licenses (Adm5).

Сервис Admin получает количество лиц с привязанными атрибутами из базы данных Faces (Adm6) и подсчитывает процент заполненности базы данных.

Сервис Admin выполняет запросы ко всем сервисам LP, получая системную информацию (см. запрос "/luna_sys_info" в спецификации OpenAPI сервиса Admin) (Adm7).

Sender. Все созданные события передаются сервису Sender через канал БД Redis (H5). Внешние сторонние приложения подписываются на получение событий в соответствии с заданными фильтрами (Se2). Сервис Sender проверяет канал Redis, получает требуемую информацию и отправляет ее стороннему ПО (Se1).

Сервис Sender включается/отключается в настройке "ADDITIONAL_SERVICE_USAGE".

Configurator. Сервисы LP получают конфигурационные параметры из сервиса Configurator (Con1). Пользователь может управлять конфигурациями в сервисе Configurator посредством пользовательского интерфейса (Con2). Изменения отправляются в Configurator (Con3). Все изменения в конфигурационных файлах сохраняются в базе данных Configurator (Con4).

Сервис Configurator используется по умолчанию для каждого сервиса LUNA PLATFORM.

Tasks. Сервис Tasks получает запросы из сервиса API (A8). Далее Tasks создает и сохраняет задачу в базе данных Tasks (T1).

Далее сервис Tasks взаимодействует со своим "рабочим процессом" через Redis (T2, T3), создавая подзадачи и объединяя результаты. См. подробную информацию в разделе "Диаграммы задач".

Сервис Tasks получает данные из сервиса Faces для задач Clustering, Linker и Additional extraction (T4).

Сервис Tasks получает данные из сервиса Events для задач Clustering и Linker (T9, T10).

Сервис Tasks получает данные из сервиса Handlers для задачи Estimator (T6).

Сервис Tasks включается/отключается в настройке "ADDITIONAL_SERVICE_USAGE".

Взаимодействие "рабочих процессов" Tasks с другими сервисами зависит от типа задачи.

"Рабочие процессы" Tasks получают данные из сервиса Faces для каждой обрабатываемой задачи (T5).

"Рабочие процессы" Tasks отправляют запрос в Python Matcher (T7) для задач Clustering, Cross-matching и ROC-curve calculation.

"Рабочие процессы" Tasks хранят все отчеты в хранилище Image Store (T8). "Рабочие процессы" Tasks также хранят и получают кластеры из Image Store.

"Рабочие процессы" Tasks отправляют запрос для выполнения повторного извлечения биометрических шаблонов в сервис Handlers (T6).

Мониторинг. Система мониторинга получает запросы и ошибки от каждого сервиса (Mon1). Эти данные хранятся в базе данных Influx (Mon2). Затем данные мониторинга отправляются в Grafana для визуализации данных мониторинга (Mon3). Более подробную информацию о мониторинге можно найти в разделе "Мониторинг".

У сервисов Grafana и Influx DB есть собственные интерфейсы (см. раздел "Пользовательские интерфейсы").

Данная схема не содержит архитектуру сервисов Backport 3, Backport 4, Lambda и сервисов видеоаналитики (Video Agent и Video Manager). См. подробную архитектуру сервиса Backport 3 в разделе "Архитектура Backport 3" и сервиса Backport 4 в разделе "Архитектура Backport 4". См. диаграмму взаимодействия сервиса Lambda в разделе "Диаграммы lambda".

Описание сервисов#

В этом разделе представлена более подробная информация о функциях сервисов LP.

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

См. таблицу с потреблением ресурсов каждым из перечисленных ниже сервисов в разделе "Потребление ресурсов сервисами".

Общая информация о сервисах#

«Рабочие процессы»#

Для сервисов LUNA PLATFORM можно задавать количество "рабочих процессов" для использования дополнительных ресурсов и памяти системы для обработки запросов к сервису. Сервис автоматически запускает несколько процессов и распределяет запросы между процессами.

При запуске сервиса в Docker-контейнере, количество "рабочих процессов" задается с помощью параметра WORKER_COUNT.

Например, если выставить значение WORKER_COUNT=2 для сервиса Faces, то сервис будет потреблять в 2 раза больше ресурсов и памяти.

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

Использование "рабочих процессов" – это альтернативный способ линейного масштабирования сервисов. При увеличении количества экземпляров сервисов на одном сервере рекомендуется использовать дополнительные "рабочие процессы".

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

Автоматическая перезагрузка конфигураций#

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

Эта функция доступна для всех настроек, предусмотренных для каждого сервиса Python. Необходимо включать эту функцию вручную при каждом запуске сервиса. См. раздел "Включение автоматической перезагрузки конфигурации".

Начиная с версии 5.5.0, перезагрузка конфигурации для сервисов Faces и Python Matcher выполняется в основном путем перезапуска соответствующих процессов.

Ограничения#

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

Применение новых настроек может привести к перезапуску сервиса и сбросу кэшей (например, кеш сервиса Python Matcher). Например, при изменении версии биометрического шаблона по умолчанию будет перезапущена платформа LP. Изменение уровня ведения журнала не вызывает перезапуска сервиса (если было указано допустимое значение параметра).

Включение автоматической перезагрузки конфигурации#

Можно включить эту функцию, указав функцию --config-reload в командной строке. В Docker конейнерах эта функция включается с помощью параметра "RELOAD_CONFIG".

Можно указать период проверки конфигурации в аргументе командной строки --pulling-time. По умолчанию установлено значение 10 секунд. В Docker конейнерах эта функция включается с помощью параметра "RELOAD_CONFIG_INTERVAL".

Процесс обновления конфигураций#

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

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

• При изменении настроек сервиса они будут запрошены и применены.

  • Если запрос конфигураций не удался, сервис продолжит работу без внесения каких-либо изменений в существующие конфигурации;

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

• Если текущие настройки и новые запрошенные настройки совпадают, сервис Configurator не будет выполнять никаких действий.

Сервис API#

LUNA API – это веб-сервис распознавания лиц. Он предоставляет интерфейс RESTful для взаимодействия с другими сервисами LUNA PLATFORM.

С помощью сервиса API можно отправлять запросы другим сервисам LP и выполнять следующие задачи:

• обработка и анализ изображений:

  • распознавание лиц/тел на фотографиях;

  • оценка атрибутов лица (возраст, пол, этническая принадлежность) и параметров лица (поза головы, эмоции, направление взгляда, атрибуты глаз, атрибуты рта);

  • оценка параметров тела (возраст, пол, аксессуары, головной убор, цвета верхней и нижней одежды, тип рукавов);

• поиск похожих лиц/тел в базе данных;

• хранение полученных атрибутов лиц в базах данных;

• создание списков для поиска;

• сбор статистики;

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

Сервис Remote SDK#

Сервис Remote SDK используется для:

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

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

Сервис Remote SDK с графическим процессором#

Сервис Remote SDK может использовать GPU для вычислений вместо CPU. Для каждого экземпляра сервиса Remote SDK используется один GPU.

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

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

Агрегирование#

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

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

Считается, что каждый параметр агрегирован из БО. Для активации агрегирования атрибутов необходимо использовать параметр "aggregate_attributes" в запросах "extract attributes" (только для лиц) и "sdk". Агрегация значений Liveness, эмоций и масок для лиц и верхней части тела, пола, возраста и аксессуаров для тел доступна с помощью параметра "aggregate_attributes" в запросе "generate events", при условии, что ранее в обработчике была произведена оценка этих параметров, а также в запросе "sdk".

В ответе выдается массив "sample_id", даже если в запросе использовался только один биометрический образец. В этом случае в массив включается один идентификатор БО.

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

В LUNA PLATFORM доступна работа со следующими форматами биометрических шаблонов:

Примечание. Форматы Raw и XPK-файлы являются устаревшими. Рекомендуется работать с форматом SDK.

SDK и Raw форматы могут быть напрямую привязаны к лицу или сохранены во временный атрибут (см. "Создание объектов с использованием внешних данных").

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

Существует несколько запросов, с помощью которых можно получить биометрический шаблон в формате SDK:

• запрос "sdk";
• запрос "get temporary attributes и "get temporary attribute.

С помощью LUNA PLATFORM невозможно получить биометрические шаблоны в формате Raw и SDK. Можно использовать другое программное обеспечение VisionLabs для получения данных форматов (например, LUNA SDK). Биометрические шаблоны, полученные с помощью вышеописанных ресурсов или с помощью программного обеспечения VisionLabs называются "сырыми" биометрическими шаблонами.

Использование "сырых" биометрических шаблонов для сравнения

Вышеописанные форматы биометрических шаблонов могут быть использованы в запросах на использование "сырых" биометрических шаблонов.

Внешний БШ можно использовать как эталон в следующих ресурсах:

• "/matcher/faces",
• "/matcher/bodies",
• "/matcher/raw",
• "/handlers/{handler_id}/events", когда установлена схема тела запроса "multipart/form-data",
• "/verifiers/{verifier_id}/verifications", когда установлена схема тела запроса "multipart/form-data",
• "/verifiers/{verifier_id}/raw".

Внешний БШ можно использовать как кандидат в следующих ресурсах:

• "/matcher/raw",
• "/verifiers/{verifier_id}/raw".

Создание объектов с использованием внешних данных#

Можно создать временный атрибут или лицо, отправив внешние базовые атрибуты и БШ в LUNA PLATFORM. Таким образом, вы можете хранить эти данные во внешнем хранилище и отправлять их в LP только для обработки запросов.

Можно создать атрибут или лицо с помощью:

• базовых атрибутов и их БО;
• биометрических шаблонов (БШ в чистом виде в Base64 или БШ SDK в Base64);
• базовых атрибутов и биометрических шаблонов с соответствующими данными.

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

Более подробная информация приведена в справочном руководстве сервиса API, в разделах "create temporary attribute" и "create face".

Проверка изображений на соответствие стандартам#

Сервис Remote SDK позволяет проверить изображения по стандарту ISO/IEC 19794-5:2011 или указанным пользователем порогам с помощью трех способов:

• запрос "iso"
• параметр "estimate_face_quality" запроса "detect faces"
• группа параметров "face_quality" политики "detect_policy" запроса "generate events"

Например, необходимо, выполнить проверку является ли изображение подходящего формата, указав в качестве удовлетворительного условия форматы "JPEG" и "JPEG2000". Если изображение подходит под данное условие, система вернет значение "1", если же формат обрабатываемого изображение отличен от заданного условия, то система вернет значение "0". Если условия не заданы — система вернет оцененное значение формата изображения.

Подробная информация и перечень выполняемых оценок и проверок описан в разделе "Проверка изображений".

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

Включение/отключение некоторых эстиматоров и детекторов#

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

При отключении эстиматора или детектора можно также удалить его нейронную сеть из контейнера Remote SDK.

Отключение эстиматоров или детекторов возможно с помощью передачи аргументов с названиями эстиматоров в команду запуска сервиса Remote SDK. Аргументы передаются в контейнер с помощью переменной "EXTEND_CMD".

Список доступных эстиматоров:

Можно явно указать какие эстиматоры и детекторы включены или выключены с помощью передачи соответствующих аргументов в переменную "EXTEND_CMD", или же включить (по умолчанию) или выключить их все с помощью аргумента enable-all-estimators-by-default. Можно выключить использование всех эстиматоров и детекторов, а затем включить определенные эстиматоры с помощью передачи соответствующих аргументов.

Пример команды запуска сервиса Remote SDK с использованием только детектора лиц и эстиматоров биометрического образца лица и эмоций.

docker run \
...
--env=EXTEND_CMD="--enable-all-estimators-by-default=0 --enable-face-detector=1 --enable-face-warp-estimator=1 --enable-emotions-estimator=1" \
...

Сервис Handlers#

Сервис Handlers используется для создания и хранения обработчиков и верификаторов.

Данные обработчиков и верификаторов хранятся в базе данных Handlers.

Отправка событий в сторонний сервис#

В LUNA PLATFORM доступна возможность отправки уведомлений через веб-сокеты или веб-хуки (HTTP). Для этого предназначена политика "callbacks".

Отправка уведомлений через веб-сокеты

Политика "callbacks" с параметром luna-ws-notification предоставляет механизм уведомлений, основанный на принципах веб-сокетов. Этот тип callback'a позволяет получать события через веб-сокеты от сервиса Sender, который взаимодействует с сервисом Handlers через механизм pub/sub по каналу Redis. Это обеспечивает прямое, мгновенное обновление данных, используя двусторонний канал связи между клиентом и сервером.

Преимущества:

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

В предыдущих версиях LUNA PLATFORM использовалась политика "notification_policy". В настоящий момент она считается устаревшей и не рекомендуется к использованию. Основным преимуществом механизма callback'ов перед устаревшей "notification_policy" является возможность указания нескольких callback'ов с разными фильтрами в запросе на создание обработчика, в результате чего будет отправлено только одно событие.

См. подробную информацию в разделе "Сервис Sender".

Отправка уведомлений через веб-хуки

Политика "callbacks" с параметром http предоставляет механизм уведомлений, основанный на принципах веб-хуков для HTTP. Они обеспечивают асинхронное взаимодействие между системами, позволяя внешним сервисам реагировать на появление событий. В рамках этой политики можно задать конкретные параметры, такие как тип протокола, адрес внешней системы, параметры и данные авторизации.

Преимущества:

• Более гибкий механизм настройки уведомлений.
• Простая интеграция с различными внешними системами.
• Использует привычные HTTP-протоколы и конфигурации.

Сервис Image Store#

Сервис Image Store хранит следующие данные:

• Биометрические образцы лица и тела. БО сохраняются в Image Store сервисом Remote SDK или с помощью запросов "samples" > "detect faces" и "samples" > "save face/body sample".
• Отчеты о задачах. Отчеты сохраняются "рабочими процессами" сервиса Tasks.
• Любые объекты, загружаемые с помощью запроса "create objects".
• Информацию о кластеризации.

Сервис Image Store имеет возможность сохранять данные либо на локальном накопителе, либо в S3-подобном облачном хранилище.

Описание бакетов#

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

В LP используются следующие бакеты:

• "visionlabs-samples" — хранит БО лиц.
• "visionlabs-body-samples" — хранит БО тел.
• "visionlabs-image-origin" — хранит исходные изображения.
• "visionlabs-objects" — хранит объекты.
• "task-result" — хранит результаты, полученные после обработки задач с помощью сервиса Tasks.
• "portraits" — необходим для использования сервиса Backport 3. В бакете хранятся портреты (см. описание портретов в документации LUNA PLATFORM 3).

Процедура создания бакетов описана в руководстве по установке LP 5 в разделе "Создание бакетов".

После запуска контейнера Image Store и команд для создания контейнеров, бакеты сохраняются в локальное хранилище или S3.

По умолчанию локальные файлы хранятся в каталоге "/var/lib/luna/current/example-docker/image_store" на сервере. Они сохраняются в каталоге "/srv/local_storage/" в контейнере Image Store.

Бакет содержит каталоги с биометрическими образцами или другими данными. Названия каталогов соответствуют первым четырем буквам идентификатора БО. Все образцы распределяются по этим каталогам в соответствии с первыми четырьмя символами их идентификаторов.

Рядом с объектом бакета расположен файл «*.meta.json», содержащий «account_id», используемый при выполнении запроса. Если объект бакета не является биометрическим образцом (например, объект бакета — JSON-файл в бакете «task-result»), то в данном файле также будет указан «Content-Type».

Пример структуры директорий бакетов "visionlabs-samples", "task-result" и "visionlabs-bodies-samples" приведен ниже.

./local_storage/visionlabs-samples/8f4f/
            8f4f0070-c464-460b-sf78-fac234df32e9.jpg
            8f4f0070-c464-460b-sf78-fac234df32e9.meta.json
            8f4f1253-d542-621b-9rf7-ha52111hm5s0.jpg
            8f4f1253-d542-621b-9rf7-ha52111hm5s0.meta.json
./local_storage/task-result/1b03/
            1b0359af-ecd8-4712-8fc0-08401612d39b
            1b0359af-ecd8-4712-8fc0-08401612d39b.meta.json
./local_storage/visionlabs-bodies-samples/6e98/
            6e987e9c-1c9c-4139-9ef4-4a78b8ab6eb6.jpg
            6e987e9c-1c9c-4139-9ef4-4a78b8ab6eb6.meta.json

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

Также рекомендуется создавать резервные копии БО. БО используются при изменении версии нейросети или при необходимости восстановить базу данных лиц.

Использование S3-подобного хранилища#

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

• убедиться, что ключ доступа имеет достаточные полномочия для доступа к бакетам S3-подобного хранилища;
• запустить сервис Image Store (см. раздел "Image Store" в руководстве по установке);
• задать значение "S3" для настройки "storage_type" настроек сервиса Image Store;
• заполнить настройки для соединения с S3-подобным хранилищем (адрес, ключи Access Key и Secret Key и др.) в группе параметров "S3" настроек сервиса Image Store

При необходимости можно отключить проверку SSL-сертификата с помощью настройки "verify_ssl" в группе параметров "S3" настроек сервиса Image Store. Это позволяет использовать самоподписанный SSL-сертификат.

Поддерживаемые облачные провайдеры#

Image Store поддерживает S3-подобные хранилища. Поддержка протестирована на MinIO и стандартном S3. Для других хранилищ степень совместимости зависит от их соответствия S3 API.

TTL объектов#

Можно задать время жизни (TTL) для объектов в бакетах (как локальных, так и S3). Под объектами понимаются:

• биометрические образцы лиц или тел
• изображения или объекты, создаваемые в ресурсах "/images" или "/objects"
• исходные изображения
• результаты задач

TTL для объектов рассчитывается относительно формата времени GMT.

TTL для объектов задается в днях следующими способами:

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

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

Кроме количества дней параметр может принимать значение "-1", означающее, что нужно хранить объекты бессрочно.

Настройка основной политики TTL бакета#

Основную политику TTL бакета можно настроить следующими способами:

• с помощью флага --bucket-ttl для команды prepare с аргументом lis_bucket. Например:

  docker run \
  --rm \
  --network=host \
  dockerhub.visionlabs.ru/luna/storages:v.0.40.0 \
  bash -c "luna_prepare prepare lis_bucket \
        --bucket-ttl=2"
  

• с помощью запроса к сервису Image Store. Например, curl -X POST http://127.0.0.1:5020/1/buckets?bucket=visionlabs-samples?ttl=2.

Настройка TTL для конкретных объектов#

TTL для конкретных объектов можно настроить с помощью параметра "ttl" в следующих местах:

• в политиках "storage_policy" > "face_sample_policy", "body_sample_policy" и "image_origin_policy" обработчика
• в запросах "create object", "create images" и "save sample"
• в запросах на создание задач или расписания в поле "result_storage_policy"

Если параметр "ttl" не задан, то будет применена основная политика бакета, в котором находится объект (cм. выше).

Добавление TTL к существующим объектам#

Добавить TTL для существующего конкретного объекта можно с помощью PUT-запросов к ресурсам /objects, /images, /samples/{sample_type} сервиса Image Store. Добавить TTL результатов задач к уже созданным и выполненным задачам невозможно. Добавить TTL результатов задач к уже созданному расписанию можно с помощью запроса "replace tasks schedule". Для созданных или запущенных на момент запроса задач TTL результатов задач применен не будет.

Добавить TTL к основной политике бакета (ко всем существующим объектам в бакете) можно с помощью PUT-запроса к ресурсу /buckets сервиса Image Store.

Для бакета, расположенного в S3, необходимо выполнить миграцию с помощью скрипта "base_scripts/migrate_ttl_settings" сервиса Image Store. Это связано с тем, что для TTL объектов в S3 применяется через фильтры, связанные с тегами. Команда выполнения миграции бакетов в S3 приведена в руководстве по установке. См. подробную информацию о миграции бакетов S3 в разделе "Миграция для добавления TTL к объектам в S3".

Миграция для добавления TTL к объектам в S3#

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

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

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

Необходимо добавить следующие теги и правила:

• для поддержки TTL для бакетов необходимо добавить тег vl-expire со значением по умолчанию для всех существующих объектов.
• для поддержки TTL для конкретных объектов необходимо добавить набор или связанные с TTL правила жизненного цикла для существующих сегментов:

{
    "ID": "vl-expire-<ttl>",
    "Expiration": {
        "Days": <ttl>,
    },
    "Filter": {"Tag": {"Key": "vl-expire", "Value": <ttl>}},
    "Status": "Enabled",
}

Поддерживается набор определенных значений тегов, связанных с TTL объекта: 1, 2, 3, 4, 5, 6, 7, 14, 30, 60, 90, 180, 365.

Процесс выполнения миграции состоит из двух этапов:

• настройка жизненного цикла бакета, расширенная набором правил жизненного цикла, связанных с TTL.
• присвоение каждому объекту в бакете тега vl-expire, если он еще не обладает таковым.

Присвоение тега для каждого объекта при необходимости можно пропустить с помощью аргумента -update-tags=0.

См. примеры команд для выполнения миграции в руководстве по обновлению.

Проблемы с разрешениями

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

Полезные ссылки на официальную документацию:

• Creating a lifecycle configuration
• Put lifecycle configuration
• Managing object tags
• Expiring objects

Окончание TTL#

Когда TTL объекта подходит к концу, то он помечается для удаления. Для локальных бакетов выполняется задача очистки 1 раз в день (в 01:00 утра). Для бакетов S3 используются внутренние правила конфигурации TTL. Чтобы предотвратить конфликты или дублирование задач очистки при задействовании нескольких экземпляров или рабочих процессов, реализован механизм блокировки. Это гарантирует, что за выполнение процесса очистки локального хранилища отвечает только один экземпляр или рабочий процесс.

Между датой истечения срока действия и датой фактического удаления объекта может возникнуть задержка. Как для локального хранилища, так и для S3.

Поиск истекающих объектов#

Чтобы узнать, когда срок действия объекта истекает, можно использовать запросы с методами HEAD к ресурсам /objects и /images. Эти запросы возвращают заголовки ответов X-Luna-Expiry-Date, в которых указана дата, когда объект больше не подлежит сохранению.

Внешние биометрические образцы#

В Image Store можно отправить внешний биометрический образец. Внешний биометрический образец можно получить с помощью стороннего программного обеспечения или программного обеспечения VisionLabs (например, FaceStream).

См. запрос POST на ресурсе "/samples/{sample_type}" в "APIReferenceManual.html" для получения дополнительной информации.

Внешний БО должен соответствовать определенным стандартам, чтобы LP могла его обработать.

БО, полученные с помощью программного обеспечения VisionLabs, удовлетворяют этому требованию.

При использовании стороннего программного обеспечения не гарантируется, что результат обработки внешнего БО будет таким же, как и для образца VisionLabs. БО может быть низкого качества (слишком темный, размытый и т.д.). В результате низкого качества можно получить неверные результаты обработки изображения.

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

Сервис Accounts#

Сервис Accounts предназначен для:

• Создания, управления и хранения аккаунтов
• Создания, управления и хранения токенов и их разрешений
• Верификации аккаунтов и токенов

См. раздел "Аккаунты, токены и способы авторизации" для более подробной информации о системе авторизации в LUNA PLATFORM 5.

Все создаваемые аккаунты, токены и их разрешения сохраняются БД сервиса Accounts.

Алгоритмы JWT-токенов#

Механизм аутентификации JWT (JSON Web Tokens) поддерживает различные алгоритмы для подписи токенов. В этом разделе описывается используемый по умолчанию алгоритм и необходимые шаги для использования альтернативного алгоритма.

Алгоритм по умолчанию#

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

Использование алгоритма ES256#

Чтобы использовать алгоритм ES256, следуйте этим шагам:

1․ Сгенерируйте закрытый ключ ECDSA

Сначала нужно сгенерировать закрытый ключ ECDSA, используя кривую prime256v1. Это можно сделать с помощью инструментов командной строки, таких как OpenSSL.

Пример команды:

openssl ecparam -genkey -name prime256v1 -out ec_private.pem

Вы также можете сгенерировать ключ, защищенный паролем, например:

openssl ecparam -genkey -name prime256v1 | openssl ec -aes256 -out ec_private_enc.pem

2․ Закодируйте закрытый ключ в формат Base64

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

Пример команды:

base64 -w0 ecdsa_private.pem > ecdsa_private_base64

3․ Установите переменную окружения

Закодированный закрытый ключ должен быть указан в переменной окружения ACCOUNTS_JWT_ECDSA_KEY при старте контейнера. Это позволяет сервису использовать ключ для подписи JWT-токенов алгоритмом ES256.

Кроме того, если ваш закрытый ключ защищен паролем, вы можете указать пароль в переменной среды ACCOUNTS_JWT_ECDSA_KEY_PASSWORD.

Пример команды запуска контейнера с передачей переменных окружения:

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=ACCOUNTS_JWT_ECDSA_KEY=jwt_ecdsa_key \
--env=ACCOUNTS_JWT_ECDSA_KEY_PASSWORD=ecdsa_key_password \
...

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

Влияние изменения типа алгоритма#

Переключение алгоритма подписи с HS256 на ES256 (или наоборот) оказывает значительное влияние на проверку токенов. Все существующие токены, подписанные предыдущим алгоритмом, станут недействительными после внесения изменений. Это происходит потому, что механизм проверки подписи токена ожидает, что структура и криптографическая база токена будут соответствовать новоуказанному алгоритму.

Сервис Faces#

Сервис Faces предназначен для:

• Создания временных атрибутов;
• Создания лиц;
• Создания списков;
• Прикрепления лиц к спискам;
• Управления общей базой данных, в которой хранятся лица с прикрепленными данными и списки;
• Получения информации о существующих лицах и списках.

Сервисы сравнения#

Python Matcher позволяет осуществлять:

• Сравнение в соответствии с заданными фильтрами. Такое сравнение выполняется непосредственно в базе данных лиц или событий. Сравнение по БД целесообразно, когда установлено несколько фильтров.
• Сравнение по спискам. В этом случае рекомендуется сохранять биометрические шаблоны в кеше Python Matcher.

Python Matcher Proxy используется для маршрутизации запросов к сервисам Python Matcher и плагинам сравнения.

Python Matcher#

Python Matcher использует базу данных Faces для фильтрации и сравнения, когда лица заданы как кандидаты для сравнения и для них указаны фильтры. Эта функция всегда включена для Python Matcher.

Python Matcher использует базу данных Events для фильтрации и сравнения, когда события заданы как кандидаты для сравнения и для них указаны фильтры. Сравнение с использованием базы данных Events является необязательным и не используется, если не используется сервис Events.

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

Сервис Python Matcher дополнительно использует "рабочие процессы", обрабатывающие запросы.

Python Matcher Proxy#

Сервис API отправляет запросы на прокси-сервер Python Matcher, если его использование включено в настройках сервиса API. Затем сервис Python Matcher Proxy перенаправляет запросы к сервису Python Matcher или на плагины сравнения (если они используются).

Если плагины сравнения не используются, то сервис перенаправляет запросы только к сервису Python Matcher. Таким образом, не нужно использовать Python Matcher Proxy если не собираетесь использовать плагины сравнения. См. описание работы плагинов сравнения в разделе "Плагины сравнения".

Кеширование списков#

Когда лица заданы как кандидаты для сравнения и идентификаторы списков для них указаны в качестве фильтров, Python Matcher выполняет сравнение по спискам.

По умолчанию при запуске сервиса Python Matcher все биометрические шаблоны во всех списках кешируются в его память.

Управление кешированием осуществляется за счет группы параметров "DESCRIPTORS_CACHE".

Сервис Python Matcher не будет запущен, пока не загрузит в кеш все доступные биометрические шаблоны.

При выполнении запроса на сравнение по спискам, сервис Python Matcher автоматически добавляет его в очередь, откуда его забирает "рабочий процесс" и направляет в сущность Cached Matcher для выполнения сравнения по кешированным данным.

После выполнения сравнения, "рабочий процесс" забирает результаты и возвращает их сервису Python Matcher и пользователю.

Такое кеширование позволяет значительно увеличить производительность сравнения.

При необходимости можно обрабатывать только конкретные списки с помощью настройки "cached_data > faces_lists > include" или исключать списки с помощью настройки "cached_data > faces_lists > exclude". Последняя особенно полезна при работе с модулем LUNA Index Module для реализации логики обработки части списков с помощью Python Matcher, а части с помощью LIM Indexed Matcher.

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

Кеш «рабочих процессов»#

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

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

Сервис Events#

Сервис Events предназначен для:

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

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

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

База данных для сервиса Events#

В качестве базы данных для сервиса Events используется PostgreSQL.

На скорость обработки запросов в первую очередь влияют:

• количество событий в базе данных
• отсутствие индексов для PostgreSQL

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

Скорость обработки запросов статистики к СУБД PostgreSQL можно увеличить, настроив базу данных и создав индексы.

Географическое положение#

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

Географического положение представлено в виде JSON с GPS-координатами географической точки:

• долгота – географическая долгота в градусах
• широта – географическая широта в градусах

Географическое положение указывается в параметре "location" тела запроса на создание события. См. запрос "create new events" в спецификации OpenAPI сервиса Events.

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

Фильтр географического положения#

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

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

• origin_longitude
• origin_latitude
• longitude_delta
• latitude_delta

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

Фильтр географического положения считается правильно заданным, если:

• заданы и origin_longitude, и origin_latitude.
• не заданы ни origin_longitude, ни origin_latitude, ни longitude_delta или latitude_delta.

Если заданы параметры origin_longitude и origin_latitude, а параметры longitude_delta не заданы – применяется значение по умолчанию (см. значение по умолчанию в документации OpenAPI).

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

Общие рекомендации и ограничения для фильтров географического положения:

• Не нужно создавать фильтры с общей точкой или границей на Международной линии перемены дат (IDL), Северном или Южном полюсе. Они не полностью поддерживаются из-за особенностей пространственного индекса базы данных. Результат фильтрации может быть непредсказуемым;
• Фильтры географического положения с границами длиной более 180 градусов не допускаются;
• Настоятельно рекомендуется использовать фильтр географического положения только в масштабах города. Если указана большая область, результаты фильтрации на границах области могут быть неожиданными из-за пространственных особенностей.
• Не нужно создавать фильтр слишком протяжённый по долготе или широте. Рекомендуется устанавливать значения дельт близкими друг к другу.

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

Эффективность фильтра#

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

Поддерживаются два типа пространственных данных:

• GEOMETRY (геометрический): пространственный объект с координатами, выраженными в виде пар (долгота, широта), определенных в декартовой плоскости. При всех расчетах используются декартовы координаты.
• GEOGRAPHY (географический): пространственный объект с координатами, выраженными в виде пар (долгота, широта), определенных как на поверхности идеальной сферы, или пространственный объект в системе координат WGS84.

Подробное описание см. в разделе геометрия в сравнении с географией.

Фильтр географического положения на основе функции PostGIS ST_Covers, поддерживается как для геометрического, так и для географического типа.

Особенности фильтра#

Фильтр географического положения имеет некоторые особенности, обусловленные PostGIS.

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

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

{
    "longitude": 16.79,
    "latitude": 64.92,
}

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

{
    "origin_longitude": 16.79,
    "origin_latitude": 64.92,
    "longitude_delta": 2,
    "latitude_delta": 0.01,
}

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

Необходимо учитывать эту особенность при создании фильтра.

Подробная информация приведена в разделе Geography сайта Postgis.

Создание событий#

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

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

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

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

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

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

Обработчик обрабатывает политику за политикой. Все данные из запроса обрабатываются политикой перед переходом к следующей политике. Сначала политика "detect" выполняется для всех изображений из запроса, затем применяется политика "multiface", затем выполняется политика "extract" для всех полученных биометрических образцов и т.д. Более подробную информацию об обработчиках см. в разделе "Описание обработчиков".

Обобщенные события#

В случае, если необходимо сохранить событие с какой-либо пользовательской структурой, сгенерированной видеоаналитикой, плагином или каким-либо клиентским приложением, следует использовать механизм обобщенных событий. Размер обобщенного события не должен превышать лимит в 2 МБ.

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

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

Несмотря на то, что структура обобщенного события свободна, она может содержать определенный набор полей, специфичных для LUNA PLATFORM (например, местоположение, идентификатор потока, идентификатор трека), поиск по которым может выполняться более эффективно за счет оптимизации хранения этих данных в базе данных Events.

Пользователю предоставляется:

• Возможность сохранять события свободной структуры.
• Возможность получать сохраненные события.
• Возможность фильтровать по общей информации обобщенного события (например, event_type, event_create_time, event_end_time, account_id).
• Возможность фильтровать по необязательным полям обобщенного события, присущим LUNA PLATFORM (например, location, stream_id, track_id).
• Возможность фильтровать по полям содержимого пользовательской структуры.

Пользователь обязуется:

• Поддерживать данные в соответствии с заданными схемами. В случае несоответствия PostgreSQL не позволит вставить строку с типом, который не может быть добавлен в существующий индекс (если таковой имеется).
• Мигрировать данные при необходимости.
• Строить частичные индексы в соответствии с типами событий.
• Указывать тип данных при выполнении запроса (по умолчанию все значения предполагаются строками).
• Обращать внимание на имена полей пользовательской структуры. Поля, по которым будет выполняться фильтрация, не должны содержать зарезервированных ключевых слов, таких как :int, двойных подчеркиваний, специальных символов и т. д.

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

Способ сохранения обобщенных событий#

Сохранить обощенное событие можно с помощью запроса "create new general events" к сервису API.

Соответственно, если пользователь пишет собественный плагин или приложение, то он должен отправлять данные в вышеописанный эндпоинт.

Поиск обобщенных событий#

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

• "get general events"
• "get general event"

В данные запросы можно передать фильтры. Существует несколько соглашений для указания фильтров:

• Для навигации по вложенным объектам используйте точку (.), например, event.user_info.temperature.
• Для указания оператора сравнения используйте суффикс с двойным подчеркиванием (__eq, __like, __in, __gt, __lt и т. д.), например, event.user_info.temperature__gte.
• Для указания типа данных используйте суффикс с двоеточием (:string, :integer, :numeric), например, event.user_info.temperature__gte:numeric.

Также можно получить статистику по обобщенным событиям с помощью запроса "get statistics on general events".

Сравнение по обобщенным событий#

Функционал сравнения по обобщенным событиям реализуется через запрос general events matching.

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

Метаинформация события#

В случае, если вместе с событием необходимо сохранить какие-либо дополнительные данные, следует использовать поле "meta". Поле "meta" хранит в себе данные формата JSON. Общий размер данных, хранимых в поле "meta" для одного события не может превышать 2 Мб. Предполагается, что с помощью данного функционала пользователь создаст свою модель данных (структуру события) и будет использовать её для хранения необходимых данных.

Обратите внимание, что в поле "meta" нельзя указывать имена полей с пробелами.

Данные в поле "meta" можно записывать следующими способами:

• в теле запроса "generate events" с типом содержимого application/json или multipart/form-data
• в теле запроса "save event"
• с помощью пользовательского плагина или клиентского приложения.

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

Пример записи поля "meta":

{
    "meta": {
        "user_info": {
            "temperature": 36.6
        }
    }
}

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

{
    "struct1": {
        ...
    },
    "struct2": {
        ...
    }
}

Поиск по полю "meta"#

Содержимое поля "meta" можно получить с помощью соответствующего фильтра в запросе "get events".

Фильтр нужно вводить с помощью определенного синтаксиса — meta.<path.to.field>__<operator>:<type>, где:

• meta. — указание, что идет обращение к полю "meta" базы данных Events;
• <path.to.field> — путь до объекта. Для навигации по вложенным объектам используется точка (.). Например, в строке {"user_info":{"temperature":"36.6"}} для обращения к объекту temperature нужно использовать следующий фильтр meta.user_info.temperature
• __<operator> — один из следующих операторов — eq (по умолчанию), neq, like, nlike, in, nin, gt, gte, lt, lte. Например, meta.user_info.temperature__gte;
• :type — один из следующих типов данных — string, integer, numeric. Например, meta.user_info.temperature__gte:numeric.

Для каждого оператора доступно использование определенных типов данных. См. таблицу зависимости операторов от типов данных в спецификации OpenAPI.

При необходимости можно построить индекс для улучшения поиска. См. подробную информацию о построении индекса в руководстве разработчика сервиса Events.

Важные замечания#

При работе с полем "meta" необходимо помнить следующее:

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

Сохранение удаленных событий#

Доступа возможность сохранения удаленных событий (обычных и обобщенных) в базу данных Events.

Удаленные события хранятся в БД Events в таблицах deleted_event и deleted_general_event. См. раздел "Описание БД Events".

Для включения этой функциональности необходимо установить переменную окружения EVENT_DELETION_LOG=1 в команде запуска сервиса Events. Например:

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=CONFIGURATOR_PORT=5070 \
--env=PORT=5040 \
--env=EVENT_DELETION_LOG=1 \
--name=luna-events \
...

После запуска сервиса идентификаторы удаленных событий будут записаны в соответствующие таблицы БД.

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

• "get deleted events"
• "get deleted general events"

Сервис Sender#

Сервис Sender – это дополнительный сервис, который используется для отправки событий через веб-сокеты. Данный сервис коммуницирует с сервисом Handlers (в котором создаются события) через механизм pub/sub по каналу БД Redis.

При необходимости можно отправлять уведомления по HTTP-протоколу. См. раздел "Отправка событий в сторонний сервис" для более подробной информации.

События создаются на основе обработчиков. Для получения уведомлений необходимо наличие включенной политики "callbacks" с параметром "luna-ws-notification". У данной политики есть фильтры, позволяющие отправлять уведомления только при определенных условиях, например, отправлять только при большом сходстве кандидата с эталоном (параметр "similarity__lte").

В предыдущих версиях LUNA PLATFORM использовалась политика "notification_policy". В настоящий момент она считается устаревшей и не рекомендуется к использованию. Основным преимуществом механизма callback'ов перед устаревшей "notification_policy" является возможность указания нескольких callback'ов с разными фильтрами в запросе на создание обработчика, в результате чего будет отправлено только одно событие.

Необходимо настроить подключение к веб-сокетам по специальному запросу. Рекомендуется создавать соединение через веб-сокеты, используя ресурс "/ws" сервиса API. В запросе можно указать фильтры (параметры запроса), т.е. можно настроить сервис Sender так, чтобы получать только определенные события. См. спецификацию OpenAPI для получения подробной информации о конфигурации создания подключения к веб-сокету.

Также можно настроить веб-сокеты напрямую через сервис Sender (ресурс "/ws" сервиса Sender). Этот способ можно использовать для снижения нагрузки на сервис API.

После создания события, оно может:

• сохраниться в базе данных сервиса Events. Для сохранения события необходимо включить сервис Events;

• быть выдано в ответ без сохранения в базе данных.

В обоих случаях событие отправляется через канал БД Redis в сервис Sender.

БД Redis в данном случае выступает в качестве связи сервисов Sender и Handlers и не хранит передаваемые события.

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

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

Создание обработчиков и указание фильтров для отправки уведомлений

1․ Пользователь отправляет запрос "create handler" в сервис API, где включает политику "callbacks" и задает фильтры, в соответствии с которыми будет выполняться отправка событий в сервис Sender;

2․ Сервис API отправляет запрос в сервис Handlers;

3․ Сервис Handlers отправляет ответ в сервис API;

4․ Сервис API отправляет "handler_id" пользователю.

Пользователь сохраняет идентификатор "handler_id", который необходим для создания событий.

Активация подписки на события и фильтрация их отправки

1․ Пользователь или приложение отправляет запрос "ws handshake" в сервис API и задает фильтры, благодаря которым можно будет фильтровать полученные данные от сервиса Handlers;

2․ Сервис API отправляет запрос в сервис Sender;

3․ Сервис Sender устанавливает постоянное соединение через веб-сокеты с пользовательским приложением.

4․ Теперь при генерации события, оно будет автоматически перенаправляться в сервис Sender (см. ниже) в соответствии с указанными фильтрами.

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

Генерация событий и отправка в Sender

1․ Пользователь или приложение отправляет запрос "generate events" в сервис API;

2․ Сервис API отправляет запрос в сервис Handlers;

3․ Сервис Handlers отправляет запрос в соответствующие сервисы LP;

4․ Сервисы LP обрабатывают запросы и отправляют результаты. Создаются новые события;

5․ Сервис Handlers отправляет событие в базу данных Redis, используя модель pub/sub. В Redis есть канал, на который подписан сервис Sender, и он ожидает получение сообщений из этого канала;

6․ Redis отправляет полученные события в сервис Sender по каналу;

7․ Для получения событий сторонние приложения должны быть подписаны на сервис Sender через веб-сокеты. Если есть подписанное стороннее приложение, Sender отправляет ему события в соответствии с указанными фильтрами.

См. документацию OpenAPI для получения информации о структуре JSON, выдаваемой сервисом Sender.

Сервис Tasks#

Сервис Tasks предназначен для выполнения длительных задач.

Общая информация о задачах#

Обработка задач занимает значительное время, поэтому после создания задачи в ответе возвращается идентификатор задачи.

После завершения обработки задачи можно получить результаты задачи с помощью запроса "task " > "get task result". Необходимо указать идентификатор задачи, чтобы получить ее результаты.

Примеры результатов обработки задач можно найти в разделе ответа на запрос "task " > "get task result". Необходимо выбрать тип задачи в разделе Response samples документации.

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

• Можно проверить статус задачи, указав идентификатор задачи в запросе "tasks" > "get task". Существуют следующие статусы задач:

• Можно получить информацию обо всех задачах с помощью запроса "tasks" > "get tasks". Можно установить фильтр, чтобы получать информацию только по интересующим задачам.

Запросы на выполнение задач доступны для различных сервисов. В данном документе рассмотрены примеры создания задач с помощью сервиса API, Admin и пользовательского интерфейса Admin. Для подробной информации о создании задач с помощью прямых запросов к сервису Tasks см. в спецификации сервиса Tasks.

Задача Clustering#

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

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

Можно использовать задачу создания отчета для получения отчета об объектах, добавленных в кластеры.

Кластеризация выполняется в несколько этапов:

• объекты с биометрическими шаблонами собираются в соответствии с предоставленными фильтрами

• каждый объект сопоставляется со всеми остальными объектами

• создаются кластеры в виде групп "связанных компонентов" из графа схожести.

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

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

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

{
    "errors": [],
    "result": {
        "clusters": [
            [
                "6c721b90-f5a0-409a-ab70-bc339a70184c"
            ],
            [
                "8bc6e8df-410b-4065-b592-abc5f0432a1c"
            ],
            [
                "e4e3fc66-53b4-448c-9c88-f430c00cb7ea"
            ],
            [
                "02a3a1c4-93d7-4b69-99ec-21d5ef23852e",
                "144244cb-e10e-478c-bdac-18cd2eb27ee6",
                "1f4cdbcb-7b1e-40cc-873b-3ff7fa6a6cf0"
            ]
        ],
        "total_objects": 6,
        "total_clusters": 4
    }
}

Результат задачи Clustering может также содержать информацию об ошибках, возникших при обработке объектов.

Для такой задачи можно создать расписание.

Задача Reporter#

В результате выполнения этой задачи создается отчет по задаче Clustering. Можно выбрать данные, которые необходимо добавить в отчет. Отчет предоставляется в формате CSV.

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

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

Необходимо убедиться в том, что выбранные столбцы соответствуют объектам, выбранным при выполнении задачи Clustering.

Также можно получить изображения для всех объектов в кластерах при их наличии.

Задача Exporter#

С помощью этой задачи можно собирать данные о событиях и/или лицах и экспортировать их из LP в CSV-файл. В строке файла представлены запрошенные объекты и соответствующие биометрические образцы (если они были запрошены).

При сборе данных с помощью этой задачи используется память. Поэтому, вполне возможно, что "рабочий процесс" Task будет завершён OOM (Out-Of-Memory) killer при запросе большого количества данных.

Экспортировать данные о событиях или лицах можно с помощью запроса "/tasks/exporter". Необходимо указать, какой тип объекта требуется, установив параметр objects_type при создании запроса. Также можно сузить количество данных для запроса, задав фильтры для лиц и событий. См. запрос "exporter task" в справочном руководстве сервиса API.

В результате выполнения задачи возвращается ZIP-архив, содержащий CSV-файл.

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

При выполнении задачи Exporter с большим количеством лиц базе данных Faces (например, 90 000 000 лиц), время выполнения запросов к сервису Faces может быть значительно увеличено. Для ускорения выполнения запросов можно задать для настройки PostgreSQL "parallel_setup_cost" значение 500. Однако следует учитывать, что изменение данной настройки может повлечь за собой другие последствия, поэтому следует внимательно отнестись к изменению настройки.

Для такой задачи можно создать расписание.

Задача Cross-matching#

При выполнении задачи выполняется сравнение всех эталонов со всем кандидатами. Кандидаты и эталоны задаются на основе фильтров для лиц и событий.

Сравнение выполняется только для объектов, содержащих извлеченные биометрические шаблоны.

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

Можно установить threshold, чтобы указать минимально допустимое значение схожести. Если схожесть двух БШ ниже указанного значения, результат сравнения будет проигнорирован и не будет выдаваться в ответе. Эталоны без совпадений с кандидатами также будут проигнорированы.

Сравнение выполняется в несколько этапов:

• На основе указанных фильтров подбираются объекты с БШ.
• Каждый объект-эталон сравнивается с каждым объектом-кандидатом.
• Результаты сравнения сортируются (лексикографически) и фильтруются (применяются limit и threshold).

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

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

{
"result": [
    {
        "reference_id": "e99d42df-6859-4ab7-98d4-dafd18f47f30",
        "candidates": [
            {
                "candidate_id": "93de0ea1-0d21-4b67-8f3f-d871c159b740",
                "similarity": 0.548252
            },
            {
                "candidate_id": "54860fc6-c726-4521-9c7f-3fa354983e02",
                "similarity": 0.62344
            }
        ]
    },
    {
        "reference_id": "345af6e3-625b-4f09-a54c-3be4c834780d",
        "candidates": [
            {
                "candidate_id": "6ade1494-1138-49ac-bfd3-29e9f5027240",
                "similarity": 0.7123213
            },
            {
                "candidate_id": "e0e3c474-9099-4fad-ac61-d892cd6688bf",
                "similarity": 0.9543
            }
        ]
    }
],
"errors": [
    {
        "error_id": 10,
        "task_id": 123,
        "subtask_id": 5,
        "error_code": 0,
        "description": "Faces not found",
        "detail": "One or more faces not found, including face with id '8f4f0070-c464-460b-bf78-fac225df72e9'",
        "additional_info": "8f4f0070-c464-460b-bf78-fac225df72e9",
        "error_time": "2018-08-11T09:11:41.674Z"
    }
]
}

Для такой задачи можно создать расписание.

Задача Linker#

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

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

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

Если не указан фильтр create_time_lt, будет установлено текущее время.

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

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

Процесс выполнения задачи Linker для лиц:

• Проверяется наличие списка с указанным list_id или создаётся новый список (если установлен параметр create_list, равный 1).
• Определяются границы идентификатора лица. Затем формируется одна или несколько подзадач примерно по 1000 идентификаторов лиц в каждой – в зависимости от распространения идентификаторов лиц.

• Для каждой подзадачи:

  • Определяются идентификаторы лиц, указанные для текущей подзадачи в соответствии с фильтрами в подзадаче.
  • Выполняется запрос в сервис Faces на привязку указанных лиц к указанному списку.
  • Результат каждой подзадачи сохраняется в сервисе Image Store.

• После завершения последней подзадачи, "рабочий процесс" собирает результаты всех подзадач, объединяет и помещает их в сервис Image Store (в виде результатов задачи).

Процесс выполнения задачи Linker для событий:

• Проверяется наличие списка с указанным list_id или создаётся новый список (если установлен параметр create_list, равный 1).
• Получение номера страниц с событиями. Затем формируется одна или несколько подзадач.

• Для каждой подзадачи:

  • С сервиса Events передается событие с его БШ.
  • В сервисе Faces создается лицо, к нему прикрепляются атрибуты и биометрические образцы.
  • Выполняется запрос в сервис Faces на привязку указанных лиц к указанному списку.
  • Результат каждой подзадачи сохраняется в сервисе Image Store.

• После завершения последней подзадачи, "рабочий процесс" собирает результаты всех подзадач, объединяет и помещает их в сервис Image Store (в виде результатов задачи).

Для такой задачи можно создать расписание.

Задача Garbage collection#

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

• когда БШ заданы в качестве target для удаления, необходимо указать версию БШ для удаления. Все БШ указанной версии будут удалены.
• если события заданы в качестве target для удаления, необходимо указать один или несколько следующих параметров:
• идентификатор учетной записи;
• верхнее исключенное пороговое значение времени создания события;
• верхнее исключенное пороговое значение появления события в видеопотоке;
• идентификатор обработчика, использованного для создания события.
• если лица заданы в качестве target для удаления, необходимо указать один или несколько следующих параметров:
• верхнее исключенное пороговое значение времени создания лица;
• нижнее включенное пороговое значение времени создания лица;
• пользовательские данные.
• идентификатор списка;

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

С помощью запроса "tasks" > "garbage collection task" сервиса API можно указать события (значение events), обобщенного события (значение general_events) или лица (значение faces) в качестве значений для поля target, тогда как в сервисах Admin или Tasks можно задавать в качестве target лица, события, обобщенные события и БШ (значение descriptors). В таком случае указанные объекты будут удалены для всех существующих аккаунтов.

Для такой задачи можно создать расписание.

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

Задача Additional extraction#

Задача Additional extraction повторно извлекает биометрические шаблоны, извлеченные с помощью предыдущей модели нейронной сети, с использованием новой версии нейронной сети. Это позволяет сохранить используемые ранее биометрические шаблоны при обновлении модели нейронной сети. Если нет необходимости в использовании старых БШ, то можно не выполнять данную задачу и просто обновить модель нейронной сети в настройках Configurator.

В данном разделе описывается работа с задачей Additional extraction. См. подробную информацию о нейросетях, процессе обновления нейросети на новую модель и соответствующие примеры в разделе "Нейросети".

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

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

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

Создайте резервную копию баз данных LP и хранилища Image Store перед запуском задачи Additional extraction.

При обработке задачи извлекается БШ новой нейросети для каждого объекта (лица или события), чья версия биометрического шаблона совпадает с версией, указанной в настройках "DEFAULT_FACE_DESCRIPTOR_VERSION" (для лиц) или "DEFAULT_HUMAN_DESCRIPTOR_VERSION" (для тел). Биометрические шаблоны, чья версия не совпадает с версией, указанной в данных настройках, повторно не извлекаются. Их можно удалить с помощью задачи Garbage collection.

Запрос к сервису Admin:

Необходимо выполнить запрос к ресурсу /additional_extract, указав следующие параметры в теле запроса:

• content > extraction_target – цель извлечения: БШ лица, БШ тела или базовые атрибуты
• content > options > descriptor_version – новая версия нейронной сети (не применимо для базовых атрибутов)
• content > filters > object_type – тип объекта: лица или события

При необходимости можно дополнительно отфильтровать тип объекта по "account_id", "face_id__lt" и пр.

Для дополнительной информации см. запрос "create additional extract task" в спецификации OpenAPI сервиса Admin.

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

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

Необходимо выполнить следующие действия:

• Открыть пользовательский интерфейс сервиса Admin: http://<admin_server_ip>:5010/tasks;

• Запустить задачу Additional extraction, нажав на соответствующую кнопку;

• В появившемся окне задать тип объекта (лица или события), цель извлечения (БШ лица, БШ тела или базовые атрибуты), новую модель нейросети (неприменимо для базовых атрибутов) и нажать "Start", подтвердив запуск задачи.

При необходимости можно дополнительно отфильтровать тип объекта по "account_id".

См. подробную информацию о пользовательском интерфейсе Admin в разделе "Пользовательский интерфейс сервиса Admin".

Для такой задачи можно создать расписание.

Задача ROC-curve calculating#

В результате выполнения этой задачи создается кривая рабочих характеристик приема с TPR (истинно положительной частотой) против FPR (ложно положительной частотой).

См. дополнительную информацию о построении ROC кривой в документе "TasksDevelopmentManual".

Задача расчета ROC

ROC (Receiver Operating Characteristic) – это измерение производительности для задач классификации при различных настройках пороговых значений. ROC-кривая строится в виде отношения TPR (True Positive Rate) к FPR (False Positive Rate). TPR – это количество пар истинно положительных совпадений, деленное на общее предполагаемое количество пар положительных совпадений, а FPR – количество пар ложных положительных совпадений, деленное на общее предполагаемое количество пар отрицательных совпадений. Каждая точка (FPR, TPR) ROC-кривой соответствует определенному порогу схожести. См. дополнительную информацию в Wikipedia.

При использовании ROC производительность модели определяется следующим образом:

• область под ROC-кривой (или AUC);
• частота ошибок типа I и типа II равна точке, то есть точке пересечения ROC-кривой и вторичной главной диагонали.

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

Для выполнения задачи ROC требуется предварительно созданная разметка. При желании можно указать threshold_hit_top (по умолчанию 0) для расчета попадания в топ-N вероятность, сравнить limit (по умолчанию 5), key_FPRs – список ключевых значений FPR для расчета ключевых точек ROC-кривой и фильтры с account_id. Также для создания задачи нужен account_id.

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

Разметка

Разметка предполагается в следующем формате:

[{'face_id': <face_id>, 'label': <label>}]

Метка (или идентификатор группы) может быть числом или любой строкой.

Пример:

[{'face_id': '94ae2c69-277a-4e46-817d-543f7d3446e2', 'label': 0},
 {'face_id': 'cd6b52be-cdc1-40a8-938b-a97a1f77d196', 'label': 1},
 {'face_id': 'cb9bda07-8e95-4d71-98ee-5905a36ec74a', 'label': 2},
 {'face_id': '4e5e32bb-113d-4c22-ac7f-8f6b48736378', 'label': 3},
 {'face_id': 'c43c0c0f-1368-41c0-b51c-f78a96672900', 'label': 2}]

Для такой задачи можно создать расписание.

Задача Estimator#

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

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

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

Ресурс может принимать в обработку пять типов источников с изображениями:

• ZIP-архив
• S3-подобное хранилище
• Сетевой диск
• FTP-сервер
• Сетевая файловая система Samba

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

Для такой задачи можно создать расписание. При создании расписания невозможно указать ZIP-архив в качестве источника изображений.

ZIP-архив как источник изображений для задачи Estimator

Размер архива задаётся с помощью параметра "ARCHIVE_MAX_SIZE" в конфигурационном файле "config.py" сервиса Tasks. По умолчанию размер равен 100 Гб. В качестве ссылки на архив можно использовать внешний URL-адрес или URL-адрес архива, сохраненного в Image Store. Во втором случае архив сначала следует сохранить в LP с помощью запроса POST к ресурсу "/objects".

При использовании внешнего URL-адреса, ZIP-архив сначала скачивается в хранилище контейнера Tasks Worker, где происходит распаковка и обработка изображений. После окончания работы задачи архив вместе с распакованными изображениями удаляются из хранилища.

Необходимо учитывать наличие свободного места для вышеописанных действий.

Передаваемый архив может быть защищён паролем. Пароль можно передать в запросе с помощью параметра "authorization" > "password".

S3-подобное хранилище как источник изображений для задачи Estimator

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

• Параметр "bucket_name" — имя бакета/Access Point ARN/Outpost ARN (обязательное действие);
• Параметр "endpoint" — endpoint (только при указании имени бакета);
• Параметр "region" — bucket region (только при указании имени бакета);
• Параметр "prefix" — префикс ключа файла. Также может использоваться для загрузки изображений из определенной папки, например, "2022/January".

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

• Public access key (обязательное действие);
• Secret access key (обязательное действие);
• Signature version ("s3v2"/"s3v4").

Также доступна возможность рекурсивного выкачивания изображений из вложенных папок бакета (параметр "recursive") и сохранения исходных изображений (параметр "save_origin").

Дополнительную информацию о работе с S3-подобными хранилищами см. в руководстве пользователя AWS.

Сетевой диск как источник изображений для задачи Estimator

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

• Параметр "path" — абсолютный путь к директории с изображениями в контейнере (обязательное поле);
• Параметр "follow_links" — включение/выключение обработки символических ссылок (symlink);
• Параметр "prefix" — префикс ключа файла. Может использоваться для загрузки изображений из определенной директории;
• Параметр "postfix" — постфикс ключа файла. Может использоваться для загрузки изображений с определенным расширением.

См. пример использования префиксов и постфиксов в описании ресурса "/tasks/estimator".

При использовании такого типа источника и запуске сервисов Tasks и Tasks Worker через Docker-контейнеры необходимо смонтировать директорию с изображениями с сетевого диска в локальную директорию и синхронизировать её с указанной директорией в контейнере. Смонтировать директорию с сетевого диска можно любым удобным способом. После этого можно синхронизировать смонтированную директорию с директорией в контейнере с помощью следующей команды при запуске сервисов Tasks и Tasks Worker:

docker run \
...
-v /var/lib/luna/current/images:/srv/images
...

/var/lib/luna/current/images — путь к предварительно смонтированной директории с изображениями с сетевого диска.

/srv/images — путь к директории с изображениями в контейнере, куда они будут перенесены с сетевого диска. Этот путь должен быть указан в теле запроса задачи Estimator (параметр "path").

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

FTP-сервер как источник изображений для задачи Estimator

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

• Параметр "host" — IP-адрес или имя хоста FTP-сервера (обязательное поле);
• Параметр "port" — порт FTP-сервера;
• Параметр "max_sessions" — максимальное количество разрешенных сеансов на FTP-сервере;
• Параметры "user" и "password" — параметры авторизации (обязательные поля).

Как и в задачах Estimator с использованием S3-подобного хранилища или сетевого диска в качестве источников изображений, доступна возможность задания пути до директории с изображениями, рекурсивного получения изображений из вложенных директорий, выбора типа передаваемых изображений, а также указания префикса и постфикса.

См. пример использования префиксов и постфиксов в описании ресурса "/tasks/estimator".

Samba как источник изображений для задачи Estimator

Для такого типа источника параметры аналогичны параметрам FTP-сервера, за исключением параметра "max_sessions". Также если не указываются данные авторизации, подключение к Samba будет осуществляться как гостевое.

Обработка задачи#

Сервис Tasks включает в себя "рабочие процессы" Tasks. Сервис Tasks получает запросы, создает задачи в БД и отправляет подзадачи "рабочим процессам" Tasks. "Рабочие процессы" сервиса Tasks реализованы в виде отдельного контейнера Tasks Worker. "Рабочие процессы" Tasks получают подзадачи и выполняют все необходимые запросы к другим сервисам для решения подзадач.

Ниже представлен общий подход к работе с задачами.

• Сервис API получает запрос на создание новой задачи;
• Сервис Tasks создает новую задачу и отправляет подзадачи "рабочим процессам";
• "Рабочие процессы" Tasks обрабатывают подзадачи и создают отчеты;
• Если несколько "рабочих процессов" обработали подзадачи и создали несколько отчетов, "рабочий процесс", выполнивший последнюю подзадачу, собирает все отчеты и создает единый отчет;
• После завершения выполнения задачи последний "рабочий процесс" обновляет свой статус в базе данных Tasks;
• Пользователь может отправлять запросы на получение информации о задачах и подзадачах и количестве активных задач. Пользователь может отменять или удалять задачи;
• Пользователь может получать информацию об ошибках, возникших при выполнении задач;
• После завершения выполнения задачи пользователь может отправить запрос на получение результатов задачи.

См. раздел "Диаграммы задач" для получения подробной информации об обработке задач.

Запуск задач по расписанию#

В LUNA PLATFORM доступна возможность задать расписание выполнения задач Garbage collection, Clusterization, Exporter, Linker, Estimator, Additional extract, Cross-matching и Roc-curve calculating. С помощью расписания можно гибко управлять временем начала выполнения задач. Например, можно настроить регулярное расписание для очистки событий старше одного месяца каждую пятницу в ночное время.

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

Расписание создается с помощью запроса "create tasks schedule" к сервису API, в котором указывается содержимое создаваемой задачи и временной интервал её запуска. Для указания временного интервала используются Cron-выражения.

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

Тем задачам, которые можно выполнить только через сервис Admin (например, задача удаления некоторых объектов через GC), можно назначить расписание только в сервисе Admin.

В ответ на запрос выдается уникальный идентификатор "schedule_id", по которому можно получить информацию о статусе задачи, время выполнения следующей задачи и пр. (запросы "get tasks schedule и "get tasks schedules). Идентификатор и вся дополнительная информация сохраняются в таблицу "schedule" БД Tasks.

При необходимости можно создать отложенное расписание, а затем активировать его с помощью параметра "action" = "start" запроса "patch tasks schedule". Аналогично можно остановить работу задачи по расписанию с помощью "action" = "stop". Для удаления расписания можно воспользоваться запросом "delete tasks schedule".

Права на работу с расписаниями задаются в токене разрешением "task". Это означает, что если у пользователя есть разрешение на работу с задачами, то он также сможет воспользоваться расписанием.

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

Примеры Cron-выражений#

В данном разделе описаны различные примеры Cron-выражений.

1․ Запускать задачу каждый день в 3 часа ночи:

0 3 * * *

2․ Запускать задачу каждую пятницу в 18:30:

30 18 * * 5

3․ Запускать задачу каждый первый день месяца в полдень:

0 12 1 * *

4․ Запускать задачу каждые 15 минут:

*/15 * * * *

5․ Запускать задачу каждое утро в 8:00, кроме выходных (суббота и воскресенье):

0 8 * * 1-5

6․ Запускать задачу в 9:00 утра в первый и 15-й день каждого месяца, но только если это понедельник:

0 9 1,15 * 1

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

При необходимости можно отправлять уведомления об изменении статуса задач и подзадач с помощью механизма callback'ов. Callback'и позволяют отправлять данные в стороннюю систему по указанному URL или в Telegram. Для настройки уведомлений необходимо настроить политику "notification_policy" в параметрах запроса соответствущей задачи.

Также можно настроить отправку уведомлений для задач и подзадач в настройках расписания.

При необходимости можно получить информацию о текущем состоянии политики уведомления или изменить какие-то данные политики с помощью запросов "get task notification policy" и "replace task notification policy".

Дополнительная защита паролей и токенов#

Пароли и токены, передаваемые в задаче Estimator и в политике "notification_policy", могут быть дополнительно зашифрованы. Для этого необходимо при старте контейнера сервиса Tasks передать пользовательские значения переменным окружения FERNET_PASSPHRASE и SALT.

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

SALT — это случайная строка, добавляемая к паролю перед его хешированием.

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

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

Пример команды запуска контейнера с передачей переменных окружения:

docker run \
--env=CONFIGURATOR_HOST=127.0.0.1 \
--env=FERNET_PASSPHRASE=security_passphrase \
--env=SALT=salt_for_passwords_and_tokens \
...

Важно! Когда контейнер запускается с указанием вышеописанных переменных окружений, то старые пароли и токены перестают работать. Необходимо выполнить дополнительные действия по миграции (см. раздел ниже).

Добавление шифрования при обновлении#

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

Сервис Admin#

Сервис Admin используется для выполнения общих административных процедур:

• Управление учетными записями пользователей;
• Получение информации об объектах, принадлежащих разным учетным записям;
• Создание задач Garbage collection;
• Создание задач Additional extraction;
• Получение отчетов и ошибок по обработанным задачам;
• Отмена и удаление существующих задач.

Сервис Admin имеет доступ ко всем данным, привязанным к разным учетным записям.

В сервисе Admin можно создать аккаунт трех типов — "user", "advanced_user" и "admin". Первые два типа создаются с помощью запроса на создание аккаунта к сервису API, однако третий тип можно создать только с помощью сервиса Admin.

С помощью типа аккаунта "admin" можно авторизироваться в пользовательском интерфейсе (см. ниже) и выполнять вышеописанные задачи. Аккаунт с типом "admin" можно создать как в пользовательском интерфейсе, так и с помощью запроса к ресурсу /accounts сервиса Admin. Для создания аккаунта последним способом требуется указать логин и пароль.

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

Пример CURL-запроса к ресурсу /accounts сервиса Admin:

curl --location --request POST 'http://127.0.0.1:5010/4/accounts' \
--header 'Authorization: Basic cm9vdEB2aXNpb25sYWJzLmFpOnJvb3Q=' \
--header 'Content-Type: application/json' \
--data '{
  "login": "mylogin@gmail.com",
  "password": "password",
  "account_type": "admin",
  "description": "description"
}' 

Все запросы к сервису Admin описаны спецификации OpenAPI сервиса Admin.

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

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

Интерфейс можно открыть в браузере, указав адрес и порт сервиса Admin: <Admin_server_address>:<Admin_server_port>.

Порт сервиса Admin по умолчанию — 5010.

Логин и пароль по умолчанию для доступа к интерфейсу — root@visionlabs.ai/root. Также можно использовать логин и пароль по умолчанию в формате Base64 при запросе к ресурсу /accounts (см. ниже) — cm9vdEB2aXNpb25sYWJzLmFpOnJvb3Q=.

Можно изменить пароль по умолчанию для сервиса Admin с помощью запроса "Change authorization".

На странице доступно три вкладки:

• Accounts. Вкладка предназначена для предоставления информации о всех созданных аккаунтах и для создания новых аккаунтов.
• Tasks. Вкладка предназначена для работы с задачами Garbage Collection и Additional extraction.
• Info. Вкладка содержит информацию о пользовательском интерфейсе и лицензии LUNA PLATFORM.

Вкладка Accounts#

На данной вкладке отображаются все существующие аккаунты.

Можно управлять существующими аккаунтами с помощью следующих кнопок:

– просмотр информации об аккаунте.

– удаление аккаунта.

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

При нажатии кнопки "Create account" открывается окно создания аккаунта, содержащее стандартные настройки создания аккаунта — логин, пароль, тип аккаунта, описание и желаемый "account_id".

См. подробную информацию об аккаунтах и их типах в разделе "Аккаунт".

Вкладка Tasks#

На данной вкладке отображаются выполняемые/выполненные задачи Garbage collection и Additional extraction.

.

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

При нажатии кнопок "Start Garbage collection" и "Start Additional extraction" открываются окна создания соответствующих задач.

Окно "Garbage collection" содержит следующие настройки, аналогичные параметрам тела запроса "garbage collecting task" к сервису Tasks:

• Description — параметр "description"
• Target — параметр "content > target"
• Account ID — параметр "content > filters > account_id"
• Remove sample — параметр "content > remove_samples"
• Remove image origins — параметр "content > remove_image_origins"
• Delete data before — параметр "content > create_time__lt"

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

Окно "Additional extraction" содержит следующие настройки, аналогичные параметрам тела запроса "additional extract task" к сервису Tasks:

• Objects type — параметр "content > filters > object_type"
• Extraction type — параметр "content > extraction_target"
• Descriptor version — параметр "content > options > descriptor_version"
• Description — параметр "description"
• Account ID — параметр "content > filters > account_id"

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

После создания задачи, начинается её выполнение. Процесс выполнения задачи отображается икнонкой . Задача считается выполненной когда значение "Parts done" совпадает со значением "Parts total" и иконка меняется на . При необходимости можно остановить выполнение задачи с помощью иконки .

Для каждой задачи доступны следующие кнопки:

– скачивание результата выполнения задачи в виде файла формата JSON.

– переход на страницу подробного описания задачи и ошибок, полученных при её выполнении.

– удаление задачи.

Задачи выполняются сервисом Tasks после получения запроса от сервиса Admin.

Вкладка Schedules#

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

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

При нажатии на кнопку "Create schedule" открывается окно создания расписания.

В окне можно задать настройки расписания для задачи Garbage collection. Параметры в данном окне соответствуют параметрам запроса "create tasks schedule".

После заполнения параметров и нажатия кнопки "Create schedule" расписание появится во вкладке Schedules.

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

– запуск расписания.

– остановка расписания.

С помощью кнопки можно редактировать расписание. С помощью кнопки можно удалить расписание.

Вкладка Info#

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

.

См. подробное описание лицензии в разделе "Информация о лицензии".

Нажав на кнопку "Download system info" можно также получить следующую техническую информацию о LP:

• версия LUNA PLATFORM,
• версии сервисов LUNA PLATFORM,
• количество биометрических шаблонов,
• значения конфигурационных файлов,
• информация о лицензии,
• статистика выполненных запросов и оценок (см. "Подсчет статистики выполненных запросов и оценок").

Эта информация необходима для технической поддержки. При отправке вопроса необходимо приложить к письму полученный файл JSON.

Получить вышеперечисленную системную информацию также можно с помощью запроса "get system info" к сервису Admin.

Сервис Configurator#

С помощью сервиса Configurator упрощается настройка сервисов LP.

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

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

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

• Пользователь редактирует конфигурации в пользовательском интерфейсе;
• Сервис Configurator сохраняет все измененные конфигурации и другие данные в базе данных;
• Сервисы LP запрашивают сервис Configurator во время запуска и получают все необходимые конфигурации. Все сервисы должны быть настроены на использование сервиса Configurator.

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

Настройки, используемые несколькими сервисами, обновляются для каждого из них. Например, при изменении параметра "LUNA_FACES_ADDRESS" для сервиса Handlers в пользовательском интерфейсе Configurator, этот параметр также будет обновлен для сервисов API, Admin и Python Matcher.

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

Пользовательский интерфейс сервиса Configurator доступен по следующему адресу: <Configurator_server_address> :5070.

URL может отличаться. В этом примере интерфейс сервиса Configurator открывается на сервере сервиса Configurator.

LP содержит бета-версию пользовательского интерфейса сервиса Configurator. Пользовательский интерфейс тестировался в браузерах Chrome и Yandex. Рекомендуемое разрешение экрана для работы с пользовательским интерфейсом – 1920 x 1080.

В пользовательском интерфейсе Configurator доступны следующие вкладки:

• Settings. Все данные в сервисе Configurator хранятся во вкладке Settings. На этой вкладке отображаются все имеющиеся настройки. Также можно управлять ими и фильтровать;
• Limitations. Эта вкладка используется для создания новых ограничений для настроек. Ограничениями являются шаблоны для файлов JSON, содержащие тип имеющихся данных и другие правила для определения параметров;
• Groups. С помощью этой вкладки можно сгруппировать все необходимые настройки. При выборе группы на вкладке Settings, будут отображаться только настройки, соответствующие группе. Можно получить настройки в соответствии с фильтрами и/или тегами для одного определенного сервиса.
• About. В этой вкладке содержится информация об интерфейсе сервиса Configurator.

Настройки#

Каждая настройка сервиса Configurator содержит следующие поля:

• Name – название настройки.
• Description – описание настройки;
• ID and Times – уникальный идентификатор настройки;
• Create time – время создания настройки;
• Last update time – время последнего обновления настройки;
• Value – тело настройки;
• Schema – шаблон проверки тела схемы;
• Tag – теги для настройки, используемые для фильтрации настроек для сервисов.

В поле "Tag" отсутствуют настройки по умолчанию. Необходимо нажать кнопку Duplicate и создать новую настройку на основе имеющейся.

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

• Создание новой настройки – нажать кнопку Create new, ввести необходимые значения и нажать Create. Также необходимо выбрать уже имеющееся существующее ограничение для настройки. Сервис Configurator попытается проверить значение параметра, если будет стоять флажок напротив Check on save и для параметра будет выбрано ограничение;

• Дублирование имеющейся настройки – нажать кнопку Duplicate справа от настройки, изменить требуемые значения и нажать Create. Сервис Configurator попытается проверить значение настройки, если в левой нижней части экрана будет установлен флажок напротив Check on save и будет такая возможность;

• Удаление имеющейся настройки – нажать кнопку Delete справа от настройки.

• Обновление имеющейся настройки – нужно изменить имя, описание, теги, значение и нажать кнопку Save справа от настройки.

• Фильтрование имеющихся настроек по имени, описанию, тегам, именам сервисов, группам – нужно указать фильтры в левой части экрана и нажать Enter или нажать кнопку Search;

Show limitations – флаг используется для включения отображения ограничений для каждой настройки.

JSON editors – с помощью флага можно переключать режим отображения поля значений. При отсутствии флага отображается наименование параметра и поле его значения. При наличии флага поле Value отображается в виде JSON.

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

• Setting. При использовании данного фильтра будет отображаться определенная настройка с указанным именем.
• Description. При использовании данного фильтра будут отображаться все настройки с указанным описанием или частью описания.
• Tags. При использовании данного фильтра будут отображаться все настройки с указанным тегом.
• Service filter. При использовании данного фильтра будут отображаться все настройки, относящиеся к выбранному сервису.
• Group. При использовании данного фильтра будут отображаться все настройки, принадлежащие указанной группе. Например, можно выбрать, чтобы отображались все сервисы, принадлежащие LP.

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

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

Для этого необходимо выполнить следующие действия:

1․ Дублировать или создать новую настройку, указав ей тег. Например, можно дублировать настройку "LUNA_EVENTS_DB" и присвоить ей тег "EVENTS_DB_TAG".

2․ Передать следующие аргументы в команду "run.py" соответствующего контейнера:

• --luna-config — флаг, содержащий адрес сервиса Configurator
• --<configuration_name> — флаг, содержащий настройку и тег

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

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

docker run \
...
dockerhub.visionlabs.ru/luna/luna-events:v.4.26.3
python3 /srv/luna_events/run.py --luna-config http://127.0.0.1:5070/1 --LUNA_EVENTS_DB EVENTS_DB_TAG

Ограничения#

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

Настройки и ограничения имеют одинаковые наименования. При создании ограничения создается новая настройка.

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

Каждое ограничение содержит следующие поля:

• Name – наименование ограничения.
• Description – описание ограничения.
• Service list – список сервисов, в которых могут использоваться настройки этого ограничения.
• Schema – это объект со схемой JSON для проверки настроек.
• Default value – это значение по умолчанию, установленное при создании ограничения.

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

• Создание нового ограничения – нажать кнопку Create new, ввести необходимые значения и нажать Create. Также будет создана настройка со значением по умолчанию;
• Дублирование существующего ограничения – нажать кнопку Duplicate справа от ограничения, изменить требуемые значения и нажать Create. Также будет создана настройка со значением по умолчанию;
• Обновление значения ограничения – изменить name/description/service list/validation schema/default values и нажать кнопку Save справа от ограничения;
• Фильтрование существующего ограничения по именам, описаниям и группам;
• Удаление существующего ограничения – нажать кнопку Delete справа от ограничения.

Группы#

У группы есть наименование и описание.

Можно:

• Создать новую группу – нажать кнопку Create new, ввести имя группы и, при необходимости, описание и нажать Create;
• Отфильтровать существующие группы по именам групп и/или именам ограничений – задать фильтры с левой стороны и нажать RETURN или нажать кнопку Search;
• Обновить описание группы – обновить существующее описание и нажать кнопку Save справа от группы;
• Обновить список, привязанный к ограничениям – чтобы отменить привязку ограничения, нужно нажать кнопку "-" справа от имени ограничения, чтобы привязать ограничение, нужно ввести его имя в поле внизу списка ограничений и нажать кнопку "+". Чтобы принять изменения, нужно нажать кнопку Save;
• Удалить группу – нажать кнопку Delete справа от группы.

Дамп-файл с настройками LP#

Дамп-файл с настройками LP содержит все настройки всех сервисов LP.

Получение дамп-файла#

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

Чтобы получить дамп-файл необходимо воспользоваться следующими командами:

• wget: wget -O settings_dump.json 127.0.0.1:5070/1/dump;
• curl: curl 127.0.0.1:5070/1/dump > settings_dump.json;
• редактор текста.

Будут получены текущие значения, имеющиеся в сервисе Configurator.

Применение дамп-файла#

Чтобы применить сохраненные настройки, нужно выполнить команду Storages для загрузки дампа (load_dump) с аргументом --dump-file: --dump-file=/srv/settings_dump.json.

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

    "limitations":[
      ...
    ],

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

docker run \
--rm \
--network=host \
-v /var/lib/luna/current/extras/conf/storages_config.conf:/srv/storages_config.conf \
-v /var/lib/luna/current/extras/conf/platform_settings.json:/srv/platform_settings.json \
dockerhub.visionlabs.ru/luna/storages:v.0.4.50 \
bash -c "luna_prepare load_dump \
    --dump-file=/srv/platform_settings.json \
    --config=/srv/storages_config.conf"

Здесь:

• luna_prepare load_dump — команда "load_dump", позволяющая загрузить дамп-файл в БД Configurator
• -v /var/lib/luna/current/extras/conf/platform_settings.json:/srv/platform_settings.json \ — команда монтирования дамп-файла platform_settings.json
• --dump-file=/srv/platform_settings.json — именованный аргумент, содержащий адрес дамп-файла внутри контейнера
• -v /var/lib/luna/current/extras/conf/storages_config.conf:/srv/storages_config.conf — команда монтирования конфигурационного файла Storages
• --config=/srv/storages_config.conf — именованный аргумент, содержащий адрес конфигурационного файла для использования сервисом Storages

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

Файл с ограничениями#

Получение файла с ограничениями#

Файл с ограничениями содержит ограничения указанного сервиса. Он не содержит имеющиеся настройки и их значения.

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

1․ Войти в контейнер сервиса Configurator;

2․ Создать выходной каталог base_scripts/results: mkdir base_scripts/results;

3․ Запустить скрипт base_scripts/get_limitation.py: python3 base_scripts/get_limitation.py --service luna-image-store luna-handlers --output base_scripts/results/my_limitations.json.

Обратите внимание на параметры скрипта base_scripts/get_limitation.py:

• --service для указания одного или нескольких имен сервисов (обязательно);
• --output для указания каталога или файла для сохранения выходных данных. Значение по умолчанию: current_dir/{timestamp}_limitation.json (необязательно).

Авторизация#

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

Использование авторизации позволяет обеспечить дополнительную степень безопасности для шифрования и защиты от несанкционированного доступа.

Для включения авторизации нужно задать следующие настройки из новой секции "LUNA_CONFIGURATOR_AUTHORIZATION" сервиса Configurator:

• "USE_AUTHORIZATION" - включение/выключение авторизации
• "LUNA_CONFIGURATOR_USER" - логин, который будет использоваться другими сервисами для авторизации
• "LUNA_CONFIGURATOR_PASS" - пароль, который будет использоваться другими сервисами для авторизации

Задать настройки можно двумя способами:

• передача настроек через переменную окружения VL_SETTINGS при старте сервиса. Например:

env "VL_SETTINGS.LUNA_CONFIGURATOR.USE_AUTHORIZATION=1"
env "VL_SETTINGS.LUNA_CONFIGURATOR.LUNA_CONFIGURATOR_USER=luna"
env "VL_SETTINGS.LUNA_CONFIGURATOR.LUNA_CONFIGURATOR_PASS=root"

• передача настроек в конфигурационный файл сервиса Configurator. Конфигурационный файл сервиса Configurator расположен по следующему пути в поставке example-docker/luna_configurator/configs/luna_configurator_postgres.conf

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

• передача настроек "LUNA_CONFIGURATOR_USER" и "LUNA_CONFIGURATOR" через переменную окружения VL_SETTINGS при старте сервиса (см. пример выше)
• передача настроек "LUNA_CONFIGURATOR_USER" и "LUNA_CONFIGURATOR в конфигурационный файл сервиса при его использовании

Сервис Licenses#

Общая информация#

Сервис Licenses содержит информацию о доступных лицензируемых возможностях и их ограничениях.

Получить информацию о лицензии можно тремя способами:

• с помощью запроса "get license" к сервису Licenses
• с помощью запроса "get system info" к сервису Admin
• с помощью пользовательского интерфейса сервиса Admin

Также можно использовать запрос "get platform features", в ответе на который можно получить информацию о состоянии лицензии, включенных функциях лицензии ("face_quality", "body_attributes" и "liveness") и состоянии опциональных сервисов Image Store, Events, Tasks и Sender из настройки "ADDITIONAL_SERVICES_USAGE" сервиса Configurator.

Если отключить какую-то лицензируемую функцию, и попытаться использовать запрос, требующий этой функции, то будет возвращена ошибка 33002 с описанием "License problem Failed to get value of License feature {value}".

Информация о лицензии#

Лицензия LP содержит следующие параметры:

• Дату окончания лицензии.
• Максимальное количество лиц с прикрепленными биометрическими шаблонами или базовыми атрибутами.
• Доступность функционала OneShotLiveness.
• Текущее количество транзакций OneShotLiveness.
• Доступность функционала Deepfake.
• Доступность функционала для проверки изображений на соответствие стандарту ISO/IEC 19794-5:2011.
• Доступность функционала оценки параметров тел.
• Доступность функционала оценки количества людей на изображении.
• Возможность использования сервиса Lambda.
• Возможность использования сервиса Indexed Matcher в модуле LUNA Index Module.
• Максимально допустимое одновременное количество потоков, которые могут быть взяты единовременно в обработку из FaceStream.
• Максимально допустимое одновременное количество потоков, которые могут быть взяты единовременно в обработку из сервиса Video Manager.

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

Параметры "Возможность использования сервиса Indexed Matcher в модуле LUNA Index Module" и "Максимально допустимое одновременное количество потоков, которые могут быть взяты единовременно в обработку из FaceStream" описаны в документации LUNA Index Module и FaceStream соответственно.

Для некоторых параметров доступны уведомления при приближении к лимиту. Уведомления работают в виде отправки сообщений в логи соответствующего сервиса. Например, при приближении к допустимому количество созданных лиц с биометрическими шаблонами, в логах сервиса Faces будет выводиться следующее сообщение: "License limit exceeded: 8 % of the available license limit is used. Please contact VisionLabs for license upgrade or delete redundant faces". Уведомления работают за счет постоянного мониторинга, реализованного с помощью базы данных Influx. Данные мониторинга сохраняются в соответствующие поля базы данных Influx.

См. подробную информацию в разделе "Мониторинг".

Дата окончания лицензии#

После истечения срока действия лицензии невозможно продолжать использование LUNA PLATFORM.

По умолчанию уведомление об окончании срока действия лицензии отправляется за две недели до истечения срока действия.

Когда срок действия лицензии истекает, сервис API выдает сообщение "License has expired. Please contact VisionLabs for license extension."

Сервис Licenses пишет данные о сроке истечения лицензии в логи и базу мониторинга Influx в поле "license_period_rest".

Максимальное количество лиц#

Сервис Faces проверяет количество оставшихся лиц на основе информации о максимально возможном количестве лиц из сервиса Licenses. Учитываются только лица со связанными биометрическими шаблонами или лица со связанными базовыми атрибутами.

Процент созданных лиц записывается в логах сервиса Faces и отображается в пользовательском интерфейсе Admin.

Сервис Faces пишет данные о созданных лицах в логи и базу мониторинга Influx в поле "license_faces_limit_rate".

Система начинает присылать уведомления, когда остается 15% от общего количества доступных лиц. При превышении максимального количества доступных лиц, в журналах появится сообщение "License limit exceeded: 8 % of the available license limit is used. Please contact VisionLabs for license upgrade or delete redundant faces". К лицам нельзя прикреплять атрибуты, если количество лиц превышает 110%.

Последствия отсутствия параметра

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

• "create face"
• "generate events" с указанием обработчика с "policies" > "storage_policy" > "face_policy" > "store_face"

OneShotLiveness#

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

Каждое использование Liveness в запросах уменьшает счётчик транзакций. После исчерпания лимита транзакций будет невозможно использовать оценку Liveness в запросах. На запросы не использующие Liveness или с отключённой оценкой Liveness исчерпание лимита не влияет, они продолжают работать в обычном режиме.

Сервис Licenses содержит информацию о количестве оставшихся транзакций Liveness. Оно отображается в ответе ресурса "/license".

Сервис Remote SDK пишет данные о количестве доступных транзакций Liveness в логи и базу мониторинга Influx в поле "liveness_balance".

Система начинает присылать уведомления при достижении 2000 оставшихся транзакций Liveness (данный порог задан в системе).

См. раздел "Описание OneShotLiveness" для более подробной информации о работе Liveness.

Последствия отсутствия параметра

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

• "sdk"
• "detect faces"
• "generate events" с указанием обработчика с "policies" > "detect_policy" > "estimate_liveness"
• "perform verification" с указанием обработчика с "policies" > "detect_policy" > "estimate_liveness"
• "estimator task" с указанием обработчика с "policies" > "detect_policy" > "estimate_liveness"
• "predict liveness"

Оценка параметров тел#

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

Последствия отсутствия параметра

При отключении данного параметра, будет невозможно выполнить оценку параметров тел (параметры "estimate_upper_body", "estimate_lower_body", "estimate_body_basic_attributes", "estimate_accessories") в следующих запросах:

• "sdk"
• "generate events" с указанием обработчика с "policies" > "detect_policy" > "body_attributes"

Оценка количества людей#

Данный параметр позволяет выполнять оценку количества людей. В лицензии может быть задано два значения — 0 или 1. Для данного параметра не предназначен мониторинг.

Последствия отсутствия параметра

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

• "sdk"
• "generate events" с указанием обработчика с "policies" > "detect_policy" > "estimate_people_count"

Проверка по стандарту ISO/IEC 19794-5:2011#

Данный параметр позволяет выполнять различные проверки изображений на соответствие стандарту ISO/IEC 19794-5:2011. В лицензии может быть задано два значения — 0 или 1. Для данного параметра не предназначен мониторинг.

Последствия отсутствия параметра

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

• "iso"
• "detect faces" с параметром "estimate_face_quality"
• "generate events" с указанием обработчика с "policies" > "detect_policy" > "face_quality"
• "estimator task" с указанием обработчика с "policies" > "detect_policy" > "face_quality"
• "perform verification" с указанием обработчика с "policies" > "detect_policy" > "face_quality"

Сервисы видеоаналитики#

В LUNA PLATFORM доступны сервисы видеоаналитики, позволяющие выполнять анализ количества людей или отследить человека на видеофайле или видеопотоке.

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

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

Оба сервиса включаются в настройке "ADDITIONAL_SERVICE_USAGE" и отключены по умолчанию.

Видеоанализ можно выполнить с помощью ресурса "/videosdk" и группы ресурсов "/streams".

При выполнении аналитики в ресурсе "/videosdk", сервис Video Agent может только обработать видеофайл и выдать результат в теле ответа.

При выполнении аналитики в группе ресурсов "/streams", сервис Video Agent взаимодействует с сервисом Video Manager, который реализует функционал потоков.

См. базовую информацию о видеоаналитиках подсчета количества людей и отслеживания людей в разделе "Видеоаналитика".

См. расширенную информацию о функционале потоков в разделе "Функционал потоков для видеоанализа".

Сервис Streams Retranslator#

Сервис Streams Retranslator обеспечивает ретрансляцию видеопотоков, предоставляя их в формате HLS, удобном для отображения в пользовательских интерфейсах. Для выполнения ретрансляции используются утилиты FFmpeg и MediaMTX, работающие в контейнере сервиса.

Важно! При запуске контейнера можно прокинуть дополнительные порты для MediaMTX и HLS-потока, чтобы обеспечить доступ к ним через нестандартные порты (см. пример запуска сервиса в документации по установке).

Ретрансляция запускается с помощью запроса "get stream retransmission". В запросе необходимо указать идентификатор потока. Опционально можно указать качество трансляции через параметр "quality". Значение параметра определяет высоту кадра в пикселях. Например, чтобы транслировать поток с высотой 720 пикселей вместо оригинальных 1080, задайте "quality=720". Ширина будет рассчитана автоматически, сохраняя исходное соотношение сторон.

В результате запроса возвращаются следующие данные:

• url — ссылка на HLS-поток (например, http://127.0.0.1:8888/84406ce5-db60-4be1-b741-781f7979ccc5/index.m3u8, где 127.0.0.1:8888 — хост и порт, а 84406ce5-db60-4be1-b741-781f7979ccc5 — идентификатор ретрансляции).
• type — тип трансляции (на текущий момент только HLS).
• quality — качество трансляции (в пикселях).
• token — JWT-токен для доступа к HLS-потоку.

Примечание. Хост и порт, возвращаемые в ответе, необходимо настроить через параметр "EXTERNAL_LUNA_STREAMS_HLS_RETRANSMISSION_ADDRESS" для того, чтобы использовать эти данные в веб-интерфейсе. Стандартные значения не подойдут если сервис запускается не там же, где потребляется HLS-поток или же если при старте контейнера был проброшен нестандартный порт для HLS (например, вместо 8888 проброшен 8899).

Данные о трансляции сохраняются в Redis и существуют до завершения ретрансляции.

Продолжительность ретрансляции контролируется параметром "luna_streams_retranslator_ignored_restream_ttl". Этот параметр задаёт время (по умолчанию 60 секунд), в течение которого поток считается востребованным (например, при наличии зрителей). Если в течение указанного времени поток не востребован, ретрансляция автоматически завершится.

При остановке ретрансляции запрос на её повторный запуск создаст новую ссылку и токен. Если запрос поступает до завершения текущей ретрансляции, пользователь получит ту же самую ссылку на трансляцию и токен, поскольку она уже активна.

Принцип работы#

1․ Пользователь отправляет запрос на рестриминг RTSP-потока с указанием качества (опционально).

2․ Сервис: - Запускает трансляцию через FFmpeg. - Сохраняет ссылку на HLS и токен в Redis. - Возвращает ссылку и токен пользователю.

3․ Пользователь внедряет ссылку и токен в интерфейс (пример).

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

Сервис Streams Retranslator имеет некоторые особенности масштабирования.

Правильный способ использования нескольких экземпляров Streams Retranslator — это разделение запросов между сервисами по различным диапазонам stream_id для каждого экземпляра.

Важно! Адрес и порт, на которых работает балансировщик нагрузки, должны соответствовать значениям параметров из группы "EXTERNAL_LUNA_STREAMS_HLS_RETRANSMISSION_ADDRESS".

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

Примеры разделения uuid4 на диапазоны:

• От 00000000-0000-4000-8000-000000000000 до 80000000-0000-4000-8000-000000000000

• От 90000000-0000-4000-8000-000000000000 до ffffffff-ffff-4fff-bfff-ffffffffffff

• От 00000000-0000-4000-8000-000000000000 до 30000000-0000-4000-8000-000000000000

• От 40000000-0000-4000-8000-000000000000 до 80000000-0000-4000-8000-000000000000
• От 90000000-0000-4000-8000-000000000000 до a0000000-0000-4000-8000-000000000000
• От c0000000-0000-4000-8000-000000000000 до ffffffff-ffff-4fff-bfff-ffffffffffff

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

См. примеры в разделе "Scaling" в руководстве разработчика Streams Retranslator.

Пример HTML-фрагмента для ретрансляции#

Ниже представлен пример, позволяющий отобразить поток на веб-странице. Замените url и token своими значениями:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HLS Stream</title>
    <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
</head>
<body>
    <h1>HLS Stream</h1>
    <video id="video" controls></video>
    <script>
        const video = document.getElementById('video');
        const url = "http://127.0.0.1:8888/84406ce5-db60-4be1-b741-781f7979ccc5/index.m3u8";
        const token = "eyJhbGciOiJ";

        if (Hls.isSupported()) {
            const hls = new Hls();
            hls.attachMedia(video);
            hls.loadSource(url);
            hls.on(Hls.Events.MEDIA_ATTACHED, () => {
                hls.config.xhrSetup = xhr => xhr.setRequestHeader('Authorization', 'Bearer ' + token);
            });
            hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
        } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
            video.src = url;
            video.play();
        } else {
            alert('HLS is not supported in this browser.');
        }
    </script>
</body>
</html>

Сервис Lambda#

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

Сервис Lambda создает образ Docker, а затем запускает его в кластере Kubernetes. Без Kubernetes невозможно управлять пользовательским модулем. Полноценная работа с сервисом Lambda возможна только при разворачивании сервисов LUNA PLATFORM в Kubernetes. Для использования необходимо самостоятельно развернуть сервисы LUNA PLATFORM в Kubernetes или обратиться за консультацией к специалистам VisionLabs. При необходимости можно использовать Minikube для локальной разработки и тестирования, обеспечивая таким образом Kubernetes-подобную среду без необходимости управления полноценным продакшн Kubernetes-кластером.

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

Настоятельно рекомендуется узнать как можно больше об объектах и механизмах LUNA PLATFORM (особенно об обработчиках), прежде чем приступать к работе с данным сервисом.

Пользовательский модуль, запущенный в кластере Kubernetes, называется lambda. Информация о созданной lambda хранится в базе данных Lambda.

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

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

Примечание. Описание, приведенное ниже, предназначено для общего знакомства с функционалом сервиса Lambda. Cм. руководство разработчика сервиса Lambda для более подробной информации. В руководстве разработчика доступен раздел "Quick start guide", позволяющий начать работу с сервисом.

Перед началом работы#

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

Требования к коду и архиву#

Модуль пишется на языке Python и должен быть передан в сервис Lambda в ZIP-архиве.

Код и архив должны соответствовать определенным требованиям, основные из которых перечислены ниже:

• должен использоваться Python версии 3.11 или выше;
• для разработки необходима библиотека "luna-lambda-tools", доступная в VisionLabs PyPi;
• архив не должен быть запаролен.

Также файлы в архиве должны иметь определенную структуру. См. подробную информацию в разделе "Requirements" руководства разработчика сервиса Lambda.

Требования к окружению#

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

• наличие запущенных сервисов Licenses и Configurator*;
• наличие бакета S3 для хранения архивов;
• наличие Docker registry для хранения образов;
• наличие кластера Kubernetes.
• во время своей работы, lambda будет дополнительно взаимодействовать с некоторыми сервисами LUNA PLATFORM. Перечень сервисов зависит от типа lambda (см. "Типы lambda").

При необходимости можно настроить TTL для хранения архивов в S3. См. раздел "Миграция для добавления TTL к объектам в S3".

Должен быть обеспечен доступ на запись/чтение в бакет хранилища S3 и настроены определенные права доступа в кластере Kubernetes. Необходимо переместить базовые образы Lambda на свой Docker registry. Команды для переноса образов приведены в документации по установке LUNA PLATFORM.

При старте сервиса Lambda выполняется проверка Docker registry и базовых образов.

См. подробную информацию в разделе "Requirements" руководства разработчика сервиса Lambda.

Настройки сервиса Lambda#

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

• местоположение кластера Kubernetes (см. настройку "CLUSTER_LOCATION"):

• "internal" — сервис Lambda работает в кластере Kubernetes и не требует других дополнительных настроек;

• "remote" — сервис Lambda работает с удаленным кластером Kubernetes и правильно определенными настройками "CLUSTER_CREDENTIALS" (хост, токен и сертификат);
• "local"- сервис Lambda работает там же, где запущен кластер Kubernetes.

В классическом варианте работы с сервисом Lambda предполагается использование параметра "internal".

• настройки бакета S3 (см. настройку "S3");

• адрес реестра (registry) для хранения образа Docker (см. настройку "LAMBDA_REGISTRY");

• адреса небезопасных реестров (registry), к которым может понадобиться доступ во время создания lambda (см. настройку "LAMBDA_INSECURE_REGISTRIES").

См. подробную информацию в разделе "Configuration requirements" руководства разработчика сервиса Lambda.

Настройка сущностей lambda#

Для запущенных сущностей lambda доступен определенный набор настроек. Их можно задать в Configurator, отфильтровав настройки по имени "luna-lambda-unit".

Настройки для сервиса Lambda и настройки для сущностей lambda отличаются.

Настройки содержат адреса сервисов, тайм-ауты подключения, настройки логирования и др., позволяющие сущностям lambda эффективно взаимодействовать с сервисами LUNA PLATFORM. См. все доступные настройки в разделе "Настройки lambda".

Настройки распространяются на все lambda одновременно.

Типы lambda#

Lambda может быть трех типов:

• Тип Handlers-lambda, предназначенный для замены функционала классического обработчика.
• Тип Standalone-lambda, предназначенный для реализации самостоятельного функционала для выполнения тесной интеграции с LUNA PLATFORM.
• Тип Tasks-lambda, предназначенный для реализации дополнительных пользовательских длинных типов задач.
• Тип Agent-lambda, предназначенный для создания агентов с пользовательскими видеоаналитиками.

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

Handlers-lambda#

Примеры возможного функционала:

• выполнение верификации с возможностью сохранения какого-либо события;
• сравнение двух изображений без выполнения остального функционала классического обработчика;
• добавление собственной логики фильтрации в функционал сравнения;
• обход определенных ограничений LUNA PLATFORM (например, указать количество максимальное кандидатов больше 100);
• встраивание нейронной сети SDK в обход LUNA PLATFORM.

Во время своей работы, Handlers-lambda будет взаимодействовать со следующими сервисами LUNA PLATFORM:

• Configurator — для получения настроек,
• Faces — для работы лицами и списками,
• Remote SDK — для выполнение детекций, эстимаций и извлечений,
• Events* — для работы с событиями,
• Python Matcher / Python Matcher Proxy** — для классического/перекрестного сравнения лиц или тел
• Image Store* — для хранения БО и исходных изображений лиц или тел

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

Для запуска сервиса Lambda требуется только наличие сервисов Configurator и Licenses. * сервис может быть отключен в настройке "ADDITIONAL_SERVICES_USAGE" ** сервис по умолчанию отключен, для включения см. настройку "ADDITIONAL_SERVICES_USAGE"

Lambda-обработчик может использоваться в двух случаях:

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

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

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

  Например, если Lambda-обработчик удовлетворяет вышеуказанным условиям, то его можно использовать в задаче Estimator в качестве классического обработчика.

См. подробную информацию и примеры кода для Handlers-lambda, в разделе "Handlers lambda development" руководства разработчика сервиса Lambda.

Standalone-lambda#

Примеры возможного функционала:

• фильтрация входящих изображений по формату для последующей отправки в сервис Remote SDK;
• создание сервиса для отправки уведомлений по аналогии с сервисом Sender;
• создание сервиса для записи видеопотока и сохранения в виде видеофайла в сервис Image Store для последующей обработки приложением FaceStream.

Во время своей работы, Standalone-lambda будет взаимодействовать как минимум с сервисом Configurator, который позволяет lambda получать свои настройки (например, настройки логирования).

Для запуска сервиса Lambda требуется только наличие сервисов Configurator и Licenses.

См. подробную информацию и пример кода для Standalone-lambda, в разделе "Standalone lambda development" руководства разработчика сервиса Lambda.

Tasks-lambda#

Примеры возможного функционала:

• открепить лица от списка, если лица не похожи на указанное лицо
• удалить дубликаты лиц из списка
• рекурсивно найти события, похожие на указанное изображение

Во время своей работы, Tasks-lambda будет взаимодействовать со следующими сервисами LUNA PLATFORM:

• Configurator
• Faces
• Python Matcher
• Remote SDK
• Tasks
• Events*
• Image Store*
• Handlers*
• сервис может быть отключен в настройке "ADDITIONAL_SERVICES_USAGE"

После создания lambda необходимо выполнить запрос "lambda task" для создания задачи Lambda. Результаты задачи/подзадачи можно получить с помощью стандартных запросов сервиса Tasks.

Задача Lambda создается согласно общему процессу создания задач, за исключением того, что вместо "рабочего процесса" Tasks используется сервис Lambda.

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

При необходимости можно создать расписание для Tasks-lambda.

См. подробную информацию и примеры кода для Tasks-lambda, в разделе "Tasks lambda development" руководства разработчика сервиса Lambda.

Agent-lambda#

Тип Agent-lambda позволяет использовать не только стандартные аналитики (отслеживание людей и подсчет количества людей), но и собственные алгоритмы для видеоанализа, написанные на основе различных моделей нейронных сетей.

Agent-lambda не может обрабатывать любые пользовательские запросы напрямую и функционирует исключительно в сочетании с сервисом Video Manager, который является обязательным компонентом для его работы. Также во время своей работы может взаимодействовать со следующими сервисами LUNA PLATFORM:

• Faces
• Sender
• Events
• Image Store

Примечание. Агенты могут быть внутренними (агенты, взаимодействующие напрямую с сервисами платформы) и внешними (агенты, взаимодействующие только через API и запущенные вне основного контура платформы, см. "внешний режим работы агента"). Agent-lambda на данный момент работает как внутренний агент.

Для создания лямбды с типом agent нужно предварительно перенести базовый образ dockerhub.visionlabs.ru/luna/lpa-lambda-agent-base:<lambda_version> в свой регистри по аналогии с другими типами лямбд.

См. подробную информацию и примеры кода для Agent-lambda, в разделе "Agent lambda development" руководства разработчика сервиса Lambda.

Создание lambda#

Для создания lambda требуется выполнить следующие действия:

1․ Написать код на языке Python в соответствии с типом будущей lambda и требованиями к коду.

2․ Переместить файлы в архив в соответствии с требованиями к архиву.

3․ Выполнить запрос "create lambda", указав следующие обязательные данные: * "archive" — адрес до архива с пользовательским модулем; * "credentials" > "lambda_name" — имя для создаваемой lambda; * "parameters" > "lambda_type" — тип создаваемой lambda ("handlers", "standalone" или "tasks").

Также опционально в секции "deploy_parameters" можно задать количество подов, выделить ресурсы на поды, задать пространства имен (namespace), а также включить использование GPU.

Кроме того можно задать метки для запуска lambda с использованием конкретных узлов Kubernetes с помощью параметра "deploy_parameters" > "selector". Это позволяет более детально контролировать развертывание lambda, позволяя администраторам указывать узлы, на которых должны быть размещены lambda в зависимости от их потребностей в ресурсах. Применяя метки к узлам Kubernetes и используя параметр "selector", администраторы могут управлять выделением ресурсов не только для отдельных lambda, но и для групп lambda с аналогичными требованиями к ресурсам.

При необходимости можно задать список дополнительных команд Docker для создания lambda-контейнера. См. раздел "Lambda — Archive requirements" сервиса Lambda руководства разработчика.

В ответе на успешный запрос будет выдан идентификатор "lambda_id".

Создание lambda состоит из нескольких этапов, а именно:

• создание образа Docker:
  • получение предоставленного ZIP-архива;
  • дополнение архива необходимыми файлами;
  • сохранение архива в хранилище S3;
  • публикация образа в реестр (registry).
• создание сервиса в кластере Kubernetes.

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

• "get lambda image creation status" для получения статуса создания образа Docker ("in_progress", "error", "completed", "not_found")
• "get lambda image creation logs" для получения логов создания образа Docker
• "get lambda status" для получения статуса создания lambda ("running", "waiting", "terminated", "not_found")

См. диаграмму последовательности создания lambda в разделе "Диаграмма создания lambda".

См. подробное описание процесса создания lambda в разделе "Creation pipeline" руководства разработчика сервиса Lambda.

Создание обработчика для Handlers-lambda#

Если предполагается использовать lambda как пользовательский обработчик, имитирующий ответ классического обработчика, то необходимо создать обработчик, указав "handler_type" = "2" и полученный "lambda_id".

Во время создания обработчика, сервис Handlers выполнит проверку работоспособности (healthcheck) до кластера Kubernetes.

Полученный "handler_id" может быть использован в запросах "generate events" или "estimator task".

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

В таблице ниже приведены ресурсы для работы с lambda в зависимости от её типа.

См. диаграмму последовательности обработки lambda в разделе "Диаграмма обработки lambda".

Каждая lambda имеет свой собственный API, описание которого также доступно с помощью запроса "get lambda openapi documentation".

Каждый ответ lambda будет содержать несколько заголовков, включая:

• "Luna-Request-Id" — классический внешний идентификатор запроса LUNA PLATFORM;
• "Lambda-Version" — содержит текущую лямбда-версию.

Полезные запросы при работе с lambda:

• "get lambda status" для получения статуса создания lambda ("running", "waiting", "terminated", "not_found", "pending")
• "get lambda" для получения полной информации о созданной lambda (время создания, имя, статус и пр.)
• "get lambda logs" для получения логов создания lambda

Создание lambda с поддержкой GPU#

Доступна возможность создания lambda, которая может использовать ресурсы графического процессора. Для возможности использования GPU, в запросе на создание lambda должен быть включен параметр "deploy_parameters" > "enable_gpu".

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

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

Сервис Lambda не управляет ресурсами кластера, включая выделение графических процессоров (GPU). Управление ресурсами осуществляется администратором Kubernetes.

Кроме того, при разворачивании LUNA PLATFORM в Kubernetes рекомендуется настроить манифест определенным образом для всех контейнеров, использующих GPU (включая контейнер сервиса Lambda) во избежание проблем с видимостью устройств. См. подробную информацию в разделе "Настройка манифеста для поддержки GPU" руководства по установке.

Обновление lambda#

Базовый образ для контейнеров lambda периодически обновляется. Этот образ содержит необходимые модули для взаимодействия с сервисами LUNA PLATFORM. Для применения обновлений требуется пересоздать lambda, чтобы контейнер мог быть перестроен на основе нового образа. После обновления базового образа и библиотеки "luna-lambda-tools", функциональность lambda может быть нарушена.

Можно обновить lambda с помощью запроса "update lambda", используя последний базовый образ. Рекомендуется иметь резервную копию архива на S3.

См. подробную информацию про механизм обновления, стратегии резервного копирования и восстановление из резервной копии в разделе "Lambda updates" руководства разработчика сервиса Lambda.

Backport 3#

Сервис Backport 3 используется для обработки запросов LUNA PLATFORM 3 с помощью LUNA PLATFORM 5.

Несмотря на то, что большинство запросов выполняется так же, как в LUNA PLATFORM 3, имеются ограничения. Более подробная информация приведена в разделе "Функции и ограничения Backport 3".

Более подробная информация об API Backport 3 приведена в "Backport3ReferenceManual.html".

Новые ресурсы Backport 3#

Оценка Liveness#

Backport 3 выполняет оценку Liveness в дополнение к функциям LUNA PLATFORM 3. См. раздел "liveness > predict liveness" в спецификации OpenAPI сервиса .

Обработчики#

В сервисе Backport 3 предусмотрено несколько обработчиков: extractor, identify, verify. С помощью этих обработчиков можно выполнить несколько действий в одном запросе:

• "handlers" > "face extractor" – можно извлечь БШ из изображения, создать персону с этим БШ, добавить персону в заранее определенный список.

• "handlers" > "identify face" – можно извлечь БШ из изображения и сравнить БШ с предопределенным списком кандидатов.

• "handlers" > "verify face" – можно извлечь БШ из изображения и сравнить БШ с БШ персоны.

См. описание персон в документации LUNA PLATFORM 3.

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

• "handlers" > "patch extractor handler"
• "handlers" > "patch verify handler"
• "handlers" > "patch identify handler"

Запросы основаны на обработчиках и в отличие от стандартных запросов "descriptors" > "extract descriptors", "matching" > "identification", и "matching" > verification», приведенные выше запросы являются более гибкими.

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

Обработчики создаются для каждой новой учетной записи в момент ее создания. Созданные обработчики содержат параметры по умолчанию.

У каждого обработчика есть соответствующий обработчик в сервисе Handlers. Параметры обработчиков хранятся в базе данных luna_backport3.

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

У каждого обработчика есть своя версия. Версия увеличивается с каждым PATCH запросом. При удалении текущего обработчика, версия сбрасывается до 1:

• Для запросов с методами POST и GET:

  Если в сервисе Handlers и/или Backport 3 нет обработчика для указанного действия, он создается с параметрами по умолчанию.

• Для запросов с PATCH методами:

  Если в сервисе Handlers и/или Backport 3 нет обработчика для указанного действия, создается новый обработчик включающий набор политик по умолчанию и набор политик из запроса.

Архитектура Backport 3#

Сервис Backport 3 взаимодействует с сервисом API и с помощью него отправляет запросы в LUNA PLATFORM 5. В свою очередь сервис API взаимодействует с сервисом Accounts для проверки аутентификационных данных.

У сервиса Backport 3 есть своя собственная база данных (см. "Описание базы данных Backport3"). Некоторые из его таблиц приравниваются к таблицам базы данных Faces LP 3. Это позволяет создавать и использовать такие же сущности (лица, токены аккаунтов и аккаунты), которые существовали в LP 3.

Сервис Backport использует Image Store для хранения портретов (см. описание портретов в документации LUNA PLATFORM 3).

Настроить Backport 3 можно с помощью сервиса Configurator.

Функции и ограничения Backport 3#

Следующие функции имеют основные отличия:

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

• /storage/descriptors

• /handlers/extractor

• /handlers/verify

• /handlers/identify

• /matching/search

Тем не менее, можно загрузить существующие БШ версий 52, 54, 56. Более старые версии БШ больше не поддерживаются.

• Оценка параметра saturation больше не поддерживается для ресурса /storage/descriptors при отправке запроса с методом POST, значение всегда устанавливается равным 1.

• Для ресурса /storage/descriptors при отправке запроса с методом POST оценка атрибута eyeglasses больше не поддерживается. В структуре attributes в ответе не будет параметра eyeglasses.

• Для ресурса /storage/descriptors при отправке запроса с методом POST пороговые значения угла положения головы по-прежнему можно отправлять в качестве плавающих значений в диапазоне [0, 180], но они будут автоматически округлены до целых значений. Как и раньше, пороги вне диапазона [0, 180] не учитываются.

Модуль сбора мусора (Garbage collection)#

Согласно логике LUNA Platform 3, мусор – это биометрические шаблоны, которые не связаны ни с персонами, ни со списками.

Для нормальной работы системы необходимо регулярно удалять мусор из баз. Для этого требуется запустить скрипт очистки системы remove_not_linked_descriptors.py из директории ./base_scripts/gc/.

Согласно архитектуре Backport 3, с помощью этого скрипта из сервиса Faces удаляются лица, которые не связаны с какими-либо персонами или списками из базы данных Luna Backport 3.

Процесс выполнения скрипта#

Процесс выполнения скрипта состоит из нескольких этапов:

1) В базе данных Faces создается временная таблица. См. дополнительную информацию о временных таблицах для oracle или postgres. 2) Получаются ID лиц, не привязанных к спискам. ID хранятся во временной таблице. 3) Пока временная таблица содержит данные, выполняются следующие операции:

• Получается пакет ID из временной таблицы. Получаются первые 10 тыс. (или меньше) идентификаторов лиц.
• Получаются filtered ids – идентификаторы, которых нет в таблице person_face базы данных Backport 3.
• Filtered ids удаляются из базы данных Faces. Если некоторые лица не удается удалить, выполнение скрипта останавливается.
• Filtered ids удаляются из базы данных Backport 3 (foolcheck). Выводится предупреждение.
• ID удаляются из временной таблицы.

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

docker run --rm -t --network=host --entrypoint bash dockerhub.visionlabs.ru/luna/luna-backport-3:v.0.12.13 -c "python3 ./base_scripts/gc/remove_not_linked_descriptors.py"

Результат будет содержать информацию о количестве удаленных лиц и количестве людей с лицами.

Backport 4#

Сервис Backport 4 используется для обработки запросов LUNA PLATFORM 4 с помощью LUNA PLATFORM 5.

Несмотря на то, что большинство запросов выполняется так же, как в LUNA PLATFORM 4, все же есть некоторые ограничения. Более подробная информация приведена в разделе "Функции и ограничения Backport 4".

Более подробна информация о сервисе API Backport 4 приведена в спецификации OpenAPI сервиса Backport 4.

Архитектура Backport 4#

Сервис Backport 4 взаимодействует с сервисом API и с помощью него отправляет запросы в LUNA PLATFORM 5.

Backport 4 напрямую взаимодействует с сервисом Faces для получения информации о количестве существующих атрибутов.

Backport 4 напрямую взаимодействует с сервисом Sender. Все запросы к сервису Sender отправляются с помощью сервиса Backport 4. См. запрос "ws" > "ws handshake" в спецификации OpenAPI сервиса Backport 4.

Настроить Backport 4 можно с помощью сервиса Configurator.

Функции и ограничения Backport 4#

Следующие функции имеют основные отличия:

Текущие версии сервисов LUNA PLATFORM выдаются по запросу к ресурсу /version. Например, выдаются версии следующих сервисов:

• "luna-faces"
• "luna-events"
• "luna-image-store"
• "luna-python-matcher" или "luna-matcher-proxy"
• "luna-tasks"
• "luna-handlers"
• "luna-api"
• "LUNA PLATFORM"
• "luna-backport4" – текущая версия

Журнал изменений ресурсов:

• Ресурс /attributes/count доступен без каких-либо параметров запроса и не поддерживает аккаунтинг. Ресурс работает с временными атрибутами.
• Ресурс /attributes по методу GET: допускается параметр запроса attribute_ids вместо параметров запроса page, page_size, time__lt и time__gte. Таким образом, можно получать атрибуты по их идентификаторам, а не по фильтрам. Ресурс работает с временными атрибутами.
• Ресурс /attributes/<attribute_id> по методам GET, HEAD, DELETE и ресурс /attributes/<attribute_id>/samples по методу GET взаимодействуют с временными атрибутами и выдают данные атрибутов, если срок действия атрибута не истек. В противном случае выдается ошибка "Not found".
• Если уже использован атрибут для создания лица, необходимо использовать face_id для получения данных атрибута. В этом случае attribute_id из запроса эквивалентен face_id.
• С помощью ресурса /faces можно создавать несколько лиц с одним и тем же attribute_id.
• С помощью ресурса /faces/<face_id> по методу DELETE можно удалить лицо без удаления его атрибута.
• С помощью ресурса /faces/<face_id> по методу PATCH можно изменить атрибут лица, сделав первый запрос на изменение event_id, external_id, user_data, avatar (при необходимости) и второй запрос на изменение атрибута (при необходимости).
• Если необходимо изменить attribute_id лица, сервис попытается изменить его с помощью данных временного атрибута, если временный атрибут существует. Или же сервис попытается изменить его с помощью данных атрибутов лица с face_id = attribute_id.
• Политика сравнения ресурсов /handlers теперь имеет ограничение на сравнение по умолчанию, которое задано с помощью настройки MATCH_LIMIT из файла config.py сервиса Backport 4.
• Ресурс /events/stats по методу POST: использование attribute_id в объекте filters запрещено, так как это поле больше не хранится в базе данных. Будет выдаваться ответ со статус кодом 403.
• Attribute_id в событиях не пустой и равен face_id для обратной совместимости. Задача Garbage collection недоступна, поскольку все атрибуты временны и будут удаляются автоматически. По запросу к ресурсу /tasks/gc выдается статус код 400.
• Столбец attribute_id не добавляется в задачу Reporter, а также этот столбец игнорируется, если он указан в запросе. Столбцы top_similar_face_id, top_similar_face_list, top_similar_face_similarity заменяются столбцом top_match в отчете, если какой-либо из этих столбцов передается в запросе задачи Reporter.
• В результате выполнения задачи Linker всегда создаются новые лица из событий и игнорируются лица, созданные при запросе обработки событий.
• Ресурс /matcher не проверяет наличие указанных лиц, поэтому ошибка FacesNotFound никогда не выдается. Если пользователь укажет несуществующего кандидата типа «faces», сообщения об ошибке не будет, и не будет выполнено фактическое сравнение с этим лицом.
• Ресурс /matcher проверяет, есть ли у эталона с атрибутом типа идентификатор атрибута лица или идентификатор временного атрибута, и выполняет подстановку типа. Следовательно, он обеспечивает отправку эталонов для сравнения таким же способом, как это было сделано в предыдущей версии.
• Ресурс /matcher учитывает ограничения сравнения. По умолчанию максимальное количество эталонов или кандидатов ограничено 30. Если необходимо превысить эти ограничения, следует настроить параметры REFERENCE_LIMIT и CANDIDATES_LIMIT.
• Добавлен ресурс /ws. В LUNA PLATFORM 4 API не было ресурса /ws, поскольку это был отдельный ресурс сервиса Sender. Этот добавленный ресурс аналогичен ресурсу сервиса Sender, за исключением того, что attribute_id лиц кандидатов аналогичен face_id.
• Ресурс /handlers выдает ошибку "Invalid handler with id {handler_id}", если обработчик был создан в LUNA PLATFORM 5 API и не поддерживается в LUNA Backport 4.

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

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

• Загружать фотографии и создавать лица с их помощью;
• Создавать списки;
• Сравнивать имеющиеся лица;
• Показать имеющиеся события;
• Показать имеющиеся обработчики.

Вся информация в пользовательском интерфейсе отображается в соответствии с данными аккаунта, указанными в файле конфигурации сервиса пользовательского интерфейса (../Imgs/Install/luna-ui/browser/env.js).

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

Необходимо открыть браузер и ввести адрес пользовательского интерфейса. Значение по умолчанию: :4200.

Можно выбрать страницу в левой части окна.

Страница списков/лиц#

Стартовая страница пользовательского интерфейса — Lists/Faces. На ней есть все лица и списки, созданные с помощью указанного в конфигурации аккаунта.

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

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

С помощью кнопки Add new faces можно создать новые лица.

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

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

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

Доступна кнопка Next step.

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

Для этого нужно нажать кнопку Next step.

На следующем этапе необходимо указать данные пользователя и внешний идентификатор (external_id) для каждого лица. Также можно выбрать списки, в которые будет добавлено каждое лицо. Для создания лиц нужно нажать кнопку Add Faces.

Страницы можно менять с помощью кнопок со стрелками.

Можно изменить отображение лиц и отфильтровать их с помощью кнопок в правом верхнем углу.

Фильтр лиц. Можно фильтровать лица по идентификатору, внешнему идентификатору или идентификатору списка;

/

Изменение вида имеющихся лиц.

Страница сервиса Handlers#

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

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

Можно отредактировать или удалить обработчик с помощью значков редактирования

и удаления

.

Страница сервиса Events#

На странице Events отображаются все события, созданные с помощью указанного в конфигурации аккаунта.

Также на ней есть фильтры для отображения событий

.

Общая информация#

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

и

. Значки появляются при наведении курсора на элемент.

Диалог сравнения#

С помощью кнопки Matching в нижнем левом углу окна можно выполнить сравнение.

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

На первом этапе необходимо выбрать эталоны для сравнения. Можно выбрать лица и/или события в качестве эталонов.

На втором этапе необходимо выбрать кандидатов для сравнения. Можно выбрать лица или списки в качестве кандидатов.

На последнем этапе необходимо нажать кнопку Start matching, чтобы получить результаты.

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

Ниже приведена таблица, описывающая наиболее значительное потребление ресурсов сервисами. Сервисы Remote SDK и Python Matcher выполняют наиболее ресурсозатратные операции. 

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

Описание 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",
• "/sdk",
• "/handlers",
• "/verifiers".

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

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

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

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

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

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

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

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

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

Порог 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 и агента".

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

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

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

3․ Агент обрабатывает поток и отправляет статус обработки и возможные ошибки сервису Video Manager.

4․ Агент отправляет результаты обработки в соответствии с выбранным типом 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 Agent#

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

Ограничения при запуске сервиса Video Agent во внешнем режиме:

• ресурс /videosdk недоступен;
• сервисы API и Licenses должны быть доступны и включены.

Запросы доступные при работе Video Agent во внешнем режиме:

• "post agent streams" - позволяет получать потоки по идентификатору агента, обработку которых необходимо начать.
• "post streams feedback" - позволяет оставить обратную связь об обработке потока.
• "create analytic" - запрос на создание аналитики.
• "put analytic" - запрос на обновление существующей аналитики.
• "register agent" - позволяет зарегистировать аналитику.
• "remove agent" - запрос на удаление агента по идентификатору.
• "publish general event" - позволяет отправлять (публиковать) в систему события, созданные пользователем.

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

См. "Запуск сервиса Video Agent во внешнем режиме".

Взаимодействие пользователя и 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 и агента описано ниже:

1․ Агент или администратор должен зарегистрировать в сервисе Video Manager аналитику с которой агент умеет работать, выполнив запрос к ресурсу /1/analytic сервиса Video Manager.

2․ При старте агент должен выполнить запрос к ресурсу /1/agent сервиса Video Manager на регистрацию самого себя. В данном запросе указываются следующие параметры:

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

В ответе на запрос агент получит уникальный идентификатор "agent_id".

3․ Агент периодически должен выполнять запросы к ресурсу /1/agent/{agent_id}/streams сервиса Video Manager для получения/остановки потока на обработку.

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

Обратите внимание, что если агент не сделает такой запрос вовремя, статус агента будет помечен как "not_ready" и агент будет исключен из списка агентов, которые могут обрабатывать потоки (подробности см. в разделе "Управление статусом агента в случае отсутствия запроса агента").

4․ Во время обработки, агент должен отправлять обратную связь о статусе обработки потока к ресурсу /1/agent/{agent_id}/streams/feedback.

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

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

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

Потоки#