Skip to content

Latest commit

 

History

History
556 lines (392 loc) · 18 KB

GRADIO_GUIDE.md

File metadata and controls

556 lines (392 loc) · 18 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. 设置（折叠式手风琴）- 服务配置、DiT/LM 参数、输出选项
  2. 生成标签页 - 主工作区，顶部有生成模式单选选择器：
    • Turbo/SFT 模型：Simple、Custom、Remix、Repaint
    • Base 模型：Simple、Custom、Remix、Repaint、Extract、Lego、Complete
  3. 结果区域 - 生成的音频播放、评分、批次导航
  4. 训练标签页 - 数据集构建器和 LoRA 训练

服务配置

模型选择

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

5Hz LM 配置

设置 说明
5Hz LM 模型路径 选择语言模型。可用模型根据 GPU 等级自动过滤 — 例如，6-8GB GPU 仅显示 0.6B，而 24GB+ GPU 显示所有尺寸（0.6B、1.7B、4B）。
5Hz LM 后端 vllm（更快，推荐显存 ≥8GB 的 NVIDIA GPU）、pt（PyTorch，通用回退方案）或 mlx（Apple Silicon）。显存 <8GB 的 GPU 限制为 pt/mlx，因为 vllm 的 KV 缓存占用过大。
初始化 5Hz LM 勾选以在初始化期间加载 LM（thinking 模式必需）。显存 ≤6GB 的 GPU（Tier 1-2）默认不勾选且禁用。

自适应默认设置: 所有 LM 设置根据 GPU 显存等级自动配置。推荐的 LM 模型、后端和初始化状态已预设为最佳性能。您可以手动覆盖，但如果选择与 GPU 不兼容，系统会发出警告。

性能选项

设置 说明
使用 Flash Attention 启用以加速推理（需要 flash_attn 包）
卸载到 CPU 空闲时将模型卸载到 CPU 以节省 GPU 显存。显存 <20GB 的 GPU 默认自动启用。
将 DiT 卸载到 CPU 专门将 DiT 模型卸载到 CPU。显存 <12GB 的 GPU 默认自动启用。
INT8 量化 使用 INT8 权重量化减少模型显存占用。显存 <20GB 的 GPU 默认自动启用。
模型编译 启用 torch.compile 优化推理。所有等级默认启用（量化激活时必需）。

等级感知设置: 卸载、量化和编译选项根据 GPU 等级自动设置。详见 GPU_COMPATIBILITY.md 了解完整的等级表。

LoRA 适配器

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

⚠️ 注意： 由于 PEFT 和 TorchAO 之间的兼容性问题，无法在量化模型上加载 LoRA 适配器。如果需要使用 LoRA，请在加载适配器之前将 INT8 量化 设置为 None。

初始化

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

  • 检测到的 GPU 等级和显存
  • 最大允许时长和批次大小（根据是否初始化了 LM 动态调整）
  • 任何不兼容设置被自动修正的警告

初始化后，音频时长 和 批量大小 滑块会自动更新以反映等级限制。

生成模式

生成标签页顶部的生成模式单选选择器决定了你的工作流。Turbo 和 SFT 模型提供四种模式；Base 模型额外增加三种。

Simple 模式

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

使用方法：

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

示例描述：

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

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

Custom 模式

完全控制所有生成参数（text2music）。

使用方法：

  1. 在生成模式中选择 Custom
  2. 手动填写 Caption 和歌词字段
  3. 可选上传参考音频用于风格引导
  4. 设置可选元数据（BPM、调性、时长等）
  5. 可选点击 格式化 使用 LM 增强您的输入
  6. 根据需要配置高级设置
  7. 点击 生成音乐 创建音频

Remix 模式

保持现有音频的旋律结构，同时改变风格。

使用方法：

  1. 在生成模式中选择 Remix
  2. 上传源音频（要 remix 的歌曲）
  3. 编写描述目标风格的 Caption
  4. 可选修改歌词
  5. 调整 Remix 强度（0.0-1.0）：越高 = 越接近原始结构
  6. 点击 生成音乐

用例： 创建翻唱版本、风格迁移、生成歌曲变体。

Repaint 模式

重新生成音频的特定时间段，保持其余部分不变。

使用方法：

  1. 在生成模式中选择 Repaint
  2. 上传源音频
  3. 设置重绘开始和重绘结束（秒；-1 表示文件末尾）
  4. 编写描述重绘部分期望内容的 Caption
  5. 点击 生成音乐

用例： 修复有问题的部分、修改某段歌词、延长歌曲。

Extract 模式（仅 Base 模型）

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

使用方法：

  1. 在生成模式中选择 Extract
  2. 上传源音频
  3. 从下拉菜单中选择要提取的轨道名称
  4. 点击 生成音乐

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

Lego 模式（仅 Base 模型）

为现有音频添加新的乐器轨道。

使用方法：

  1. 在生成模式中选择 Lego
  2. 上传源音频
  3. 从下拉菜单中选择要添加的轨道名称
  4. 编写描述轨道特征的 Caption
  5. 点击 生成音乐

Complete 模式（仅 Base 模型）

用指定的乐器完成部分轨道（自动编排）。

使用方法：

  1. 在生成模式中选择 Complete
  2. 上传源音频
  3. 选择多个要添加的轨道名称
  4. 编写描述期望风格的 Caption
  5. 点击 生成音乐

输入参数

音频输入

字段 说明
参考音频 用于风格/音色引导的可选音频（Custom 模式下可见）
源音频 Remix、Repaint、Extract、Lego、Complete 模式必需
转换为代码 从源音频提取 5Hz 语义代码

LM 代码提示（Custom 模式）

可以在此粘贴预计算的音频语义代码来引导生成。使用 转录 按钮分析代码并提取元数据。这是一个高级功能，用于在不上传源音频的情况下控制旋律结构。

音乐描述

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

  • 风格和类型
  • 乐器
  • 情绪和氛围
  • 节奏感（如果不指定 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 适配器的工具。

📖 完整的分步教程（数据准备、标注、预处理、训练和导出），请参阅 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 更具体

显存不足 (OOM)：

  • 系统包含自动显存管理（显存守卫、自适应 VAE 解码、自动批次减小）。如果仍然 OOM：
  • 手动减少批量大小
  • 启用 CPU 卸载（显存 <20GB 应已自动启用）
  • 启用 INT8 量化（显存 <20GB 应已自动启用）
  • 减少 LM 批处理块大小
  • 详见 GPU_COMPATIBILITY.md 了解各等级推荐设置

LM 不工作：

  • 确保初始化期间勾选了"初始化 5Hz LM"（显存 ≤6GB 的 GPU 默认禁用）
  • 检查是否选择了有效的 LM 模型路径（仅显示与等级兼容的模型）
  • 验证 vllm 或 PyTorch 后端可用（显存 <8GB 限制使用 vllm）
  • 如果 LM 复选框灰色不可用，说明您的 GPU 等级不支持 LM — 请使用纯 DiT 模式

键盘快捷键

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

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

语言支持

界面支持多种 UI 语言：

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

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

更多信息，请参阅：