ACE-Step 共绩算力镜像

基于共绩算力的无服务器 ACE-Step 部署方案

共绩算力平台 | GitHub 仓库 | 共绩算力平台 | Discord 社区

📋 目录

✨ 特性
📦 快速部署
🚀 使用方法
🏗️ 架构说明
🔧 自定义配置
📊 性能优化
🔨 开发指南

📝 项目简介

我们提供了一套完整的 ACE-Step 共绩算力镜像部署方案，让您能够轻松在共绩算力平台上部署和运行 ACE-Step 音乐生成模型。该方案提供了直观的 Web 界面，支持复杂的音乐生成工作流。

ACE-Step 是由人工智能公司阶跃星辰（StepFun）与数字音乐平台 ACE Studio 联合研发并于 2025 年 5 月 7 日开源。模型在 A100 GPU 上只需 20 秒即可合成长达 4 分钟的音乐，比基于 LLM 的基线快 15 倍，同时在旋律、和声和节奏指标方面实现了卓越的音乐连贯性和歌词对齐。此外，该模型保留了精细的声学细节，支持高级控制机制，例如语音克隆、歌词编辑、混音和音轨生成。

🎯 核心优势

🚀 一键部署: 预配置的 Docker 镜像，支持在共绩算力上快速部署
🎨 可视化界面: 基于 Gradio 的 Web 界面，支持直观的音乐生成操作
⚡ 高性能: 优化的 CUDA 12.6 环境，支持 GPU 加速推理
🔧 灵活配置: 支持自定义模型和参数配置
📊 实时监控: 内置健康检查和日志监控功能
💰 按需付费: 只为使用时间付费，弹性算力资源

📢 最新更新

🔥 2025.01.15: 发布 ACE-Step 共绩算力镜像 v1.0
- 支持 ACE-Step 3.5B 模型推理
- 集成 Gradio Web 界面
- 优化内存使用，支持 8GB+ GPU
- 添加健康检查和自动重启功能
- 支持共绩算力弹性部署服务
🎮 2025.01.10: 添加高级功能支持
- 支持 LoRA 模型加载
- 添加音频处理功能
- 支持批量推理
- 集成模型缓存机制
- 支持预制镜像快速部署

✨ 特性

🎵 音乐生成能力

🌈 多样化风格支持

🎸 支持主流音乐风格，包括流行、摇滚、电子、古典等
🎷 支持多种乐器音色和编曲风格
🎼 支持复杂的多轨道音乐生成

🌍 多语言支持

🗣️ 支持 19 种语言的歌词生成
🇺🇸 英语、🇨🇳 中文、🇷🇺 俄语、🇪🇸 西班牙语等
⚠️ 注意：由于数据不平衡，较少使用的语言可能表现较差

🎤 人声技术

🎙️ 支持多种人声风格和技巧
🗣️ 支持不同的人声表达和演唱技巧
🎵 支持人声与伴奏的完美融合

🎛️ 控制能力

🔄 变体生成

⚙️ 使用训练无关的推理时优化技术
🌊 Flow-matching 模型生成初始噪声，然后使用 trigFlow 的噪声公式添加额外的高斯噪声
🎚️ 可调节原始初始噪声和新高斯噪声之间的混合比例来控制变体程度

🎨 重绘功能

🖌️ 通过对目标音频输入添加噪声并在 ODE 过程中应用掩码约束来实现
🔍 当输入条件与原始生成不同时，可以只修改特定方面而保留其余部分
🔀 可以与变体生成技术结合，在风格、歌词或人声方面创建局部变体

✏️ 歌词编辑

💡 创新性地应用 flow-edit 技术，实现局部歌词修改，同时保留旋律、人声和伴奏
🔄 适用于生成内容和上传音频，大大增强创作可能性
ℹ️ 当前限制：一次只能修改小段歌词以避免失真，但可以顺序应用多次编辑

🚀 应用场景

🎤 Lyric2Vocal (LoRA)

