ACE-Step 1.5 安装指南

Language / 语言 / 言語: English | 中文 | 日本語

目录

• 环境要求
• 快速开始（全平台）
• 启动脚本
• Windows 便携包
• AMD / ROCm 显卡
• Intel 显卡
• 仅 CPU 模式
• Linux 注意事项
• 环境变量 (.env)
• 命令行参数
• 模型下载
• 如何选择模型？
• 开发

环境要求

快速开始（全平台）

1. 安装 uv（包管理器）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 克隆 & 安装

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync

3. 启动

Gradio 网页界面（推荐）：

uv run acestep

REST API 服务器：

uv run acestep-api

直接使用 Python（Conda / venv / 系统 Python）：

# 先激活你的环境，然后：
python acestep/acestep_v15_pipeline.py          # Gradio UI
python acestep/api_server.py                     # REST API

首次运行时模型会自动下载。打开 http://localhost:7860（Gradio）或 http://localhost:8001（API）。

🚀 启动脚本

为所有平台提供开箱即用的启动脚本。这些脚本会自动处理环境检测、依赖安装和应用启动。所有脚本默认在启动时检查更新（可配置）。

可用脚本

Windows

# 启动 Gradio 网页界面（NVIDIA CUDA）
start_gradio_ui.bat

# 启动 REST API 服务器（NVIDIA CUDA）
start_api_server.bat

# 启动 Gradio 网页界面（AMD ROCm）
start_gradio_ui_rocm.bat

# 启动 REST API 服务器（AMD ROCm）
start_api_server_rocm.bat

ROCm 用户： ROCm 脚本（start_gradio_ui_rocm.bat、start_api_server_rocm.bat）会自动设置 HSA_OVERRIDE_GFX_VERSION、ACESTEP_LM_BACKEND=pt、MIOPEN_FIND_MODE=FAST 及其他 ROCm 相关环境变量。这些脚本使用独立的 venv_rocm 虚拟环境，以避免 CUDA/ROCm wheel 冲突。

Linux

# 首次使用需添加执行权限
chmod +x start_gradio_ui.sh start_api_server.sh

# 启动 Gradio 网页界面
./start_gradio_ui.sh

# 启动 REST API 服务器
./start_api_server.sh

注意： 需要通过系统包管理器安装 Git（sudo apt install git、sudo yum install git、sudo pacman -S git）。

macOS（Apple Silicon / MLX）

macOS 脚本使用 MLX 后端，提供原生 Apple Silicon 加速（M1/M2/M3/M4）。

# 首次使用需添加执行权限
chmod +x start_gradio_ui_macos.sh start_api_server_macos.sh

# 启动 Gradio 网页界面（MLX 后端）
./start_gradio_ui_macos.sh

# 启动 REST API 服务器（MLX 后端）
./start_api_server_macos.sh

macOS 脚本会自动设置 ACESTEP_LM_BACKEND=mlx 和 --backend mlx 以启用原生 Apple Silicon 加速，在非 arm64 机器上则回退到 PyTorch 后端。

注意： 通过 xcode-select --install 或 brew install git 安装 Git。

脚本功能

• 启动时自动检查更新（默认启用，可配置）
• 自动环境检测（便携 Python 或 uv）
• 自动安装 uv（如需要）
• 可配置下载源（HuggingFace/ModelScope）
• 可自定义模型和参数

如何修改配置

所有可配置选项均定义为每个脚本顶部的变量。如需自定义，请用文本编辑器打开脚本并修改变量值。

示例：将界面语言改为中文并使用 1.7B LM 模型

set LANGUAGE=en
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-0.6B

set LANGUAGE=zh
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B

LANGUAGE="en"
LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-0.6B"

LANGUAGE="zh"
LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-1.7B"

示例：禁用启动时更新检查

REM set CHECK_UPDATE=true
set CHECK_UPDATE=false

# CHECK_UPDATE="true"
CHECK_UPDATE="false"

示例：启用已注释的选项 —— 删除注释前缀（.bat 用 REM，.sh 用 #）：

REM set SHARE=--share

set SHARE=--share

# SHARE="--share"

SHARE="--share"

常用可配置选项：

更新与维护工具

更新工作流：

# Windows                          # Linux / macOS
check_update.bat                    ./check_update.sh
merge_config.bat                    ./merge_config.sh

🪟 Windows 便携包

为 Windows 用户提供了预装依赖的便携包：

1. 下载并解压：ACE-Step-1.5.7z
2. 包含 python_embedded，所有依赖已预装
3. 要求： CUDA 12.8

快速启动脚本

两个脚本均支持自动环境检测、自动安装 uv、可配置下载源、可选 Git 更新检查、可自定义模型和参数。

配置

start_gradio_ui.bat：

REM 界面语言 (en, zh, he, ja)
set LANGUAGE=zh

