ACE-Step 1.5 - Intel XPU Setup Guide

Quick start guide for running ACE-Step on Intel Arc GPUs and integrated graphics.

🎯 What You Need

• Intel Arc GPU: A770, A750, A580, A380, or Intel integrated graphics
• Python 3.11: Download from python.org
• Latest Intel GPU drivers: Install from Intel's website
• Internet connection: For first-time setup
• Disk space: ~5-10 GB for dependencies

🚀 Quick Start

Option 1: Automatic Setup (Recommended)

1. Run the setup script: bat setup_xpu.bat

2. Wait for installation (takes a few minutes on first run)

3. Launch the Gradio UI: bat start_gradio_ui_xpu.bat

4. Open your browser: http://127.0.0.1:7860

Option 2: Manual Setup

1. Create virtual environment: bat python -m venv venv_xpu

2. Activate it: bat call venv_xpu\Scripts\activate

3. Upgrade pip: bat python -m pip install --upgrade pip

4. Install XPU dependencies: bat pip install -r requirements-xpu.txt

5. Launch: bat start_gradio_ui_xpu.bat

📁 Model Configuration

Models should be placed in the checkpoints folder. If you already have models from a previous installation, they will be automatically detected.

Default Models

• DiT Model: acestep-v15-turbo (fast generation)
• LM Model: acestep-5Hz-lm-4B (best quality, uses CPU offload)

Launch Options

1. Automatic (uses defaults): bat start_gradio_ui_xpu.bat

2. Manual (choose models interactively): bat start_gradio_ui_xpu_manual.bat

3. API Server (REST API access): bat start_api_server_xpu.bat

⚙️ XPU Environment Variables

The bat files automatically set these performance optimizations:

set SYCL_CACHE_PERSISTENT=1
set SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS=1
set PYTORCH_DEVICE=xpu
set TORCH_COMPILE_BACKEND=eager

These settings improve XPU performance and are based on verified working configurations.

🔧 Configuration (.env file)

Create a .env file in the root directory to customize settings:

# Gradio UI Settings
PORT=7860
SERVER_NAME=127.0.0.1
LANGUAGE=en

# Model Settings
ACESTEP_CONFIG_PATH=acestep-v15-turbo
ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-4B
ACESTEP_OFFLOAD_TO_CPU=true

# API Settings
ACESTEP_API_KEY=your-secret-key

🛠️ Troubleshooting

"venv_xpu not found"

Run setup_xpu.bat to create the virtual environment.

"Intel XPU not detected"

1. Check that your GPU drivers are up to date
2. Verify PyTorch XPU installation: bat call venv_xpu\Scripts\activate python -c "import torch; print(torch.xpu.is_available())"

"torch.xpu.is_available() returns False"

Reinstall PyTorch XPU:

call venv_xpu\Scripts\activate
pip uninstall torch torchaudio torchvision
pip install --pre torch torchaudio torchvision --index-url https://download.pytorch.org/whl/nightly/xpu

Out of memory errors

1. Use a smaller LM model (0.6B or 1.7B instead of 4B)
2. Enable CPU offload in the UI
3. Close other GPU-intensive applications

Audio loading issues

• MP3/Opus/AAC files use torchaudio with ffmpeg backend (bundled)
• FLAC/WAV files use soundfile (fastest)
• If issues occur, try converting to WAV format

📊 Launch Scripts

🎵 Audio Support

• ✅ WAV/FLAC: Native support via soundfile (fastest)
• ✅ MP3: Supported via torchaudio with ffmpeg backend
• ✅ Opus/AAC: Supported via torchaudio

No additional codec installation needed!

📝 Notes

1. First launch takes longer as models are initialized
2. CPU offload is recommended for 4B LM on GPUs with <=16GB VRAM
3. torch.compile is disabled (not fully supported on XPU yet)
4. Python 3.11 is recommended for best compatibility

🆘 Need Help?

• Check the main documentation: README.md
• Verify XPU installation: Run verification commands above
• Update check: Bat files automatically check for updates on startup

🎉 You're Ready!

Once setup is complete, simply run:

start_gradio_ui_xpu.bat

And start creating music with ACE-Step on your Intel GPU!