PyTorch Object Detection for Beginners

简体中文: README.zh-CN.md

This is a beginner-friendly PyTorch object-detection project. You will use torchvision Faster R-CNN to learn bounding boxes, VOC data, training, evaluation, and prediction, then complete a real training run on a free Kaggle GPU.

You do not need to configure local CUDA or read every reference page first. Start on Kaggle and return to the reference notes when you want to understand a concept in more depth.

Completed Kaggle training

The project has completed a 26-epoch VOC 2007 run on a Kaggle Tesla T4. The validation score selected epoch 18 as best.pt, which was evaluated once on all 4,952 test images.

Item	Result
Model	Faster R-CNN MobileNet V3 Large 320 FPN
Test mAP@0.5:0.95	0.322312
Test mAP@0.5	0.609917
Training time	3,025.660 seconds, about 50 minutes
Complete Kaggle job	3,223.9 seconds, about 54 minutes

This is a real prediction saved by the completed Kaggle run, not a teaching diagram. See the Kaggle run record for full metrics, per-class results, false positives, and missed objects. It is the only complete training result published by this repository; small runs and synthetic examples are used only to explain the code.

Start training on Kaggle

You need a Kaggle account with GPU access. The supplied runner uploads the source, downloads official VOC 2007, prepares the data, trains, evaluates, and saves the outputs. It performs the complete sequence:

download -> prepare -> inspect -> dry run -> train -> evaluate -> predict

1. Get the project and install the Kaggle CLI

git clone https://github.com/Doithoo/pytorch-object-detection-lab.git
cd pytorch-object-detection-lab
uv tool install kaggle
kaggle auth login

The Kaggle CLI is a submission and download tool, not a project training dependency. This runner does not require kagglehub or an attached Kaggle Dataset.

2. Set your Kaggle username

Open docs/recorded-run/kaggle/kernel-metadata.json and replace yashowhoo in the id with your Kaggle username. Keep enable_gpu: true and enable_internet: true.

3. Submit and watch the run

kaggle kernels push -p docs/recorded-run/kaggle
kaggle kernels status <your-username>/pytorch-object-detection-lab-voc2007-gpu

Open the job on Kaggle and confirm it received a T4 or newer GPU. The page may show T4 x2, but this is a single-GPU project and uses only one card. That is expected. The log prints a heartbeat every 60 seconds, and the complete run takes roughly 50-60 minutes.

4. Download the result

After the status becomes COMPLETE, download only the training artifacts so you do not also download the temporary VOC directory:

kaggle kernels output <your-username>/pytorch-object-detection-lab-voc2007-gpu --file-pattern 'artifacts/.*' -p kaggle-output

Start with these files under kaggle-output:

• metrics.csv: training losses and validation metrics for every epoch.
• best.pt: the model selected by validation performance.
• last.pt: the final epoch and resume state.
• evaluation/evaluation.json: the test-set summary.
• evaluation/per_class.csv: results for all 20 VOC classes.
• evaluation/visualizations/: real predictions, false positives, and misses.

The Kaggle training guide covers account setup, monitoring, downloads, and the failures already encountered while producing the recorded run.

Reference notes and guides

You do not need to read everything at once. Choose the pages that match the question you are working on:

1. Read the repository overview and choose a relevant page.
2. Understand images, labels, and boxes.
3. Inspect the VOC data.
4. Read how Faster R-CNN is assembled.
5. Run the recorded Kaggle workflow.
6. Read evaluation and prediction outputs.

See the documentation home for every guide and reference.

Optional: check the project locally

To inspect the environment and commands before submitting to Kaggle, use Python 3.10-3.12 and run:

uv sync --locked --extra dev
uv run detect --version
uv run detect list-models
uv run detect show-config --config configs/reference_fasterrcnn.yaml
uv run detect verify-data --data-dir data/raw --manifest-dir data/manifests

These commands do not start full training. After preparing VOC locally, you can also perform one small CPU update:

uv run python scripts/download_data.py --data-dir data/raw
uv run detect prepare-data --data-dir data/raw --manifest-dir data/manifests
uv run detect train --config configs/learning_minimal.yaml --dry-run --device cpu

Full local training is intended for readers who already have a compatible GPU. The command and considerations are in the reference notes.

What you can learn here

• How VOC XML annotations become torchvision boxes, labels, and image_id.
• Why an object-detection batch is a list of images and a list of targets.
• Why Faster R-CNN returns losses during training and boxes, labels, and scores during evaluation.
• How validation selects best.pt before one final test-set report.
• How to inspect per-class AP, false positives, misses, and prediction images instead of relying on one score.
• How to resume from a checkpoint or run predictions on your own images.
• How to export the same validated splits and labels for a separate YOLO-compatible engine.

The project includes five registered model configurations plus explicit external factories:

Name	Good for
fasterrcnn_mobilenet_v3_large_320_fpn	Default beginner model and the recorded Kaggle model
fasterrcnn_resnet50_fpn	A larger Faster R-CNN comparison
retinanet_resnet50_fpn	Anchor-based one-stage detector with focal loss
fcos_resnet50_fpn	Anchor-free one-stage detector with centerness
ssdlite320_mobilenet_v3_large	A compact one-stage detector comparison

See choosing a model and the configuration directory for details.

Development

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest -W error::DeprecationWarning

Tests use synthetic data and temporary files; they do not download VOC or pretrained weights. Read CONTRIBUTING.md before contributing. The project uses the MIT License.