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

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

Сервисы

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

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

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

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

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

Сервис	Описание	База данных	Отключаемый
API	Основной интерфейс доступа для работы с LP. Получает запросы, распределяет задачи между другими сервисами LP.	-	Нет
Accounts	Создает аккаунты и управляет ими.	PostgreSQL/ Oracle	Нет
Remote SDK	Распознает лица и тела на изображениях, оценивает лица и тела по параметрам и создает биометрические образцы. Извлекает из биометрических образцов биометрические шаблоны. Извлекает базовые атрибуты изображений.	-
Python Matcher	Выполняет операции сравнения биометрических шаблонов.	Нет	Нет
Faces	Создает лица, списки и атрибуты. Сохраняет эти объекты в базе данных. Позволяет другим сервисам получать требуемые данные из базы данных.	PostgreSQL/ Oracle, Redis	Нет
Configurator	Хранит конфигурации всех сервисов в одном месте.	PostgreSQL/ Oracle	Нет
Licenses	Проверяет данные лицензии и возвращает информацию о них.	-	Нет
Handlers	Создает и хранит обработчики. Принимает запросы на детекцию, эстимацию и извлечение и перенаправляет их в сервис Remote SDK.	PostgreSQL/ Oracle	Да
Image Store	Хранит биометрические образцы, любые объекты, отчеты о длительном выполнении задач, создаваемые кластеры и дополнительные метаданные.	Local storage/ Amazon S3	Да
Events	Отвечает за сохранение событий в БД.	PostgreSQL	Да
Admin	Выполняет общие административные процедуры.	PostgreSQL/ Oracle	Да
Tasks	Выполняет длительные задачи, такие как Garbage collection, Additional extraction, Clustering и др.	PostgreSQL/ Oracle	Да
Tasks Worker	Выполняет внутреннюю работу сервиса Tasks.	-	Да
Sender	Отправляет уведомления о создаваемых событиях через веб-сокет.	Redis	Да

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

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

Сервис	Описание	База данных
Backport 3	Используется для обработки запросов LUNA PLATFORM 3 с использованием LUNA PLATFORM 5.	PostgreSQL/ Oracle
Backport 4	Используется для обработки запросов LUNA PLATFORM 4 с использованием LUNA PLATFORM 5.	-
User Interface 3	Пользовательский интерфейс, используемый для визуального представления возможностей, предоставляемых сервисом Backport 3. Он не включает в себя весь функционал LP 3.	Нет
User Interface 4	Пользовательский интерфейс, используемый для визуального представления возможностей, предоставляемых сервисом Backport 4. Он не включает в себя весь функционал LP 4.	-
Python Matcher Proxy	Управляет запросами сравнения и направляет их в Python Matcher или в плагины сравнения.	Нет
Lambda	Работает с пользовательскими модулями, имитирующими функционал отдельного сервиса.	PostgreSQL/ Oracle
Video Manager	Распределяет потоки между агентами с учетом полученной информации об аналитиках от агента.	PostgreSQL/ Oracle
Video Agent	Выполняет видеоаналитику подсчета количества людей.	PostgreSQL/ Oracle

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

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

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

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

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

Сервис	Описание	Поддерживаемые сервисы
Балансировщик	Осуществляет балансировку запросов между сервисами LP, в случае если запущено несколько аналогичных сервисов. К примеру, можно балансировать запросы между сервисами API или между двумя контурами LP при масштабировании.	NGINX
Система мониторинга	Используется для сбора статистики о запросах и работе системы.	Supervisor
База данных мониторинга	База данных, используемая для хранения собранной информации по мониторингу системы.	InfluxDB
Визуализация мониторинга	Визуализация мониторинга представленная набором дашбордов. С ее помощью можно оценить общую нагрузку на систему или нагрузку на отдельные сервисы.	Grafana, Grafana Loki
Ротация логов	Все сервисы LP пишут логи, размер которых может очень сильно расти. Сервис распределения логов позволяет удалять старые файлы логов и освобождать место на диске.	Logrotate, etc.

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

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

