README.md

metadata

title: Tiny ViT ImageNet-1k
emoji: 🦖
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 5.32.0
python_version: '3.11'
app_file: app.py
pinned: false
license: apache-2.0
short_description: Tiny ViT top-k image classifier (ImageNet-1k).

Tiny ViT — ImageNet-1k Gradio Demo

A minimal Gradio app that classifies uploaded images using the tiny Vision Transformer WinKawaks/vit-tiny-patch16-224, pretrained on ImageNet-1k (1000 classes), and returns the top-k predictions with a configurable confidence threshold.

Features

• Upload from disk, paste from clipboard, or capture via webcam.
• Adjustable top-k (1–10) and confidence threshold sliders.
• Three bundled example images (cat, dog, bird) in examples/.
• CPU or CUDA auto-detection.

Local setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Then open the URL printed in the terminal (usually http://127.0.0.1:7860).

Model

• Model: WinKawaks/vit-tiny-patch16-224 (~5.7M params)
• Pretraining: ImageNet-1k (1000 classes)
• Input size: 224×224 RGB

Swap MODEL_ID in app.py for a larger variant, e.g.:

• WinKawaks/vit-small-patch16-224
• google/vit-base-patch16-224
• facebook/deit-tiny-patch16-224

Deploy to Hugging Face Spaces

This repo is already Spaces-ready — the YAML frontmatter above is the Space config.

hf auth login
hf repo create <your-username>/vit-tiny-imagenet-demo --repo-type space --space_sdk gradio
hf upload <your-username>/vit-tiny-imagenet-demo . --repo-type space

Or push via git:

git init
git remote add origin https://huggingface.co/spaces/<your-username>/vit-tiny-imagenet-demo
git add .
git commit -m "Initial commit: tiny ViT ImageNet-1k demo"
git push -u origin main

The Space will build on a free CPU runtime by default. For faster inference you can upgrade the Space hardware to a small GPU (T4, A10G, etc.) in the Space settings.

Training a new LoRA adapter

The demo also supports LoRA adapters that add new tasks on top of the frozen backbone. Train one with:

python train_lora.py \
  --rank 8 --alpha 16 --target-modules query value \
  --epochs 5 --batch-size 64 --lr 5e-4 \
  --push-to-hub <your-username>/vit-tiny-lora-food101

The script freezes the base weights, injects a low-rank (\Delta W) into the attention projections, and trains a new classification head. Because the original weights are untouched, disabling the adapter at inference time recovers the original ImageNet-1k model exactly.

Useful flags: --max-train-samples N (quick smoke test), --eval-only (metrics-only pass), --dataset-id (any HF image classification dataset with image / label features).

Adapters loaded at runtime

adapters.py holds the registry of adapters the Gradio app pulls in at startup. Add more entries to expose additional tasks in the UI:

Name	Hub repo	Dataset	Classes
food101	turhancan97/vit-tiny-lora-food101	Food-101	101

Adapters that fail to load (e.g. repo not yet pushed) are logged and skipped; the app still starts with whatever is reachable. The UI gains a "Compare: Base vs LoRA" tab whenever at least one adapter is loaded.

Project layout

.
├── app.py              # Gradio Blocks app
├── adapters.py         # LoRA adapter registry
├── train_lora.py       # LoRA fine-tuning CLI
├── requirements.txt    # Python deps
├── examples/           # Sample images used in the UI
│   ├── bird.jpg
│   ├── cat.jpg
│   └── dog.jpg
└── README.md           # This file (+ Spaces config)