Docker で InsightFace Server をデプロイ

完全な InsightFace チェックアウトのルートでコマンドを実行し、Compose スタックを 1 つ選びます。CPU は評価を始めやすくポート 18097、CUDA はポート 18098 を公開します。CUDA には互換 Driver と NVIDIA Container Toolkit が必要ですが、ホストに CUDA や cuDNN を入れる必要はありません。

以下は非対話式の --accept-license を意図的に使い、続けて buffalo_l を検証します。組織内でモデル条件を確認して受諾した場合だけ実行してください。同じツールで buffalo_m、buffalo_sc、antelopev2 も導入できます。

Server のソースコードと Python SDK は MIT ライセンスですが、モデルファイルと重みはその MIT ライセンスの対象外です。buffalo_l を含む公開 InsightFace モデルパッケージは、InsightFace から別途商用許諾を得ていない限り、原則として非商用の学術研究用途に限定され、セルフホストしても商用モデル利用権は付与されません。

導入時に manifest.json と署名済み MODEL.LICENSE が server/.models に保存されます。verify はパッケージ ID、署名、期限、現在の許諾を確認します。このライセンスは利用条件を示すコンプライアンス証明であり、DRM でもモデルファイルのチェックサムでもありません。

導入したスタックだけを起動します。CPU は http://SERVER:18097/、CUDA は http://SERVER:18098/ を開きます。health が HTTP 応答を確認したら、登録前にダッシュボードまたはシステムでサービス、データベース、モデル、実行 Provider がすべて ready であることを確認します。

CUDA 版は CUDAExecutionProvider を表示しなければなりません。起動時に GPU、Driver、CUDA/cuDNN/ONNX Runtime、実際の検出・認識 Session、Provider 配置、warm-up 推論を検証し、失敗時は CPU へ自動フォールバックせず終了します。

Collections で employees のような安定 ID を作成します。System が表示する search profile を選び、メモリ予算に合う capacity を設定し、まず raw cosine の既定 threshold 0.4 を使います。Collection はモデル ID、digest、埋め込み次元、前処理、検出プロファイルの契約に固定されます。

People でその Collection を選び、鮮明な JPEG、PNG、WebP を 1 枚以上使って Person を登録します。standard review は、利用可能な顔が 1 つで、サイズ、信頼度、鮮明度、明るさ、姿勢の条件を満たすか確認するため、初期設定に適しています。バッチは一部だけ成功する場合があるので、却下理由を個別に確認します。

Search で同じ Collection を選び、その Person の別写真をアップロードします。結果は raw cosine similarity の降順で、Person のスコアは FaceSample 中の最大値です。similarity は確率ではありません。該当なしの空リストは正常な成功応答です。

付属 Compose は隔離された評価向けに認証が無効です。他のユーザーやネットワークから到達可能にする前に認証を有効化し、長くランダムな API Key をシークレット環境へ設定して、選んだスタックを再起動します。Web UI は現在のタブのメモリ内だけに Key を保持できます。

信頼できるリバースプロキシで HTTPS を終端し、広い CORS ではなく必要な origin だけを許可し、入口で rate/body/time limit を設けます。Docker、/data、/models、バックアップへのアクセスを制限し、画像、埋め込み、RTSP 認証情報、API Key をログへ残さないでください。

/data の SQLite が永続的な正本で、メモリ内の厳密検索 index は再生成可能です。Compose はモデルを読み取り専用でマウントし、/data を名前付き volume に保存します。書き込み停止中、または SQLite-safe な snapshot 方式で、データベースと設定済み crop 領域を一緒にバックアップします。

起動したスタックに対応する完全な down コマンドを使います。通常の down は container と network を削除しても database volume を保持します。絶対に -v を追加しないでください。docker compose down -v は名前付きデータ volume を完全に削除します。

health から始め、System、選択した Compose スタックの状態、container log を確認します。CUDA は Driver、GPU、モデル Session、CUDAExecutionProvider、Provider audit、warm-up のいずれかが失敗すると意図的に起動を止め、CPU へ静かに切り替わることはありません。

全応答には x-request-id があり、エラー本文には request_id があります。障害報告では該当時間の log と一緒に保存してください。401 unauthorized は Key 未設定またはローテーション、409 collection_model_mismatch は別モデル契約、422 face_not_found は利用可能な顔が選べなかったことを示します。