🔊 基于纯人声数据微调的 LoRA，允许从歌词直接生成人声样本
🛠️ 提供众多实用应用，如人声演示、指导轨道、歌曲创作辅助和人声编曲实验
⏱️ 提供快速测试歌词演唱效果的方法，帮助词曲作者更快地迭代

📝 Text2Samples (LoRA)

🎛️ 类似于 Lyric2Vocal，但在纯器乐和样本数据上微调
🎵 能够从文本描述生成概念性音乐制作样本
🧰 用于快速创建乐器循环、音效和音乐制作元素

🖥️ 硬件性能

我们在不同硬件配置上评估了 ACE-Step ComfyUI 的性能，得到以下吞吐量结果：

设备	RTF (27步)	渲染1分钟音频时间 (27步)	RTF (60步)	渲染1分钟音频时间 (60步)
NVIDIA RTX 4090	34.48 ×	1.74 s	15.63 ×	3.84 s
NVIDIA A100	27.27 ×	2.20 s	12.27 ×	4.89 s
NVIDIA RTX 3090	12.76 ×	4.70 s	6.48 ×	9.26 s
MacBook M2 Max	2.27 ×	26.43 s	1.03 ×	58.25 s

我们使用 RTF（实时因子）来衡量 ACE-Step 的性能。更高的值表示更快的生成速度。27.27x 意味着生成1分钟的音乐需要2.2秒（60/27.27）。性能在单GPU上测量，批次大小为1，步数为27。

📦 快速部署

1. 在共绩算力上运行 ACE-Step

共绩算力平台提供预构建的 ACE-Step 容器镜像，用户无需本地复杂环境配置，可快速完成部署并启用服务。以下是详细部署步骤：

1.1 创建部署服务

登录共绩算力控制台，在控制台首页点击"弹性部署服务"进入管理页面。首次使用需确保账户已开通弹性部署服务权限。

1.2 选择 GPU 型号

根据实际需求选择 GPU 型号：

初次使用或调试阶段：推荐配置单张 NVIDIA RTX 4090 GPU
生产环境：推荐使用 NVIDIA A100 GPU 以获得最佳性能

1.3 选择预制镜像

在"服务配置"模块切换至"预制服务"选项卡，搜索并选择 ACE-Step 官方镜像。

1.4 部署并访问服务

点击"部署服务"，平台将自动拉取镜像并启动容器。

部署完成后，在"快捷访问"中找到端口为 7865 的公网访问链接，点击即可在浏览器中使用 ACE-Step 的 Web 界面，或通过该地址调用 API 服务。

2. 本地开发环境部署

2.1 克隆仓库

首先，克隆 ACE-Step 共绩算力镜像仓库到本地机器并进入项目目录：

git clone https://github.com/gongjiyun/ace-step-worker.git
cd ace-step-worker

2.2 环境要求

确保您已安装以下软件：

Docker: 版本 20.10 或更高版本
Docker Compose: 版本 2.0 或更高版本
NVIDIA Docker: 用于 GPU 支持

2.3 使用 Docker Compose 部署

选项 A: 使用预构建镜像

创建 docker-compose.yml 文件：

version: '3.8'
services:
  ace-step-comfyui:
    image: gongjiyun/ace-step-comfyui:latest
    container_name: ace-step-comfyui
    hostname: ace-step-comfyui
    stop_grace_period: 2s
    ports:
      - "7865:7865"
    volumes:
      - ./checkpoints:/app/checkpoints
      - ./outputs:/app/outputs
      - ./logs:/app/logs
      - ./workflows:/app/workflows
    environment:
      - ACE_OUTPUT_DIR=/app/outputs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7865/"]
      interval: 60s
      timeout: 10s
      retries: 30
      start_period: 3s
    restart: unless-stopped
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: ["compute", "utility", "graphics", "video"]

启动服务：

docker-compose up -d

选项 B: 本地构建镜像

构建镜像：

docker build -t ace-step-comfyui:latest .

运行容器：

docker run -d \
  --name ace-step-comfyui \
  --gpus all \
  -p 7865:7865 \
  -v $(pwd)/checkpoints:/app/checkpoints \
  -v $(pwd)/outputs:/app/outputs \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/workflows:/app/workflows \
  ace-step-comfyui:latest

