Gesichtserkennung

Die “Gesichtserkennung” ist eine BETA-Funktion des Archiv-Plugins. Sie erkennt Gesichter in hochgeladenen Bildern automatisch, schlägt Zuordnungen zu bereits benannten Personen vor und macht Datensätze über “wer ist darauf zu sehen” durchsuchbar. Die Erkennung selbst läuft vollständig lokal in einem separaten Docker-Container — es werden keine Bilder oder Daten an externe Dienste übertragen.

Die Funktion folgt konsequent dem Prinzip “vorschlagen, nie automatisch anwenden”: Ein erkanntes Gesicht wird nie eigenständig einer Person zugewiesen. Das letzte Wort hat immer ein Mensch, der eine Zuordnung explizit bestätigt.

Voraussetzungen

Damit die Gesichtserkennung funktioniert, muss zusätzlich zum eigentlichen CrispyCMS-Container der separate Gesichtserkennungs-Dienst laufen (siehe Der Gesichtserkennungs-Dienst weiter unten) und in den Archiv-Einstellungen aktiviert sein:

Einstellungen → Archiv → Gesichtserkennung

• Gesichtserkennung aktivieren — globaler Schalter für die gesamte Funktion.
• Endpunkt — die Adresse des Gesichtserkennungs-Dienstes (z. B. http://archive-face-recognition:8000).
• Batch-Größe der Warteschlange — wie viele wartende Dateien pro Minute verarbeitet werden.
• Sperre als veraltet markieren nach (Minuten) — verhindert, dass ein abgestürzter Verarbeitungslauf die Warteschlange dauerhaft blockiert.
• Ähnlichkeits-Schwellenwert — wie ähnlich sich zwei Gesichter sein müssen, um als “vermutlich dieselbe Person” vorgeschlagen zu werden. Ein niedrigerer Wert liefert strengere, ein höherer Wert großzügigere Vorschläge.

Ohne einen erreichbaren Gesichtserkennungs-Dienst bleibt der Schalter zwar aktivierbar, es werden aber keine neuen Erkennungen durchgeführt — bereits erkannte Gesichter und benannte Personen bleiben davon unberührt.

Wie die Erkennung abläuft

1. Automatisch beim Hochladen. Jedes neu hochgeladene Bild wird — sofern die Funktion aktiviert ist — automatisch in eine Warteschlange eingereiht.
2. Verarbeitung im Hintergrund. Ein Cron-Job verarbeitet die Warteschlange minütlich und fragt dabei den lokalen Gesichtserkennungs-Dienst ab. Solange eine Datei noch verarbeitet wird, zeigt der Reiter “Gesichter” einer Datei einen Lade-Indikator; das gilt auch direkt nach dem Hochladen oder nach einem manuellen “Neu scannen”.
3. Ergebnis. Für jedes erkannte Gesicht wird ein zugeschnittener Ausschnitt sowie eine Positionsmarkierung (Rahmen) auf dem Originalbild gespeichert — sichtbar direkt im Bild-Vorschaubild sowie in der Vollbildansicht.

Nur Bilddateien werden verarbeitet (kein PDF, Video oder Audio) — dies ist eine bewusste Einschränkung der aktuellen Beta-Version.

Bestehende Dateien nachträglich erkennen lassen

Der automatische Warteschlangen-Eintrag gilt nur für neu hochgeladene Dateien. Dateien, die bereits vor der Aktivierung der Gesichtserkennung (oder vor einem Update auf eine Version mit dieser Funktion) hochgeladen wurden, werden nicht automatisch nachträglich gescannt.

Für eine einzelne Datei genügt der Button “Neu scannen” im Reiter “Gesichter” der jeweiligen Datei.

Für den gesamten Bestand steht Ihrem Administrator ein Konsolenbefehl zur Verfügung, der alle bislang nie eingereihten, geeigneten Dateien in einem Rutsch nachträgt:

crisp crispy:archive:queue-face-detection

Mit der Option --force werden zusätzlich Dateien, die bereits einmal verarbeitet wurden, verworfen und erneut gescannt (identisch zum manuellen “Neu scannen”, nur für den gesamten Bestand). Die eigentliche Verarbeitung läuft danach wie gewohnt asynchron über den regulären Cron-Job — der Befehl reiht die Dateien nur ein.

Personen benennen und zuordnen

Erkannte, aber noch unbenannte Gesichter finden Sie unter Archiv → Verwalten → Personen (Gesichtserkennung). Dort werden zwei Arten von Vorschlägen unterschieden:

• Vorgeschlagene Gruppen — mehrere Gesichter, die einander sehr ähnlich sehen und vermutlich zur selben, noch unbenannten Person gehören. Eine ganze Gruppe kann mit einem Klick auf einmal benannt werden.
• Einzelne unbenannte Gesichter — Gesichter ohne passenden Gruppen-Treffer, die einzeln einer bestehenden oder neuen Person zugewiesen werden.

Sobald eine Person mindestens ein benanntes Gesicht hat, wird bei jedem weiteren, noch unbenannten Gesicht im Reiter “Gesichter” einer Datei automatisch geprüft, ob es einer bereits bekannten Person ähnelt (“Ist das Name?”) — auch das ist nur ein Vorschlag, keine automatische Zuordnung.

Auf der Detailseite einer Person sehen Sie außerdem, in welchen Datensätzen diese Person vorkommt — die eigentliche “wer ist hierauf zu sehen”-Suche.

Falsch erkannte Gesichter entfernen

Zwei unterschiedliche Aktionen stehen zur Verfügung, je nachdem, was korrigiert werden soll:

• Entfernen löst nur die Zuordnung zu einer Person, die eigentliche Erkennung (Ausschnitt, Position) bleibt bestehen und kann neu zugewiesen werden.
• Löschen (Papierkorb-Symbol) entfernt eine Erkennung vollständig — für “falsch positive” Treffer, bei denen gar kein Gesicht vorliegt (z. B. ein gesichtsähnliches Muster).

Personen löschen

Eine Person kann erst gelöscht werden, wenn ihr keine Gesichter mehr zugewiesen sind — der entsprechende Button ist so lange deaktiviert. Das verhindert, dass beim Löschen einer Person versehentlich stillschweigend Zuordnungen verloren gehen; bestehende Zuordnungen müssen zuerst bewusst entfernt werden.

Der Gesichtserkennungs-Dienst

Die eigentliche Erkennung übernimmt kein Bestandteil von CrispyCMS selbst, sondern ein separater, kleiner Dienst (Python/FastAPI, Modell: InsightFace buffalo_l), der als eigener Docker-Container neben CrispyCMS betrieben wird. Der Quellcode liegt im Repository unter plugins/archive/docker/face-recognition.

Vollständig lokal und offline. Der Dienst lädt keine Modelle zur Laufzeit nach und stellt selbst keine ausgehenden Netzwerkverbindungen her — die Modellgewichte sind bereits beim Bau des Images enthalten. Bilder, die zur Erkennung übermittelt werden, verlassen die eigene Infrastruktur nie.

CPU-basiert. Der Dienst benötigt keine GPU. Eine einzelne Erkennung dauert auf üblicher Server-Hardware üblicherweise deutlich unter einer Sekunde; da die Verarbeitung asynchron über den Cron-Job läuft, ist das für den normalen Betrieb unkritisch.

Bereitgestellte Images

Ein fertiges Image wird automatisch bereitgestellt und kann direkt bezogen werden, statt es selbst zu bauen (ein lokaler Build dauert wegen der eingebetteten Modellgewichte mehrere Minuten):

docker pull images.crispycms.de/distribution/face-recognition-server:stable

Verfügbare Tags:

Selbst betreiben

Der Dienst wird üblicherweise als eigener Service in derselben Docker-Compose-Umgebung wie CrispyCMS betrieben, ohne einen nach außen veröffentlichten Port — erreichbar ist er ausschließlich für CrispyCMS selbst, über das interne Docker-Netzwerk:

services:
  archive-face-recognition:
    image: images.crispycms.de/distribution/face-recognition-server:stable
    restart: always
    networks:
      - <ihr-internes-netzwerk>
    volumes:
      - archive_face_models:/root/.insightface

volumes:
  archive_face_models:

Der Endpunkt in den Archiv-Einstellungen zeigt anschließend auf den Service-Namen und Port 8000, z. B. http://archive-face-recognition:8000 — passend zum obigen Beispiel-Service-Namen.

Das benannte Volume archive_face_models ist optional, aber empfohlen: Die Modellgewichte sind zwar bereits im Image enthalten, das Volume verhindert lediglich, dass sie bei jedem Neuerstellen des Containers erneut initialisiert werden müssen.

Eigene Schnittstelle

Der Dienst stellt zwei Endpunkte bereit, die ausschließlich von CrispyCMS selbst angesprochen werden — eine manuelle Nutzung ist nicht vorgesehen:

Gesichter mit einer Erkennungs-Konfidenz unter 50 % werden bereits im Dienst selbst verworfen und erreichen CrispyCMS gar nicht erst — das reduziert Fehlerkennungen, bevor sie überhaupt als Vorschlag auftauchen könnten.

Häufige Probleme

Neue Dateien werden nicht erkannt. Prüfen Sie, ob “Gesichtserkennung aktivieren” eingeschaltet ist, ob der konfigurierte Endpunkt erreichbar ist (der Gesichtserkennungs-Dienst muss laufen), und ob es sich tatsächlich um eine Bilddatei handelt.

Der Reiter “Gesichter” zeigt dauerhaft “Wird verarbeitet…”. In der Regel ein Zeichen dafür, dass der Gesichtserkennungs-Dienst nicht erreichbar ist oder abgestürzt ist. Nach Ablauf der konfigurierten “Sperre als veraltet markieren nach”-Zeit wird ein hängender Verarbeitungslauf automatisch als fehlgeschlagen markiert und kann über “Neu scannen” erneut versucht werden.

Bereits vorhandene Dateien haben keine erkannten Gesichter. Erwartungsgemäß — die automatische Erkennung gilt nur für neue Uploads. Nutzen Sie den Konsolenbefehl crisp crispy:archive:queue-face-detection oder den “Neu scannen”-Button der jeweiligen Datei (siehe Bestehende Dateien nachträglich erkennen lassen).

Zwei unterschiedliche Personen werden fälschlich als dieselbe vorgeschlagen (oder umgekehrt, dieselbe Person wird als zwei verschiedene vorgeschlagen). Passen Sie den “Ähnlichkeits-Schwellenwert” in den Archiv-Einstellungen an — ein niedrigerer Wert macht Vorschläge strenger, ein höherer großzügiger. Da es sich um eine Beta-Funktion handelt, ist der Standardwert ein Ausgangspunkt, kein für jeden Bildbestand optimal kalibrierter Wert.