Интеграция REST API Server

Сначала вызовите GET /v1/health. Этот endpoint всегда публичен и сообщает readiness и auth_enabled. Если auth_enabled равен true, всем остальным endpoints нужен Authorization: Bearer <api_key>. При отключенной аутентификации header Authorization следует полностью убрать — нельзя отправлять пустой header. Первый блок команд показывает правильный вариант без аутентификации, второй предназначен для защищенного deployment.

API использует snake_case JSON и multipart/form-data для изображений. Каждый ответ содержит UUID header x-request-id, а JSON body повторяет его как request_id. Сигналы detection и качества имеют диапазон 0.0–1.0, но recognition similarity — это необработанный cosine в [-1.0, 1.0], а не вероятность. threshold принимает включительный диапазон [0.0, 1.0], по умолчанию равен 0.4, совпадение означает similarity >= threshold.

Collection — изолированная база идентичностей и одновременно deployment contract. При создании закрепляются model ID, version, bundle digest, embedding dimension, preprocessing version, detection profile и exact-search profile активной модели. Возвращаемый embedding_contract_id непрозрачен: копируйте его для trusted external enrollment и никогда не конструируйте самостоятельно.

Начните с threshold 0.4 и откалибруйте его на репрезентативных validation data. Ответ Collection содержит detection_revision и итоговые search settings. Последующие изменения detection profile применяются к новым запросам, но не извлекают заново существующие FaceSamples. Search profiles выполняют точный полный линейный поиск; режимы низкой точности приближают FP32 cosine, но не являются ANN indexes.

Enrollment использует multipart и принимает несколько изображений за запрос. review_mode=off следует стратегии выбора лица Collection; standard требует ровно одно пригодное лицо и применяет настроенные проверки размера, confidence, качества и pose; strict добавляет сравнение similarity внутри и вне класса человека. Batch может частично завершиться с HTTP 201, поэтому всегда проверяйте faces и rejected_images.

Search выбирает query face по профилю Collection, сравнивает со всеми активными FaceSamples и назначает каждому человеку максимальный score его samples. Возвращаются только результаты не ниже effective threshold, в порядке убывания similarity. Для проверки используйте изображение, отличное от регистрационного.

Detect возвращает все пригодные лица по убыванию площади: pixel/normalized boxes, пять landmarks, detector confidence и локальные quality signals. Embeddings не возвращаются, данные не сохраняются. Передайте collection_id, чтобы использовать detection profile Collection вместо неизменного системного профиля.

Compare выбирает по одному лицу из source и target, вычисляет raw cosine similarity и возвращает matched по effective threshold. Similarity может быть отрицательной, ее нельзя показывать как процент confidence. Если на одном из изображений нет пригодного лица, возвращается 422 face_not_found.

Установите client непосредственно из этого checkout. Он основан на httpx, не содержит inference runtime и принимает пути, bytes или бинарные file-like objects. Стандартный timeout 65 секунд немного превышает 60-секундный request deadline Server.

Пример использует CPU-адрес из User Guide с портом 18097 и аутентифицированный Server. Если аутентификация отключена, создайте Client("http://localhost:18097") без api_key, чтобы Authorization header не отправлялся. Client также предоставляет create_monitor, update_monitor, monitor_state и cursor-based monitor_events.

Ошибки используют единый JSON envelope с error.code, error.message, необязательными details и request_id. Типичные соответствия: 400 неверные параметры, 401 отсутствующий/неверный key, 404 отсутствующий resource, 409 state/model conflict, 413 превышение размера, 422 неверное изображение или непригодное лицо, 500 неожиданная ошибка, 503 timeout либо недоступная runtime/index.

GET безопасно повторять. 429 и временные 503 повторяйте с ограниченным exponential backoff и jitter; validation 4xx требуют исправить запрос. После transport failure результат создания Person/FaceSample неоднозначен: сначала прочитайте resource ID, заданный client. Если registration 503 содержит write_committed: true, запись уже находится в SQLite. Не повторяйте вслепую — сначала прочитайте Person.

Monitor — server-side RTSP recognition task, конфигурация которой хранится в SQLite. Enabled task возобновляется после перезапуска Server и работает после закрытия браузера. Decoder хранит только самый новый frame, поэтому медленная inference снижает фактическую частоту, а не создает очередь старых кадров. match_threshold: null наследует threshold Collection.

Preview намеренно выключен по умолчанию, recognition от него не зависит. При включении /preview.mjpeg передает raw JPEG frames без разметки, а client рисует boxes по /state. Никогда не помещайте API key в preview URL. Опрашивайте /events с opaque cursor для enter, exit, error и recovery events и явно обрабатывайте truncated и stream_reset.

Сохраняйте /data, подключайте /models read-only и создавайте backup SQLite вместе с crop storage при остановленных writes либо через SQLite-safe snapshot. Volume и backup являются биометрическими данными. Завершайте HTTPS на доверенном reverse proxy, разрешайте только необходимые CORS origins и задавайте edge rate/body/time limits. Не выставляйте в сеть evaluation deployment без аутентификации.

Исходный код Server и Python SDK распространяются по MIT; модели этой лицензией явно не покрываются. Container image не содержит моделей. Installer показывает model license, а verify проверяет package identity, signed license, срок действия и текущую authorization. Публичные пакеты InsightFace, включая buffalo_l, обычно разрешены только для некоммерческих академических исследований без отдельной коммерческой лицензии.