Key Hyperparameters for Training PFLD: Complete Configuration Guide

The key hyperparameters for training PFLD (Portable Facial Landmark Detector) are defined as command-line arguments in train_model.py, controlling learning rate schedules, batch sizes, model architecture variants, and regularization strength.

Training the PFLD model from the guoqiangqi/pfld repository requires careful configuration of optimization parameters exposed through the parse_arguments function. These key hyperparameters for training PFLD govern everything from Adam optimizer settings to MobileNet-V2 backbone selection, directly impacting facial landmark detection accuracy and convergence stability.

Core Optimization Hyperparameters

Learning Rate and Scheduling Strategy

The --learning_rate parameter sets the base value for the Adam optimizer, defaulting to 0.001 in train_model.py (lines 32-33). The critical --lr_epoch parameter accepts a comma-separated string of epoch milestones (default: "10,20,30,40,200,500") that trigger a tenfold reduction in learning rate at each specified boundary.

Batch Size and Training Duration

The --batch_size parameter controls the mini-batch size for both training and validation phases, defaulting to 64 (lines 29-30). The --max_epoch parameter defines the total training iterations, set to 1000 by default (lines 26-27), determining how many complete passes through the dataset the model performs.

Regularization Settings

Weight decay is controlled via --weight_decay, which applies L2 regularization with a default value of 5e-5 (lines 34-35) to all learnable parameters in the network, helping prevent overfitting on facial landmark datasets.

Model Architecture and Data Configuration

Model Level Variants

The --level parameter selects specific architectural configurations defined in model2.py. Valid options include L1 through L5, with L5 serving as the default (lines 35-36). Each level adjusts the depth and width of the MobileNet-V2 backbone, trading off between inference speed and landmark accuracy. Higher levels like L5 provide greater precision for dense facial feature detection, while L1 prioritizes real-time performance.

Input Image Specifications

Input preprocessing is governed by --image_size (default 112 pixels) and --image_channels (default 3 for RGB). These parameters (lines 27-29) must align with the dataset preprocessing pipeline to ensure correct tensor dimensions reach the network. The square input resolution of 112×112 is standard for the PFLD architecture, balancing computational efficiency with sufficient spatial resolution for precise landmark localization.

Training Workflow Controls

Reproducibility and Initialization

The --seed parameter (default 666) sets random seeds for NumPy and TensorFlow to ensure deterministic results across runs (lines 25-26). For fine-tuning scenarios, --pretrained_model accepts a path to a checkpoint file (e.g., ./models1/L5_run/model.ckpt-500), allowing training to resume from a specific iteration or transfer learning from pre-trained weights (lines 31-32).

Output and Debugging

The --model_dir parameter defines the destination for checkpoints and TensorBoard summaries, defaulting to 'models1/model_test' (lines 31-33). The boolean --debug flag enables verbose logging for troubleshooting data pipeline issues (lines 37-38), while --save_image_example controls whether training visualizations are written to disk for inspection (lines 36-37).

Learning Rate Schedule Implementation

The piecewise learning rate decay logic resides in utils.py within the train_model function. The implementation converts epoch milestones into global step boundaries and computes decayed learning rates using TensorFlow's piecewise_constant operation:

# utils.py – learning rate schedule implementation

lr_factor = 0.1
lr_epoch = args.lr_epoch.strip().split(',')
lr_epoch = list(map(int, lr_epoch))
boundaries = [epoch*data_num//args.batch_size for epoch in lr_epoch]
lr_values = [args.learning_rate*(lr_factor**x) for x in range(0, len(lr_epoch)+1)]
lr_op = tf.train.piecewise_constant(global_step, boundaries, lr_values)

This schedule multiplies the base learning rate by 0.1 at each boundary, creating a stepped decay pattern that facilitates fine convergence in later epochs while allowing rapid initial progress.

Practical Configuration Examples

Standard training configuration for the L5 model variant:

python train_model.py \
  --model_dir=./models1/L5_run \
  --image_size=112 \
  --batch_size=64 \
  --learning_rate=0.001 \
  --lr_epoch=10,20,30,40,200,500 \
  --weight_decay=5e-5 \
  --max_epoch=1000 \
  --level=L5 \
  --debug=False

Fine-tuning from a pretrained checkpoint with reduced batch size and adjusted learning schedule:

python train_model.py \
  --pretrained_model=./models1/L5_run/model.ckpt-500 \
  --batch_size=32 \
  --learning_rate=5e-4 \
  --lr_epoch=5,15,30,60,120 \
  --max_epoch=300 \
  --level=L1 \
  --debug=True

Summary

• The key hyperparameters for training PFLD are exposed as command-line arguments in train_model.py, parsed via the parse_arguments function.
• Optimization is controlled by --learning_rate, --lr_epoch (schedule milestones), --batch_size, and --weight_decay (L2 regularization).
• Model architecture is selected via --level (L1-L5) in model2.py, while input dimensions are set by --image_size and --image_channels.
• Training duration is determined by --max_epoch, with reproducibility ensured through --seed and fine-tuning supported via --pretrained_model.
• The learning rate schedule implementation in utils.py uses TensorFlow's piecewise_constant to decay the rate by 0.1 at specified epoch boundaries.

Frequently Asked Questions

What is the default learning rate for training PFLD?

The default learning rate is 0.001, configured for the Adam optimizer. This value is defined in train_model.py (lines 32-33) and can be overridden using the --learning_rate command-line argument.

How does the learning rate schedule work in PFLD training?

The learning rate follows a piecewise constant decay schedule defined in utils.py. The --lr_epoch parameter accepts comma-separated epoch numbers (default: 10,20,30,40,200,500). At each specified epoch, the learning rate is multiplied by 0.1, creating stepped reductions that help the model converge to finer minima.

What is the difference between PFLD model levels L1 through L5?

The --level parameter selects architectural variants defined in model2.py. Each level (L1, L2, L3, L4, L5) represents a different configuration of the MobileNet-V2 backbone, varying in depth and width. Higher levels (like L5) typically offer greater accuracy at the cost of increased computational complexity, while lower levels (like L1) prioritize inference speed.

How do I resume training from a checkpoint in PFLD?

To resume or fine-tune from a previous checkpoint, use the --pretrained_model argument in train_model.py. Provide the full path to the checkpoint file (e.g., --pretrained_model=./models1/L5_run/model.ckpt-500). When this argument is provided, the script loads the saved weights before starting the training loop, allowing you to continue from a specific epoch or adapt the model to new data with a reduced learning rate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}