README.md

---
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`](https://huggingface.co/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

```bash
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.

```bash
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:

```bash
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:

```bash
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)
```