# Key Hyperparameters for Training PFLD: Complete Configuration Guide

> Master PFLD training with this guide to key hyperparameters. Learn to configure learning rates, batch sizes, model architecture, and regularization for optimal facial landmark detection performance.

- Repository: [Guoqiang QI/pfld](https://github.com/guoqiangqi/pfld)
- Tags: configuration-guide
- Published: 2026-03-02

---

**The key hyperparameters for training PFLD (Portable Facial Landmark Detector) are defined as command-line arguments in [`train_model.py`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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:

```python

# 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:

```bash
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:

```bash
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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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`](https://github.com/guoqiangqi/pfld/blob/main/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.