InsightFace Server с Docker: быстрый старт

Выполните один блок в корне репозитория. Команды напрямую используют поставляемый файл Compose, который определяет загружаемый образ. Если актуальный репозиторий уже есть, пропустите git clone.

После запуска откройте http://SERVER:18097/ для CPU или http://SERVER:18098/ для CUDA 12. --accept-license означает согласие с условиями модели; прочитайте их до выполнения команды.

В Collections создайте стабильный ID, например employees. Выберите профиль из System, задайте capacity по памяти и начните с стандартного raw cosine threshold 0,4. Collection привязана к идентичности и digest модели, размерности, предобработке и профилю детекции.

В People выберите Collection и зарегистрируйте Person по одному или нескольким четким JPEG, PNG, WebP или BMP. standard review — разумный старт: требуется ровно одно пригодное лицо и проверяются размер, confidence, резкость, яркость и поза. Пакет допускает частичный успех, поэтому изучайте каждую причину отклонения.

В Search выберите ту же Collection и загрузите другое фото Person. Результаты сортируются по raw cosine similarity, а оценка Person — максимум среди FaceSamples. Similarity не является вероятностью. Отсутствие совпадений корректно возвращает пустой список.

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

Для работающего сервиса выполните подходящую команду ниже, затем перезапустите его. Обычная установка и models addons install liveness не включают проверку.

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

Исходный код Server и Python SDK распространяются по лицензии MIT, но файлы и веса моделей ею не охватываются. Публичные пакеты InsightFace, включая buffalo_l, обычно разрешены только для некоммерческих академических исследований без отдельного коммерческого разрешения InsightFace; самостоятельное размещение не дает коммерческих прав на модель.

Установка записывает manifest.json и подписанный MODEL.LICENSE в server/.models. verify проверяет идентичность, подпись, срок и текущую авторизацию. Лицензия указывает модель и разрешенное использование; это документ соответствия, а не DRM и не контрольная сумма файлов.

Поддерживаются buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s и raccoon_l. Server использует детектор и распознаватель Raccoon, без verifier из PrivateFrame. Смена модели требует совместимой Collection и повторной регистрации либо миграции данных.

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

Завершайте HTTPS на доверенном reverse proxy, разрешайте только нужные origins вместо широкого CORS, задайте ограничения частоты, размера и времени, защитите Docker, /data, /models и резервные копии. Не журналируйте изображения, эмбеддинги, RTSP-данные или ключи.

Постоянно храните /data, модели и server/config. Копируйте SQLite и кадрированные лица вместе при остановленной записи либо используйте безопасный снимок SQLite. Защищайте их как биометрические данные; перед сетевым доступом включите API-ключ и HTTPS.

Используйте полную команду down запущенного стека. Обычный down удаляет контейнеры и сеть, но сохраняет том. Никогда не добавляйте -v: docker compose down -v безвозвратно удаляет именованный том данных.

Оба контейнера работают как root (0:0), с одним доступным для записи /models и каталогом конфигурации. Каталоги моделей и addons/ создаются по необходимости. UID/GID хоста и ручная настройка прав не нужны. Корневая файловая система контейнера остаётся доступной только для чтения.

Остановите запись и сохраните базу и кадрированные лица. Обновите файлы развёртывания и объедините свои настройки, сохранив server/config/server.toml, модели, исходные имена проекта и тома, порты и API-ключ. Используйте подходящий файл Compose, добавив прежние файлы переопределений и имя проекта при необходимости.

Загрузите оба образа и пересоздайте Server. restart не применяет новые образы или монтирования. Проверьте готовность, провайдер, имеющиеся данные и известный поисковый запрос. При неизменном распознавателе и контракте эмбеддингов образцы сохраняются; смена модели требует отдельной миграции. Обновите SDK из того же актуального репозитория.

Начните с health, затем смотрите System, состояние контейнера и логи выбранного стека. В CUDA остановка старта намеренна при ошибке Driver, GPU, сессий, CUDAExecutionProvider, provider audit или прогрева; скрытого перехода на CPU нет.

Каждый ответ несет x-request-id, ошибки также содержат request_id. Сохраняйте ID с соответствующими логами. 401 unauthorized обычно означает отсутствующий или замененный ключ; 409 collection_model_mismatch — другой контракт; 422 face_not_found — не выбрано пригодное лицо.

CUDA должна показывать CUDAExecutionProvider. При старте проверяются GPU, Driver, CUDA/cuDNN/ONNX Runtime, реальные сессии детектора и распознавания, размещение provider и прогрев. При ошибке процесс завершается, а не незаметно переходит на CPU.