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