How johnnyau19/face-id works
Project Type and Purpose
• This is a machine-learning–based face verification system (a specialized full-stack project comprising data-prep pipelines, model training/evaluation/inference scripts, and a minimal serving component).
• Purpose: Given two face images, decide if they belong to the same person. Under the hood it uses a Siamese-style neural network (SNN) trained with contrastive loss.
File Structure
• Top-level scripts:
• prepare_dataset.py – Splits raw VGGFACE2 into train/val/test folders, removes bad faces, and generates labeled .npy files.
• compute_mean_std.py – Scans train data to compute normalization stats.
• train.py – Loads cached/preprocessed data, trains SNN, saves model checkpoints.
• evaluate.py – Loads a checkpoint and validation set, sweeps thresholds to compute F1/precision/recall/accuracy.
• inference.py – Applies a fixed threshold on test set to compute final metrics.
• server.py – Loads trained model and exposes inference over HTTP (likely via Flask/FastAPI).
• Supporting packages:
• data_manipulate/ – Dataset and preprocessing routines (MTCNN + transform pipeline + caching).
• model/SNN.py – Defines the Siamese CNN encoder + distance layer.
• script/ – Lower-level compute/generate utility scripts.
• utils.py – Shared helper functions (e.g., checkpoint I/O, metric computations).
• Artifacts & config:
• requirements.txt – Python dependencies (PyTorch, facenet-pytorch MTCNN, numpy, flask/fastapi, etc.).
• dataset/*.npy & data/ folders – Data splits & caches.
• mean_std.pt – Stored normalization parameters.
README–Driven Architectural Insights
• Three pipeline stages: preprocessing (face detection, cropping, normalization), embedding (SNN encoder), comparison (Euclidean distance + thresholding).
• Caching layer ensures images are preprocessed once per run (speeds up train/eval loops).
• Contrastive loss + L2 regularization drive model optimization.
• Serving component to expose prediction API for pairwise comparisons.
1. Data Ingestion & Splitting
• Raw VGGFACE2 images → prepare_dataset.py → data/train, data/validate, data/test
2. Preprocessing & Caching
• data_manipulate.Dataset + preprocess → MTCNN face crop → transformations → cache on disk (batches/)
• compute_mean_std.py → mean_std.pt
3. Model Training
• train.py: loads cached tensors + mean_std → SNN model (model/SNN.py) → Contrastive Loss + L2 reg → saves checkpoint(s)
4. Model Evaluation
• evaluate.py: loads checkpoint + cached val set → distance computation + threshold sweep → metrics
5. Inference & Testing
• inference.py: loads checkpoint + cached test set → fixed threshold → metrics
6. Serving/API Layer
• server.py: loads best checkpoint + mean_std → REST endpoint receives two images → preprocess → embed → distance → result
Raw Data → prepare_dataset → Split Data → preprocess → Cache → train/evaluate/inference → model checkpoints → server
c. Architectural Patterns & Principles:
• Pipeline pattern: data split → preprocess → model loops → evaluation → deployment
• Modular separation: data manipulation, model definition, training scripts, evaluation, serving
• Caching layer decouples expensive I/O & preprocessing from training/eval loops
• Reproducibility: fixed directory structure and config files
d. Key Technologies & Libraries:
• PyTorch (model, training, checkpointing)
• facenet-pytorch (MTCNN)
• NumPy (.npy datasets)
• Flask/FastAPI (server.py)
• Python standard libraries for CLI parsing (argparse), file I/O