Docker で InsightFace Server をデプロイ

どちらかのコマンド一式をリポジトリのルートで実行します。付属の Compose ファイルを直接使い、取得するイメージはその設定に従います。最新のソース一式があれば git clone を省略してください。

起動後、CPU は http://SERVER:18097/、CUDA 12 は http://SERVER:18098/ を開きます。--accept-license はモデルの利用条件への同意を表すため、実行前に確認してください。

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

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

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

新規環境では、上のモデルインストールコマンドに --enable-liveness を追加します。必要なモデルを検証し、初回起動前に有効化設定を保存します。

稼働中の環境では下の対応するコマンドを実行してから再起動します。通常のインストールや models addons install liveness だけでは有効になりません。

インストール成功後に稼働中のサービスを再起動します。up -d だけでは既存コンテナの設定は再読み込みされません。既定では無効で、登録には独立した liveness_on_registration 設定があります。

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

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

対応モデルは buffalo_l、buffalo_m、buffalo_s、buffalo_sc、antelopev2、raccoon_s、raccoon_l です。Server は Raccoon の検出・認識のみを使用し、PrivateFrame verifier は読み込みません。変更時は対応する Collection と再登録またはデータ移行が必要です。

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

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

/data、モデル、server/config を永続化します。書き込み停止中に SQLite と顔画像を一緒にバックアップするか、安全なスナップショットを使ってください。生体情報として保護し、ネットワーク公開前に API キー認証と HTTPS を有効にします。

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

両コンテナは root（0:0）で動作し、単一の書き込み可能な /models と設定ディレクトリを使います。モデルルートと必要な addons/ は自動作成され、ホストの UID/GID や権限設定は不要です。コンテナのルートファイルシステムは読み取り専用です。

書き込みを停止し、データベースと保存済み顔画像をバックアップします。デプロイファイルを更新し、独自設定を統合します。server/config/server.toml、モデル、元のプロジェクト名とデータボリューム名、ポート、API キーを保持してください。以下の対応する Compose に、既存の上書きファイルやプロジェクト名も指定してください。

両イメージを取得して Server を再作成します。restart だけではイメージやマウントは更新されません。状態、実行プロバイダー、既存データ、既知の検索を確認します。同じ認識モデルと embedding 契約ならサンプルは保持されます。モデル変更は別途移行が必要です。SDK も同じ最新ソースから更新します。

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 は利用可能な顔が選べなかったことを示します。

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