Hugging Face's logo

Spaces:
ACE-Step
/
Ace-Step-v1.5
Running on A100

App Files Community
3
Ace-Step-v1.5 / docs /zh /GRADIO_GUIDE.md
ChuxiJ's picture
ChuxiJ
add docs and readme
428436b
preview code
|
raw
history blame contribute delete
15.8 kB

ACE-Step Gradio 演示用户指南

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

本指南提供使用 ACE-Step Gradio Web 界面进行音乐生成的综合文档，包括所有功能和设置。

目录

快速开始

启动演示 

# 基本启动
python app.py

# 预初始化
python app.py --config acestep-v15-turbo --init-llm

# 指定端口
python app.py --port 7860

界面概述

Gradio 界面包含以下主要部分：

  1. 服务配置 - 模型加载和初始化
  2. 必需输入 - 任务类型、音频上传和生成模式
  3. 音乐描述和歌词 - 生成的文本输入
  4. 可选参数 - BPM、调性、时长等元数据
  5. 高级设置 - 细粒度的生成控制
  6. 结果 - 生成的音频播放和管理

服务配置

模型选择

设置 说明
检查点文件 选择已训练的模型检查点（如果可用）
主模型路径 选择 DiT 模型配置（例如 acestep-v15-turbo、acestep-v15-turbo-shift3）
设备 处理设备：auto（推荐）、cuda 或 cpu

5Hz LM 配置

设置 说明
5Hz LM 模型路径 选择语言模型（例如 acestep-5Hz-lm-0.6B、acestep-5Hz-lm-1.7B）
5Hz LM 后端 vllm（更快，推荐）或 pt（PyTorch，兼容性更好）
初始化 5Hz LM 勾选以在初始化期间加载 LM（thinking 模式必需）

性能选项

设置 说明
使用 Flash Attention 启用以加速推理（需要 flash_attn 包）
卸载到 CPU 空闲时将模型卸载到 CPU 以节省 GPU 内存
将 DiT 卸载到 CPU 专门将 DiT 模型卸载到 CPU

LoRA 适配器

设置 说明
LoRA 路径 已训练的 LoRA 适配器目录路径
加载 LoRA 加载指定的 LoRA 适配器
卸载 移除当前加载的 LoRA
使用 LoRA 启用/禁用已加载的 LoRA 进行推理

初始化

点击 初始化服务 加载模型。状态框将显示进度和确认信息。

生成模式

简单模式

简单模式专为快速、基于自然语言的音乐生成设计。

使用方法：

  1. 在生成模式单选按钮中选择"简单"
  2. 在"歌曲描述"字段中输入自然语言描述
  3. 如果不想要人声，可选择勾选"纯音乐"
  4. 可选择首选人声语言
  5. 点击 创建样本 生成 caption、歌词和元数据
  6. 在展开的部分中查看生成的内容
  7. 点击 生成音乐 创建音频

示例描述：

  • "一首适合安静夜晚的柔和孟加拉情歌"
  • "欢快的电子舞曲，重低音"
  • "忧郁的独立民谣，原声吉他"
  • "在烟雾弥漫的酒吧里演奏的爵士三重奏"

随机样本： 点击 🎲 按钮加载随机示例描述。

自定义模式

自定义模式提供对所有生成参数的完全控制。

使用方法：

  1. 在生成模式单选按钮中选择"自定义"
  2. 手动填写 Caption 和歌词字段
  3. 设置可选元数据（BPM、调性、时长等）
  4. 可选点击 格式化 使用 LM 增强您的输入
  5. 根据需要配置高级设置
  6. 点击 生成音乐 创建音频

任务类型

text2music（默认）

从文本描述和/或歌词生成音乐。

用例： 基于提示从头创建新音乐。

必需输入： Caption 或歌词（至少一个）

cover

转换现有音频，保持结构但改变风格。

用例： 创建不同风格的翻唱版本。

必需输入：

  • 源音频（在音频上传区域上传）
  • 描述目标风格的 Caption

关键参数： 音频翻唱强度（0.0-1.0）

  • 较高的值保持更多原始结构
  • 较低的值允许更多创意自由

repaint

重新生成音频的特定时间段。

用例： 修复或修改生成音乐的特定部分。

必需输入：

  • 源音频
  • 重绘开始（秒）
  • 重绘结束（秒，-1 表示文件末尾）
  • 描述期望内容的 Caption

lego（仅 Base 模型）

在现有音频的上下文中生成特定乐器轨道。

用例： 为伴奏添加乐器层。

必需输入：

  • 源音频
  • 轨道名称（从下拉菜单选择）
  • 描述轨道特征的 Caption

可用轨道： vocals、backing_vocals、drums、bass、guitar、keyboard、percussion、strings、synth、fx、brass、woodwinds

extract（仅 Base 模型）

从混音音频中提取/分离特定乐器轨道。

用例： 音轨分离、分离乐器。

必需输入：

  • 源音频
  • 要提取的轨道名称

complete（仅 Base 模型）

用指定的乐器完成部分轨道。

用例： 自动编排不完整的作品。

