Skip to content

Latest commit

 

History

History
183 lines (134 loc) · 4.48 KB

README-XPU.md

File metadata and controls

183 lines (134 loc) · 4.48 KB

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:

    setup_xpu.bat

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

  3. Launch the Gradio UI:

    start_gradio_ui_xpu.bat

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

Option 2: Manual Setup

  1. Create virtual environment:

    python -m venv venv_xpu

  2. Activate it:

    call venv_xpu\Scripts\activate

  3. Upgrade pip:

    python -m pip install --upgrade pip

  4. Install XPU dependencies:

    pip install -r requirements-xpu.txt

  5. Launch:

    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):

    start_gradio_ui_xpu.bat

  2. Manual (choose models interactively):

    start_gradio_ui_xpu_manual.bat

  3. API Server (REST API access):

    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: 
    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

Script Description
setup_xpu.bat One-command environment setup
start_gradio_ui_xpu.bat Launch Gradio web UI (automatic)
start_gradio_ui_xpu_manual.bat Launch Gradio UI with model selection
start_api_server_xpu.bat Launch REST API server

🎵 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!