MODEL_HUB_SETUP.md

Setting Up Model Hub for Checkpoints

Step-by-Step Guide

Step 1: Create Model Hub Repository

1. Go to: https://huggingface.co/new
2. Select: "Model" (not Space or Dataset)
3. Fill in:
   • Repository name: starflow-3b-checkpoint
   • Owner: GlobalStudio (or your username)
   • Visibility: Private (recommended) or Public
4. Click: "Create repository"

Step 2: Upload Checkpoint to Model Hub

1. Go to your Model repository: https://huggingface.co/GlobalStudio/starflow-3b-checkpoint

2. Click: "Files" tab

3. Click: "Add file" → "Upload files"

4. Upload: starflow_3B_t2i_256x256.pth (14GB)

   • Drag and drop or browse
   • Wait for upload (30-60 minutes)
   • ✅ No storage limit issues in Model Hub!

Step 3: Update app.py (Already Done!)

The app is already configured! Just make sure the repo ID matches:

IMAGE_CHECKPOINT_REPO = "GlobalStudio/starflow-3b-checkpoint"

If your repo name is different, update this line in app.py.

Step 4: Test Your Space

1. Go to your Space: https://huggingface.co/spaces/GlobalStudio/starflow
2. Wait for rebuild (if app.py was updated)
3. Open the Gradio interface
4. Enter a prompt (no need to upload checkpoint!)
5. Click "Generate Image"
6. First time: Will download checkpoint (one-time, ~5-10 minutes)
7. After that: Uses cached checkpoint (fast!)

How It Works

1. First Request:

   • App checks for local checkpoint → Not found
   • Downloads from Model Hub → /tmp/checkpoints/
   • Caches it for future use

2. Subsequent Requests:

   • Uses cached checkpoint → Fast!
   • No download needed

3. Cache Location: /tmp/checkpoints/ (persists in Space)

Benefits

✅ No storage limit - Model Hub designed for large files ✅ Free - No cost for Model Hub storage ✅ Automatic caching - Downloads once, uses forever ✅ Version control - Can update checkpoints easily ✅ Shareable - Can use across multiple Spaces

Troubleshooting

Issue: "Repository not found"

• Solution: Make sure repo ID matches exactly: "username/repo-name"
• Check: https://huggingface.co/GlobalStudio/starflow-3b-checkpoint exists

Issue: "Download failed"

• Solution: Check internet connection, repo visibility (private repos need auth)
• For private repos, set HF_TOKEN in Space settings

Issue: "Checkpoint not found"

• Solution: Verify filename matches exactly: starflow_3B_t2i_256x256.pth
• Check Model Hub Files tab to confirm filename

For Video Model (Optional)

If you also have the video checkpoint:

1. Create another Model repo: starflow-v-7b-checkpoint
2. Upload: starflow-v_7B_t2v_caus_480p_v3.pth
3. Update app.py:

   VIDEO_CHECKPOINT_REPO = "GlobalStudio/starflow-v-7b-checkpoint"
   

Summary

1. ✅ Create Model Hub repo
2. ✅ Upload checkpoint (14GB, no limit!)
3. ✅ App already configured
4. ✅ Test and enjoy!

The app will automatically download and cache the checkpoint on first use! 🎉