言語: English · 中文 · 日本語 · Deutsch · Español · Français · Русский · Português · 한국어
GPU 1基で50M+の顔ベクトル。INT8特徴量子化による高速検索を、実質的な精度低下なく実現。
Web UI、分かりやすい REST API、SQLite、ローカル CPU または NVIDIA GPU 推論を1つのコンテナで提供するセルフホスト型顔認識サーバーです。
画像をアップロード -> 検出、生体検知、比較、登録、検索
モデルライセンス: 公開 InsightFace 学習済みモデルは通常、非商用研究用途に 限定されます。商用利用には個別の許諾が必要です。 InsightFace 公式サイトからお問い合わせください。
InsightFace Server は、管理下のインフラで一般的な顔認識を行うための、AWS Rekognition よりシンプルでプライバシー重視の選択肢です。画像、Embedding、 モデル、索引をネットワーク内に保持できます。AWS 互換製品ではなく、SigV4、 IAM、Region、AWS リソース意味論は実装しません。
現在のリリース: 0.3.1、Linux x86_64。
| Runtime | Image |
|---|---|
| CPU | ghcr.io/deepinsight/insightface-server:0.3.1-cpu |
| NVIDIA GPU | ghcr.io/deepinsight/insightface-server:0.3.1-cuda12 |
移動タグ cpu と cuda12 は各 Runtime の最新安定版を示します。曖昧な
latest は提供しません。リリース方針は
Maintainer Guide — Englishを参照してください。
0.3.1 のデプロイ更新: Server とモデルインストーラーを root で実行し、
モデルを単一の書き込み可能なマウントにまとめ、ダウンロード時に addon ディレクトリを
自動作成します。ホスト UID/GID や共有グループの設定は不要です。イメージタグと
Compose の両方を更新し、既存のモデル、設定、データを保持してください。0.3.0 から
Raccoon のモデル記述、生体検知、BMP 入力に対応し、API/SDK の model_version を
廃止しています。アップグレード手順を参照してください。
- SCRFD 検出、5点ランドマーク、アラインメント、ArcFace Embedding、L2 normalization、元の cosine similarity、厳密な 1:N Person 検索。
- 複数解像度の候補を統合して1回の NMS を実行し、
largestとcenter_largestの単一顔選択をサポート。 Collection -> Person -> FaceSample、モデルに固定された Collection、 複数画像登録、部分成功、metadata、明確な拒否理由。- 登録
review_modeはoff、standard、strict。external_trustedの事前計算済み Embedding も利用可能。 - GPU 厳密検索は FP32、FP16、BF16、INT8 のベクトル保存に対応。
- Dashboard、Collections、People、Detect、Compare、Search、RTSP Monitor、 System、Help を備えた多言語 Web UI。
/v1配下の31個の snake_case REST operation。保護された/v1/embeddingsと軽量 Python SDK を含みます。- 有界メモリイベント、複数クライアント、任意の
preview.mjpegを備えた サーバー側 RTSP Monitor。ブラウザを閉じても監視は停止しません。 - SQLite を永続的な正本とし、再構築可能なメモリ内厳密索引、単一の書き込み可能なモデルマウントと設定ディレクトリ、永続
/data、migration、health check、CPU fallback を許さない CUDA 起動検証を提供。 - JPEG、PNG、WebP、BMP をサポートし、元のアップロード画像は既定で保持しません。
生体検知は既定で無効です。server/config/server.toml の inference.addons = [] と addons.auto_download = [] が初期値です。システム → 生体検知 でモデルをダウンロード・検証すると次回起動の設定が保存され、手動再起動で有効になります。検証済みキャッシュは再利用します。起動時にはダウンロードせず、有効な addon のモデルがなければインストール方法を示して起動を停止します。評価済みの顔は基本の3項目 status、is_live、live_score を返し、input_rejected の場合だけユーザー向け説明 reason が追加されます。既定モードは normal、登録時は既定で省略します(liveness_on_registration = false)。設定、Web 権限、更新手順を参照してください。
1基の NVIDIA GeForce RTX 5090(32,607 MiB)で、ネイティブ CUDA exact-flat index は INT8 使用時に 58.9M 個の512次元画像ベクトルを 格納できました。
| GPU データ型 | 最大画像ベクトル数 | 10M Top-5 p50 | 10M serial QPS |
|---|---|---|---|
| FP32 | 15.8M | 12.84 ms | 77.85 |
| FP16 | 30.7M | 6.83 ms | 146.32 |
| BF16 | 30.7M | 6.83 ms | 146.33 |
| INT8 | 58.9M | 3.84 ms | 260.81 |
INT8 は FP32 に対し、実測容量 3.73 倍、10M Top-5 throughput 3.35 倍でした。 数値は同一の RTX 5090、Driver 580.105.08、CUDA 12.9 による GPU 測定です。容量は ONNX モデルや Server 負荷を含まない独立ネイティブ索引の 上限です。速度は正確に 10M 個の画像ベクトルを対象に、GPU 常駐 Top-5 全件厳密走査、同時1 query、warm-up 10回と測定100回で計測しました。 索引は各保存表現内では厳密ですが、量子化により FP32 から score が変わる 場合があります。本番ではモデル、request、並行処理、索引再構築、allocator のための VRAM 余裕が必要です。
ICCV21-MFR の多人種(MR)テストセットで、
MR-ALL の全組合せ 1:1 プロトコルと FAR 1e-6 を用いてネイティブ検索
profile を評価しました。すべての profile は Server API で一度だけ抽出し
L2 normalization を施した同一の512次元 buffalo_l embedding を使用し、
ベクトルの保存形式と検索時の計算表現だけを変更しています。
| 検索 profile | FAR 1e-6 での MR-ALL | Cosine threshold | FP32 との差 |
|---|---|---|---|
| FP32 | 91.249107% | 0.407787 | — |
| FP16 | 91.249197% | 0.407787 | +0.000090ポイント |
| BF16 | 91.248502% | 0.407787 | -0.000605ポイント |
| INT8 | 91.248005% | 0.407739 | -0.001102ポイント |
このベンチマークでは INT8 に実質的な精度低下はありません。 challenge と同じ小数第2位までの表示では FP32 と INT8 の MR-ALL はともに 91.25% で、丸め前の差もわずか0.0011ポイントです。同時に、上記の実測 容量3.73倍と 10M Top-5 throughput 3.35倍の利点を維持します。この比較は ベクトル保存・検索精度の評価であり、INT8 モデル推論の評価ではありません。
必要条件:
- Docker Engine と Docker Compose を備えた Linux x86_64。
- CUDA 版は、対応 NVIDIA GPU、NVIDIA Driver、NVIDIA Container Toolkit。
ホストに Python、OpenCV、ONNX Runtime、CUDA Toolkit、cuDNN は不要です。 公開 Image にモデル、顧客データ、API Key、本番設定は含まれません。
InsightFace リポジトリ全体の checkout で、server/.models にモデルを
インストールします。
リポジトリのルートで実行し、server/config/server.toml を用意してください。Server とモデルインストーラーは root(0:0)で実行します。Compose は server/.models がなければ作成し、単一の書き込み可能な /models としてマウントします。addons/ は addon のダウンロードを要求したときに作成されます。UID/GID の export、addon ディレクトリの手動作成、権限設定は不要です。
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 install buffalo_l --accept-license --enable-livenessServer を先に起動する必要はありません。新規環境では次の up -d で生体検知が有効になります。すでに実行中の場合は docker compose -f server/deploy/compose.cpu.yml restart server が必要で、up -d だけでは保存済み設定を再読込しません。CUDA では compose.cuda12.yml を使います。
モデルツールは buffalo_l、buffalo_m、buffalo_s、buffalo_sc、
antelopev2、raccoon_s、raccoon_l の全 7 パッケージに対応します。
manifest.json と署名済み MODEL.LICENSE を作成し、models verify で
検証できます。モデル条件は Server ソースライセンスとは別です。
CPU を起動:
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/health代わりに CUDA 12 を起動:
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 up -d
curl -fsS http://127.0.0.1:18098/v1/healthCPU は http://SERVER:18097/、CUDA は http://SERVER:18098/ を開きます。
Collection を作成し、Person に1枚以上の画像を登録して、別の画像で検索します。
データを保持するには -v を付けずに docker compose ... down します。
同梱 Compose は隔離評価向けに認証を既定で無効にします。他のユーザーや ネットワークへ公開する前に次を設定します。
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='十分に長いランダムな秘密へ置換'
docker compose -f server/deploy/compose.cpu.yml up -d完全な初回手順は初心者向けユーザーガイドを参照してください。
完全なローカルソースディレクトリから直接ビルドできます。未コミットの変更が
あっても、.git ディレクトリがなくても構いません。Git のコミットやプッシュは
ビルドの前提条件ではありません。
Dockerfile は server/ と python-package/insightface/ の選択された推論
モジュールをコピーするため、完全なソースディレクトリが build context です。
CPU:
make -C server build-cpu
docker compose -f server/deploy/compose.cpu.yml \
run --rm --pull never models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml \
up -d --no-build --pull neverCUDA 12:
make -C server build-cuda12
docker compose -f server/deploy/compose.cuda12.yml \
run --rm --pull never models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cuda12.yml \
up -d --no-build --pull never--pull never によりローカル build の Image を使用します。build 時には固定済み
base image と依存を、モデル install 時には許諾したモデル package を別途
download します。
- Similarity は確率ではなく元の cosine 値です。Threshold は
0.0..1.0、 既定は0.4。 - Collection はモデルと embedding contract に固定されます。不一致でも表示は
できますが、登録/検索は
collection_model_mismatchを返します。 - 起動時 Detection Profile は新しい Collection にコピーされ、その後の Collection Profile は独立して変更でき、次の Request から有効になります。
- 任意の顔保存は 112x112 にリサイズした bounding-box JPEG crop であり、 元画像や認識用のアライン済み入力ではありません。既定は無効です。
- SQLite commit が正本です。登録/削除の成功応答前に索引を同期し、再起動後は SQLite から再構築します。
- Response は
x-request-idを持ち、一覧 API は不透明な署名 cursor を使います。
正確な field、default、lifecycle、failure behavior は以下の詳細文書が正本です。
主な API group:
- System:
/v1/health、/v1/system、/v1/models。 - Stateless face:
/v1/detect、/v1/compare、/v1/embeddings。 - Collection、Person、FaceSample CRUD。
- Collection の Person search。
- RTSP Monitor の設定、state、events、preview。
全 parameter、response、error、example は
REST API 利用ガイドを参照してください。Interactive OpenAPI
は /docs に残ります。
from insightface_server import Client
with Client("http://localhost:18097", api_key=None) as client:
faces = client.detect("photo.jpg")
matches = client.search("employees", "unknown.jpg", limit=5)SDK のインストール、入力形式、メソッド、完全な手順は ユーザーガイドを参照してください。
顔画像と Embedding は生体情報です。ネットワーク公開時は認証を有効にし、信頼する reverse proxy で HTTPS を終端し、Docker と volume へのアクセスを制限し、広い CORS を無効のまま保ち、backup、retention、deletion、consent、incident response を定義してください。画像、Embedding、RTSP credential、API Key を log に 記録しないでください。
Server は TLS、ユーザーアカウント、RBAC、cloud IAM、法令遵守レイヤーを内蔵 しません。運用とセキュリティはユーザーガイドを 参照してください。
AWS/CompreFace 互換、CUDA 11、Jetson、ARM64、Windows Container、 TensorRT、Kubernetes、分散 Worker、Monitor event の永続化、録画/NVR、 deepfake、属性分析は実装しません。
- ユーザーガイド — インストール、設定、モデル、 Web UI、SDK、GPU、セキュリティ、バックアップ、トラブルシュート。
- REST API 利用ガイド — 全公開 Endpoint、Field、挙動、 Result、Error、Pagination、Example。
- Maintainer Guide — English — Architecture、 Search 内部、Test、Contribution、Container Release。
GitHub と Web UI Help は同じローカライズ済み User Guide/API Guide Markdown を読み込み、表示方法だけが異なります。
ライセンスの唯一の入口は LICENSING.md です。Server ソースと Python SDK は MIT License ですが、この宣言はモデルファイル、 モデル重み、データセット、第三者コンポーネントには適用されません。公開 InsightFace 学習済みモデルは、別途許諾がない限り通常は非商用研究用途に 限定されます。商用ライセンス: https://www.insightface.ai。


