Hugging Face's logo

Spaces:
Gamahea
/
ACE-Step-Custom
Running on Zero

App Files Community
ACE-Step-Custom / DEPLOYMENT.md
ACE-Step Custom
Deploy ACE-Step Custom Edition with bug fixes
a602628
preview code
|
raw
history blame contribute delete
8.24 kB

A newer version of the Gradio SDK is available: 6.6.0

Upgrade

HuggingFace Spaces Deployment Guide

Quick Deploy to HuggingFace Spaces

Prerequisites

Method 1: Web Upload (Easiest)

  1. Create New Space

  2. Upload Files

    • Click "Files and versions" tab
    • Click "Add file" → "Upload files"
    • Upload all files from d:\2025-vibe-coding\ACE-Step-Custom\:
      • app.py
      • requirements.txt
      • config.yaml
      • README.md (with YAML frontmatter)
      • LICENSE
      • .gitignore
      • Entire src/ directory
      • Entire scripts/ directory
    • Commit changes

  3. Configure Space

    • Go to "Settings" tab
    • Set Python version: 3.10
    • Enable GPU: A10G Small (minimum) or A100 (recommended)
    • Set timeout: 30 minutes (for long generations)
    • Save settings

  4. Wait for Build

    • Space will automatically build and deploy
    • First build takes 5-10 minutes
    • Model will download on first run (~7GB)

Method 2: Git Push (For Developers)

  1. Create Space on HuggingFace

  2. Clone and Push

    # Navigate to project
cd d:\2025-vibe-coding\ACE-Step-Custom

# Initialize git (if not already)
git init
git add .
git commit -m "Initial commit"

# Add HuggingFace remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/ace-step-custom

# Push to HuggingFace
git push hf main

  3. Configure Git LFS for Large Files

    git lfs install
git lfs track "*.wav"
git lfs track "*.pth"
git lfs track "*.bin"
git lfs track "models/**"
git add .gitattributes
git commit -m "Add LFS tracking"
git push hf main

Method 3: HuggingFace CLI (Fastest)

  1. Install HuggingFace CLI

    pip install huggingface_hub

  2. Login

    huggingface-cli login
# Enter your HuggingFace token

  3. Create and Upload

    cd d:\2025-vibe-coding\ACE-Step-Custom

# Create space
huggingface-cli repo create ace-step-custom --type space --space_sdk gradio

# Upload files
huggingface-cli upload YOUR_USERNAME/ace-step-custom . --repo-type space

Space Configuration

Hardware Recommendations

GPU VRAM Cost Performance Recommended For
CPU - Free Very Slow Testing only
T4 Small 16GB ~$0.60/hr Slow Light testing
A10G Small 24GB ~$1.05/hr Good Recommended
A10G Large 24GB ~$3.15/hr Good Production
A100 Large 40GB ~$4.13/hr Excellent Best quality

Recommendation: Start with A10G Small for testing, upgrade to A100 for production.

Environment Variables (Optional)

In Space settings, you can add:

GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=7860
HF_HOME=/data/huggingface
TORCH_HOME=/data/torch

Secrets (If Needed)

For API keys or sensitive data:

  • Go to Space Settings → Repository secrets
  • Add secrets like HF_TOKEN, API_KEY, etc.
  • Access in code: os.environ.get("SECRET_NAME")

Post-Deployment Setup

First Launch

  1. Wait for Model Download

    • First launch downloads ACE-Step model (~7GB)
    • Takes 5-10 minutes depending on connection
    • Model cached for subsequent runs

  2. Test Basic Generation

    • Go to Tab 1 (Standard ACE-Step)
    • Enter simple prompt: "Happy pop song"
    • Set duration to 10 seconds
    • Click Generate

  3. Test Timeline

    • Go to Tab 2 (Timeline Workflow)
    • Enter prompt and lyrics
    • Set context length to 30s
    • Generate first clip

  4. Test LoRA Training

    • Go to Tab 3 (LoRA Training)
    • Upload 2-3 test audio files
    • Run quick training (2-3 epochs)

