# ACE-Step Gradio 演示用户指南

**Language / 语言 / 言語:** [English](../en/GRADIO_GUIDE.md) | [中文](GRADIO_GUIDE.md) | [日本語](../ja/GRADIO_GUIDE.md)

---

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

## 目录

- [快速开始](#快速开始)
- [服务配置](#服务配置)
- [生成模式](#生成模式)
- [输入参数](#输入参数)
- [高级设置](#高级设置)
- [结果区域](#结果区域)
- [LoRA 训练](#lora-训练)
- [技巧与最佳实践](#技巧与最佳实践)

---

## 快速开始

### 启动演示

```bash
# 基本启动
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](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 训练教程](./LoRA_Training_Tutorial.md)。

### 数据集构建器选项卡

#### 步骤 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](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)

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

---

更多信息，请参阅：
- 主 README：[`../../README.md`](../../README.md)
- REST API 文档：[`API.md`](API.md)
- Python 推理 API：[`INFERENCE.md`](INFERENCE.md)