Skip to content

Training, Evaluation & Export Guide

LiteALPR includes a modular suite of scripts under tools/ for preparing datasets, training custom detectors or recognizers, running evaluations, and exporting to optimized ONNX models.

0. Environment & Setup

Clone the repository and install all dependencies:

git clone https://github.com/vn-anhnth/LiteALPR.git
cd LiteALPR

# Choose based on your runtime environment:
pip install -r requirements.txt        # CPU environment
pip install -r requirements-gpu.txt    # GPU ONNX acceleration

1. Model Weights Preparation

Before training (fine-tuning) or evaluation, download the official pre-trained weights from our HuggingFace Repository and place them in pretrained_models/:

LiteALPR/
└── pretrained_models/
    ├── det/
    │   └── yolov8n_efficient/
    │       └── best.pt
    └── rec/
        └── svtr26_tiny/
            └── best.pth

You can download them using wget or curl:

# Download Detection pre-trained weights
wget -O pretrained_models/det/yolov8n_efficient/best.pt https://huggingface.co/anhone3/LiteALPR/resolve/main/yolov8n_efficient/best.pt

# Download Recognition pre-trained weights
wget -O pretrained_models/rec/svtr26_tiny/best.pth https://huggingface.co/anhone3/LiteALPR/resolve/main/svtr26_tiny/best.pth

2. Dataset Preparation

Detection Dataset

Detection models use the standard YOLO dataset format (data.yaml pointing to image and label folders).

Recognition Dataset (LMDB)

The recognition stage uses Lightning Memory-Mapped Databases (LMDB) for maximum I/O throughput during training.

Convert text label files into LMDB format:

python tools/create_lmdb_dataset.py \
    --data_dir ./dataset/rec \
    --label_files train_labels.txt val_labels.txt test_labels.txt \
    --output_dir ./dataset/rec/lmdb_data

3. Training Models

Before training, configure your dataset paths, batch sizes, and learning parameters:

Train YOLOv8n-Efficient Detector

Configure your dataset paths, batch sizes, and training hyperparameters inside the Global: section of configs/det/yolov8/yolov8n_efficient.yml:

Global:
  pretrained_model: "pretrained_models/det/yolov8n_efficient/best.pt"  # or null to train from scratch
  data: "dataset/det/data.yaml"
  epochs: 50
  imgsz: 640
  batch: 256
  device: 0  # GPU ID (e.g. 0), or list for multi-GPU (e.g. [0, 1] or more)
  project: "output/det/yolov8n_efficient"
  workers: 8

Start training with the CLI:

# Single GPU training (set device: 0 in YAML)
python tools/train_det.py -c configs/det/yolov8/yolov8n_efficient.yml

# Multi-GPU training (set device to GPU IDs, e.g. [0, 1] or [0, 1, 2, 3] in configs/det/yolov8/yolov8n_efficient.yml)
python tools/train_det.py -c configs/det/yolov8/yolov8n_efficient.yml

Train SVTR26-Tiny Recognizer

Configure your training hyperparameters in Global: and Train: sections of configs/rec/svtr26/svtr26_tiny.yml:

Global:
  device: gpu
  epoch_num: 150
  pretrained_model: "./pretrained_models/rec/svtr26_tiny/best.pth"  # or null to train from scratch
  output_dir: "./output/rec/svtr26_tiny/train"

Train:
  dataset:
    name: RatioDataSetTVResize
    data_dir_list: ['./dataset/rec/lmdb_data/train']
  sampler:
    first_bs: &bs 256             # Batch size per GPU
  loader:
    batch_size_per_card: *bs
    num_workers: 4

Eval:
  dataset:
    name: RatioDataSetTVResize
    data_dir_list: ['./dataset/rec/lmdb_data/val']

Start training with torchrun:

# Single GPU training
torchrun --nproc_per_node=1 tools/train_rec.py -c configs/rec/svtr26/svtr26_tiny.yml

# Multi-GPU training (e.g. set --nproc_per_node to number of GPUs, such as 2, 4, 8)
torchrun --nproc_per_node=2 tools/train_rec.py -c configs/rec/svtr26/svtr26_tiny.yml

Pre-trained Models (Fine-tuning)

By default, the training process will load pre-trained weights to speed up convergence. You can change the path or remove it to train from scratch:

  • For Detection: Edit the Global.pretrained_model field inside configs/det/yolov8/yolov8n_efficient.yml.
  • For Recognition: Edit the Global.pretrained_model field inside your .yml config file (e.g. configs/rec/svtr26/svtr26_tiny.yml).

4. Evaluation (Validation)

Evaluate your trained checkpoints on the validation set:

Evaluate Detector

python tools/eval_det.py -m output/det/yolov8n_efficient/train/weights/best.pt

Evaluate Recognizer

python tools/eval_rec.py \
    -c configs/rec/svtr26/svtr26_tiny.yml \
    -m output/rec/svtr26_tiny/train/best.pth

5. Batch Inference

Test your checkpoints directly on directories of images. Pass --save_log to persist prediction logs:

Infer Detection

python tools/infer_det.py \
    -m pretrained_models/det/yolov8n_efficient/best.pt \
    -d dataset/det/test/images \
    --save_log

Infer Recognition

python tools/infer_rec.py \
    -m pretrained_models/rec/svtr26_tiny/best.pth \
    -d dataset/rec/test \
    --save_log

6. Exporting to ONNX

Export your trained PyTorch models to the ONNX format for deployment in production environments (C++, C#, TensorRT, Triton, OpenVINO, etc.). You can configure the ONNX operator set version via --opset (default: 12).

Export Detector

The ONNX file will automatically be saved alongside the original .pt file (e.g. best_416.onnx):

python tools/export_det.py \
    -m output/det/yolov8n_efficient/train/weights/best.pt \
    --imgsz 416 \
    --opset 18

Export Recognizer

If you need it to accept dynamic width images in production, include the --dynamic flag:

python tools/export_rec.py \
    -m output/rec/svtr26_tiny/train/best.pth \
    --save_path output/rec/svtr26_tiny/train/best.onnx \
    --opset 18 \
    --dynamic