Full-Stack VisionOps

Full-Stack VisionOps is an opinionated template for end-to-end computer vision R&D. It combines PyTorch Lightning, Hydra, DVC, MLflow, and Optuna into a single workflow that is ready for local development, reproducible training, and containerized deployment.

Project Highlights

• Hydra-configurable experiments with clean separation between datasets, models, trainers, optimizers, and schedulers under conf/.
• PyTorch Lightning modules in src/models/ with metric helpers and training orchestration in src/train.py.
• Data versioning with DVC using the TinyImageNet example dataset.
• Experiment tracking via MLflow (Hydra plugin) and Optuna sweeps.
• uv-powered dependency management with CUDA-ready Docker images for development, training, and inference.

Quickstart

Prerequisites

• Python ≥ 3.10
• uv (installed via pip install uv or one of the official installers)
• DVC with an S3-compatible remote if you plan to push data or artifacts
• (Optional) NVIDIA GPU with CUDA 12.1 drivers for accelerated training

Local Environment Setup

uv sync --locked --extra dev

This creates an isolated virtual environment under .venv/ (respecting the UV_PROJECT_ENVIRONMENT environment variable if set) and installs runtime plus developer dependencies.

Data Preparation

Download the TinyImageNet dataset with DVC:

dvc pull data/raw/tiny-imagenet-200.dvc

Or replace the dataset by updating the paths under conf/dataset/ and committing the corresponding DVC metafiles.

Training

Run the default configuration:

uv run python -m src.train

Override any Hydra config group on the command line, e.g.:

uv run python -m src.train model=convnext_tiny_lit optim=adamw trainer=default

Hydra experiment logs and checkpoints are stored under hydra/ by default.

Evaluation & Benchmarking

Use the bundled benchmark helper to evaluate saved checkpoints:

uv run python -m src.utils.benchmark --help

Linting & Tests

uv run ruff check src tests
uv run mypy src
uv run pytest -q

These commands are orchestrated in the Makefile for convenience:

• make lint → Ruff and MyPy
• make test → Pytest
• make format → Ruff format and import sorting

Docker Workflow

Build Images

docker build -t cvops-dev --target dev .
docker build -t cvops-train --target train .
docker build -t cvops-infer --target infer .

The multi-stage Dockerfile supplies CUDA-ready environments with cached uv installs. Use the dev image for interactive work, train for launching jobs, and infer for lightweight deployments.

Run the Dev Container

docker run --gpus all -it --rm \
	-v ${PWD}:/workspace \
	-v cvops-cache:/root/.cache/uv \
	cvops-dev

The container mounts your workspace and reuses the uv cache to speed up installs. Omit --gpus all on CPU-only setups.

Configuration Layout

• conf/experiment/ – High-level experiment presets (learning rate schedules, EMA, etc.).
• conf/model/ – Model architectures mapped to src/models/ implementations.
• conf/trainer/ – PyTorch Lightning trainer settings.
• conf/data/ – Datamodule settings, including augmentations and batch sizes.

Refer to conf/config.yaml for the default composition of these groups.

Continuous Integration

GitHub Actions (.github/workflows/ci.yml) installs the project with uv, runs linting (Ruff + MyPy), and executes the test suite. The workflow mirrors the Dockerfile dev stage to ensure parity between local, CI, and containerized environments.

Contributing

1. Fork and clone the repository.
2. Install dependencies with uv sync --locked --extra dev.
3. Create a feature branch and make your changes.
4. Run make lint test and ensure all checks pass.
5. Submit a pull request describing your changes and validation steps.

Resources

• PyTorch Lightning
• Hydra Configs
• uv Documentation
• DVC User Guide

---

Licensed under the MIT License. See LICENSE for details.