Python と InsightFace Server で RGB ライブネス検出を有効にする
認識前にチェックを行い、顔ごとの状態とスコアを取得できます。検出、照合、検索、RTSP の各処理で、結果に応じて認識を制御するモードや観測モードを設定できます。
このガイドで作るもの
Python で顔を解析。認識前のオプションの RGB ライブネス検出と、顔ごとの結果に対応しています。
初期設定では無効です。登録時のチェックは個別に設定します。
始める前に
- python-package/docs/liveness.md を含む更新版 InsightFace 2 のソース一式と、Python 3.10 以降およびパッケージ依存関係。本ガイドはこのソース版を対象とし、古いインストール済みパッケージにはアドオン API がない場合があります。
- 顔の周囲に十分な画像領域があるローカルの input.jpg と、基本モデルおよびライブネスアドオンをインストールできる環境。各モデルに付属する利用条件に従ってください。
- Server：基本モデルを導入済みの、更新された稼働中の Linux 環境。Web インストールには、Server ユーザー（Compose では UID/GID 10001）がマウントされた addons ディレクトリと設定ディレクトリ全体に書き込める必要があります。
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 は英語の説明文で、固定の状態コードとして解析しないでください。
3. Server でインストール、再起動、状態確認
はい。Server Web UI からオプションの RGB ライブネスアドオンをインストールして有効にできます。通常モードはライブネスの結果に応じて認識を制御し、観測モードは結果を報告しながら認識を続行します。初期設定では無効で、登録処理には個別のスイッチがあります。設定と結果の見方については、ライブネス検出ガイドをご覧ください。
System → Liveness を開き、Download and enable after restart を選びます。公開アドオンをダウンロード（または検証済みキャッシュを再利用）し、SHA-256 を検証して、inference.addons と addons.auto_download に ['liveness'] を保存します。インストールと設定の成功を待ってから再起動してください。
リポジトリのルートで再起動コマンドを実行します。CUDA は compose.cuda12.yml を使います。System で 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 restart server