Для большинства запросов к 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. Матчинг — процесс сравнения биометрических шаблонов.

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

Основные операции LUNA PLATFORM

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

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

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

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

• с помощью запроса "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. Ниже приведена таблица с их преимуществами и недостатками:

Формат	Сжатие	Преимущества	Недостатки
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":

Название параметра в теле запроса	Тело ответа	Сохранение в БД
"detect_face" или "detect_body" политики "detect_policy"	Идентификатор обработчика, содержащий правила детекции	Информация об обработчике сохраняется в базу данных Handlers

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

Тело запроса	Тело ответа	Сохранение в БД
Изображение	Результат детекции	БО сохраняется в хранилище Image Store, можно отключить сохранение с помощью параметра "store_sample". Если в обработчике включен параметр "store_event", то результаты детекции будут занесены в базу данных Events в таблицу "face_detect_result" или "body_detect_result"

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

Запрос "detect faces"

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

Тело запроса	Тело ответа	Сохранение в БД
Изображение	Результат детекции	БО сохраняется в хранилище Image Store, невозможно отключить сохранение

В запросе можно отправить изображение или указать 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":

Название параметров в теле запроса	Тело ответа	Сохранение в БД
БШ лица: "extract_face_descriptor" политики "extract_policy"	Идентификатор обработчика, содержащий правила извлечения	Информация об обработчике сохраняется в базу данных Handlers
БШ тела: "extract_body_descriptor" политики "extract_policy"	Аналогично описанию выше	Аналогично описанию выше
Базовые атрибуты лица: "extract_basic_attributes" политики "extract_policy"	Аналогично описанию выше	Аналогично описанию выше

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

Тело запроса	Тело ответа	Сохранение в БД
Изображение	Результаты извлечения	Если в обработчике включен параметр "store_event", то БШ лица или тела будет занесен в базу данных Events, в таблицу "face_descriptor" или "body_descriptor", а базовые атрибуты лица в таблицу "event". Если в обработчике включен параметр "store_face", то будет создано лицо и соответствующий БШ будет занесен в базу данных Faces в таблицу "descriptor", а базовые атрибуты лица в таблицу "event". Если в обработчике включен параметр "store_attribute", то БШ и базовые атрибуты лица будут занесен в базу данных Redis на период TTL.

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

Запрос "extract attributes"

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

Параметр запроса	Тело запроса	Тело ответа	Сохранение в БД
"extract_descriptor" и "extract_basic_attributes"	Изображение	Результаты извлечения	Временные атрибуты сохраняются в базу данных Redis и удаляются оттуда по истечении периода TTL. В момент создания лица, БШ сохраняется в в таблицу "descriptor" базы данных Faces, а базовые атрибуты сохраняются в таблицу "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":

Название политики в теле запроса	Тело ответа	Сохранение в БД
"match_policy"	Идентификатор обработчика, содержащий правила сравнения.	Информация об обработчике сохраняется в базу данных Handlers

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

Тело запроса	Тело ответа	Сохранение в БД
Изображение	Результаты матчинга	Если в обработчике включен параметр "store_event", то результаты матчинга будут занесены в таблицы "face_match_result" или "event_match_result" базы данных Events

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

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

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

Тело запроса	Тело ответа	Сохранение в БД
кандидаты, эталоны и фильтры указываются в параметрах "candidates" и "references"	Результаты матчинга	Нет

Запрос "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".

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

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

Запрос	Описание
"create face"	Создать лицо.
"get faces"	Получить информацию о лицах в соответствии с установленными фильтрами. Можно указать идентификатор списка в качестве фильтра для получения информации обо всех лицах, связанных со списком.
"delete faces"	Удалить несколько лиц по их идентификаторам.
"get face count"	Получить информацию о количестве ранее созданных лиц в соответствии с установленными фильтрами.
"get count of faces with attributes"	Получить информацию о количестве ранее созданных лиц с прикрепленными атрибутами.
"get face"	Получить информацию о лице по его идентификатору.
"patch face"	Обновить поля "user_data", "external_id", "event_id", "avatar" уже созданного лица.
"remove face"	Удалить лицо по его идентификатору.
"check if face exists"	Проверить существует ли лицо с указанным идентификатором.

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

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

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

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

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

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

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

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

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

