How dog-qiuqiu/yolo-fastestv2 works
1. What this repo is
- This is a compact object-detection project centered on Yolo-FastestV2 / FastestDet.
- The architecture is split into three clear paths: training/evaluation in Python, model export, and embedded deployment with NCNN.
2. Core model boundary
- The detector lives under model/ and is assembled from three parts:
- model/backbone/shufflenetv2.py for the lightweight feature extractor
- model/fpn.py for multi-scale feature aggregation
- model/detector.py for the decoupled detection heads
- The README says the head is separated into obj / cls / reg branches, so the model is not a single monolithic classifier but a staged detection pipeline.
3. Training data contract
- The repo follows the Darknet YOLO dataset format.
- Labels are image-aligned .txt files with category cx cy w h, and dataset splits are referenced by text files such as train.txt and val.txt.
- Class names are stored in data/coco.names, which is loaded through the dataset config.
4. Configuration layer
- data/coco.data is the main runtime configuration file.
- It defines:
- model metadata and input size
- training schedule and batch settings
- anchor parameters
- dataset paths
- class-name file
- This file is the main boundary between code and experiment setup.
5. Training flow
- train.py is the entry point for optimization.
- It likely wires together:
- dataset loading from utils/datasets.py
- model construction from model/
- detection loss from utils/loss.py
- helper logic from utils/utils.py
- Pretrained initialization can come from model/backbone/backbone.pth or a full checkpoint via pre_weights in the .data file.
6. Loss and target assignment
- utils/loss.py and the README indicate the detection training uses YOLOv5-style anchor matching rather than the older YOLO/FastestDet logic.
- The repo also mentions different loss weights per output scale, which implies multi-scale supervision across the FPN heads.
- This is a key architectural boundary: target assignment and loss are decoupled from the model definition.
7. Evaluation and single-image inference
- test.py is for ad hoc image inference, taking a data config, a trained .pth, and an input image.
- evaluation.py computes benchmark metrics such as COCO mAP using the same model and dataset configuration.
- These scripts are separate from training, which keeps inference-only logic isolated from optimization logic.
8. Anchor generation
- genanchors.py derives anchor priors from the training set.
- The resulting anchor list is fed back into data/coco.data, so anchor design is part of the experiment setup rather than hardcoded into the model.
9. Export path for deployment
- pytorch2onnx.py converts the trained PyTorch detector into ONNX.
- The README then uses onnxsim and NCNN tooling to produce optimized .param and .bin artifacts.
- This makes the deployment boundary explicit: Python training graph → ONNX interchange → NCNN runtime graph.
10. Embedded runtime / C++ sample
- sample/ncnn/ is the deployment target, with a C++ demo in demo.cpp and implementation in src/.
- sample/ncnn/model/ contains the optimized NCNN artifacts used by the demo.
- This sample is the non-Python execution boundary for low-resource inference.
11. Pretrained and packaged artifacts
- modelzoo/ stores a trained checkpoint for COCO, used for evaluation and testing.
- weights/ appears to be a generic output or bookkeeping directory.
- img/ contains demo assets/results, not part of the runtime path.
12. External dependencies that matter
- The repo is built around PyTorch for training/inference and NCNN for deployment.
- The architecture is therefore split by runtime: GPU/CPU-friendly Python experimentation on one side, and lightweight C++ inference on the other.
13. Big-picture data flow
- Training path: dataset files → dataloader → ShufflenetV2/FPN/detector → loss → checkpoint.
- Evaluation path: checkpoint + validation set → detector → mAP metrics.
- Deployment path: checkpoint → ONNX → simplified ONNX → NCNN model files → C++ demo inference.
Main entry points: train.py Train · coco.data coco.data · yolo-fastestv2.cpp NCNN src · yolo-fastestv2-opt.param NCNN model
Components 19
Python pipeline
Training, evaluation, export, and model code in PyTorch.
- Train · Training entrypoint that builds the detector, loads data, and optimizes weights.
train.py - Test · Single-image inference script for ad hoc prediction.
test.py - Eval · Evaluation script for dataset metrics such as COCO mAP.
evaluation.py - Anchors · Utility that derives anchor priors from the training set.
genanchors.py - ONNX export · Converts the PyTorch detector into ONNX for deployment.
pytorch2onnx.py - Dataset loader · Loads Darknet-style splits, images, and labels for training and evaluation.
utils/datasets.py - Detection loss · YOLOv5-style target matching and multi-scale detection loss.
utils/loss.py - Helpers · Shared training and inference helpers.
utils/utils.py - ShuffleNetV2 · Lightweight feature extractor used by the detector.
model/backbone/shufflenetv2.py - FPN · Multi-scale feature aggregation layer.
model/fpn.py - Detector · Decoupled detection heads for obj, cls, and reg prediction.
model/detector.py
NCNN deploy
C++ inference sample and optimized runtime artifacts.
- NCNN demo · Embedded inference demo that runs the exported model in NCNN.
sample/ncnn/demo.cpp - NCNN src · C++ implementation of preprocessing, inference, and postprocessing.
sample/ncnn/src/yolo-fastestv2.cpp - NCNN API · Public interface for the NCNN demo wrapper.
sample/ncnn/src/include/yolo-fastestv2.h - NCNN model · Optimized param/bin files consumed by the embedded demo.
sample/ncnn/model/yolo-fastestv2-opt.param
Data and artifacts
Configs, labels, checkpoints, and generated assets.
- coco.data · Main experiment config for model metadata, anchors, dataset paths, and training settings.
data/coco.data - coco.names · Class-name list loaded by the dataset and runtime config.
data/coco.names - COCO ckpt · Packaged COCO model checkpoint used for testing and evaluation.
modelzoo/coco2017-0.241078ap-model.pth - Backbone ckpt · Pretrained backbone weights used for initialization.
model/backbone/backbone.pth
Connections 20
- Train → Dataset loader: loads · Training uses the dataset loader for Darknet-style splits and labels.
- Train → ShuffleNetV2: builds · Training constructs the model backbone.
- Train → FPN: builds · Training constructs the feature pyramid neck.
- Train → Detector: builds · Training constructs the detection heads.
- Train → Detection loss: optimizes with · Loss module computes multi-scale supervision and anchor matching.
- Train → Helpers: uses · Training reuses shared helper logic.
- Train → coco.data: reads · Experiment settings and paths come from the data config.
- coco.data → coco.names: references · Config points to the class-name file.
- coco.data → Backbone ckpt: initializes · Config may point to pretrained backbone weights.
- Anchors → coco.data: updates · Generated anchors are fed back into the config.
- Eval → COCO ckpt: evaluates · Evaluation runs the packaged checkpoint.
- Eval → Dataset loader: loads · Evaluation reads validation data through the same loader boundary.
- Test → COCO ckpt: infers · Ad hoc inference runs a trained checkpoint.
- Test → coco.data: reads · Inference uses the runtime config for paths and settings.
- ONNX export → COCO ckpt: exports · ONNX export starts from a trained PyTorch checkpoint.
- ONNX export → NCNN model: produces · Exported model is simplified and converted into NCNN artifacts.
- NCNN demo → NCNN src: uses · Demo entrypoint calls into the C++ runtime implementation.
- NCNN src → NCNN API: includes · Implementation is exposed through the header interface.
- NCNN demo → NCNN model: loads · Demo consumes the optimized param/bin model files.
- NCNN src → NCNN model: runs · Runtime implementation executes the exported NCNN graph.