Перейти к содержанию

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

Диаграмма активности для Liveness и Primary Track Policy#

Ниже приведена диаграмма активности работы FaceStream при использовании Liveness и политики Главного Трека.

Диаграмма активности для Liveness и Primary Track Policy
Диаграмма активности для Liveness и Primary Track Policy

Особенности работы с предварительным просмотром потока#

Для того, чтобы записывать в поток LUNA Streams адрес предварительного просмотра потока (поле preview > live > url), FaceStream должен определять свой IP-адрес. Он определяет свой IP-адрес одним из двух способов:

  • через подключение к сервису LUNA Streams
  • через переменную окружения системы VL_FACE_HOST. Переменная окружения может быть задана с помощью выполнения следующей команды в терминале сервера: export VL_FACE_HOST=<your_ip_address>.

Если IP-адрес переменной VL_FACE_HOST задан неверно, то LUNA Streams будет удалять потоки с некорректным адресом, а FaceStream завершит работу следующей ошибкой Failed to validate input json.

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

Если IP-адрес FaceStream определяется путем подключения к сервису LUNA Streams, то для определения своего IP-адреса, FaceStream всегда должен запускаться после LUNA Streams. Если по каким-то причинам FaceStream запустился перед LUNA Streams (например, выполнился перезапуск сервера, где запущены и FaceStream и LUNA Streams), то FaceStream может завершить работу ошибкой Failed to get local IP address. Reason. Если IP-адрес FaceStream определяется через переменную окружения системы VL_FACE_HOST, то вышеописанная ошибка не возникнет.

Проксирование запросов в LUNA Streams через LUNA API#

Если FaceStream используется совместно с LUNA PLATFORM, то доступна возможность отправлять часть запросов в сервис LUNA Streams через сервис LUNA API.

Для этого необходимо включить и настроить специальный встроенный плагин "luna-streams.py" в сервисе API. Плагин расположен в контейнере сервиса API по пути /srv/luna_api/plugins и включается с помощью настройки "LUNA_API_ACTIVE_PLUGINS".

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

Для плагина доступны следующие настройки, указываемые в конфигурации "LUNA_API_PLUGINS_SETTINGS" сервиса API:

  • "luna-streams-address" > "origin" — протокол, IP адрес и порт сервиса LUNA Streams
  • "luna-streams-address" > "api_version" — версия API сервиса LUNA Streams
  • "luna-streams-timeouts" > "connect" — таймаут для установки соединения при отправке HTTP-запроса к сервису LUNA Streams
  • "luna-streams-timeouts" > "request" — общий таймаут для выполнения всего HTTP-запроса
  • "luna-streams-timeouts" > "sock_connect" — таймаут для установки соединения на уровне сокетов
  • "luna-streams-timeouts" > "sock_read" — таймаут на чтение данных с сокета после успешного соединения

При отсутствии указания конфигурации "LUNA_API_PLUGINS_SETTINGS" или вышеописанных настроек, будут применены значения по умолчанию. См. подробную информацию о вышеперечисленных настройках и их значениях по умолчанию в разделе "LUNA_API_PLUGINS_SETTINGS" руководства администратора LUNA PLATFORM.

Пример задания настройки "LUNA_API_PLUGINS_SETTINGS":

{
    "luna-streams": {
        "luna-streams-address": {
            "origin": "http://127.0.0.1:5160",
            "api_version": 2
        },
        "luna-streams-timeouts": {
            "request": 60,
            "connect": 20,
            "sock_connect": 10,
            "sock_read": 60
        }
    }
}

При необходимости можно разграничить права доступа для запросов к LUNA Streams с помощью разрешений для токена. Для этого нужно создать новый или обновить существующий токен, передав пользовательский ключ "streams" с разрешениями для токена.

Для проксирования запросов из сервиса LUNA API к сервису LUNA Streams нужно указывать разрешение с именем "streams". Другие пользовательские названия ключей не подходят.

Можно задать следующие разрешения:

  • "creation" (POST-запросы)
  • "view" (GET-запросы)
  • "modification" (PUT-запросы и PATCH-запросы)
  • "deletion" (DELETE-запросы)

Пример указания пользовательского ключа "streams" со всеми возможными разрешениями в теле запроса на создание токена:

