Server mit Docker starten
InsightFace Server auf CPU oder CUDA mit Docker starten, ein lizenziertes Modell installieren, die erste exakte 1:N-Suche ausführen und den Dienst absichern.
Was Sie umsetzen
InsightFace Server bündelt Gesichtserkennung, Vergleich, Registrierung, exakte 1:N-Personensuche, eine mehrsprachige Weboberfläche, REST API, SQLite und lokale Inferenz in einem selbst gehosteten Dienst. Bilder, Embeddings, Modelle und Indizes können in Ihrer eigenen Infrastruktur verbleiben.
Dieser Schnellstart führt von einem vollständigen InsightFace-Checkout über die Modellinstallation bis zu einer funktionierenden Suche. Er behandelt außerdem Modellberechtigung, Authentifizierung, HTTPS, dauerhafte Daten, sicheres Herunterfahren und die Fail-fast-Diagnose für CUDA.
Der Server ist eine datenschutzorientierte Lösung für typische Gesichtserkennungsabläufe, aber kein AWS-Rekognition-kompatibler Ersatz. AWS IAM, SigV4, Regionssemantik, integriertes TLS, Benutzerkonten und RBAC werden nicht bereitgestellt.
Vor dem Start
- Ein vollständiger InsightFace-Checkout auf einem Linux-x86_64-Host mit Docker Engine und Docker Compose.
- Für CUDA 12: eine unterstützte NVIDIA-GPU, NVIDIA Driver und NVIDIA Container Toolkit. CUDA Toolkit, cuDNN, ONNX Runtime, Python und OpenCV werden auf dem Host nicht benötigt.
- Netzwerkzugang zum Abrufen des Containers und Installieren des Modells. Der normale Serverstart kann danach offline erfolgen.
- Eine Berechtigung zur Verarbeitung biometrischer Daten sowie dokumentierte Regeln für Einwilligung, Zugriff, Aufbewahrung, Löschung, Sicherung und Vorfälle.
1. CPU oder CUDA wählen und das Modell installieren
Führen Sie die Befehle im Stammverzeichnis eines vollständigen InsightFace-Checkouts aus und wählen Sie genau einen Compose-Stack. CPU ist der einfachste Evaluationspfad und nutzt Port 18097. CUDA nutzt Port 18098 und benötigt einen kompatiblen NVIDIA Driver sowie das NVIDIA Container Toolkit; CUDA oder cuDNN müssen nicht auf dem Host installiert werden.
Die folgenden Befehle verwenden bewusst die nicht interaktive Option --accept-license und prüfen buffalo_l direkt danach. Führen Sie sie nur aus, wenn Ihre Organisation die Modellbedingungen geprüft und akzeptiert hat. Der Installer unterstützt außerdem buffalo_m, buffalo_sc und antelopev2.
- Turing, Ampere, Ada und Hopper benötigen Driver R535 oder neuer; Blackwell und die RTX-50-Serie benötigen 570.26 oder neuer. Für neue Systeme wird ein stabiler R580 oder neuer empfohlen.
- Öffentliche Images enthalten keine Modelle, Kundendaten, API-Schlüssel oder Produktionskonfiguration.
- Mischen Sie CPU- und CUDA-Compose-Dateien nicht in einer Bereitstellung; Images, Ports, Provider und benannte Daten-Volumes sind getrennt.
mkdir -p server/.models
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 verify buffalo_lmkdir -p server/.models
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 \
run --rm models verify buffalo_l2. Die Grenze der Modelllizenz verstehen
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.
- Ohne --accept-license zeigt der Installer die Bedingungen an und beendet sich ohne Download.
- Bewahren Sie Modell, Manifest und Lizenz zusammen auf und binden Sie /models im Normalbetrieb nur lesbar ein.
- Kontaktieren Sie InsightFace vor kommerzieller Nutzung oder wenn der Einsatzzweck nicht eindeutig durch die öffentlichen Bedingungen gedeckt ist.
3. Dienst starten und Bereitschaft prüfen
Starten Sie nur den installierten Stack. Öffnen Sie für CPU http://SERVER:18097/ oder für CUDA http://SERVER:18098/. Nach erfolgreichem Health-Aufruf prüfen Sie vor der Registrierung unter Übersicht oder System, ob Dienst, Datenbank, Modell und Ausführungs-Provider bereit sind.
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.
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/healthdocker compose -f server/deploy/compose.cuda12.yml up -d
curl -fsS http://127.0.0.1:18098/v1/health4. Den ersten Ablauf Collection → Person → Search abschließen
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-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.
- Originaluploads werden standardmäßig nicht gespeichert. Optional wird nur ein auf 112×112 skaliertes JPEG des Begrenzungsrahmens gespeichert, nicht das Original oder der ausgerichtete Erkennungseingang.
- Akzeptierte Samples werden in SQLite bestätigt und vor der Erfolgsantwort dem exakten In-Memory-Index hinzugefügt. Nach einem Neustart wird er aus SQLite neu aufgebaut.
- Kein Gesicht ist bei Detect ein gültiges leeres Ergebnis; Compare liefert 422 face_not_found, wenn auf einer Seite kein nutzbares Gesicht gewählt wurde.
5. Dienst vor der Netzwerkfreigabe absichern
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.
- Phase eins verwendet einen undifferenzierten API-Schlüssel; dies ist keine Multi-Tenant-Autorisierung und bietet weder Benutzerkonten noch RBAC.
- Ein späterer Start desselben Daten-Volumes mit einem anderen INSIGHTFACE_API_KEY rotiert den aktiven Schlüssel absichtlich.
- Der Server besitzt weder integriertes TLS noch eine Compliance-Schicht; rechtmäßige Verarbeitung und Betriebskontrollen liegen beim Betreiber.
export INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cpu.yml up -dexport INSIGHTFACE_AUTH_ENABLED=true
export INSIGHTFACE_API_KEY='replace-with-a-long-random-secret'
docker compose -f server/deploy/compose.cuda12.yml up -d6. Daten erhalten, sichern und sicher stoppen
SQLite unter /data ist die dauerhafte Quelle der Wahrheit; exakte In-Memory-Suchindizes sind ersetzbar. Compose bindet Modelle nur lesbar ein und speichert /data in einem benannten Volume. Sichern Sie SQLite und konfigurierten Crop-Speicher gemeinsam bei gestoppten Schreibzugriffen oder mit einer SQLite-sicheren Snapshot-Methode.
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.
- Erstellen Sie vor Upgrades einen sicheren Snapshot, behalten Sie /models samt Lizenzdateien und testen Sie das neue Image zuerst mit einer Datenkopie.
- Prüfen Sie danach Migrationen, /v1/health, Modellvertrag und eine bekannte Suche.
- Das Löschen eines FaceSample entfernt Embedding und optionalen Crop; eine nicht leere Collection erfordert eine ausdrückliche Force-Bestätigung.
docker compose -f server/deploy/compose.cpu.yml downdocker compose -f server/deploy/compose.cuda12.yml down7. Start- und Anfragefehler diagnostizieren
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.
- Prüfen Sie unter System, ob CPUExecutionProvider oder CUDAExecutionProvider zur gewählten Compose-Datei passt.
- Prüfen Sie das verifizierte Paket und die signierte Lizenz in server/.models sowie den schreibgeschützten /models-Mount.
- Beheben Sie bei CUDA Host-Driver, GPU-Sichtbarkeit oder NVIDIA Container Toolkit, statt einen CPU-Fallback zu erwarten.
curl -fsS http://127.0.0.1:18097/v1/health
docker compose -f server/deploy/compose.cpu.yml ps
docker compose -f server/deploy/compose.cpu.yml logs --tail=200 servercurl -fsS http://127.0.0.1:18098/v1/health
docker compose -f server/deploy/compose.cuda12.yml ps
docker compose -f server/deploy/compose.cuda12.yml logs --tail=200 serverBenötigen Sie Hilfe beim Produktions-Deployment?
Kontaktieren Sie InsightFace für Modelllizenzen, Runtime-Optimierung und Deployment-Support für Ihre Zielhardware.
Enterprise-Anfrage senden