QUICKSTART.md

Quick Start: Fix ZeroGPU CUDA Error

The Problem

RuntimeError: CUDA has been initialized before importing the `spaces` package.

The Solution (Applied ✅)

1. Import spaces FIRST in app.py

# BEFORE (❌ Wrong):
import os
import torch
import spaces  # Too late!

# AFTER (✅ Fixed):
import spaces  # MUST BE FIRST!
import os
import torch

2. Add GPU Decorators

@spaces.GPU
def sam_refine(...):
    initialize_models()  # Lazy load
    # ... processing

@spaces.GPU(duration=120)  # 2 minutes for video processing
def run_videomama_with_sam2(...):
    initialize_models()  # Lazy load
    # ... processing

3. Lazy Load Models

# Don't load at startup:
if __name__ == "__main__":
    # initialize_models()  # ❌ Remove this
    demo.launch()

# Load on first use instead:
@spaces.GPU
def inference_function():
    initialize_models()  # ✅ Load here
    # ...

4. Update requirements.txt

spaces  # Add this at the top
torch>=2.0.0
gradio==4.31.0
# ... rest

5. Update README.md

---
hardware: zero-a10g  # For ZeroGPU Pro
sdk_version: 4.31.0
---

All Changes Applied ✅

The following files have been updated:

• ✅ app.py - Added import spaces at top, GPU decorators, lazy loading
• ✅ requirements.txt - Added spaces package
• ✅ README.md - Added hardware configuration

Deploy Now

Simply push to your Hugging Face Space:

git add app.py requirements.txt README.md
git commit -m "Fix ZeroGPU CUDA initialization error"
git push

Test Result

Your Space should now:

1. ✅ Start without CUDA errors
2. ✅ Allocate GPU only when needed (clicks or processing)
3. ✅ Work with ZeroGPU Pro subscription

Need Help?

See HUGGINGFACE_DEPLOY.md for detailed documentation.