QUICKSTART.md

Quick Start Guide - ResNet-50 ImageNet-1k Classifier

🚀 Getting Started

Option 1: Test Locally (Without Training)

# 1. Install dependencies
pip install -r requirements.txt

# 2. Test the model architecture
python test_model.py

# 3. Run the Gradio app (with random weights for demo)
python app.py

The app will automatically download ImageNet class labels from HuggingFace on first run.

Option 2: With Trained Model

# 1. Clone and set up training repository
git clone https://github.com/arghyaiitb/assignment_9
cd assignment_9

# 2. Train the model (quick test with partial dataset)
python main.py train --partial-dataset --partial-size 5000 --use-ffcv --epochs 5

# OR train for full accuracy (requires GPUs)
python main.py distributed --use-ffcv --batch-size 2048 --epochs 100 --progressive-resize --use-ema --compile

# 3. Copy the trained checkpoint
cp best_model.pt ../resnet50-imagenet-1k/

# 4. Run the app with trained weights
cd ../resnet50-imagenet-1k
python app.py

📤 Deploy to HuggingFace Spaces

Method 1: Using Git

# 1. Create a new Space on HuggingFace (https://huggingface.co/new-space)
#    Choose: Gradio SDK, Python 3.10+

# 2. Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 3. Copy all files
cp ../resnet50-imagenet-1k/* .

# 4. Add your trained model (optional, but recommended)
cp ../path/to/best_model.pt .

# 5. Push to HuggingFace
git add .
git commit -m "Initial commit: ResNet-50 ImageNet classifier"
git push

Method 2: Using HuggingFace Hub

# 1. Install huggingface_hub
pip install huggingface_hub

# 2. Login
huggingface-cli login

# 3. Upload files
python -c "
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
    folder_path='.',
    repo_id='YOUR_USERNAME/resnet50-imagenet-1k',
    repo_type='space'
)
"

🔧 Troubleshooting

"Module not found" errors

pip install -r requirements.txt

"Model checkpoint not found" warning

This is normal if you haven't trained the model yet. The app will work with random weights for demonstration purposes.

Out of memory during training

Reduce batch size:

python main.py train --batch-size 512 --epochs 100

ImageNet classes not loading

The app will automatically download them from HuggingFace. Ensure you have internet connection on first run.

📊 Expected Performance

Configuration	Top-1 Acc	Top-5 Acc	Training Time
Random Init	~0.1%	~0.5%	N/A
Partial (5k)	~5-10%	~20-30%	~5 min
Full Training	78%+	94%+	~90 min (8xA100)

📚 Additional Resources

• Training Code: https://github.com/arghyaiitb/assignment_9
• HuggingFace Labels: https://huggingface.co/datasets/huggingface/label-files
• Original Paper: Deep Residual Learning for Image Recognition (He et al., 2016)

🆘 Need Help?

• Check the training repository for detailed training instructions
• Verify your Python version: python --version (requires 3.8+)
• Check installed packages: pip list | grep -E "(torch|gradio)"