必需输入：

  • 源音频
  • 轨道名称（多选）
  • 描述期望风格的 Caption

输入参数

必需输入

任务类型

从下拉菜单选择生成任务。指令字段会根据选择的任务自动更新。

音频上传

字段 说明
参考音频 用于风格参考的可选音频
源音频 cover、repaint、lego、extract、complete 任务必需
转换为代码 从源音频提取 5Hz 语义代码

LM 代码提示

可以在此粘贴预计算的音频语义代码来引导生成。使用 转录 按钮分析代码并提取元数据。

音乐描述

期望音乐的文本描述。请具体说明：

  • 风格和类型
  • 乐器
  • 情绪和氛围
  • 节奏感（如果不指定 BPM）

示例： "欢快的流行摇滚，电吉他、有力的鼓点和朗朗上口的合成器钩子"

点击 🎲 加载随机示例 caption。

歌词

输入带结构标签的歌词：

[Verse 1]
今天走在街上
想着你曾说过的话

[Chorus]
我在前进，我很坚强
这就是我属于的地方

[Verse 2]
...

纯音乐复选框： 勾选此项以生成纯音乐，无论歌词内容如何。

人声语言： 选择人声语言。对于自动检测或纯音乐，使用"unknown"。

格式化按钮： 点击使用 5Hz LM 增强 caption 和歌词。

可选参数

参数 默认值 说明
BPM 自动 每分钟节拍数（30-300）
调性 自动 音乐调性（例如"C Major"、"Am"、"F# minor"）
拍号 自动 拍号：2（2/4）、3（3/4）、4（4/4）、6（6/8）
音频时长 自动/-1 目标长度（秒）（10-600）。-1 为自动
批量大小 2 要生成的音频变体数量（1-8）

高级设置

DiT 参数

参数 默认值 说明
推理步数 8 去噪步数。Turbo：1-20，Base：1-200
引导比例 7.0 CFG 强度（仅 base 模型）。越高 = 越遵循提示
种子 -1 随机种子。批量使用逗号分隔的值
随机种子 ✓ 勾选时生成随机种子
音频格式 mp3 输出格式：mp3、flac
偏移 3.0 时间步偏移因子（1.0-5.0）。turbo 推荐 3.0
推理方法 ode ode（Euler，更快）或 sde（随机）
自定义时间步 - 覆盖时间步（例如"0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0"）

仅 Base 模型参数

参数 默认值 说明
使用 ADG ✗ 启用自适应双引导以获得更好的质量
CFG 区间开始 0.0 何时开始应用 CFG（0.0-1.0）
CFG 区间结束 1.0 何时停止应用 CFG（0.0-1.0）

LM 参数

参数 默认值 说明
LM 温度 0.85 采样温度（0.0-2.0）。越高 = 越有创意
LM CFG 比例 2.0 LM 引导强度（1.0-3.0）
LM Top-K 0 Top-K 采样。0 禁用
LM Top-P 0.9 核采样（0.0-1.0）
LM 负面提示 "NO USER INPUT" CFG 的负面提示

CoT（思维链）选项

选项 默认值 说明
CoT Metas ✓ 通过 LM 推理生成元数据
CoT Language ✓ 通过 LM 检测人声语言
约束解码调试 ✗ 启用调试日志

生成选项

选项 默认值 说明
LM 代码强度 1.0 LM 代码对生成的影响程度（0.0-1.0）
自动评分 ✗ 自动计算质量分数
自动 LRC ✗ 自动生成歌词时间戳
LM 批处理块大小 8 每个 LM 批次的最大项目数（GPU 内存）

主要生成控制

控制 说明
Think 启用 5Hz LM 进行代码生成和元数据
ParallelThinking 启用并行 LM 批处理
CaptionRewrite 让 LM 增强输入 caption
AutoGen 完成后自动开始下一批次

结果区域

生成的音频

根据批量大小最多显示 8 个音频样本。每个样本包括：

  • 音频播放器 - 播放、暂停和下载生成的音频
  • 发送到源 - 将此音频发送到源音频输入以进行进一步处理
  • 保存 - 将音频和元数据保存到 JSON 文件
  • 评分 - 计算基于困惑度的质量分数
  • LRC - 生成歌词时间戳（LRC 格式）

详情折叠面板

点击"评分 & LRC & LM 代码"展开并查看：

  • LM 代码 - 此样本的 5Hz 语义代码
  • 质量分数 - 基于困惑度的质量指标
  • 歌词时间戳 - LRC 格式的时间数据

批次导航

控制 说明
◀ 上一批 查看上一批
批次指示器 显示当前批次位置（例如"批次 1 / 3"）
下一批状态 显示后台生成进度
下一批 ▶ 查看下一批（如果 AutoGen 开启则触发生成）

恢复参数

点击 应用这些设置到 UI 将当前批次的所有生成参数恢复到输入字段。适用于迭代优化好的结果。

批次结果

"批次结果和生成详情"折叠面板包含：

  • 所有生成的文件 - 下载所有批次的所有文件
  • 生成详情 - 关于生成过程的详细信息

LoRA 训练