3. 验证部署

访问 http://localhost:7865 查看 ComfyUI 界面。

注意: 使用 Safari 浏览器时，音频可能无法直接播放，需要下载后进行播放。

🚀 使用方法

🔍 基本使用

该项目提供多任务创作面板：Text2Music Tab、Retake Tab、Repainting Tab、Edit Tab 和 Extend Tab。

访问界面: 打开浏览器访问 http://localhost:7865
配置参数: 设置音乐生成参数
开始生成: 点击运行按钮开始音乐生成

⚙️ 高级配置

环境变量配置

# 模型路径配置
ACE_MODEL_PATH=/app/checkpoints/ace-step-v1-3.5b

# 输出目录配置
ACE_OUTPUT_DIR=/app/outputs

# GPU 配置
CUDA_VISIBLE_DEVICES=0

# 内存优化
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

命令行参数

# 启动 ACE-Step 服务器
python acestep/gui.py \
  --server_name 0.0.0.0 \
  --port 7865 \
  --bf16 true

🔍 API 使用

如果您打算将 ACE-Step 作为库集成到自己的 Python 项目中，可以使用以下 pip 命令直接从 GitHub 安装最新版本。

通过 pip 直接安装：

确保已安装 Git: 此方法需要系统上安装 Git 并在系统的 PATH 中可访问。
执行安装命令：

pip install git+https://github.com/gongjiyun/ace-step-worker.git

建议在虚拟环境中使用此命令以避免与其他包冲突。

3. API 调用指南

ACE-Step 提供完整的 API 接口体系，支持通过编程方式实现音乐创作全流程自动化。以下为核心接口详解与调用示范：

3.1 环境准备

pip install gradio_client

from gradio_client import Client, handle_file

client = Client("https://<您的部署 ID>.550c.cloud/")

3.2 核心功能接口

1. 文本生成音乐（Text2Music）

result = client.predict(
    format="wav",                         # 输出格式 [mp3/ogg/flac/wav]
    audio_duration=-1,                    # 时长 (秒)，-1=随机生成
    prompt="pop, upbeat, guitar, 120 BPM", # 音乐描述标签
    lyrics="[verse] 清晨的阳光...[chorus] 自由飞翔...",  # 带结构标签的歌词
    infer_step=60,                        # 推理步数（建议 50-80）
    guidance_scale=15,                    # 控制生成自由度
    cfg_type="apg",                       # 配置类型 [cfg/apg/cfg_star]
    manual_seeds="12345",                 # 固定种子值保证可复现
    api_name="/__call__"                  # 固定端点名称
)

audio_path = result[0]  # 生成的音频路径
params_json = result[1] # 参数 JSON（用于后续操作）

2. 音乐编辑（Edit）

result = client.predict(
    edit_type="remix",                    # 编辑模式 [only_lyrics/remix]
    edit_prompt="rock, electric guitar",  # 新音乐标签
    edit_lyrics="[chorus] 新的副歌歌词...",  # 新歌词
    edit_n_min=0.7,                       # 最小保留比例（0-1）
    source_audio=handle_file("原曲.wav"), # 上传待编辑音频
    api_name="/edit_process_func"
)

3. 音乐扩展（Extend）

result = client.predict(
    left_extend_length=10,     # 开头延长秒数
    right_extend_length=15,    # 结尾延长秒数
    extend_source="text2music",# 源类型 [text2music/upload]
    source_audio=handle_file("原曲.wav"),
    api_name="/extend_process_func"
)

4. 局部重生成（Retake）

result = client.predict(
    json_data=params_json,     # 原始生成参数
    retake_variance=0.3,       # 变化强度（0.1 微调，>0.5 巨变）
    retake_seeds="67890",      # 新种子值
    api_name="/retake_process_func"
)

3.3 高级控制参数