Запрос	Описание
"create list"	Создать список.
"get lists"	Получить информацию обо всех ранее созданных списках в соответствии с фильтрами.
"delete lists"	Удалить несколько списков по их идентификаторам.
"get list count"	Получить информацию о количестве ранее созданных списков в соответствии с установленными фильтрами.
"get list"	Получить информацию о списке по его идентификатору.
"check if list exists"	Проверить существует ли список с указанным идентификатором.
"update list"	Обновить поле "user_data" уже созданного списка.
"delete list"	Удалить список по его идентификатору.
"attach/detach faces to the list"	Прикрепить/открепить определенные идентификаторы лиц к списку.

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

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

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

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

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

В 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, приведенных в столбце "Сервис".

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

Политика	Описание	Сервис
detect_policy	Задаются оцениваемые параметры лица, тела и изображения.	Remote SDK
extract_policy	Задается необходимость извлечения БШ и базовых атрибутов (пол, возраст, этническая принадлежность). Также определяется пороговое значение качества БШ.	Remote SDK
match_policy	Задается массив списков для сравнения с текущим лицом и дополнительные фильтры для сравнения для каждого списка. Результаты сравнения можно использовать в "create_face_policy" и "link_to_lists_policy"	Python Matcher
storage_policy	Активируется сохранение данных в базе данных для: БО лиц и тел (подполитики "face_sample_policy" и "body_sample_policy") исходные изображения (подполитика "image_origin_policy") атрибуты (подполитика "attribute_policy") лица (подполитика "face_policy") события (подполитика "events_policy") Можно указать фильтры для сохранения объектов. Можно выполнять автоматическую привязку к спискам для лиц и устанавливать TTL для атрибутов. Можно включать и отключать отправку уведомлений через веб-собкеты или через вебхуки. См. подробную информацию в разделе "Отправка событий в сторонний сервис".	Image Store, Faces, Events, Handlers
conditional_tags_policy	Задаются фильтры для присвоения тегов событиям.	Handlers

Если какие-то из политик не требуются, их можно отключить или не указывать в обработчике. Не указанные политики будут выполняться в соответствии с заданным для них значениями по умолчанию. Например, если сохранение БО не требуется, то следует явно отключить их в политике. Если просто не указать "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".

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

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

Запрос	Описание
"create handler"	Создать обработчик.
"get handlers"	Получить информацию обо всех ранее созданных обработчиках в соответствии с установленными фильтрами.
"get handler count"	Получить информацию о количестве ранее созданных обработчиков в соответствии с установленными фильтрами.
"validate handler policies"	Проверить политики обработчика, прежде чем использовать их для создания или обновления обработчика.
"get handler"	Получить информацию об обработчике по его идентификатору.
"replace handler"	Обновить параметры уже созданного обработчика.
"check if handler exist"	Проверить существует ли обработчик с указанным идентификатором.
"remove handler"	Удалить обработчик по его идентификатору.

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

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

Сервис 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".

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

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

Запрос	Описание
"create verifier"	Создать верификатор.
"get verifiers"	Получить информацию обо всех ранее созданных верификаторах в соответствии с установленными фильтрами.
"raw verification"	Выполнить верификацию "сырых" биометрических шаблонов.
"perform verification"	Выполнить верификацию по заданным объектам.
"count verifiers"	Получить информацию о количестве ранее созданных верификаторов в соответствии с установленными фильтрами.
"get verifier"	Получить информацию о верификаторе по его идентификатору.
"replace verifier"	Обновить параметры уже созданного верификатора.
"check if verifier exists"	Проверить существует ли верификатор с указанным идентификатором.
"remove verifier"	Удалить верификатор по его идентификатору.

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

В сервисе 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 см. раздел "Сервис 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 и отправляет отклик.

LP3 vs Backport 3 и LP 5

Ограничения при работе с сервисами 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 можно использовать в запросах на сравнение "сырых" биометрических шаблонов.