ACE-Step 1.5

开源 AI 音乐生成引擎 · 本地部署版（macOS Apple Silicon / MLX）

Open-source AI music generation engine, running locally on consumer hardware.

⚠️ 声明 / Attribution：本项目基于 ACEMusic / StepFun 开源的 ACE-Step 1.5（MIT License）整理与本地部署。原始项目地址见文末链接。本仓库保留了完整的 MIT License 与原始文档，仅供学习、研究与本地使用。

---

项目概览

项目字段	说明
项目类型	第三方开源音乐引擎的本地部署整理
上游项目	ACE-Step / ACE-Step-1.5
主要环境	macOS / Apple Silicon，使用 MLX 相关启动配置
本仓库产出	中文启动说明、环境配置说明、下载进度查看脚本

贡献与能力边界

音乐模型与核心引擎来自上游项目。本仓库聚焦本地部署整理，不将上游模型训练、生成能力或性能成绩作为个人成果。

模型功能与硬件支持以 上游文档 为准。本仓库未提供独立性能评测，因此不作“商用级音质”或优于其他模型的比较承诺。

核心架构

ACE-Step 采用混合架构，语言模型（LM）作为全能规划器，把简单的用户输入转换成完整的歌曲蓝图（歌词、结构、元数据），再由 扩散 Transformer（DiT） 生成音乐：

组件	作用
Qwen3-Embedding-0.6B	文本编码器：prompt / 歌词 → 向量
acestep-5Hz-lm-1.7B	语言模型：生成歌词与结构的 5Hz token
acestep-v15-turbo	DiT 主扩散模型：按条件生成音乐 latent
vae	音频编解码：音乐 latent ↔ 音频波形

---

快速开始

环境要求

• Python 3.11–3.12
• macOS（Apple Silicon，推荐，MLX 后端）/ Linux（CUDA）/ Windows（CUDA）
• 模型权重约 9.4 GB 磁盘空间

1. 安装依赖

# 安装 uv（macOS / Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆并安装
git clone https://github.com/Moro-w/ACE-Step.git
cd ACE-Step
uv sync

2. 下载模型权重

模型会自动在首次运行时下载（支持 HuggingFace / ModelScope 自动切换）。也可以手动下载：

uv run acestep-download

3. 启动

# Gradio Web 界面（macOS Apple Silicon）
./start_gradio_ui_macos.sh

# 或跨平台通用方式
uv run acestep          # Gradio UI
uv run acestep-api      # REST API

启动后打开浏览器访问：

• Gradio UI：http://localhost:7860
• REST API：http://localhost:8001

4. 生成音乐

在界面中输入文字描述，例如：

"A cheerful pop song with piano accompaniment and female vocals."

生成结果会保存到 gradio_outputs/ 目录。

---

自定义配置

在项目根目录创建 .env 文件（参考 .env.example），可以配置模型、端口等。常用配置项：

ACESTEP_CONFIG_PATH=acestep-v15-turbo     # DiT 模型
ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-1.7B # LM 模型
ACESTEP_INIT_LLM=false                    # 纯 DiT 模式（跳过 LM，出歌最快）
ACESTEP_DEVICE=auto                       # 设备（auto/cuda/mps/mlx）
ACESTEP_LM_BACKEND=mlx                    # LM 后端

---

模型选择建议

GPU 显存	推荐 DiT	推荐 LM
≤6GB	2B turbo	无（纯 DiT）
6–8GB	2B turbo	acestep-5Hz-lm-0.6B
8–16GB	2B turbo/sft	acestep-5Hz-lm-0.6B / 1.7B
≥16GB	2B sft / XL turbo	acestep-5Hz-lm-1.7B

UI 会自动根据你的硬件选择最优配置。

---

项目结构

.
├── acestep/               # 核心源码（模型、生成、服务）
├── checkpoints/           # 模型权重（gitignore，需自行下载）
├── docs/                  # 详细文档
├── examples/              # 示例
├── scripts/               # 工具脚本
├── cli.py                 # 命令行入口
├── start_gradio_ui_*.sh   # 各平台启动脚本
└── README.original.md     # 原始完整文档

---

致谢 / Credits

• 原始项目：ACE-Step / ACE-Step-1.5（ACEMusic / StepFun）
• 模型下载：Hugging Face | ModelScope
• 在线体验：acemusic.ai（免费）

License

本项目遵循原始项目的 MIT License。保留原作者版权声明，感谢 ACEMusic / StepFun 的开源贡献。