← Zurück zu den Leitfäden
InsightFacePythonInsightFace ServerOptionale RGB-Lebenderkennung

Optionale RGB-Lebenderkennung in Python und InsightFace Server aktivieren

Ergänzen Sie Prüfungen vor dem Identitätsabgleich und erhalten Sie Status und Bewertungen für jedes Gesicht. Konfigurieren Sie eine Freigabe anhand des Lebendergebnisses oder den Beobachtungsmodus für Erkennung, Vergleich, Suche und RTSP-Abläufe.

•5 Min. Lesezeit

Was Sie umsetzen

Gesichtsanalyse in Python mit optionaler RGB-Lebenderkennung vor dem Identitätsabgleich und Ergebnissen für jedes Gesicht.

Standardmäßig deaktiviert. Prüfungen bei der Registrierung werden separat eingestellt.

Vor dem Start

  • Der aktualisierte InsightFace-2-Quellcode mit python-package/docs/liveness.md sowie Python 3.10+ und installierten Paketabhängigkeiten. Diese Anleitung bezieht sich auf diesen Quellstand; ältere installierte Pakete bieten die Addon-API möglicherweise noch nicht.
  • Eine lokale input.jpg mit einem Gesicht und ausreichendem Bildbereich darum sowie Zugriff zur Installation des Basismodells und des Liveness-Addons. Beachten Sie die jeweiligen Modellbedingungen.
  • Für Server: eine aktualisierte, laufende Linux-Installation mit installiertem Basismodell. Für die Web-Installation benötigt der Server-Benutzer (UID/GID 10001 in Compose) Schreibzugriff auf das eingebundene Addon-Verzeichnis und das gesamte Konfigurationsverzeichnis.

1. Liveness in Python ausdrücklich aktivieren

Installieren Sie vom Stammverzeichnis des aktualisierten Repositorys aus das Python-Paket in Ihrer aktiven virtuellen Umgebung. Legen Sie input.jpg vor dem Start im Arbeitsverzeichnis ab. Das CPU-Beispiel wählt Erkennung und Identifizierung aus; addons=['liveness'] aktiviert das separate Liveness-Modell.

Beim ersten Aufruf können fehlende Modelle heruntergeladen werden. Das Addon liegt unter ~/.insightface/addons/liveness.onnx; vor dem Laden wird SHA-256 geprüft. Die Datei allein aktiviert keine Prüfung: Geben Sie addons=['liveness'] ausdrücklich an. Ohne addons bleibt Liveness aus.

Aus dem aktualisierten Quellcode installieren
cd python-package
python -m pip install .
CPU-Beispiel mit Liveness-Ergebnissen je Gesicht
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. Ergebnisse lesen und die Erkennungsregel wählen

Im Modus normal erfolgt die Identifizierung nur bei is_live=True. Andere Gesichter bleiben mit Detektionsergebnissen, aber ohne Embedding in der Liste. observe setzt die Identifizierung auch bei negativer Liveness-Klassifikation oder abgelehnter Eingabe fort und behält die Ergebnisse. Modell-, Ausrichtungs- und Inferenzfehler lösen in beiden Modi Ausnahmen aus.

  • status='ok': is_live ist True oder False und live_score eine Zahl in [0, 1]. Der Standardschwellenwert beträgt 0.8; Gleichheit genügt. Validieren Sie den Schwellenwert mit repräsentativen Eingaben und dem Ausführungsanbieter Ihrer Installation.
  • status='input_rejected': is_live und live_score sind None. Das bedeutet zu wenig Quellbildfläche um das ausgerichtete Gesicht, keine Spoofing-Klassifikation. Zentrieren Sie das Gesicht, vergrößern Sie den Kameraabstand oder verwenden Sie einen weniger engen Zuschnitt. reason erläutert den Grund.
  • Ohne ausgewähltes Addon ist face.liveness None; ohne erkannte Gesichter lautet das Ergebnis []. Verwenden Sie status und is_live in der Programmlogik. Der reason-Text in Python/API ist Englisch und kein stabiler Statuscode.

3. Im Server installieren, neu starten und prüfen

Ja. Installieren und aktivieren Sie die optionale Erweiterung zur RGB-Lebenderkennung über die Server-Weboberfläche. Im Normalmodus hängt die Freigabe des Identitätsabgleichs vom Lebendergebnis ab; der Beobachtungsmodus meldet Ergebnisse, während der Abgleich weiterläuft. Die Lebenderkennung ist standardmäßig deaktiviert, und die Registrierung hat einen separaten Schalter. Einrichtung und Ergebnisinterpretation sind in der Anleitung beschrieben.

Öffnen Sie System → Liveness und wählen Sie Download and enable after restart. Die Aktion lädt das veröffentlichte Addon herunter oder nutzt einen verifizierten Cache, prüft SHA-256 und speichert ['liveness'] in inference.addons und addons.auto_download. Starten Sie erst nach erfolgreicher Installation und Speicherung neu.

Führen Sie den Neustartbefehl im Repository-Stamm aus; für CUDA verwenden Sie compose.cuda12.yml. Prüfen Sie unter System: enabled=true und restart_required=false. installed bezeichnet die geprüfte Datei, configured_enabled die Einstellung für den nächsten Start. Keiner dieser beiden Werte allein bestätigt die laufende Inferenz. Geänderte Mounts erfordern eine Neuerstellung des Containers.

Liveness ist standardmäßig aus. Die Web-Aktion ändert die Registrierung nicht; liveness_on_registration=false bleibt der Standard. Setzen Sie diesen Wert separat auf true, um normal/observe auch bei der Registrierung anzuwenden. Zum Deaktivieren speichern Sie leere Listen für inference.addons und addons.auto_download und starten neu.

Gespeicherte Einstellungen auf die bestehende CPU-Installation anwenden
docker compose -f server/deploy/compose.cpu.yml restart server

Benötigen Sie Hilfe beim Produktions-Deployment?

Kontaktieren Sie InsightFace für Modelllizenzen, Runtime-Optimierung und Deployment-Support für Ihre Zielhardware.

Enterprise-Anfrage senden