Компонент Extraction API

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

Примечание

Будучи аналогом компонента findface-facenapi в том, что касается извлечения данных через API, компонент Extraction API является более ресурсоемким. Данный компонент не может служить полноценной заменой findface-facenapi, поскольку не позволяет добавлять лица и работать с базой данных.

Примечание

Вы также можете использовать Extraction API для непосредственного извлечения биометрических образцов, т. е. как альтернативу findface-nnapi.

Совет

Нормализованные изображения в формате base64, полученные с помощью компонента Extraction API, подходят для обработки в компоненте findface-facenapi.

Важно

Для того чтобы использовать такие функции Extraction API, как оценка качества лица и автоповорот исходных изображений, активируйте модуль Face Quality (Качество лица). Узнайте больше у наших специалистов техподдержки по адресу info@ntechlab.com.

В этом разделе:

Развертывание Extraction API

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

Примечание

Для работы Extraction API необходимы пакеты с моделями нейронных сетей <findface-data>.deb. Убедитесь, что они установлены.

  1. Установите компонент.

    sudo apt-get install findface-extraction-api

  2. Откройте для редактирования файл конфигурации findface-extraction-api.ini.

    sudo vi /etc/findface-extraction-api.ini

  3. В случае если локальный сервер лицензий NTLS является удаленным, укажите его IP-адрес.

    license_ntls_server: 192.168.113.2:3133

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

    fetch:
  enabled: true
  size_limit: 10485760

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

    nnd:
  min_face_size: 30
  max_face_size: .inf

  6. Параметр model_instances задает количество экземпляров каждого активированного детектора лиц (nnd, legacy или prenormalized) и каждой активированной модели нейронной сети (вектор признаков, пол, возраст, эмоции), которое может выполняться параллельно. Значение по умолчанию (0) означает, что данное количество равно числу ядер процессора. Если количество запущенных экземпляров потребляет чересчур много памяти (что проявляется в том, что компонент Extraction API не запускается или самопроизвольно останавливается), отредактируйте значение данного параметра.

    model_instances: 2

  7. Для оценки качества лица включите опцию quality_estimator. В этом случае компонент extraction-api будет возвращать показатель качества в лица в параметре detection_score.

    Совет

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

    quality_estimator: true

    Важно

    Данная функция доступна только после активации модуля Face Quality (Качество лица). Узнайте больше у наших специалистов техподдержки по адресу info@ntechlab.com.

  8. Добавьте сервис Extraction API в автозагрузку Ubuntu и запустите его.

    sudo systemctl enable findface-extraction-api && sudo systemctl start findface-extraction-api

API-запросы

Компонент Extraction API принимает POST-запросы по адресу http://127.0.0.1:18666/.

Существует 2 способа настроить формат тела запроса:

  • application/json: тело запроса целиком состоит из данных в формате JSON.
  • multipart/form-data: тело запроса включает в себя часть в формате JSON, содержащую собственно запрос, остальные части тела используются для передачи изображения.

Часть в формате JSON тела запроса представляет собой набор запросов:

{
    "requests": [request1, request2, .., requestN]
}

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

  • "image": загруженное изображение (используйте формат multipart:часть для указания соответствующей части тела запроса) или публичный URL с изображением (http:, https:).

  • "roi": интересующая область на изображении. Если данная область не задана, обрабатывается все изображение.

  • "detector": детектор лиц, который будет применен к изображению (legacy, nnd или prenormalized). Детектор prenormalized принимает нормализованные изображения лиц, при этом стадия обнаружения лица пропускается. Используйте nnd, если вам нужна оценка качества лиц ("quality_estimator": true).

  • "need_facen": если true, запрос возвращает в ответе вектор признаков.

  • "need_gender": возвращает пол.

  • "need_emotions": возвращает эмоции.

  • "need_age": возвращает возраст.

  • "need_normalized": возвращает нормализованное изображение лица в формате base64. Нормализованное изображение может быть снова отправлено в Extraction API в режиме детектора prenormalized.

  • "auto_rotate": если true, автоматически поворачивает исходное изображение в 4-х различных ориентациях и возвращает лица, найденные в каждой из них. Работает, если "detector": "nnd" и "quality_estimator": true.

    Важно

    Данная функция доступна только после активации модуля Face Quality (Качество лица). Узнайте больше у наших специалистов техподдержки по адресу info@ntechlab.com.

{
    "image": "http://static.findface.pro/sample.jpg",
    "roi": {"left": 0, "right": 1000, "top": 0, "bottom": 1000},
    "detector": "nnd",
    "need_facen": true,
    "need_gender": true,
    "need_emotions": true,
    "need_age": true,
    "need_normalized": true,
    "auto_rotate": true
}

Формат API-ответа

Типичный ответ компонента Extraction API представляет собой набор ответов на соответствующие запросы, вложенные в основной API-запрос:

{
    "response": [response1, response2, .., responseN]
}

