← Назад к руководствам
InsightFace ServerDockerРаспознавание лицCUDAЛокальное размещение

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

Запустите InsightFace Server на CPU или CUDA с Docker, установите лицензированную модель, выполните первый точный поиск 1:N и защитите сервис.

•Время чтения: 10 минут
Панель InsightFace Server со статусом сервиса, модели, базы и runtime
До регистрации убедитесь в Dashboard и System, что все компоненты готовы.

Что вы настроите

InsightFace Server объединяет детекцию, сравнение, регистрацию, точный поиск Person 1:N, многоязычный Web UI, REST API, SQLite и локальный инференс в одном самостоятельно размещаемом сервисе. Изображения, эмбеддинги, модели и индексы могут оставаться внутри вашей инфраструктуры.

Руководство начинает с полного checkout InsightFace и заканчивает работающим поиском. Оно также охватывает границы реальной эксплуатации: разрешение на модель, аутентификацию, HTTPS, постоянное хранение, безопасную остановку и fail-fast диагностику CUDA.

Server — ориентированное на конфиденциальность решение для типовых задач, но не совместимая замена AWS Rekognition. В нем нет AWS IAM, SigV4, семантики Region, встроенного TLS, учетных записей и RBAC.

Перед началом

  • Полный checkout InsightFace на Linux x86_64 с Docker Engine и Docker Compose.
  • Для CUDA 12: поддерживаемая NVIDIA GPU, NVIDIA Driver и NVIDIA Container Toolkit. CUDA Toolkit, cuDNN, ONNX Runtime, Python и OpenCV на хосте не нужны.
  • Сеть для загрузки контейнера и установки модели. После этого обычный запуск Server может быть автономным.
  • Правовые основания для обработки биометрии и документированные правила согласия, доступа, хранения, удаления, резервирования и реагирования.

1. Выбрать CPU или CUDA и установить модель

Выполняйте команды из корня полного checkout и выберите один Compose-стек. CPU проще для оценки и публикует порт 18097. CUDA публикует 18098 и требует совместимые Driver и NVIDIA Container Toolkit; устанавливать CUDA или cuDNN на хост не нужно.

Команды намеренно используют неинтерактивный --accept-license и сразу проверяют buffalo_l. Запускайте их только после рассмотрения и принятия условий вашей организацией. Установщик также поддерживает buffalo_m, buffalo_sc и antelopev2.

  • Turing, Ampere, Ada и Hopper требуют Driver R535 или новее; Blackwell и RTX 50 — 570.26 или новее. Для новых систем рекомендуется стабильный R580 или новее.
  • Публичные образы не содержат моделей, данных клиентов, API-ключей и production-конфигурации.
  • Не смешивайте CPU- и CUDA-Compose: у них разные образы, порты, providers и именованные тома данных.
CPU: загрузить, принять лицензию, установить и проверить
mkdir -p server/.models
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
  run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
  run --rm models verify buffalo_l
CUDA 12: загрузить, принять лицензию, установить и проверить
mkdir -p server/.models
docker compose -f server/deploy/compose.cuda12.yml pull
docker compose -f server/deploy/compose.cuda12.yml \
  run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cuda12.yml \
  run --rm models verify buffalo_l

2. Понять границы лицензии модели

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

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

  • Без --accept-license утилита показывает условия и завершает работу без загрузки.
  • Храните модель, manifest и лицензию вместе, а /models монтируйте только для чтения.
  • До коммерческого применения или при неясном охвате публичных условий обратитесь в InsightFace.

3. Запустить сервис и проверить готовность

Запустите только установленный стек. Для CPU откройте http://SERVER:18097/, для CUDA — http://SERVER:18098/. После health до регистрации проверьте в Dashboard или System готовность сервиса, базы, модели и execution provider.

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

Запустить CPU и проверить health
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/health
Запустить CUDA 12 и проверить health
docker compose -f server/deploy/compose.cuda12.yml up -d
curl -fsS http://127.0.0.1:18098/v1/health

4. Выполнить первый сценарий Collection → Person → Search

Экран Collections InsightFace Server для управления доступными для поиска коллекциями лиц
До регистрации Person и FaceSamples создайте Collection, привязанную к модели.

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

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

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

  • Исходные загрузки по умолчанию не хранятся. Опционально сохраняется JPEG crop рамки 112×112, а не оригинал или выровненный вход распознавания.
  • Принятые samples фиксируются в SQLite и до успешного ответа добавляются в точный индекс памяти. После перезапуска он строится из SQLite.
  • Отсутствие лица для Detect — допустимый пустой результат; Compare возвращает 422 face_not_found, если с одной стороны нет пригодного лица.

5. Защитить сервис до публикации в сети

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

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

  • В первой фазе один ключ без ролей; это не multi-tenant авторизация, учетных записей и RBAC нет.
  • Запуск того же тома с другим INSIGHTFACE_API_KEY намеренно заменяет активный ключ.
  • Встроенных TLS и юридического compliance-слоя нет; законность обработки и контроль отвечают операторы.
CPU: включить аутентификацию до запуска
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cpu.yml up -d
CUDA 12: включить аутентификацию до запуска
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cuda12.yml up -d

6. Сохранить данные, создать копию и безопасно остановить

SQLite в /data — постоянный источник истины; точные индексы памяти можно пересоздать. Compose монтирует модели только для чтения и хранит /data в именованном томе. Копируйте SQLite и crop-хранилище вместе при остановленных записях или безопасным для SQLite snapshot.

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

  • Перед обновлением сделайте безопасный snapshot, сохраните /models и лицензии, проверьте новый образ на копии данных.
  • После этого проверьте migrations, /v1/health, контракт модели и известный поиск.
  • Удаление FaceSample удаляет embedding и crop; непустая Collection требует явного force-подтверждения.
Остановить CPU без удаления тома
docker compose -f server/deploy/compose.cpu.yml down
Остановить CUDA без удаления тома
docker compose -f server/deploy/compose.cuda12.yml down

7. Диагностировать ошибки запуска и запросов

Начните с 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 — не выбрано пригодное лицо.

  • Проверьте в System соответствие CPUExecutionProvider или CUDAExecutionProvider выбранному Compose.
  • Проверьте пакет и подписанную лицензию в server/.models, а также read-only mount /models.
  • Для CUDA исправляйте Driver, видимость GPU или NVIDIA Container Toolkit, не ожидая fallback на CPU.
Health, статус и свежие логи CPU
curl -fsS http://127.0.0.1:18097/v1/health
docker compose -f server/deploy/compose.cpu.yml ps
docker compose -f server/deploy/compose.cpu.yml logs --tail=200 server
Health, статус и свежие логи CUDA 12
curl -fsS http://127.0.0.1:18098/v1/health
docker compose -f server/deploy/compose.cuda12.yml ps
docker compose -f server/deploy/compose.cuda12.yml logs --tail=200 server

Нужна помощь с production-развертыванием?

Свяжитесь с InsightFace по вопросам лицензирования моделей, оптимизации runtime и поддержки целевого hardware.

Отправить корпоративный запрос