REM 下载源 (auto, huggingface, modelscope)
set DOWNLOAD_SOURCE=--download-source modelscope

REM Git 更新检查 (true/false)
set CHECK_UPDATE=true

REM 模型配置
set CONFIG_PATH=--config_path acestep-v15-turbo
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B

更新与维护

AMD / ROCm 显卡

⚠️ uv run acestep 会安装 CUDA PyTorch wheels，可能覆盖已有的 ROCm 环境。

推荐工作流

# 1. 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate

# 2. 安装 ROCm 兼容的 PyTorch
pip install torch --index-url https://download.pytorch.org/whl/rocm6.0

# 3. 安装 ACE-Step
pip install -e .

# 4. 启动服务
python -m acestep.acestep_v15_pipeline --port 7680

GPU 检测问题排查

如果显示 "No GPU detected, running on CPU"：

1. 运行诊断工具：python scripts/check_gpu.py
2. RDNA3 GPU 设置 HSA_OVERRIDE_GFX_VERSION：

3. Windows 上使用 start_gradio_ui_rocm.bat / start_api_server_rocm.bat
4. 验证 ROCm 安装：rocm-smi

Linux（cachy-os / RDNA4）

详见 ACE-Step1.5-Rocm-Manual-Linux.md

Intel 显卡

注意：生成超过 2 分钟的音频时，LLM 推理速度可能下降。Intel 独立显卡预计可用但尚未测试。

仅 CPU 模式

ACE-Step 可以在 CPU 上运行仅推理，但速度会显著变慢。

• 不推荐在 CPU 上训练（包括 LoRA）。
• 低显存系统可使用 DiT-only 模式（禁用 LLM）。

如果没有 GPU，建议：

• 使用云 GPU 服务
• 仅运行推理工作流
• 使用 ACESTEP_INIT_LLM=false 启用 DiT-only 模式

Linux 注意事项

Python 3.11 预发布版问题

部分 Linux 发行版（包括 Ubuntu）自带 Python 3.11.0rc1 预发布版，可能导致 vLLM 后端出现段错误。

建议： 使用稳定版 Python（≥ 3.11.12）。Ubuntu 上可通过 deadsnakes PPA 安装。

如无法升级 Python，使用 PyTorch 后端：

uv run acestep --backend pt

环境变量 (.env)

cp .env.example .env   # 复制并编辑

关键变量

LLM 初始化 (ACESTEP_INIT_LLM)

处理流程：GPU 检测 → ACESTEP_INIT_LLM 覆盖 → 模型加载

示例 .env：

# 自动模式（推荐）
ACESTEP_INIT_LLM=auto

# 低显存 GPU 强制启用
ACESTEP_INIT_LLM=true
ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-0.6B

# 禁用 LLM 加速生成
ACESTEP_INIT_LLM=false

命令行参数

Gradio UI (acestep)

示例：

# 公开访问 + 中文界面
uv run acestep --server-name 0.0.0.0 --share --language zh

# 启动时预初始化模型
uv run acestep --init_service true --config_path acestep-v15-turbo

# 使用 ModelScope 下载
uv run acestep --download-source modelscope

📥 模型下载

首次运行时模型会从 HuggingFace 或 ModelScope 自动下载。

CLI 下载

uv run acestep-download                              # 下载主模型
uv run acestep-download --all                         # 下载所有模型
uv run acestep-download --download-source modelscope  # 从 ModelScope 下载
uv run acestep-download --model acestep-v15-sft       # 指定模型
uv run acestep-download --list                        # 列出所有可用模型

手动下载 (huggingface-cli)

# 主模型
huggingface-cli download ACE-Step/Ace-Step1.5 --local-dir ./checkpoints

# 可选模型
huggingface-cli download ACE-Step/acestep-5Hz-lm-0.6B --local-dir ./checkpoints/acestep-5Hz-lm-0.6B
huggingface-cli download ACE-Step/acestep-5Hz-lm-4B --local-dir ./checkpoints/acestep-5Hz-lm-4B

共享模型目录

如果你有多个 ACE-Step 安装（例如训练器、不同版本），可以共享同一个模型目录以避免重复下载、节省磁盘空间：

# 添加到 shell 配置文件（~/.bashrc、~/.zshrc 等）
export ACESTEP_CHECKPOINTS_DIR=~/ace-step-models

所有安装将使用相同的模型文件。也可以在 .env 文件中设置。

可用模型

💡 如何选择模型？

ACE-Step 会自动适配你的 GPU 显存。UI 会根据检测到的 GPU 等级预配置所有设置（LM 模型、后端、卸载、量化）：

📖 详细 GPU 兼容性信息（等级表、时长限制、批量大小、自适应 UI 默认设置、显存优化），请参阅 GPU 兼容性指南。

开发

# 添加依赖
uv add package-name
uv add --dev package-name

# 更新所有依赖
uv sync --upgrade