{
    "permissions": {
        "streams": [
            "creation",
            "view",
            "modification",
            "deletion"
        ]
    }
}

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

В таблице ниже отражено соотношение маршрутов в LUNA API и LUNA Streams, а также ссылки на запросы и возможные разрешения токена.

Маршрут в LUNA API Маршрут в LUNA Streams Запросы Разрешение токена
prefix/version /version get version Нет
prefix/docs/spec /{api_version}/docs/spec get openapi documentation Нет
prefix/plugins /{api_version}/plugins get list of plugins Нет
prefix/streams /{api_version}/streams create stream Пользовательский
get streams
delete streams
prefix/streams/count /{api_version}/streams/count delete streams Пользовательский
prefix/streams/{stream_id} /{api_version}/streams/{stream_id} get stream Пользовательский
update stream
put stream
remove stream
prefix/streams/logs /{api_version}/streams/logs get streams logs Пользовательский
delete streams logs
prefix/streams/{stream_id}/preview/handler/live /{api_version}/streams/{stream_id}/preview/handler/live get live preview Пользовательский
prefix/streams/{stream_id}/preview/handler/frame /{api_version}/streams/{stream_id}/preview/handler/frame get last frame preview Пользовательский

prefix — /6/plugins/luna-streams.

Можно отправлять запросы как в первую версию API LUNA Streams, так и во вторую. Для этого нужно использовать заголовок LUNA-STREAMS-API-VERSION следующим образом:

  • если заголовок LUNA-STREAMS-API-VERSION не указан, будет автоматически выбрана первая версия API
  • если значение заголовка LUNA-STREAMS-API-VERSION равно "1", будет выбрана первая версия
  • если значение заголовка LUNA-STREAMS-API-VERSION равно "2", будет выбрана вторая версия API
  • в противном случае вернется ошибка

Данные событий, генерируемых с помощью FaceStream#

Обрабатывая потоки, FaceStream передает запросы на генерацию событий в LUNA PLATFORM. Для генерации события необходимо при создании потока заполнить поле "event_handler", указывая идентификатор обработчика в поле "bestshot_handler", адрес и версию API сервиса LUNA API и адрес сохранения исходного кадра (при необходимости). 

Ниже приведена таблица, поясняющая какие данные, обработанные FaceStream, записываются в событие LUNA PLATFORM.

Имя параметра Описание
account_id Идентификатор аккаунта, задаваемый при создании потока в LUNA Streams.
create_time Время начала трека (время возникновения события в видеопотоке) относительно времени сервера FS.
end_time Время окончания трека (время окончания события в видеопотоке) относительно времени сервера FS.
handler_id Идентификатор обработчика, задаваемый при создании потока в LUNA Streams.
stream_id Идентификатор потока в LUNA Streams.
source Поле "name", задаваемое при создании потока в LUNA Streams.
track_id Номер трека FaceStream.
face_detections: Данные об обнаружении лица:
* sample_id: Идентификатор БО (лучшего снимка), создаваемый если включена политика "face_sample_policy".
* detect_time: Время обнаружения лучшего снимка лица относительно времени сервера FS.
* image_origin: Исходный кадр.
* detect_ts: Время обнаружения лучшего снимка лица относительно начала видеофайла.
* detection: Координаты ограничивающего треугольника с детекцией лица ("x", "y", ширина, высота).
body_detections: Данные об обнаружении тела:
* sample_id: Идентификатор БО (лучшего снимка), создаваемый если включена политика "body_sample_policy".
* detect_time: Время обнаружения лучшего снимка тела относительно времени сервера FS.
* image_origin: Исходный кадр.
* detect_ts: Время обнаружения лучшего снимка тела относительно начала видеофайла.
* detection: Координаты ограничивающего треугольника с детекцией тела ("x", "y", ширина, высота).
location Данные о местоположении, задаваемые при создании потока в LUNA Streams.

Кроме вышеописанных параметров, событие будет дополнено параметрами, генерируемыми по указанному обработчику (например, "face_id", "match_result", "attach_result", "gender", и др.). Поля "external_id" и "user_data" всегда будут оставаться пустыми при генерации события по биометрическому образцу, передаваемому из FaceStream.