Каждый ответ в наборе содержит следующие данные в формате JSON:

  • "faces": набор лиц, обнаруженных на предоставленном изображении или в интересующей области изображения.
  • "error": ошибка обработки запроса (если имела место). Тело ошибки содержит код ошибки, который может быть интерпретирован автоматически ("code") и описание ошибки, удобное для восприятия человеком ("desc").
{
    "faces": [face1, face2, .., faceN],
    "error": {
        "code": "IMAGE_DECODING_FAILED",
        "desc": "Failed to decode: reason"
    }
}

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

  • "bbox": координаты рамки с лицом.
  • "detection_score": показатель качества лица или точность обнаружения лица (в зависимости от того, включена ли опция quality_estimator в файле /etc/findface-extraction-api.ini). Прямые изображения лиц анфас считаются наиболее качественными. Для них возвращаются значения вблизи 0, как правило, отрицательные (такие как -0.00067401276, например). Перевернутые лица и лица, повернутые под большими углами, оцениваются отрицательными значениями от -5 и меньше.
  • "facen": вектор признаков, если запрашивался.
  • "gender": информация о поле (MALE или FEMALE) с указанием точности оценки, если запрашивалась.
  • "age": оценка возраста, если запрашивалась.
  • "emotions": все доступные эмоции в порядке убывания вероятности, если запрашивались.
  • "normalized": нормализованное изображение лица в формате base64, если запрашивалось.
{
    "bbox": { "left": 1, "right": 2, "top": 3, "bottom": 4},
    "detection_score": -0.0004299,
    "facen": "...",
    "gender": {
        "gender": "MALE",
        "score": "1.123"
    },
    "age": 23.59,
    "emotions": [
        { "emotion": "neutral", "score": 0.95 },
        { "emotion": "angry", "score": 0.55 },
        ...
    ],
    "normalized": "...",
}

Примеры

Запрос №1

curl -X POST -F sample=@sample.jpg -F 'request={"requests":[{"image":"multipart:sample","detector":"nnd", "need_gender":true, "need_normalized": true, "need_facen": true}]}' http://127.0.0.1:18666/| jq

Ответ

{
  "responses": [
    {
      "faces": [
        {
          "bbox": {
            "left": 595,
            "top": 127,
            "right": 812,
            "bottom": 344
          },
          "detection_score": -0.0012599,
          "facen": "qErDPTE...vd4oMr0=",
          "gender": {
            "gender": "FEMALE",
            "score": -2.6415858
          },
          "normalized": "iVBORw0KGgoAAAANSUhE...79CIbv"
        }
      ]
    }
  ]
}

Запрос №2

curl -X POST  -F 'request={"requests": [{"need_age": true, "need_gender": true, "detector": "nnd", "roi": {"left": -2975, "top": -635, "right": 4060, "bottom": 1720}, "image": "https://static.findface.pro/sample.jpg", "need_emotions": true}]}' http://127.0.0.1:18666/ |jq

Ответ

{
  "responses": [
    {
      "faces": [
        {
          "bbox": {
            "left": 595,
            "top": 127,
            "right": 812,
            "bottom": 344
          },
          "detection_score": 0.9999999,
          "gender": {
            "gender": "FEMALE",
            "score": -2.6415858
          },
          "age": 26.048346,
          "emotions": [
            {
              "emotion": "neutral",
              "score": 0.90854686
            },
            {
              "emotion": "sad",
              "score": 0.051211596
            },
            {
              "emotion": "happy",
              "score": 0.045291856
            },
            {
              "emotion": "surprise",
              "score": -0.024765536
            },
            {
              "emotion": "fear",
              "score": -0.11788454
            },
            {
              "emotion": "angry",
              "score": -0.1723868
            },
            {
              "emotion": "disgust",
              "score": -0.35445923
            }
          ]
        }
      ]
    }
  ]
}

Запрос №3. Автоповорот

curl -s -F 'sample=@/path/to/your/photo.png' -F 'request={"requests":[{"image":"multipart:sample","detector":"nnd", "auto_rotate": true, "need_normalized": true }]}' http://192.168.113.79:18666/

Ответ

{
 "responses": [
   {
     "faces": [
       {
         "bbox": {
           "left": 96,
           "top": 99,
           "right": 196,
           "bottom": 198
         },
         "detection_score": -0.00019264,
         "normalized": "iVBORw0KGgoAAAANSUhE....quWKAAC"
        },
       {
         "bbox": {
           "left": 205,
           "top": 91,
           "right": 336,
           "bottom": 223
         },
         "detection_score": -0.00041600747,
         "normalized": "iVBORw0KGgoAAAANSUhEUgAA....AByquWKAACAAElEQVR4nKy96XYbybIdnF"
       }
     ]
   }
 ]
}

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

По умолчанию, компонент findface-facenapi обнаруживает лица на фото и отправляет их в компонент findface-nnapi для извлечения биометрического образца (вектора признаков). Затем findface-facenapi сохраняет полученные образцы в базах данных MongoDB и Tarantool. В качестве лучшей альтернативы findface-nnapi в этой последовательности можно использовать Extraction API.

Основным преимуществом Extraction API по сравнению с findface-nnapi является его способность к распараллеливанию и автоматическому распределению нагрузки между параллельными экземплярами, в то время как для findface-nnapi балансировку нагрузки нужно настраивать с помощью NginX вручную.

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

  1. Откройте для редактирования файл конфигурации findface-facenapi.ini:

    sudo vi /etc/findface-facenapi.ini

  2. Раскомментируйте и отредактируйте следующим образом параметр extractor:

    extractor = 'extraction-api'

    Предупреждение

    Содержимое файла findface-facenapi.ini должно представлять собой синтаксически верный код Python.

  3. Раскомментируйте и/или отредактируйте extraction_api_url в соответствии с фактическим расположением сервера Extraction API:

    extraction_api_url = 'http://localhost:18666'

  4. Запустите сервис Extraction API и добавьте его в автозагрузку Ubuntu.

    sudo service findface-extraction-api start && sudo systemctl enable findface-extraction-api

  5. Перезапустите сервис findface-facenapi.

    sudo service findface-facenapi restart

  6. Остановите сервис findface-nnapi и удалите его из автозагрузки.

    sudo service findface-nnapi stop && sudo systemctl disable findface-nnapi

  7. Проверьте статус сервисов. Команда вернет описание сервисов, их статус (должен быть Активен), путь и длительность текущей сессии.

    sudo service 'findface*' status