参数	作用	推荐值
guidance_interval	控制节奏变化密度	0.3-0.7
omega_scale	音符粒度精细度	8-12
use_erg_diffusion	启用声学细节增强	True
ref_audio_strength	语音克隆强度（需上传参考音频）	0.5-0.8
lora_weight	风格 LoRA 权重（如中文说唱）	0.7-1.0

通过 API 集成，开发者可构建自动化音乐生产线，结合 Retake 的种子控制、Edit 的歌词替换、Extend 的时长扩展等功能，实现全链路音乐创作智能化。

📱 用户界面指南

ACE-Step Web 界面提供了多个选项卡，用于不同的音乐生成和编辑任务：

📝 Text2Music 选项卡

📋 输入字段：
- 🏷️ 标签: 输入描述性标签、音乐流派或场景描述，用逗号分隔
- 📜 歌词: 输入带有结构标签的歌词，如 [verse]、[chorus] 和 [bridge]
- ⏱️ 音频时长: 设置生成音频的所需时长（-1 表示随机生成）
⚙️ 设置：
- 🔧 基本设置: 调整推理步数、指导比例和种子值
- 🔬 高级设置: 微调调度器类型、CFG 类型、ERG 设置等参数
🚀 生成: 点击"Generate"按钮，根据输入内容创作音乐

🔄 Retake 选项卡

🎲 通过不同种子值重新生成音乐并产生细微变化
🎚️ 调整变化参数以控制新版本与原版的差异程度

🎨 Repainting 选项卡

🖌️ 选择性地重新生成音乐的特定部分
⏱️ 指定要重绘部分的开始和结束时间
🔍 选择源音频（text2music 输出、上次重绘或上传）

✏️ Edit 选项卡

🔄 通过修改标签或歌词来改编现有音乐
🎛️ 可选择"only_lyrics"模式（保留原旋律）或"remix"模式（改变旋律）
🎚️ 通过调整编辑参数控制对原曲的保留程度

📏 Extend 选项卡

➕ 在现有音乐的开头或结尾添加音乐片段
📐 指定左右两侧的扩展时长
🔍 选择需要扩展的源音频

🏗️ 架构说明

📁 项目结构

ace-step-worker/
├── Dockerfile                 # Docker 镜像构建文件
├── docker-compose.yaml        # Docker Compose 配置
├── requirements.txt           # Python 依赖
├── acestep/                  # ACE-Step 核心文件
│   ├── gui.py                # Web 界面
│   ├── pipeline_ace_step.py  # 推理管道
│   └── models/               # 模型文件
├── checkpoints/              # 模型检查点
├── outputs/                  # 输出文件
├── logs/                     # 日志文件
└── examples/                 # 示例文件

🔧 核心组件

🐳 Docker 配置

Dockerfile 解读：

# 基础镜像：CUDA 12.6 + Ubuntu 22.04
FROM nvidia/cuda:12.6.0-runtime-ubuntu22.04 AS base

# 环境变量设置
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PORT=7865 \
    HF_HUB_ENABLE_HF_TRANSFER=1 \
    DEBIAN_FRONTEND=noninteractive

# 安装 Python 和系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.10 \
    python3-pip \
    python3-venv \
    python3-dev \
    build-essential \
    git \
    curl \
    wget \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && ln -s /usr/bin/python3 /usr/bin/python

# 创建并激活虚拟环境
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 创建非 root 用户
RUN useradd -m -u 1001 appuser

# 设置工作目录
WORKDIR /app

# 克隆仓库
RUN git clone https://github.com/ace-step/ACE-Step.git .

# 安装特定版本的 PyTorch（兼容 CUDA 12.6）
RUN pip3 install --no-cache-dir --upgrade pip && \
    pip3 install --no-cache-dir hf_transfer peft && \
    pip3 install --no-cache-dir -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu126
RUN pip3 install --no-cache-dir .

# 确保卷的目标目录存在并具有正确的初始所有权
RUN mkdir -p /app/outputs /app/checkpoints /app/logs && \
    chown -R appuser:appuser /app/outputs /app/checkpoints /app/logs

# 将应用程序文件的所有权更改为 appuser
RUN chown -R appuser:appuser /app

# 切换到非 root 用户
USER appuser

