Deep Learning Training Template

A layered architecture template for deep learning training projects.

Architecture

Apps → Pipelines → Core

• Core: Reusable components (models, data, training utils)
• Pipelines: Task-specific workflows that orchestrate Core components
• Apps: Entry points (train.py, eval.py)

Quick Start

Installation

# Using uv
uv sync

# Or pip
pip install -e .

Training

# Single GPU
uv run train --config configs/experiments/example.yaml

# Or run as a module
uv run python -m apps.train --config configs/experiments/example.yaml

# Multi-GPU (DDP)
uv run torchrun --nproc_per_node=4 -m apps.train --config configs/experiments/example.yaml

# Override config from command line
uv run train --config configs/experiments/example.yaml optimizer.lr=0.001

# Resume from checkpoint
uv run train --config configs/experiments/example.yaml --resume /path/to/checkpoint.pth

Evaluation

uv run eval --config configs/experiments/example.yaml --checkpoint /path/to/checkpoint.pth

Project Structure

├── src/               # Source code (src layout)
│   ├── core/          # Core components
│   │   ├── modeling/  # Models, losses, metrics
│   │   ├── data/      # Datasets, transforms
│   │   ├── engine/    # Training loop, distributed
│   │   ├── eval/      # Evaluation utilities
│   │   └── utils/     # Registry, config, checkpoint
│   ├── pipelines/     # Task-specific pipelines
│   └── apps/          # Entry points
├── configs/           # Configuration files
├── tests/             # Unit tests
└── scripts/           # Shell scripts

Adding New Components

New Backbone

# src/core/modeling/backbones/my_backbone.py
from core.utils import BACKBONES

@BACKBONES.register("my_backbone")
class MyBackbone(nn.Module):
    ...

New Pipeline

See src/pipelines/README.md for details.

Configuration

Configs support inheritance via _base_:

_base_:
  - ../_base_/models/resnet.yaml
  - ../_base_/datasets/cifar100.yaml

model:
  head:
    num_classes: 100

Output Directory

By default, outputs go to external directory. Set via:

• Config: output_root: /path/to/outputs
• Environment: export EXP_OUTPUT_ROOT=/path/to/outputs