# 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. **服务配置** - 模型加载和初始化
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)

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

---

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