InsightFace Server mit Docker starten

Führen Sie einen der Blöcke im Stammverzeichnis des Repositorys aus. Die mitgelieferte Compose-Datei wird direkt verwendet und legt das zu ladende Image fest. Bei einem aktuellen Checkout können Sie git clone überspringen.

Öffnen Sie danach http://SERVER:18097/ für CPU oder http://SERVER:18098/ für CUDA 12. --accept-license akzeptiert die Modellbedingungen; prüfen Sie diese vor der Ausführung.

Erstellen Sie unter Collections eine stabile ID wie employees. Wählen Sie ein von System angebotenes Suchprofil, setzen Sie die Kapazität passend zum Speicherbudget und beginnen Sie mit dem Standardwert 0,4 für den rohen Kosinus-Schwellenwert. Eine Collection ist an Modellidentität, Digest, Embedding-Dimension, Vorverarbeitung und Erkennungsprofil gebunden.

Wählen Sie unter People die Collection und registrieren Sie eine Person mit mindestens einem klaren JPEG-, PNG- oder WebP, BMP-Bild. standard review ist ein sinnvoller Ausgangspunkt: Es verlangt genau ein nutzbares Gesicht und prüft Größe, Konfidenz, Schärfe, Helligkeit und Pose. Bei Stapeln sind Teilerfolge möglich; prüfen Sie deshalb jeden Ablehnungsgrund.

Wählen Sie unter Search dieselbe Collection und laden Sie ein anderes Foto der Person hoch. Ergebnisse sind nach roher Kosinusähnlichkeit sortiert; der Person-Score ist der beste Score ihrer FaceSamples. Ähnlichkeit ist keine Wahrscheinlichkeit. Eine erfolgreiche Suche ohne Treffer liefert eine leere Liste.

Ergänzen Sie bei einer neuen Installation den Modellinstallationsbefehl um --enable-liveness. Die benötigten Modelle werden geprüft und die Aktivierung vor dem ersten Start gespeichert.

Bei einem laufenden Dienst verwenden Sie den passenden Befehl unten und starten ihn danach neu. Eine normale Installation und models addons install liveness aktivieren die Funktion nicht.

Starten Sie den laufenden Dienst nach erfolgreicher Installation neu. up -d allein lädt gespeicherte Einstellungen nicht erneut. Die Funktion ist standardmäßig aus; für die Registrierung gilt der separate Schalter liveness_on_registration.

Der Server-Quellcode und das Python SDK stehen unter der MIT-Lizenz; Modelldateien und Gewichte fallen jedoch nicht unter diese Lizenz. Öffentliche InsightFace-Modellpakete einschließlich buffalo_l sind ohne separate kommerzielle Genehmigung von InsightFace grundsätzlich auf nichtkommerzielle akademische Forschung beschränkt; Self-Hosting gewährt keine kommerziellen Modellrechte.

Die Installation schreibt manifest.json und die signierte MODEL.LICENSE nach server/.models. verify prüft Paketidentität, Signatur, Gültigkeitsdaten und aktuelle Berechtigung. Die Lizenz beschreibt Modell und erlaubte Nutzung; sie ist ein Compliance-Nachweis, kein DRM und keine Prüfsumme der Modelldateien.

Unterstützt werden buffalo_l, buffalo_m, buffalo_s, buffalo_sc, antelopev2, raccoon_s und raccoon_l. Server nutzt nur Raccoons Erkennung und Detektion, ohne PrivateFrame-Verifier. Ein Modellwechsel benötigt eine passende Collection sowie erneute Registrierung oder Datenmigration.

Die mitgelieferten Compose-Dateien deaktivieren die Authentifizierung für isolierte Tests. Bevor andere Benutzer oder Netze den Dienst erreichen können, aktivieren Sie sie, hinterlegen einen langen zufälligen API-Schlüssel in der Secret-Umgebung und starten den gewählten Stack neu. Die Weboberfläche kann den Schlüssel nur im Speicher des aktuellen Tabs halten.

Beenden Sie HTTPS an einem vertrauenswürdigen Reverse Proxy, erlauben Sie nur benötigte Origins statt weitem CORS, setzen Sie Rate-, Body- und Zeitlimits am Rand und beschränken Sie den Zugriff auf Docker, /data, /models und Sicherungen. Protokollieren Sie niemals Bilder, Embeddings, RTSP-Zugangsdaten oder API-Schlüssel.

Speichern Sie /data, Modelle und server/config dauerhaft. Sichern Sie SQLite und Gesichtsausschnitte gemeinsam ohne Schreibzugriffe oder mit einem SQLite-sicheren Snapshot. Schützen Sie alles als biometrische Daten und aktivieren Sie vor Netzwerkfreigabe API-Schlüssel und HTTPS.

Verwenden Sie den vollständigen down-Befehl des gestarteten Stacks. Normales down entfernt Container und Netzwerk, erhält aber das benannte Daten-Volume. Hängen Sie niemals -v an: docker compose down -v löscht dieses Volume dauerhaft.

Beide Container laufen als root (0:0) mit einem beschreibbaren /models-Mount und Konfigurationsverzeichnis. Modellverzeichnisse und benötigte addons/ werden automatisch erstellt. Host-UID/GID und manuelle Rechtevergabe entfallen. Das Root-Dateisystem des Containers bleibt schreibgeschützt.

Stoppen Sie Schreibzugriffe und sichern Sie Datenbank und Gesichtsausschnitte. Aktualisieren Sie die Bereitstellungsdateien und übernehmen Sie eigene Einstellungen. Behalten Sie server/config/server.toml, Modelle, ursprüngliche Projekt- und Volume-Namen, Ports und API-Schlüssel. Verwenden Sie die passende Compose-Datei und ergänzen Sie gegebenenfalls bestehende Override-Dateien und den Projektnamen.

Laden Sie beide Images und erstellen Sie Server neu. restart übernimmt keine neuen Images oder Mounts. Prüfen Sie Status, Ausführungsanbieter, vorhandene Daten und eine bekannte Suche. Bei gleichem Modell und Embedding-Vertrag bleiben die Samples erhalten; ein Modellwechsel erfordert eine eigene Migration. Aktualisieren Sie auch das SDK aus demselben aktuellen Checkout.

Beginnen Sie mit dem Health-Endpunkt und prüfen Sie anschließend System, Containerstatus und Logs des gewählten Compose-Stacks. Unter CUDA ist ein Startabbruch beabsichtigt, wenn Driver, GPU, Modell-Sessions, CUDAExecutionProvider, Provider-Audit oder Warm-up fehlschlagen; es gibt keinen stillen CPU-Fallback.

Jede Antwort enthält x-request-id, Fehlertexte außerdem request_id. Bewahren Sie diese ID zusammen mit dem passenden Log-Zeitraum auf. 401 unauthorized bedeutet meist fehlenden oder rotierten Schlüssel, 409 collection_model_mismatch einen anderen Modellvertrag und 422 face_not_found, dass kein nutzbares Gesicht gewählt wurde.

Eine CUDA-Instanz muss CUDAExecutionProvider melden. Beim Start werden GPU, Driver, CUDA/cuDNN/ONNX Runtime, echte Detektor- und Erkennungs-Sessions, Provider-Platzierung und Warm-up-Inferenz geprüft. Bei einem Fehler beendet sich der Dienst, statt still auf CPU zurückzufallen.