Face Search

Описание#

Face Search Api - это сервис для поиска лиц по индексу, сгенерированному с помощью алгоритма FAISS (сокр. от " Facebook AI Research Similarity Search").

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

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

Проект передается в зашифрованном виде в целях нераспространения исходного кода в формате zip-архива.

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

Этапы:#

1. Распаковка проекта#

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

$ sudo apt install unzip

После установки утилиты необходимо распаковать архив с проектом. Для этого необходимо перейти в папку, в которой находится архив, и выполнить команду:

$ unzip face_search.zip

2. Заполнение переменных среды проекта#

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

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

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

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

Название	Описание	Пример значения	Путь к файлу переменных среды
MINIO_ROOT_USER	Логин для локального хранилища minio	admin	.envs/.base docker-compose.base.yml
MINIO_ROOT_PASSWORD	Пароль для локального хранилища minio	qwerty12345	.envs/.base docker-compose.base.yml
RABBIT_USERNAME	Логин для брокера сообщений RabbitMQ	rabbit_admin	.envs/.base
RABBIT_PASSWORD	Пароль для брокера сообщений RabbitMQ	qwerty12345	.envs/.base
RABBITMQ_DEFAULT_USER	Логин брокера сообщений RabbitMQ, должен совпадать с RABBIT_USERNAME	rabbit_admin	docker-compose.base.yml
RABBITMQ_DEFAULT_PASS	Пароль для брокера сообщений RabbitMQ, должен совпадать с RABBIT_PASSWORD	qwerty12345	docker-compose.base.yml
AWS_REGION_NAME	Регион AWS	us-east-1	.envs/.base
AWS_ACCESS_KEY_ID	AWS Access Key ID		.envs/.base
AWS_SECRET_ACCESS_KEY	AWS Secret Access Key		.envs/.base
AWS_IMAGES_BUCKET_PATH	Путь к бакету с фотографиями	images	.envs/.base
INDEX	Название файла индекса	test	.envs/.base
LIMIT	Количество pickle-файлов, которые будут извлечены для индексирования	500	.envs/.indexer
TRAIN_BLOCK_SIZE	Количество pickle-файлов, которые будут отправлены на индексацию	100 (значение должно быть меньше LIMIT)	.envs/.indexer
BATCH_SIZE	Количество эмбеддингов, которые будут сериализованы в один pickle-файл	40 (значение должно быть меньше количества фотографий в хранилище s3	.envs/.indexer

3. Запуск проекта#

Краткую инструкцию по запуску проекта можно найти в README.md файле в корне проекта.

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

После установки необходимых утилит, необходимо перейти в папку с проектом и выполнить команды:

# Создание сети для взаимодействия контейнеров docker
$ docker network create face-net
# Запуск базовых сервисов - minio, rabbitmq, mongodb
$ make base

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

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

# Векторизация фотографий
$ make vectorize

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

Чтобы посмотреть ход векторизации, можно выполнить команду:

# Просмотр логов векторизации
$ make vectorize-logs

Затем необходимо запустить сервис индексации:

# Индексация эмбеддингов
$ make index

Чтобы посмотреть ход индексации, можно выполнить команду:

# Просмотр логов индексации
$ make index-logs

После успешного запуска сервиса индексации, необходимо запустить сервис поиска:

# Запуск сервиса поиска
$ make api

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

# Запуск периодической задачи
$ make setup-cronjob

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

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

# Удаление периодической задачи
$ make remove-cronjob

Документация OpenApi сервиса поиска будет доступна локально по данному адресу.

4. Использование сервиса#

Сервис содержит два эндпойнта:

Эндпойнт для поиска по фотографии
Эндпойнт для загрузки фотографий в хранилище s3 и загрузки векторов и эмбеддингов в базу данных MongoDB

Важно: API-KEY будет убран в дальнейших обновлениях проекта. Его текущее значение - 123123123

4.1 Использования эндпойнта для поиска лиц по фотографии#

В запросах к сервису используются данные в формате multipart/form-data. Ответные данные от сервиса будут представлены в формате JSON.

URL запроса для поиска фотографий:

https://{server_api}/api/v1/search/

server_ip - адрес сервера, на котором запущен сервис поиска. Необходимо заменить на реальный адрес сервера.

Формат запроса	Метод запроса
multipart/form-data	POST

API KEY необходимо передать в заголовках запроса:

Наименование поля	Тип	Обязательно	Описание
img	File	Да	Фотография лица для поиска

Примеры запроса:

cURL

curl -X 'POST' \
  'http://{server-ip}/api/v1/search/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: 123123123' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<path_to_face_photo>;type=image/jpeg'

Python

import pprint
import requests

url = 'http://{server-ip}/api/v1/search/'
headers = {
    'accept': 'application/json',
    'X-API-KEY': '123123123',
}
files = {
    'file': ('face_photo.jpg', open('<path_to_face_photo>', 'rb'), 'image/jpeg')
}

response = requests.post(url, headers=headers, files=files)

pprint.pprint(response.json())

В качестве ответа придет массив JSON со следующими полями:

url - адрес фотографии в хранилище s3;
prediction - процентное значение похожести лица на искомое;

Пример ответа:

{
  "url": "https://face2face-storage.s3.eu-central-1.amazonaws.com/face_photo.jpg",
  "prediction": 81,
}

Ошибки при поиске фотографий#

Код состояния	Ответ	Описание
404	No faces found on provided image	Лицо не найдено. Возникает если на фотографии нет лица
400	File must be an image	Недопустимое расширение файла. Возникает, если файл с изображением лица не имеет расширения .jpeg, .jpg или .png

4.2 Использования эндпойнта для загрузки фотографий#

В запросах к сервису используются данные в формате multipart/form-data. Ответные данные от сервиса будут представлены в формате JSON

URL запроса для загрузки фотографий:

https://{server_api}/api/v1/search/

server_ip - адрес сервера, на котором запущен сервис поиска. Необходимо заменить на реальный адрес сервера.

Формат запроса	Метод запроса
multipart/form-data	POST

API KEY необходимо передать в заголовках запроса:

Наименование поля	Тип	Обязательно	Описание
img	File	Да	Фотография лица для поиска

Примеры запроса:

cURL

curl -X 'POST' \
  'http://{server-ip}/api/v1/upload/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: 123123123' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<path_to_face_photo>;type=image/jpeg'

Python

import requests

url = 'http://{server-ip}/api/v1/upload/'
headers = {
    'accept': 'application/json',
    'X-API-KEY': '123123123',
}
files = {
    'file': ('face_photo.jpg', open('<path_to_face_photo>', 'rb'), 'image/jpeg')
}

response = requests.post(url, headers=headers, files=files)

print(response.text)

В качестве ответа должен прийти следующий JSON:

{
  "message": "File was successfully uploaded"
}

Ошибки при загрузке фотографий#

Код состояния	Ответ	Описание
400	File must be an image	Недопустимое расширение файла. Возникает, если файл с изображением лица не имеет расширения .jpeg, .jpg или .png