Python と InsightFace Server で RGB ライブネス検出を有効にする
認識前にチェックを行い、顔ごとの状態とスコアを取得できます。検出、照合、検索、RTSP の各処理で、結果に応じて認識を制御するモードや観測モードを設定できます。
このガイドで作るもの
顔の処理には FaceAnalysis、人物検出・顔照合・身体 ReID の組み合わせには PersonAnalysis を利用できます。
初期設定では無効です。登録時のチェックは個別に設定します。
始める前に
- python-package/docs/liveness.md を含む更新版 InsightFace 2 のソース一式と、Python 3.10 以降およびパッケージ依存関係。本ガイドはこのソース版を対象とし、古いインストール済みパッケージにはアドオン API がない場合があります。
- 顔の周囲に十分な画像領域があるローカルの input.jpg と、基本モデルおよびライブネスアドオンをインストールできる環境。各モデルに付属する利用条件に従ってください。
- Docker ガイドのデプロイと既存設定を使用します。コンテナは root で動作し、モデルと設定は書き込み可能です。CLI は Server の初回起動前にも使用できます。
1. Python でライブネス検出を明示的に実行
更新されたリポジトリのルートから、使用中の仮想環境に Python パッケージをインストールします。実行前に input.jpg を作業ディレクトリに置いてください。CPU の例は検出と認識を選択し、addons=['liveness'] で独立したライブネスモデルを有効にします。
初回実行時に不足しているモデルをダウンロードする場合があります。アドオンは ~/.insightface/addons/liveness.onnx に保存され、読み込み前に SHA-256 を検証します。ファイルの配置だけでは有効になりません。addons=['liveness'] を明示し、addons を省略すると無効のままです。
cd python-package
python -m pip install .import cv2
from insightface.app import FaceAnalysis
image_bgr = cv2.imread("input.jpg")
if image_bgr is None:
raise FileNotFoundError("input.jpg")
app = FaceAnalysis(
name="buffalo_l",
allowed_modules=["detection", "recognition"],
addons=["liveness"],
liveness_mode="normal",
liveness_threshold=0.8,
providers=["CPUExecutionProvider"],
)
app.prepare(ctx_id=-1, det_size=(640, 640))
for face in app.get(image_bgr):
print(face.liveness)
if face.liveness is not None:
print(
face.liveness.status,
face.liveness.is_live,
face.liveness.live_score,
)2. 結果を読み取り、認識方針を選ぶ
normal モードでは is_live が True の場合のみ認識します。それ以外の顔も検出結果付きでリストに残りますが、embedding はありません。observe モードでは、非ライブ判定や入力拒否でもライブネス結果を保持して認識を続けます。モデル、位置合わせ、推論の障害は、どちらのモードでも例外になります。
- status='ok'：is_live は True または False、live_score は [0, 1] の数値です。初期しきい値は 0.8 で、等しい場合も通過します。導入先の実行プロバイダーと代表的な入力を使ってしきい値を検証してください。
- status='input_rejected'：is_live と live_score は None です。位置合わせ後の顔の周囲に元画像の領域が不足していることを表し、偽装の判定ではありません。顔を中央に寄せる、カメラから離れる、余白の多い画像を使うなどで調整できます。reason に説明が入ります。
- アドオン未選択では face.liveness は None、顔が検出されなければ [] です。プログラムでは status と is_live で判断してください。Python/API の reason は英語の説明文で、固定の状態コードとして解析しないでください。
任意：RGB ライブネス検出を有効化
はい。モデルインストール時に --enable-liveness を追加するか、Web UI のシステム画面で有効化し、起動または再起動します。normal は認識を制御し、observe は結果を記録して認識を続けます。既定では無効で、登録には独立した設定があります。
新規環境では、Docker デプロイガイドのモデルインストールコマンドに --enable-liveness を追加します。必要なモデルを検証し、初回起動前に有効化設定を保存します。
稼働中の環境では下の対応するコマンドを実行してから再起動します。通常のインストールや models addons install liveness だけでは有効になりません。
Web UI の「システム → ライブネス検出」から、ダウンロードして再起動後に有効化する操作も利用できます。Web と CLI はモデルを検証し、他の設定を保持して両リストに liveness を追加します。ダウンロード失敗時は有効化されません。設定保存の成功を待ってください。
新規環境ではインストール後に起動し、稼働中なら下の対応する CPU/CUDA コマンドで再起動します。システムで enabled=true、restart_required=false を確認します。installed は検証済みファイル、configured_enabled は保存設定です。マウント変更時はコンテナを再作成します。
初期設定では無効です。Web 操作は登録設定を変更せず、liveness_on_registration=false が維持されます。登録時にも設定済みの normal/observe 方針を適用するには、別途 true にします。無効にするには inference.addons と addons.auto_download を空のリストで保存し、再起動します。
docker compose -f server/deploy/compose.cpu.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cuda12.yml run --rm models install buffalo_l --accept-license --enable-livenessdocker compose -f server/deploy/compose.cpu.yml restart serverdocker compose -f server/deploy/compose.cuda12.yml restart server