# 暴露应用程序运行的端口
EXPOSE 7865

VOLUME [ "/app/checkpoints", "/app/outputs", "/app/logs" ]

# 设置健康检查
HEALTHCHECK --interval=60s --timeout=10s --start-period=5s --retries=5 \
  CMD curl -f http://localhost:7865/ || exit 1

# 运行应用程序的命令（支持 GPU）
CMD ["python3", "acestep/gui.py", "--server_name", "0.0.0.0", "--bf16", "true"]

关键特性：

🐳 基于 NVIDIA CUDA 12.6 运行时环境
🔒 使用非 root 用户运行，提高安全性
📦 预安装所有必要的 Python 依赖
🔍 内置健康检查机制
💾 支持数据卷挂载

🚀 Docker Compose 配置

docker-compose.yaml 解读：

services:
  ace-step-comfyui:
    build:
      context: https://github.com/ace-step/ACE-Step.git
      dockerfile: Dockerfile
    container_name: ace-step-comfyui
    hostname: ace-step-comfyui
    stop_grace_period: 2s
    ports:
      - "7865:7865"  # 暴露 ComfyUI 端口
    volumes:
      - ./checkpoints:/app/checkpoints  # 模型检查点
      - ./outputs:/app/outputs          # 输出文件
      - ./logs:/app/logs                # 日志文件
    environment:
      - ACE_OUTPUT_DIR=/app/outputs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7865/"]
      interval: 60s
      timeout: 10s
      retries: 30
      start_period: 3s
    restart: unless-stopped
    runtime: nvidia  # 启用 NVIDIA 运行时
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: ["compute", "utility", "graphics", "video"]

关键特性：

🎮 完整的 GPU 支持配置
🔄 自动重启策略
📊 健康检查监控
💾 数据持久化存储
🔧 环境变量配置

🔧 自定义配置

📦 依赖管理

requirements.txt 解读：

# 核心依赖
datasets==3.4.1              # Hugging Face 数据集
diffusers>=0.33.0            # 扩散模型框架
gradio                        # Web 界面框架
librosa==0.11.0              # 音频处理
loguru==0.7.3                # 日志管理
matplotlib==3.10.1           # 数据可视化
numpy                        # 数值计算
pypinyin==0.53.0             # 中文拼音处理
pytorch_lightning==2.5.1     # PyTorch 训练框架
soundfile==0.13.1            # 音频文件处理
torch                        # PyTorch 深度学习框架
torchaudio                   # PyTorch 音频处理
torchvision                  # PyTorch 计算机视觉
tqdm                         # 进度条
transformers==4.50.0         # Hugging Face 转换器
py3langid==0.3.0             # 语言识别
hangul-romanize==0.1.0       # 韩文罗马化
num2words==0.5.14            # 数字转文字
spacy==3.8.4                 # 自然语言处理
accelerate==1.6.0            # Hugging Face 加速库
cutlet                       # 日文罗马化
fugashi[unidic-lite]         # 日文分词
click                        # 命令行界面
peft                         # 参数高效微调
tensorboard                  # 训练监控
tensorboardX                 # TensorBoard 扩展

🔧 环境变量配置

# 基础配置
PYTHONDONTWRITEBYTECODE=1    # 不生成 .pyc 文件
PYTHONUNBUFFERED=1           # 无缓冲输出
PORT=7865                    # 服务端口
HF_HUB_ENABLE_HF_TRANSFER=1  # 启用 HF 传输
DEBIAN_FRONTEND=noninteractive  # 非交互式安装

# GPU 配置
CUDA_VISIBLE_DEVICES=0       # 指定 GPU 设备
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128  # 内存分配策略

# 模型配置
ACE_MODEL_PATH=/app/checkpoints/ace-step-v1-3.5b
ACE_OUTPUT_DIR=/app/outputs

📊 性能优化

🚀 内存优化

# 启用 CPU 卸载
acestep --cpu_offload true

# 启用重叠解码
acestep --overlapped_decode true

# 使用 torch.compile 优化
acestep --torch_compile true