Monitoring

View Logs:

  • Click "Logs" tab in your Space
  • Monitor for errors or warnings
  • Check GPU usage and memory

Performance Metrics:

  • Generation time
  • Memory usage
  • Error rate
  • User feedback

Troubleshooting

Space Not Building:

  • Check requirements.txt for conflicts
  • Verify Python 3.10 compatibility
  • Check logs for specific errors

Out of Memory:

  • Upgrade to larger GPU
  • Reduce batch size in LoRA training
  • Limit generation duration

Model Not Loading:

  • Check HuggingFace Hub access
  • Verify model ID in config.yaml
  • Check internet connectivity

Slow Performance:

  • Upgrade GPU tier
  • Reduce concurrent users
  • Optimize generation parameters

Optimization Tips

Reduce Startup Time

  1. Cache Models

    # In app.py, add before model loading:
os.environ["HF_HOME"] = "/data/huggingface"

  2. Preload on Startup

    • Models download on first run
    • Cached for subsequent uses
    • Consider pre-downloading to Space

Improve Response Time

  1. Use Queuing

    • Gradio automatically queues requests
    • Set max_size in app.launch()

  2. Optimize Generation

    • Lower default duration
    • Reduce sampling steps
    • Use FP16 precision

Cost Optimization

  1. Auto-Sleep

    • Space sleeps after inactivity
    • Wakes on first request
    • Configure in Space settings

  2. Usage Limits

    • Set max concurrent users
    • Limit generation duration
    • Add rate limiting if needed

Going Live

Before Public Release

  • Test all three tabs thoroughly
  • Verify LoRA training works
  • Test with different prompts and styles
  • Check error handling
  • Review logs for issues
  • Test on mobile devices
  • Add usage examples
  • Create demo video

Public Space Settings

  1. Enable Discussions

    • Let users report issues
    • Gather feedback

  2. Add Examples

    • Create example prompts
    • Show best practices
    • Include sample outputs

  3. Update README

    • Clear usage instructions
    • Feature highlights
    • Limitations and known issues

  4. Pin Space

    • Makes it discoverable
    • Shows on your profile

Maintenance

Regular Updates 

# Update code
cd d:\2025-vibe-coding\ACE-Step-Custom
git add .
git commit -m "Update description"
git push hf main

Monitor Usage

  • Check Space analytics
  • Review user feedback
  • Monitor error rates
  • Track popular features

Scaling

If Space Gets Popular:

  1. Upgrade GPU tier
  2. Add request queuing
  3. Implement caching
  4. Consider duplicate Spaces for load balancing

Support & Community

Get Help

Share Your Space

  • Post on Twitter/X with #HuggingFace #ACEStep
  • Share in AI music communities
  • Add to your portfolio
  • Write blog post about it

Advanced Configuration

Custom Domain (Pro)

HuggingFace Pro users can set custom domains:

  1. Go to Space settings
  2. Add custom domain
  3. Configure DNS

Persistent Storage

For saving user data:

import os
PERSIST_DIR = os.environ.get("SPACE_ID", "local")
# Save to /data/{SPACE_ID}/

Analytics Integration

Add Google Analytics or similar:

# In app.py
analytics_code = """
<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR-ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'YOUR-ID');
</script>
"""

Success Checklist

Before announcing your Space:

  • ✅ All features working
  • ✅ Clear documentation
  • ✅ Example outputs included
  • ✅ Error handling robust
  • ✅ Performance optimized
  • ✅ Mobile-friendly UI
  • ✅ Clear limitations stated
  • ✅ License properly attributed
  • ✅ Usage guidelines clear
  • ✅ Contact/support info provided

Your Space URL

After deployment, your Space will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/ace-step-custom

Share it with the world! 🎵🚀