ACE-Step & ACE-Step UI 完整本地部署指南

ACE-Step UI 是一款开源的 AI 音乐生成专业图形界面，作为 Suno 的完美替代方案，它基于强大的 ACE-Step 1.5 引擎。通过本指南，您可以完全在本地（免费、无限制、私有化）部署这一套强大的 AI 音乐生成环境。

核心特性 (Features)

• 完全免费且本地运行：摆脱订阅费用，无需联网即可在本地 GPU 上完成推理。
• 完整的音乐生成能力：支持生成带人声、歌词的完整歌曲（长达 4 分钟以上），支持纯音乐模式。
• ️ 高度自定义：精细控制 BPM、调式（Key）、拍号及歌曲风格标签（Style Tags）。
• 🧠 AI Enhance (智能增强)：内置 LLM 增强模式，将简单的标签自动扩写为高质量的音乐提示词。
• 专业级类 Spotify 界面：支持深/浅色模式、播放列表管理、实时生成进度队列。
• ️ 内置音频工具：集成 AudioMass 音频编辑器、Demucs 音轨分离以及视频背景生成等进阶功能。

0. 前置环境与目录规划

为了避免路径错误，本指南统一将主目录设置在 D:\AI 下。

1. 安装 Visual Studio Build Tools 2026

1. 运行安装程序。

2. 勾选所需组件：仅需勾选 “使用 C++ 的桌面开发”。

3. 关键步骤（修改路径）：点击上方的“安装位置”，将路径全部改到 D:\Microsoft Visual Studio。

   ️ 注意：安装路径名称不能和缓存路径名称相同。

4. 点击右下角的“安装”并等待完成。

2. 下载并配置依赖工具 (Node.js & FFmpeg)

1. 新建工具文件夹：D:\AI\tools
2. 配置 Node.js：
   • 前往官网下载 Node.js 的 独立文件.zip 二进制版（不要下载 .msi 安装程序）。
   • 将其解压到 D:\AI\tools 目录下。
   • 将解压后的文件夹重命名为更短的名字：node。
3. 配置 FFmpeg：
   • 下载 Windows 版本的 .exe 压缩包（请选择带 full 的完整版）。
   • 将其解压到 D:\AI\tools 目录下。
   • 将解压后的文件夹重命名为：ffmpeg。

3. 配置终端启动脚本

在 D:\AI 文件夹内新建一个名为 start_dev.bat 的脚本文件。
(双击运行该脚本时，它会打开一个终端并自动安装必要的依赖，完成后终端的工作路径应指向 D:\AI。接下来的所有步骤，都需要通过双击此脚本打开的终端来进行。)

️ 1. 部署后端模型 (ACE-Step-1.5)

双击运行 start_dev.bat 打开终端，执行以下命令：

:: 切换到 AI 目录
cd /d D:\AI

:: 克隆后端仓库
git clone https://github.com/ace-step/ACE-Step-1.5
cd ACE-Step-1.5

:: 使用 uv 同步环境 (会自动下载完整版 Python 到 D:\AI\tools\uv_python)
uv sync

:: 启动 AI 核心服务
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

成功标志：当终端提示 API endpoints enabled 时，说明后端已成功启动，运行在 8001 端口。(请保持此窗口开启，不要关闭)

️ 2. 部署 UI 服务端 (Server)

保持刚才的后端窗口运行。重新双击 start_dev.bat 打开一个新的终端窗口：

:: 切换到 AI 目录
cd /d D:\AI

:: 克隆前端 UI 仓库
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui/server

:: 安装 Node 依赖
npm install

:: 复制环境变量配置文件
copy .env.example .env

配置环境变量：
使用文本编辑器（如记事本）打开 D:\AI\ace-step-ui\server\.env 文件，找到（或手动添加）以下路径指向配置之一：

ACESTEP_PATH=D:\AI\ACE-Step-1.5
# 或者使用以下配置：
# PYTHON_PATH=D:\AI\ACE-Step-1.5\.venv\Scripts\python.exe

启动 Server 服务：

npm run dev

成功标志：终端显示服务端成功启动，运行在 3001 端口。(请保持此窗口开启)

3. 部署前端 UI (Web 界面)

保持后端和 UI服务端 的窗口都在运行。第三次双击 start_dev.bat 打开又一个新的终端窗口：

:: 切换到前端根目录
cd /d D:\AI\ace-step-ui

:: 安装前端依赖
npm install

:: 启动前端界面
npm run dev

成功标志：终端显示前端服务启动，运行在 3000 端口。(请保持此窗口开启)

4. 开始使用 (Usage)

1. 打开您的浏览器，访问前端 UI 本地地址：
   http://localhost:3000
2. 页面加载后会显示登录界面，随便输入一个任意的用户名即可登录进入。
3. 进入主界面后，您就可以像使用 Suno 一样，使用类 Spotify 风格的 UI 来尽情创作您的 AI 音乐了！

日常启动说明：
以后每次重新启动电脑后想使用 AI 音乐生成器，您只需按顺序开启三个终端：

1. 启动 ACE-Step (8001 端口)
2. 启动 UI Server (3001 端口)
3. 启动 UI Frontend (3000 端口)

Enjoy your AI music creation!