# Windows 需要安装 triton
pip install triton-windows

⚡ 推理优化

# 使用 bfloat16 精度
acestep --bf16 true

# 调整推理步数
acestep --num_inference_steps 27

# 启用模型缓存
export HF_HUB_ENABLE_HF_TRANSFER=1

📊 监控指标

RTF (Real-Time Factor): 实时因子，衡量生成速度
GPU 内存使用: 监控显存占用
推理延迟: 单次推理耗时
吞吐量: 单位时间内的处理量

🔨 开发指南

🛠️ 本地开发环境

克隆仓库：

git clone https://github.com/gongjiyun/ace-step-worker.git
cd ace-step-worker

创建虚拟环境：

python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

安装依赖：

pip install -r requirements.txt

运行开发服务器：

python acestep/gui.py --server_name 0.0.0.0 --port 7865 --bf16 true

🔧 自定义功能开发

创建自定义功能：

# acestep/custom_functions.py
import torch
import torch.nn.functional as F

class CustomMusicFunction:
    def __init__(self):
        self.output_dir = "outputs"
    
    def generate_music(self, text, duration):
        # 实现音乐生成逻辑
        return f"Generated music for: {text}"

# 在 gui.py 中集成
from .custom_functions import CustomMusicFunction

🧪 测试

# 运行单元测试
python -m pytest tests/

# 运行集成测试
python -m pytest tests/integration/

# 运行性能测试
python -m pytest tests/performance/

📂 示例

examples/workflows 目录包含示例工作流，可用作音乐生成的参考。

📜 许可证和免责声明

本项目采用 Apache License 2.0 许可证。

ACE-Step ComfyUI 支持跨多种流派的原创音乐生成，适用于创意制作、教育和娱乐。虽然设计用于支持积极和艺术用例，但我们承认潜在风险，如由于风格相似性导致的无意版权侵权、文化元素的不当混合以及用于生成有害内容的滥用。为确保负责任的使用，我们鼓励用户验证生成作品的原创性，明确披露 AI 参与，并在改编受保护的风格或材料时获得适当许可。通过使用 ACE-Step ComfyUI，您同意维护这些原则并尊重艺术完整性、文化多样性和法律合规性。作者不对模型的任何滥用负责，包括但不限于版权侵权、文化不敏感或有害内容的生成。

🔔 重要通知
ACE-Step Worker 项目的唯一官方网站是我们的 GitHub Pages 网站。
我们不运营任何其他网站。
🚫 虚假域名包括但不限于： ac**p.com, a**p.org, a***c.org
⚠️ 请谨慎。不要访问、信任或在任何这些网站上付款。

📚 参考文档

🙏 致谢

本项目由共绩算力平台和 ACE Studio 共同开发。

📖 引用

如果您发现本项目对您的研究有用，请考虑引用：

@misc{gong2025acestepworker,
	title={ACE-Step Worker: A Gongjiyun Serverless API for Music Generation},
	author={Junmin Gong, Wenxiao Zhao, Sen Wang, Shengyuan Xu, Jing Guo}, 
	howpublished={\url{https://github.com/gongjiyun/ace-step-worker}},
	year={2025},
	note={GitHub repository}
}

Name		Name	Last commit message	Last commit date
Latest commit History 265 Commits
acestep		acestep
assets		assets
config		config
data		data
examples		examples
zh_lora_dataset		zh_lora_dataset
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TRAIN_INSTRUCTION.md		TRAIN_INSTRUCTION.md
ZH_RAP_LORA.md		ZH_RAP_LORA.md
colab_inference.ipynb		colab_inference.ipynb
convert2hf_dataset.py		convert2hf_dataset.py
docker-compose.yaml		docker-compose.yaml
infer-api.py		infer-api.py
infer.py		infer.py
inference.ipynb		inference.ipynb
requirements.txt		requirements.txt
setup.py		setup.py
trainer-api.py		trainer-api.py
trainer.py		trainer.py

License

slmnb-lab/ACE-Step-GONGJI

Folders and files

Latest commit

History

Repository files navigation