MANTAX bauen: Ein ethisches Gesichtserkennungssystem für NGOs
#Einleitung
Dies ist ein technischer Tiefeneinblick in MANTAX, ein ethisches Gesichtserkennungssystem für NGO-Anwendungsfälle. In diesem Blogpost erkunden wir die vollständige Architektur, Datenflüsse und Implementierungsdetails—alles, was ein Entwickler wissen muss, um zu verstehen, wie dieses System funktioniert.
#Systemarchitektur-Überblick
MANTAX folgt einer Drei-Schichten-Architektur mit klarer Trennung zwischen Präsentation, Geschäftslogik und maschinellem Lernen.
#Technologie-Stack
| Schicht | Technologie | Zweck | |---------|-------------|-------| | Frontend | Electron + Vanilla JS | Desktop-App mit Custom Titlebar | | Styling | SCSS → CSS | macOS Tahoe Liquid Glass Design | | Backend | Flask (Python) | REST API mit 31 Endpunkten | | ML-Laufzeit | ONNX Runtime (ArcFace) + PyTorch (FaceNet) | Dual-Modell-Embedding-Extraktion | | Gesichtserkennung | OpenCV DNN + MediaPipe | Gesichtslokalisierung + 468-Punkt-Landmarks |
#Die Daten-Pipeline
Wenn ein Benutzer ein Bild hochlädt, durchläuft es eine gut definierte Pipeline. Verfolgen wir diese Reise:
#Gesichtserkennungsmodul
Das Erkennungsmodul (src/detection/__init__.py) behandelt den ersten kritischen Schritt: Finden, wo sich Gesichter in einem Bild befinden.
#Erkennungsablauf
#Primäre Erkennungsmethode: OpenCV DNN
Das System verwendet ein vortrainiertes Caffe-Modell für Deep-Learning-basierte Gesichtserkennung:
Erforderliche Modell-Dateien:
deploy.prototxt.txt- Caffe-Architekturdefinitionres10_300x300_ssd_iter_140000.caffemodel- Vortrainierte Gewichte
#Fallback: Haar Cascade
Wenn DNN nicht geladen werden kann, fällt das System elegant auf Haar Cascade zurück:
#Gesicht-ROI-Extraktion
Sobald Gesichter erkannt wurden, extrahiert die API den Bereich von Interesse (ROI):
#Gesichtspunkt-Erkennung
Nach der Erkennung von Gesichtern extrahiert das System 468 Gesichtspunkte mit MediaPipe Face Mesh:
#Landmark-Extraktionscode
#Geometrische Merkmalsextraktion
Zu Vergleichszwecken extrahieren wir skaleninvariante geometrische Merkmale:
#Embedding-Extraktion (Dual-Modell)
Dies ist der Kern des Systems—Umwandlung von Gesichtsbildern in mathematische Embeddings, die verglichen werden können.
#ArcFace-Implementierung
ArcFace bietet überlegene Diskriminierung zwischen verschiedenen Gesichtern:
#FaceNet-Implementierung
FaceNet bietet sekundäre Signale und Visualisierungen neuronaler Aktivierungen:
#Neuronale Netzwerk-Aktivierungen
FaceNet extrahiert auch Zwischenschichten-Aktivierungen zur Visualisierung:
Extrahierte Aktivierungen: | Schicht | Ausgabeform | Zweck | |---------|-------------|-------| | conv1 | (64, 112, 112) | Erste Konvolutionen | | bn1 | (64, 112, 112) | Erste Batch-Norm | | layer1 | (64, 56, 56) | Niedrigstufige Merkmale | | layer2 | (128, 28, 28) | Mittelstufige Merkmale | | layer3 | (256, 14, 14) | Hochstufige Merkmale | | layer4 | (512, 7, 7) | Endgültige Merkmale | | embedding | (128,) | Endgültiges Embedding |
#Der Compare-Endpunkt (Vollständiger Ablauf)
Hier ist der vollständige Vergleichsablauf vom /api/compare-Endpunkt:
#Dual-Modell-Bewertung
Die Bewertung kombiniert mehrere Signale mit gelernten Gewichten:
#Konfidenzbänder
Anstelle von Binärentscheidungen gibt das System Konfidenzbänder aus:
#API-Endpunkte-Referenz
Die Flask-API expose 31 Endpunkte für alle Operationen:
| Endpunkt | Methode | Zweck |
|----------|---------|-------|
| /api/health | GET | System-Gesundheitscheck |
| /api/embedding-info | GET | Aktuelle Modellinfo |
| /api/diagnostics | GET | System-Diagnose |
| /api/detect | POST | Gesichtserkennung |
| /api/extract | POST | Embedding-Extraktion |
| /api/add-reference | POST | Referenzbild hinzufügen |
| /api/references | GET | Alle Referenzen auflisten |
| /api/references/<id> | DELETE | Referenz entfernen |
| /api/compare | POST | Embeddings vergleichen |
| /api/visualizations/<type> | GET | Visualisierung abrufen |
| /api/clear | POST | Sitzung löschen |
#Visualisierungen (14 Typen)
Das System bietet 14 verschiedene KI-Visualisierungen, um Ermittlern zu helfen zu verstehen, warum Scores berechnet wurden:
#Visualisierungsimplementierung-Beispiel
#Sitzungszustandsverwaltung
Die API verwaltet den In-Memory-Sitzungszustand:
#Persistenz
Referenzen werden zur Persistenz über Neustarts hinweg in JSON gespeichert:
#Testinfrastruktur
Das System umfasst umfassende Tests:
#Tests ausführen
#Dateistruktur
#Wichtige Designentscheidungen
#1. Dual-Modell-Architektur
Die Verwendung sowohl von ArcFace (512-dim) als auch FaceNet (128-dim) zusammen bietet bessere Diskriminierung als jedes allein. ArcFace bewältigt den primären Abgleich, während FaceNet sekundäre Signale und Aktivierungsvisualisierungen bietet.
#2. Konfidenzbänder, keine Binärentscheidungen
Das System gibt Konfidenzbänder (Sehr Hoch/Hoch/Mittel/Unzureichend) statt "Match/Kein Match" aus. Dies stellt sicher, dass menschliche Ermittler immer die endgültige Entscheidung treffen.
#3. Lokale Verarbeitung
Keine Bilder werden an externe Server gesendet. Alle Berechnungen finden auf dem Computer des Benutzers statt, was die Datenschutzbedenken der NGOs adressiert.
#4. Nicht umkehrbare Embeddings
Gesichtserkennungs-Embeddings können nicht verwendet werden, um das ursprüngliche Gesicht zu rekonstruieren—was eine zusätzliche Schutzebene bietet.
#5. Einwilligungsverfolgung
Jedes Referenzbild enthält Metadaten über Einwilligungsstatus, Quelle und Zweck—wesentlich für NGO-Dokumentationsanforderungen.
#Zusammenfassung
MANTAX ist ein vollständig funktionsfähiges ethisches Gesichtserkennungssystem, gebaut mit:
- Flask API (2.131 Zeilen) mit 31 Endpunkten
- Dual-Modell-Embedding (ArcFace 512-dim + FaceNet 128-dim)
- OpenCV DNN Gesichtserkennung mit MediaPipe-Landmarks
- Electron Desktop-App mit macOS Tahoe Liquid Glass UI
- Umfassende Tests (E2E, Grenzfälle, Frontend)
Das System ist für NGO-Anwendungsfälle konzipiert mit:
- Lokaler Verarbeitung (kein Cloud)
- Mensch-in-the-loop Verifizierung
- Einwilligungsverfolgung
- Konfidenzbändern statt Binärentscheidungen
Im nächsten Blogpost erkunden wir die JavaScript-Refactoring-Reise—wie wir eine 3.429-Zeilen monolithische app.js übernommen und sie in 7 modulare Dateien nach Best Practices aufgeteilt haben.
#Demo-Video
Hier ist eine Demo, die ein No-Match-Szenario zeigt:
Als Nächstes: Die JavaScript-Refactoring-Geschichte