Введение#

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 токену (выдается после создания токена).
• LunaAccountIdAuth. Авторизация по заголовку "Luna-Account-Id", в котором указывается сгенерированный после создания аккаунта "account_id" (данный способ был принят за основной до версии 5.30.0).

Авторизация LunaAccountIdAuth имеет наименьший приоритет по сравнению с другими способами и может быть отключена с помощью настройки "ALLOW_LUNA_ACCOUNT_AUTH_HEADER" в секции "OTHER" настроек сервиса API в Configurator (по умолчанию включена). В спецификации OpenAPI заголовок "Luna-Account-Id" помечен словом Deprecated.

См. подробную информацию о системе авторизации 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 под словом "экстракция" понимается:

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

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

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

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

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

Биометрический шаблон извлекается с помощью нейронной сети, расположенной в контейнере 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, приведенных в столбце "Сервис".

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

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

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

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

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

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

Кроме того, доступна возможность обработки пакета изображений с помощью обработчика (см. "Задача 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 описаны в AdminReferenceManual.html.

См. раздел "Сервис 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" по умолчанию не требуют никакой авторизации.

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

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

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

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

• тип "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" (данный способ был принят за основной до версии 5.30.0).

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

Параметры изображений#

Формат изображения#

Данная оценка определяет формат входящего изображения ("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".

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".

• "/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".

Количество людей#

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

Данная оценка определяет количество людей на изображении.

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

• "/handlers"

  Название оценки - "policies" > "detect_policy" > "estimate_people_count".

• "/sdk"

  Название оценки - "estimate_people_count".

Взаимодействие сервисов 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") (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. См. подробную архитектуру сервиса Backport 3 в разделе "Архитектура Backport 3" и сервиса Backport 4 в разделе "Архитектура Backport 4".

Описание сервисов#

В этом разделе представлена более подробная информация о функциях сервисов 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 не будет выполнять никаких действий.

Выполнение переноса базы данных#

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

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

Можно запускать перенос из контейнера или использовать одиночную команду.

Одиночная команда#

Ниже приведен пример для сервиса Tasks.

docker run \
-v /etc/localtime:/etc/localtime:ro \
-v /tmp/logs/tasks:/srv/logs \
--rm \
--network=host \
dockerhub.visionlabs.ru/luna/luna-tasks:v.3.20.0 \
alembic -x luna-config=http://127.0.0.1:5070/1 upgrade head

Запуск из контейнера#

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

• Зайти в Docker-контейнер сервиса. См. "Вход в контейнер" в руководстве по установке LP 5.

• Запустить перенос.

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

alembic -x luna-config=http://127.0.0.1:5070/1 upgrade head

-x luna-config = http://127.0.0.1:5070/1 – указывает, что параметры конфигурации для переноса должны быть получены от сервиса Configurator.

Для сервиса Configurator параметры берутся из файла "srv/luna_configurator/configs/config.conf".

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

alembic upgrade head

• Выход из контейнера. Контейнер будет удален после выхода.

exit

Сервис 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 доступна работа со следующими форматами биометрических шаблонов:

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 доступна возможность отправки уведомлений с помощью двух политик - "notification_policy" и "callbacks".

Описание данных политик приведено ниже.

Сервис Image Store#

Сервис Image Store хранит следующие данные:

• Биометрические образцы лица и тела. БО сохраняются в Image Store сервисом Remote SDK или с помощью запросов "samples" > "detect faces" и "samples" > "save face/body sample".
• Отчеты о задачах. Отчеты сохраняются "рабочими процессами" сервиса Tasks.
• Любые объекты, загружаемые с помощью запроса "create objects".
• Информацию о кластеризации.

Сервис Image Store имеет возможность сохранять данные либо на локальном накопителе, либо в S3-подобном облачном хранилище (например, Amazon 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;
• запустить скрипт по созданию бакетов lis_bucket_create.py (см. раздел "Создание бакетов" в руководстве по установке)

При необходимости можно отключить проверку SSL-сертификата с помощью настройки "verify_ssl" в группе параметров "S3" настроек сервиса Image Store. Это позволяет использовать самоподписанный SSL-сертификат.

Внешние биометрические образцы#

В Image Store можно отправить внешний биометрический образец. Внешний биометрический образец можно получить с помощью стороннего программного обеспечения или программного обеспечения VisionLabs (например, FaceStream).

См. запрос POST на ресурсе "/samples/{sample_type}" в "APIReferenceManual.html" для получения дополнительной информации.

Внешний БО должен соответствовать определенным стандартам, чтобы LP могла его обработать.

БО, полученные с помощью программного обеспечения VisionLabs, удовлетворяют этому требованию.

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

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

Сервис Accounts#

Сервис Accounts предназначен для:

• Создания, управления и хранения аккаунтов
• Создания, управления и хранения токенов и их разрешений
• Верификации аккаунтов и токенов

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

Все создаваемые аккаунты, токены и их разрешения сохраняются БД сервиса Accounts.

Сервис 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" в документе "EventsReferenceManual".

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

Фильтр географического положения#

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

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

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

Метаинформация события#

В случае, если вместе с событием необходимо сохранить какие-либо дополнительные данные, следует использовать поле "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, двойные подчеркивания, специальные символы и так далее.

Сервис Sender#

Сервис Sender – это дополнительный сервис, который используется для отправки событий через веб-сокеты. Данный сервис коммуницирует с сервисом Handlers (в котором создаются события) через механизм pub/sub по каналу БД Redis.

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

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

Необходимо настроить подключение к веб-сокетам по специальному запросу. Рекомендуется создавать соединение через веб-сокеты, используя ресурс "/ws" сервиса API. В запросе можно указать фильтры (параметры запроса), т.е. можно настроить сервис Sender так, чтобы получать только определенные события. См. спецификацию OpenAPI для получения подробной информации о конфигурации создания подключения к веб-сокету.

Также можно настроить веб-сокеты напрямую через сервис Sender (ресурс "/ws" сервиса Sender). Этот способ можно использовать для снижения нагрузки на сервис API.

После создания события, оно может:

• сохраниться в базе данных сервиса Events. Для сохранения события необходимо включить сервис Events;

• быть выдано в ответ без сохранения в базе данных.

В обоих случаях событие отправляется через канал БД Redis в сервис Sender.

БД Redis в данном случае выступает в качестве связи сервисов Sender и Handlers и не хранит передаваемые события.

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

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

Создание обработчиков и указание фильтров для отправки уведомлений

1. Пользователь отправляет запрос "create handler" в сервис API, где включает политику "notification_policy" и задает фильтры, в соответствии с которыми будет выполняться отправка событий в сервис 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) или лица (значение 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 * * *

1. Запускать задачу каждую пятницу в 18:30:

30 18 * * 5

1. Запускать задачу каждый первый день месяца в полдень:

0 12 1 * *

1. Запускать задачу каждые 15 минут:

*/15 * * * *

1. Запускать задачу каждое утро в 8:00, кроме выходных (суббота и воскресенье):

0 8 * * 1-5

1. Запускать задачу в 9:00 утра в первый и 15-й день каждого месяца, но только если это понедельник:

0 9 1,15 * 1

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

При необходимости можно отправлять уведомления об изменении статуса задач с помощью механизма callback'ов. Callback'и позволяют отправлять данные в стороннюю систему по указанному URL. Для настройки уведомлений необходимо настроить политику "notification_policy" в параметрах запроса соответствущей задачи.

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

При необходимости можно получить информацию о текущем состоянии расписания или обновить его с помощью ресурсов get task notification policy и replace task notification policy .

Сервис Admin#

Сервис Admin используется для выполнения общих административных процедур:

• Управление учетными записями пользователей;
• Получение информации об объектах, принадлежащих разным учетным записям;
• Создание задач Garbage collection;
• Создание задач Additional extraction;
• Получение отчетов и ошибок по обработанным задачам;
• Отмена и удаление существующих задач.

Сервис Admin имеет доступ ко всем данным, привязанным к разным учетным записям.

В сервисе Admin можно создать аккаунт трех типов - "user", "advanced_user" и "admin". Первые два типа создаются с помощью запроса на создание аккаунта к сервису API, однако третий тип можно создать только с помощью сервиса Admin.

С помощью типа аккаунта "admin" можно авторизироваться в пользовательском интерфейсе (см. ниже) и выполнять вышеописанные задачи. Аккаунт с типом "admin" можно создать как в пользовательском интерфейсе, так и с помощью запроса к ресурсу "/4/accounts" сервиса Admin. Для создания аккаунта последним способом требуется указать логин и пароль.

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

Пример CURL-запроса к ресурсу "/4/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 описаны справочном руководстве сервиса Admin.

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

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

Интерфейс можно открыть в браузере, указав адрес и порт сервиса Admin: <Admin_server_address>:<Admin_server_port>.

Порт сервиса Admin по умолчанию - 5010.

Логин и пароль по умолчанию для доступа к интерфейсу - root@visionlabs.ai/root. Также можно использовать логин и пароль по умолчанию в формате Base64 при запросе к ресурсу "/4/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" соответствующего контейнера:

3. --luna-config - флаг, содержащий адрес сервиса Configurator

4. --<configuration_name> - флаг, содержащий настройку и тег

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

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

docker run \
...
dockerhub.visionlabs.ru/luna/luna-events:v.4.11.7
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.

Применение дамп-файла#

Чтобы применить сохраненные настройки, нужно использовать скрипт db_create.py с аргументом командной строки--dump-file (за которым следует имя созданного дамп-файла): base_scripts/db_create.py --dump-file settings_dump.json.

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

    "limitations":[
      ...
    ],

Для применения дамп-файла нужно выполнить следующие действия:

1. Войти в контейнер сервиса Configurator;

2. Запустить скрипт python3 base_scripts/db_create.py --dump-file settings_dump.json

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

Файл с ограничениями#

Получение файла с ограничениями#

Файл с ограничениями содержит ограничения указанного сервиса. Он не содержит имеющиеся настройки и их значения.

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

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 (необязательно).

Сервис 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.
• Максимально допустимое количество потоков, создаваемых сервисом LUNA Streams.

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

Параметры "Возможность использования сервиса Indexed Matcher в модуле LUNA Index Module" и "Максимально допустимое количество потоков, создаваемых сервисом LUNA Streams" описаны в документации 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"

Сервис 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м. руководство разработчика для более подробной информации. В руководстве разработчика доступен раздел "Quick start guide", позволяющий начать работу с сервисом.

Перед началом работы#

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

Требования к коду и архиву#

Модуль пишется на языке Python и должен быть передан в сервис Lambda в ZIP-архиве.

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

• должен использоваться Python версии 3.11 или выше;
• для разработки необходима библиотека "luna-lambda-tools", доступная в VisionLabs PyPi;
• архив не должен быть запаролен.

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

Требования к окружению#

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

• наличие запущенных сервисов Licenses и Configurator*;
• наличие бакета S3 для хранения архивов;
• наличие Docker registry для хранения образов;
• наличие кластера Kubernetes.

* во время своей работы, lambda будет дополнительно взаимодействовать с некоторыми сервисами LUNA PLATFORM. Перечень сервисов зависит от типа lambda (см. "Типы lambda").

Должен быть обеспечен доступ на запись/чтение в бакет хранилища S3 и настроены определенные права доступа в кластере Kubernetes. Необходимо переместить базовые образы Lambda на свой Docker registry. Команды для переноса образов приведены в документации по установке LUNA PLATFORM.

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

Настройки сервиса 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 доступен определенный набор настроек. Их можно задать в Configurator, отфильтровав настройки по имени "luna-lambda-unit".

Настройки для сервиса Lambda и настройки для сущностей lambda отличаются.

Настройки содержат адреса сервисов, тайм-ауты подключения, настройки логирования и др., позволяющие сущностям lambda эффективно взаимодействовать с сервисами LUNA PLATFORM. См. все доступные настройки в разделе "Настройки lambda".

Настройки распространяются на все lambda одновременно.

Типы lambda#

Lambda может быть трех типов:

• Тип Handlers-lambda, предназначенный для замены функционала классического обработчика.
• Тип Standalone-lambda, предназначенный для реализации самостоятельного функционала для выполнения тесной интеграции с LUNA PLATFORM.
• Тип Tasks-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" руководства разработчика.

Standalone-lambda#

Примеры возможного функционала:

• фильтрация входящих изображений по формату для последующей отправки в сервис Remote SDK;
• создание сервиса для отправки уведомлений по аналогии с сервисом Sender;
• создание сервиса для записи видеопотока и сохранения в виде видеофайла в сервис Image Store для последующей обработки приложением FaceStream.

Во время своей работы, Standalone-lambda будет взаимодействовать как минимум с сервисом Configurator, который позволяет lambda получать свои настройки (например, настройки логирования).

Для запуска сервиса Lambda требуется только наличие сервисов Configurator и Licenses.

См. подробную информацию и пример кода для Standalone-lambda, в разделе "Standalone lambda development" руководства разработчика.

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#

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

1. Написать код на языке Python в соответствии с типом будущей lambda и требованиями к коду.
2. Переместить файлы в архив в соответствии с требованиями к архиву.
3. Выполнить запрос "create lambda", указав следующие обязательные данные:
4. "archive" - адрес до архива с пользовательским модулем;
5. "credentials" > "lambda_name" - имя для создаваемой lambda;
6. "parameters" > "lambda_type" - тип создаваемой lambda ("handlers", "standalone" или "tasks").

При необходимости можно задать список дополнительных команд Docker для создания lambda-контейнера. См. раздел "Lambda - Archive requirements" руководства разработчика.

В ответе на успешный запрос будет выдан идентификатор "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" руководства разработчика.

Создание обработчика для 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")
• "get lambda" для получения полной информации о созданной lambda (время создания, имя, статус и пр.)
• "get lambda logs" для получения логов создания lambda

Обновление lambda#

Базовый образ для контейнеров lambda периодически обновляется. Этот образ содержит необходимые модули для взаимодействия с сервисами LUNA PLATFORM. Для применения обновлений требуется пересоздать lambda, чтобы контейнер мог быть перестроен на основе нового образа. После обновления базового образа и библиотеки "luna-lambda-tools", функциональность lambda может быть нарушена.

Можно обновить lambda с помощью запроса "update lambda", используя последний базовый образ. Рекомендуется иметь резервную копию архива на S3.

См. подробную информацию про механизм обновления, стратегии резервного копирования и восстановление из резервной копии в разделе "Lambda updates" руководства разработчика.

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" в "Backport3ReferenceManual.html".

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

В сервисе 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.10.6 -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 приведена в "Backport4ReferenceManual.html".

Архитектура Backport 4#

Сервис Backport 4 взаимодействует с сервисом API и с помощью него отправляет запросы в LUNA PLATFORM 5.

Backport 4 напрямую взаимодействует с сервисом Faces для получения информации о количестве существующих атрибутов.

Backport 4 напрямую взаимодействует с сервисом Sender. Все запросы к сервису Sender отправляются с помощью сервиса Backport 4. См. запрос "ws" > "ws handshake" в "Backport4ReferenceManual.html".

Настроить 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 threshold.

• Image quality (качество изображения) [0..1]. Здесь 1 означает хорошее качество, 0 - плохое. Данный параметр оценивает характеристики изображения, лица, внешних условий в целом. Расчетный уровень качества должен превышать порог Quality threshold.

• Prediction (вердикт). На основе вышеперечисленных данных LUNA PLATFORM выдаёт следующие вердикты:

• 0 (spoof). Проверка выявила, что человек не является реальным.

• 1 (real). Проверка выявила, что человек является реальным.
• 2 (unknown). Результат проверки неизвестен. Такой вердикт может вернуться, если качество проверяемого изображения ниже порога Quality threshold, определяющего качество обрабатываемого изображения.

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

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

• "/liveness",
• "/sdk",
• "/handlers",
• "/verifiers".

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

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

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

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

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

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

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

Пороги Liveness#

По умолчанию для оценки Liveness используется два порога - Quality threshold и Liveness threshold.

Quality threshold#

Quality threshold - порог качества обрабатываемого изображения, ниже которого не будет осуществляться проверка и будет выдан результат "unknown". Данный порог задается в настройке "quality_threshold" из секции "LUNA_REMOTE_SDK_LIVENESS_ESTIMATOR_SETTINGS" сервиса Configurator. Значение порога по умолчанию - 0.5 (50%).

Если качество проверяемого изображения ниже, чем значение Quality threshold, то рекомендуется выполнить повторное фотографирование и отправить изображение в систему для выполнения повторной проверки Liveness. Если же такой возможности нет и требуется выполнить проверку Liveness по отправленному ранее изображению, то можно установить порог Quality threshold равным "0", либо интерпретировать значение "unknown" как "spoof".

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

• FNR (False Negative Rate) - процент подлинных изображений, оцененных как поддельные;
• Drop rate - примерный процент изображений, отсеченных по порогу Quality threshold (оценка сделана по выборке из 170000 изображений).

Liveness threshold#

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

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

Если качество проверяемого изображения ниже, чем значение Quality threshold, то задание порога Liveness threshold не будет имеет смысла, поскольку результат проверки Liveness будет неизвестен ("unknown").

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

В ресурсах "/handlers" и "/verifiers" есть два дополнительных параметра:

• "quality_threshold" - задаёт порог Quality threshold
• "liveness_threshold" - задаёт порог Liveness threshold

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

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

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

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

В LUNA PLATFORM доступна возможность выполнения видеоаналитики с помощью ресурса "videosdk".

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

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

Для выполнения видеоаналитики необходимо указать внешнюю ссылку на видеофайл, не превышающий размер 1 Гб.

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

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

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

Примечание. В текущей версии видео декодируется только на CPU. В будущих релизах будет добавлено декодирование на GPU.

В настоящий момент поддерживается только видеоаналитика подсчета количества людей.

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

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

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

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

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

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

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 в процентах:

Фильтры#

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

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

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

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

__lt

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

__lte

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

__gte

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

Фильтры now-time#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• объекты типа images, objects, samples и политики сохранения биометрических образцов в обработчиках/верификаторах будут недоступны.

• пропадет возможность использования всех задач, кроме задач Garbage Collection, Linker и Estimator, однако для этих задач есть ряд ограничений:

  • Garbage Collection, Estimator, Linker: результаты задач/подзадач не будут сохраняться
  • Garbage Collection, Estimator, Linker: после завершения подзадачи, статус задачи будет обновлен на Done и идентификатор результата задачи будет равен None
  • Garbage Collection: удаление биометрических образцов станет недоступным

  Если сервис Image Store отключается после того, как были сгенерированы события с включенной политикой "image_origin_policy", то при использовании задачи Garbage Collection и параметра remove_image_origins, сервис Tasks будет по-прежнему пытаться удалять исходные изображения, имеющие внешний URL-адрес.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нейросети#

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

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

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

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

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

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

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

Доступные модели нейронных сетей для извлечения БШ в текущей сборке LUNA PLATFORM:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

unzip <archive_name>.zip

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

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

Копирование нейросети и конфигурационного файла в контейнер Remote SDK#

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

docker cp <archive_name>/cnn<model>_<architecture>.plan luna-remote-sdk:/srv/fsdk/data/

docker cp <archive_name>/cnndescriptor_<model>.conf luna-remote-sdk:/srv/fsdk/data/

luna-remote-sdk - имя запущенного контейнера Remote SDK. Это имя может отличаться в разных инсталляциях.

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

docker exec -t luna-remote-sdk ls /srv/fsdk/data/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Вердикт о прохождении проверок, который равен 1, если все проверки успешны.

• Результаты выполнения каждой из проверок. Это позволяет определить, какая именно проверка не была пройдена. Возвращаются следующие значения:

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

• Координаты найденного лица.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• python3.7
• python3.7-devel

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

yum -y install gcc

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

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

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

python3.7 -m venv venv

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

source venv/bin/activate

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

pip3.7 install tqdm 

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

pip3.7 install ../luna3*.whl

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

deactivate

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

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

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

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

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

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

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

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

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

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

python3.7 folder_uploader.py --help

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

• account_id: ID аккаунта, используемый в запросах в LUNA PLATFORM (требуется)

• source: директория с изображениями для загрузки (требуется)

• warped: является ли изображение биометрическим образцом (0,1) (требуется)

• descriptor: извлекать ли биометрический шаблон (0,1); по умолчанию - 0

• origin: адрес API; по умолчанию - "http://127.0.0.1:5000"

• avatar: использовать ли биометрический образец как аватар (0,1); по умолчанию - 0

• list_id: ID списка, к которому прикрепляются лица (новый список LUNA будет создан, если list_id не задан и list_linked=1); по умолчанию - None

• list_linked: прикреплять ли лица к списку (0,1); по умолчанию - 1

• list_userdata: пользовательские данные для списка, к которому прикрепляются лица (для нового списка); по умолчанию - None

• pitch_threshold: максимальный угол головы вверх/вниз [0..180];

• roll_threshold: максимальный угол отклонения головы вправо/влево [0..180];

• yaw_threshold: максимальный угол поворота головы вправо/влево [0..180];

• multi_face_allowed: разрешено ли обнаружение нескольких лиц на одном изображении (0,1); по умолчанию - 0

• get_major_detection: выбрать ли основное обнаружение лица посредством "манхеттенского расстояния" на одном изображении (0,1); по умолчанию - 0

• basic_attr: извлекать ли базовые атрибуты (0,1); по умолчанию - 1

• score_threshold: пороговое значение качества биометрического шаблона (0..1); по умолчанию - 0

• name_as_userdata: использовать ли имя изображения в качестве пользовательских данных (0,1); по умолчанию - 0

• concurrency: число параллельной обработки изображений; по умолчанию - 10

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• python3.7
• python3.7-devel

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

yum -y install gcc

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

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

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

python3.7 -m venv venv

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

source venv/bin/activate

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

pip3.7 install ../luna3*.whl

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

deactivate

Плагины#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• из-за большого объема данных и невозможности ускорить запрос любыми изменениями конфигурации базы данных;

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

• из-за внутренних ограничений базы данных.

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

Примеры:

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

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

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

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

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

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

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

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

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

Thin event

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

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

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

Thin face

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

Cached Matcher

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

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

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

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

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

• Получение сложности подзапроса (см. "Затраты ресурсов на сравнение").

• Выбор способа обработки подзапроса: с помощью плагина сравнения или сервиса Python Matcher.

  • Если на предыдущем шаге был выбран сервис Python Matcher, он обработает подзапрос и вернет ответ сервису Python Matcher Proxy.

  • Если на предыдущем шаге был выбран плагин сравнения, то он обработает подзапрос. Если подзапрос успешно обработан, ответ возвращается в сервис Python Matcher Proxy. Если подзапрос не был успешно обработан, будет совершена попытка обработки в сервисе Python Matcher.

• Если запрос был успешно обработан плагином сравнения, но у него нет доступа ко всем полям объекта, указанным в позапросе в поле "target" для сравнения, то сервис Python Matcher Proxy получит эти данные перед следующим шагом.

• Сервис Python Matcher Proxy собирает результаты от всех подзапросов, сортирует их в правильном порядке, и выдает ответ пользователю.

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

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

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

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

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

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

• ответ на сравнение содержит следующие поля target: face_id , user_data и similarity, а выбранный плагин сравнения не имеет доступа к полю user_data, тогда:

  • плагин сравнения сравнивает эталон с указанными face_id и возвращает результат сравнения сервису Python Matcher Proxy, который содержит только пары face_id и similarity.

  • для каждого кандидата на сравнение в результате сервис Python Matcher Proxy получит user_data из основной базы данных по face_id и объединит face_id и similarity с user_data.

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

• ответ на сравнение содержит следующие поля target: age и gender, а выбранный плагин сравнения имеет доступ только к полям event_id , descriptor и age.

  • плагин сравнения сравнивает эталон и возвращает соответствующий ответ в сервис Python Matcher Proxy, который содержит только пары event_id , age и similarity.

  • для каждого кандидата на сравнение в результате сервис Python Matcher Proxy получит gender из основной базы данных по event_id и объединит event_id с age, а также после этого удалит ненужные event_id и similarity из ответа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Обновление настройки вручную в сервисе Configurator в соответствии с вышеописанным способом.

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

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

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

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

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

Мониторинг#

Мониторинг реализован как отправка данных в InfluxDB. Мониторинг включён в сервисах по умолчанию.

InfluxDB#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• "API"
• "Licenses"
• "Configurator"
• "Image Store"
• "Faces"
• "Admin"
• "Backport 3"
• "Backport 4"
• "Events"
• "Remote SDK"
• "Handlers"
• "Python Matcher"
• "Sender"
• "Tasks"
• "Lambda"

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

• теги

• поля

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

• теги

• поля