HF_MODEL_SETUP.md

Quick Guide: Setting Up Model Weights on Hugging Face

TL;DR: Host your FoundationPose weights in a HF model repository instead of your Space. It's easier, faster, and better.

Why This Way is Better

Method	Pros	Cons
HF Model Repo ✅	Fast CDN downloads, version control, share across Spaces, no git-lfs needed	Initial setup required
Git-LFS in Space	All-in-one repo	Slow, complex, Space bloat, hard to share
Manual upload to Space files	Simple	Not version controlled, no programmatic access

5-Minute Setup

1. Download Weights (One-Time)

# Download from Google Drive:
# https://drive.google.com/drive/folders/1GCyGE-LbFGgRC-FuGsF3a1zeBuzsQ1Da

# You need:
# - 2023-10-28-18-33-37/ (~900MB)
# - 2024-01-11-20-02-45/ (~900MB)

2. Create Model Repo

pip install huggingface_hub
huggingface-cli login
huggingface-cli repo create foundationpose-weights --type model

Or create at: https://huggingface.co/new (select "Model")

3. Upload Weights

cd /path/to/your/downloaded/weights

huggingface-cli upload YOUR_USERNAME/foundationpose-weights \
  ./2023-10-28-18-33-37 \
  2023-10-28-18-33-37

huggingface-cli upload YOUR_USERNAME/foundationpose-weights \
  ./2024-01-11-20-02-45 \
  2024-01-11-20-02-45

4. Configure Your Space

Add to your Space's environment variables (Settings → Variables and secrets):

FOUNDATIONPOSE_MODEL_REPO=YOUR_USERNAME/foundationpose-weights
USE_HF_WEIGHTS=true
USE_REAL_MODEL=true

5. Deploy

cd foundationpose
git push origin main

Your Space will automatically download weights on first run!

Verify It Works

Check your Space logs at: https://huggingface.co/spaces/YOUR_USERNAME/foundationpose/logs

Look for:

Downloading from Hugging Face Model Repository
Repository: YOUR_USERNAME/foundationpose-weights
✓ Download complete!

Example Model Repo Structure

Your model repo should look like:

YOUR_USERNAME/foundationpose-weights/
├── README.md
├── 2023-10-28-18-33-37/
│   ├── model_0000000.pth
│   ├── config.json
│   └── ...
└── 2024-01-11-20-02-45/
    ├── model_0000000.pth
    ├── config.json
    └── ...

Use in Other Projects

Anyone can now use your weights:

from huggingface_hub import snapshot_download

# Download weights
snapshot_download(
    repo_id="YOUR_USERNAME/foundationpose-weights",
    local_dir="./weights"
)

Make It Public or Private?

Public (Recommended):

• ✅ Anyone can use (including your Space)
• ✅ No token needed
• ✅ Community can benefit

Private:

• ✅ Control access
• ❌ Need HF token in Space secrets
• ❌ More complex setup

For private repos, add HF_TOKEN to Space secrets.

Common Issues

"Repository not found" → Check name matches: YOUR_USERNAME/foundationpose-weights

"Access denied" → Make repo public or add HF_TOKEN secret

"Download slow" → First download is cached, subsequent runs are instant

"Out of space" → Free tier: ~50GB. Upgrade or use smaller models.

Complete Example

# Assuming weights downloaded to ~/Downloads/foundationpose-weights/

# 1. Login
huggingface-cli login

# 2. Create repo
huggingface-cli repo create foundationpose-weights --type model

# 3. Upload
cd ~/Downloads/foundationpose-weights
huggingface-cli upload gpue/foundationpose-weights . .

# 4. Done! Configure your Space:
# FOUNDATIONPOSE_MODEL_REPO=gpue/foundationpose-weights
# USE_HF_WEIGHTS=true
# USE_REAL_MODEL=true

---

Full details: See UPLOAD_WEIGHTS.md for comprehensive guide.