LoRA 训练选项卡提供创建自定义 LoRA 适配器的工具。

数据集构建器选项卡

步骤 1：加载或扫描

选项 A：加载现有数据集

  1. 输入之前保存的数据集 JSON 路径
  2. 点击 加载

选项 B：扫描新目录

  1. 输入音频文件夹路径
  2. 点击 扫描 查找音频文件（wav、mp3、flac、ogg、opus）

步骤 2：配置数据集

设置 说明
数据集名称 您的数据集名称
全部纯音乐 如果所有曲目都没有人声，请勾选
自定义激活标签 激活此 LoRA 风格的唯一标签
标签位置 放置标签的位置：前置、追加或替换 caption

步骤 3：自动标注

点击 自动标注全部 为所有音频文件生成元数据：

  • Caption（音乐描述）
  • BPM
  • 调性
  • 拍号

跳过 Metas 选项将跳过 LLM 标注并使用 N/A 值。

步骤 4：预览和编辑

使用滑块选择样本并手动编辑：

  • Caption
  • 歌词
  • BPM、调性、拍号
  • 语言
  • 纯音乐标志

点击 保存更改 更新样本。

步骤 5：保存数据集

输入保存路径并点击 保存数据集 导出为 JSON。

步骤 6：预处理

将数据集转换为预计算张量以加快训练：

  1. 可选加载现有数据集 JSON
  2. 设置张量输出目录
  3. 点击 预处理

这会将音频编码为 VAE 潜变量，将文本编码为嵌入，并运行条件编码器。

训练 LoRA 选项卡

数据集选择

输入预处理张量目录路径并点击 加载数据集。

LoRA 设置

设置 默认值 说明
LoRA 秩 (r) 64 LoRA 容量。越高 = 容量越大，内存越多
LoRA Alpha 128 缩放因子（通常是秩的 2 倍）
LoRA Dropout 0.1 用于正则化的 dropout 率

训练参数

设置 默认值 说明
学习率 1e-4 优化学习率
最大 Epochs 500 最大训练 epochs
批量大小 1 训练批量大小
梯度累积 1 有效批次 = batch_size × accumulation
每 N Epochs 保存 200 检查点保存频率
偏移 3.0 turbo 模型的时间步偏移
种子 42 用于可重复性的随机种子

训练控制

  • 开始训练 - 开始训练过程
  • 停止训练 - 中断训练
  • 训练进度 - 显示当前 epoch 和损失
  • 训练日志 - 详细训练输出
  • 训练损失图 - 可视化损失曲线

导出 LoRA

训练后，导出最终适配器：

  1. 输入导出路径
  2. 点击 导出 LoRA

技巧与最佳实践

获得最佳质量

  1. 使用 thinking 模式 - 保持"Think"复选框启用以获得 LM 增强的生成
  2. 具体描述 caption - 包含风格、乐器、情绪和风格细节
  3. 让 LM 检测元数据 - 将 BPM/调性/时长留空以自动检测
  4. 使用批量生成 - 生成 2-4 个变体并选择最好的

加快生成速度

  1. 使用 turbo 模型 - 选择 acestep-v15-turbo 或 acestep-v15-turbo-shift3
  2. 保持推理步数为 8 - 这是 turbo 的最佳默认值
  3. 减少批量大小 - 如果需要快速结果，降低批量大小
  4. 禁用 AutoGen - 手动控制批次生成

获得一致结果

  1. 设置特定种子 - 取消勾选"随机种子"并输入种子值
  2. 保存好的结果 - 使用"保存"导出参数以便重现
  3. 使用"应用这些设置" - 从好的批次恢复参数

长格式音乐

  1. 设置明确的时长 - 以秒为单位指定时长
  2. 使用 repaint 任务 - 初始生成后修复有问题的部分
  3. 链式生成 - 使用"发送到源"在之前的结果上构建

风格一致性

  1. 训练 LoRA - 为您的风格创建自定义适配器
  2. 使用参考音频 - 在音频上传中上传风格参考
  3. 使用一致的 caption - 保持相似的描述性语言

故障排除

没有生成音频：

  • 检查模型是否已初始化（绿色状态消息）
  • 如果使用 thinking 模式，确保 5Hz LM 已初始化
  • 检查状态输出中的错误消息

结果质量差：

  • 增加推理步数（对于 base 模型）
  • 调整引导比例
  • 尝试不同的种子
  • 使 caption 更具体

内存不足：

  • 减少批量大小
  • 启用 CPU 卸载
  • 减少 LM 批处理块大小

LM 不工作：

  • 确保初始化期间勾选了"初始化 5Hz LM"
  • 检查是否选择了有效的 LM 模型路径
  • 验证 vllm 或 PyTorch 后端可用

键盘快捷键

Gradio 界面支持标准 Web 快捷键：

  • Tab - 在输入字段之间移动
  • Enter - 提交文本输入
  • Space - 切换复选框

语言支持

界面支持多种 UI 语言：

  • 英文 (en)
  • 中文 (zh)
  • 日文 (ja)

在服务配置区域选择您的首选语言。

更多信息，请参阅：