Side-Step on Modal - Complete Setup Guide

This repository contains scripts and instructions to run Side-Step LoRA training on Modal, a serverless GPU platform. This allows you to train high-quality audio models without needing a powerful local GPU. You only pay for the exact seconds you use.

⚠️ Important Scope: These scripts are designed for the training stage only. They assume you have already built your dataset and preprocessed your audio files locally into a tensors folder. This preprocessed folder is what you will upload to Modal for training.

🌟 Why use Modal?

• Serverless Performance: No need to manage servers, install drivers, or pay for idle time. The environment spins up when you start and disappears when you're done.
• Pay Only for Execution: Traditional services (like RunPod or Lambda) often charge for a full hour or require you to pay while a machine is sitting idle. Modal charges by the second and only while your code is actually running.
• Cost-Effective in Real Terms: While Modal's hourly rate might be higher than some persistent instance providers, it often works out cheaper because you never pay for setup time, idle time, or disk storage for "stopped" instances.
• $30 Monthly Free Credit: Modal currently provides $30 of free credits every month—plenty for exploring and running several training jobs on high-end GPUs.
• Powerful GPUs: Instant access to A10G (24GB), L4 (24GB), or H100 (80GB) on demand without waiting for availability.

---

🚀 Getting Started (For Beginners)

1. Register for Modal

1. Go to modal.com and sign up (usually with GitHub).
2. You will get $30 of free credits per month as of now, which is enough for several training runs!

2. Install Python locally

If you don't have Python, download and install it from python.org.

3. Install Modal and Authenticate

Open your terminal (Command Prompt, PowerShell, or Terminal on Mac) and run:

# Install the modal package
pip install modal

# Authenticate your machine
modal token new

This will open your browser. Click Approve to link your computer to your Modal account.

---

📦 One-Time Setup

1. Clone this repository

Download these scripts to a folder on your computer.

2. Create Modal Volumes

Modal uses "Volumes" to store your models and data. Create them by running:

modal volume create sidestep-models
modal volume create sidestep-tensors
modal volume create sidestep-output

3. Upload the ACE-Step Base Model

You need to upload the base model checkpoint once.

# Replace /path/to/acestep-v15-xl-base with the actual path on your PC
# or whichever model you want to train on
python upload_models.py /path/to/acestep-v15-xl-base

This uploads ~6GB. It takes about 10-15 minutes depending on your internet speed.

---

🛠️ Per-Job Workflow

Step 1: Upload your Dataset (Tensors)

After preprocessing your audio into tensors locally:

# Format: python upload_tensors.py <local_folder> <dataset_name_on_modal>
python upload_tensors.py C:\my_tensors\my_dataset my-dataset

Step 2: Generate & Run Training Command

1. Use the Side-Step Jobs Queue Webform to build your training command.
2. The webform generates a command for local use, starting with call uv run.
3. To run it on Modal, you must wrap the command like this:
   • Remove call uv run.
   • Start with modal run sidestep_modal.py --cmd ".
   • Paste the rest of the command and close it with a double quote ".

Example Conversion:

Webform output: call uv run sidestep --yes train --checkpoint-dir "" --dataset-dir "" --model xl-base ...

Modal command:

modal run sidestep_modal.py --cmd "sidestep --yes train --checkpoint-dir /checkpoints --dataset-dir /tensors/my-dataset --output-dir /output/my-lora --model acestep-v15-xl-base --rank 128 --alpha 256 --batch-size 2 --epochs 800"

Note: Ensure you update the paths to use Modal volumes: /checkpoints, /tensors/your-dataset, and /output/your-lora.

Step 3: Download your trained LoRA

Once training is finished, download your results:

# List all outputs in the volume
python download_outputs.py --list

# Download a specific LoRA
# Format: python download_outputs.py <remote_name> <local_destination>
python download_outputs.py my-lora C:\my_downloads\my-lora

---

🔄 Automatic Resume & Preemption

Modal's basic tier uses "preemptible" instances. This means your training might be interrupted if the system needs the GPU for another task.

Don't worry!

• Modal automatically restarts any training job that was interrupted.
• The sidestep_modal.py script includes an Automatic Resume function. Before starting, it checks your /output volume for existing checkpoints (epoch_*).
• If it finds a previous checkpoint, it will automatically append the --resume flag to your command and continue from the latest saved epoch.
• This ensures you don't lose progress and only pay for the work that still needs to be done.

---

🧹 Housekeeping

To save on storage costs (~$0.10/GB/month), you can clean up old datasets or outputs:

# Clean up temporary tensors
python cleanup-tensors-volume.py

# Clean up outputs (Be careful! Download them first)
python cleanup-output-volume.py

---

💡 Pro Tips for Novices

• Detach training: If you want to close your terminal while training, add --detach to the command: modal run sidestep_modal.py --cmd "..." --detach
• Monitor in browser: You can see live logs and GPU usage at modal.com/apps.
• GPU Types: By default, the script uses an A10G. You can change this in sidestep_modal.py to L4 (cheaper) or A100 (faster/more memory).

---

📄 Included Scripts

• sidestep_modal.py: The main app that defines the cloud environment and runs commands.
• upload_models.py: Helper to upload large base models.
• upload_tensors.py: Helper to upload your preprocessed datasets.
• download_outputs.py: Helper to retrieve your trained .safetensors files.
• cleanup-*.py: Scripts to manage your cloud storage.

---

Created by mmoalem. Aimed at making high-end audio AI training accessible to everyone.