ACE-Step UI 零基础上手：本地 AI 音乐生成工具完整部署与快速入门-育师

ACE-Step UI 零基础上手：本地 AI 音乐生成工具完整部署与快速入门

【免费下载链接】ace-step-ui🎵 The Ultimate Open Source Suno Alternative - Professional UI for ACE-Step 1.5 AI Music Generation. Free, local, unlimited. Stop paying for Suno!项目地址: https://gitcode.com/GitHub_Trending/ac/ace-step-ui

ACE-Step UI 是一款开源、本地运行的 AI 音乐生成工具，为 ACE-Step 1.5 模型提供专业级创作界面，是 Suno 的开源替代方案。如果你有一块 NVIDIA 显卡、想在自己电脑上生成带人声的完整歌曲，按本文装完后，即可在浏览器打开 http://localhost:3000 开始出歌。

硬件与软件要求预检

部署前先对照下表确认环境，缺哪项先补哪项：

项目	要求	说明
操作系统	Windows / Linux / macOS	项目为三平台都提供了脚本
Node.js	18 或更高	前端与后端服务的基础运行环境
Python	3.10+（推荐 3.11）	Windows 可选官方便携包，免安装
显卡	NVIDIA，显存 4GB+	推荐 12GB+，不足时 Thinking Mode 不可用
FFmpeg	任意较新版本	音频处理依赖，缺失会导致歌曲时长显示异常
uv	任意较新版本	运行 AI 引擎所用的 Python 包管理工具
磁盘空间	建议预留 15GB 以上	模型文件约 5GB，另有 Python 与 Node 依赖
网络	首次运行需稳定连接	模型文件在首次启动时自动下载

阶段一：拿到代码，把引擎摆到位

ACE-Step UI 与 AI 引擎（ACE-Step 1.5）分属两个仓库，UI 仓库本身不含任何模型文件。启动脚本默认在上级目录的ACE-Step-1.5中查找引擎，因此最简单的布局是让两个目录并排存放。

克隆 UI 仓库

Windows 打开 CMD 或 PowerShell，Linux/macOS 打开终端，执行：

git clone https://gitcode.com/GitHub_Trending/ac/ace-step-ui cd ace-step-ui

摆放 ACE-Step 1.5 引擎

将 ACE-Step 1.5 引擎克隆到同级目录ACE-Step-1.5，并用uv venv与uv pip install -e .建好虚拟环境；Windows 用户也可以改用官方便携包（约 5GB，内含 Python 运行环境与 CUDA 12.8，解压即用）。如果引擎放在别处，用环境变量把实际路径告诉脚本：

export ACESTEP_PATH=/path/to/ACE-Step-1.5 # Linux / macOS set ACESTEP_PATH=C:\path\to\ACE-Step-1.5 # Windows

阶段二：一键配置环境

进入项目目录运行安装脚本，它会自动完成三件事：安装前后端依赖、生成.env配置文件（结构可参考 server/.env.example）、初始化本地 SQLite 数据库：

./setup.sh # Linux / macOS setup.bat # Windows

看到 "Setup Complete" 字样即代表本阶段完成。偏好手动操作的话，也可以分别在根目录与 server/ 目录执行npm install，再把server/.env.example复制为server/.env。

阶段三：启动全部服务

启动脚本会按顺序拉起 ACE-Step API（端口 8001）、后端服务（端口 3001）与前端页面（端口 3000），并自动打开浏览器：

./start-all.sh # Linux / macOS start-all.bat # Windows

运行日志会写入项目根目录的logs/文件夹；用完之后执行./stop-all.sh即可干净地停掉全部服务。

模型文件自动下载与手动兜底

API 服务首次启动时，ACE-Step 会自动下载主模型（约 5GB）并显示进度，之后每次启动都会跳过这一步。若下载中断，可以这样做：

确认ACESTEP_PATH指向的引擎目录磁盘空间充足，且没有残留的损坏文件；
直接重跑start-all.sh，让下载从头再来一遍；
到logs/下的api.log里查看具体报错，判断是网络问题还是路径问题。

自动下载反复失败时，可从 ACE-Step 官方渠道手动获取模型文件放入引擎的模型目录，再重新启动即可。

首次运行：生成你的第一首 AI 歌曲

浏览器打开 http://localhost:3000，看到的是 Spotify 风格的曲库界面。左侧创作面板里填入歌词或歌曲描述，选好风格标签（例如 Industrial Metal），还可以微调时长、BPM、调式等参数。点击生成后进度实时可见，完成的歌曲会进入曲库，随时可播放、加入歌单，或送入内置音频编辑器做剪辑。如果风格总生成得"千人一面"，打开 AI Enhance 开关，让 LLM 帮你把风格标签扩写成更详细的描述。

同一局域网内的其他设备也可以通过http://你的内网IP:3000访问这个界面，记得在防火墙放行对应端口。

常见故障速查表

现象	可能原因	解决方法
脚本报 "ACE-Step not found"	引擎目录不在默认同级位置，或未设置路径变量	按阶段一设置`ACESTEP_PATH`后重跑`start-all.sh`
启动被拒，提示依赖未安装	未执行 setup.sh / setup.bat	先跑安装脚本，再启动服务
页面能打开，但生成请求失败	ACE-Step API 未正常启动，或 8001 端口被占用	查看`logs/api.log`，确认 API 进程存活
CUDA out of memory	显存不足	保持默认 PT 后端、批量大小设为 1、缩短时长、关闭 Thinking Mode
生成歌曲时长显示 0:00	未安装 FFmpeg	安装 FFmpeg 后重新生成
局域网其他设备无法访问	防火墙拦截	放行 3000 与 3001 端口