# VoxCPM 微调指南

本指南介绍了如何使用全量微调（Full Fine-tuning）和 LoRA 微调两种方式对 VoxCPM 模型进行微调。

### 🎓 SFT (监督微调)

全量微调会更新所有模型参数。适用于：
- 📊 大型、专业的数据集
- 🔄 需要显著改变模型行为的场景

### ⚡ LoRA 微调

LoRA (Low-Rank Adaptation) 是一种参数高效的微调方法，它：
- 🎯 仅训练少量额外参数
- 💾 显著降低显存需求和训练时间
- 🔀 支持多个 LoRA 适配器热插拔

## 目录

- [快速开始：WebUI](#快速开始webui)
- [数据准备](#数据准备)
- [全量微调](#全量微调)
- [LoRA 微调](#lora-微调)
- [推理](#推理)
- [LoRA 热插拔](#lora-热插拔)
- [常见问题](#常见问题)

---

## 快速开始：WebUI

对于喜欢图形界面的用户，我们提供了 `lora_ft_webui.py` —— 一个用于训练和推理的综合 WebUI：

### 启动 WebUI

```bash
python lora_ft_webui.py
```

然后在浏览器中打开 `http://localhost:7860`。

### 功能特点

- **🚀 训练标签页**：通过直观的界面配置并启动 LoRA 训练
  - 设置训练参数（学习率、Batch Size、LoRA Rank 等）
  - 实时监控训练进度
  - 从现有断点恢复训练

- **🎵 推理标签页**：使用训练好的模型生成音频
  - 从 LoRA 检查点配置自动加载基座模型
  - 带自动 ASR（参考文本识别）的声音克隆
  - 在多个 LoRA 模型间热切换
  - 无参考音频的零样本 TTS

## 数据准备

训练数据应准备为 JSONL 清单文件，每行一个样本：

```jsonl
{"audio": "path/to/audio1.wav", "text": "音频1的文本内容。"}
{"audio": "path/to/audio2.wav", "text": "音频2的文本内容。"}
{"audio": "path/to/audio3.wav", "text": "可选的时长字段。", "duration": 3.5}
{"audio": "path/to/audio4.wav", "text": "多数据集训练可选的 dataset_id。", "dataset_id": 1}
```

### 必填字段

| 字段 | 描述 |
|-------|-------------|
| `audio` | 音频文件路径（绝对或相对路径） |
| `text` | 对应的文本内容 |

### 可选字段

| 字段 | 描述 |
|-------|-------------|
| `duration` | 音频时长（秒），用于加速样本过滤 |
| `dataset_id` | 多数据集训练的数据集 ID（默认：0） |

### 要求

- 音频格式：WAV
- 采样率：VoxCPM-0.5B 为 16kHz，VoxCPM1.5 为 44.1kHz
- 文本：与音频内容匹配的文本

查看 `examples/train_data_example.jsonl` 获取完整示例。

---

## 全量微调

全量微调更新所有模型参数。适用于大数据集或需要显著改变模型行为的情况。

### 配置

创建 `conf/voxcpm_v1.5/voxcpm_finetune_all.yaml`：

```yaml
pretrained_path: /path/to/VoxCPM1.5/
train_manifest: /path/to/train.jsonl
val_manifest: ""

sample_rate: 44100
batch_size: 16
grad_accum_steps: 1
num_workers: 2
num_iters: 2000
log_interval: 10
valid_interval: 1000
save_interval: 1000

learning_rate: 0.00001   # 全量微调使用较小的学习率
weight_decay: 0.01
warmup_steps: 100
max_steps: 2000
max_batch_tokens: 8192

save_path: /path/to/checkpoints/finetune_all
tensorboard: /path/to/logs/finetune_all

lambdas:
  loss/diff: 1.0
  loss/stop: 1.0
```

### 训练

```bash
# 单 GPU
python scripts/train_voxcpm_finetune.py --config_path conf/voxcpm_v1.5/voxcpm_finetune_all.yaml

# 多 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc_per_node=4 \
    scripts/train_voxcpm_finetune.py --config_path conf/voxcpm_v1.5/voxcpm_finetune_all.yaml
```

### 检查点结构

全量微调保存完整的模型目录，可以直接加载：

```
checkpoints/finetune_all/
└── step_0002000/
    ├── model.safetensors     # 模型权重 (不含 audio_vae)
    ├── config.json            # 模型配置
    ├── audiovae.pth           # Audio VAE 权重
    ├── tokenizer.json         # Tokenizer
    ├── tokenizer_config.json
    ├── special_tokens_map.json
    ├── optimizer.pth
    └── scheduler.pth
```

---

## LoRA 微调

LoRA (Low-Rank Adaptation) 是一种参数高效的微调方法，仅训练少量额外参数，显著降低显存需求。

### 配置

创建 `conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml`：

```yaml
pretrained_path: /path/to/VoxCPM1.5/
train_manifest: /path/to/train.jsonl
val_manifest: ""

sample_rate: 44100
batch_size: 16
grad_accum_steps: 1
num_workers: 2
num_iters: 2000
log_interval: 10
valid_interval: 1000
save_interval: 1000

learning_rate: 0.0001    # LoRA 可以使用较大的学习率
weight_decay: 0.01
warmup_steps: 100
max_steps: 2000
max_batch_tokens: 8192

save_path: /path/to/checkpoints/finetune_lora
tensorboard: /path/to/logs/finetune_lora

lambdas:
  loss/diff: 1.0
  loss/stop: 1.0

# LoRA 配置
lora:
  enable_lm: true        # 对语言模型应用 LoRA
  enable_dit: true       # 对 Diffusion Transformer 应用 LoRA
  enable_proj: false     # 对投影层应用 LoRA (可选)
  
  r: 32                  # LoRA rank (越高容量越大)
  alpha: 16              # LoRA alpha, scaling = alpha / r
  dropout: 0.0
  
  # 目标模块
  target_modules_lm: ["q_proj", "v_proj", "k_proj", "o_proj"]
  target_modules_dit: ["q_proj", "v_proj", "k_proj", "o_proj"]

# 分发选项 (可选)
# hf_model_id: "openbmb/VoxCPM1.5"  # HuggingFace ID
# distribute: true                   # 如果为 true，在 lora_config.json 中保存 hf_model_id
```

### LoRA 参数

| 参数 | 描述 | 推荐值 |
|-----------|-------------|-------------|
| `enable_lm` | 对 LM (语言模型) 应用 LoRA | `true` |
| `enable_dit` | 对 DiT (扩散模型) 应用 LoRA | `true` (声音克隆必须) |
| `r` | LoRA rank (越高容量越大) | 16-64 |
| `alpha` | 缩放因子, `scaling = alpha / r` | 通常 `r/2` 或 `r` |
| `target_modules_*` | 添加 LoRA 的层名称 | attention layers |

### 分发选项 (可选)

| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| `hf_model_id` | HuggingFace 模型 ID (例如 `openbmb/VoxCPM1.5`) | `""` |
| `distribute` | 如果为 `true`，将 `hf_model_id` 作为 `base_model` 保存到检查点；否则保存本地 `pretrained_path` | `false` |

> **注意**：如果 `distribute: true`，则必须提供 `hf_model_id`。

### 训练

```bash
# 单 GPU
python scripts/train_voxcpm_finetune.py --config_path conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml

# 多 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc_per_node=4 \
    scripts/train_voxcpm_finetune.py --config_path conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml
```

### 检查点结构

LoRA 训练保存 LoRA 参数和配置：

```
checkpoints/finetune_lora/
└── step_0002000/
    ├── lora_weights.safetensors    # 仅含 lora_A, lora_B 参数
    ├── lora_config.json            # LoRA 配置 + 基座模型路径
    ├── optimizer.pth
    └── scheduler.pth
```

`lora_config.json` 包含：
```json
{
  "base_model": "/path/to/VoxCPM1.5/",
  "lora_config": {
    "enable_lm": true,
    "enable_dit": true,
    "r": 32,
    "alpha": 16,
    ...
  }
}
```

`base_model` 字段包含：
- 本地路径 (默认)：当 `distribute: false` 或未设置时
- HuggingFace ID：当 `distribute: true` 时 (例如 `"openbmb/VoxCPM1.5"`)

这允许在没有原始训练配置文件的情况下加载 LoRA 检查点。

---

## 推理

### 全量微调推理

检查点目录是一个完整的模型，直接加载：

```bash
python scripts/test_voxcpm_ft_infer.py \
    --ckpt_dir /path/to/checkpoints/finetune_all/step_0002000 \
    --text "你好，这是微调后的模型。" \
    --output output.wav
```

带声音克隆：

```bash
python scripts/test_voxcpm_ft_infer.py \
    --ckpt_dir /path/to/checkpoints/finetune_all/step_0002000 \
    --text "这是声音克隆的结果。" \
    --prompt_audio /path/to/reference.wav \
    --prompt_text "参考音频的文本内容" \
    --output cloned_output.wav
```

### LoRA 推理

LoRA 推理只需要检查点目录（基座模型路径和 LoRA 配置从 `lora_config.json` 读取）：

```bash
python scripts/test_voxcpm_lora_infer.py \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --text "你好，这是 LoRA 微调的结果。" \
    --output lora_output.wav
```

带声音克隆：

```bash
python scripts/test_voxcpm_lora_infer.py \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --text "这是带 LoRA 的声音克隆。" \
    --prompt_audio /path/to/reference.wav \
    --prompt_text "参考音频的文本内容" \
    --output cloned_output.wav
```

覆盖基座模型路径 (可选)：

```bash
python scripts/test_voxcpm_lora_infer.py \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --base_model /path/to/another/VoxCPM1.5 \
    --text "使用不同的基座模型。" \
    --output output.wav
```

---

## LoRA 热插拔

LoRA 支持在推理时动态加载、卸载和切换，无需重新加载整个模型。

### API 参考

```python
from voxcpm.core import VoxCPM
from voxcpm.model.voxcpm import LoRAConfig

# 1. 加载带 LoRA 结构和权重的模型
lora_cfg = LoRAConfig(
    enable_lm=True, 
    enable_dit=True, 
    r=32, 
    alpha=16,
    target_modules_lm=["q_proj", "v_proj", "k_proj", "o_proj"],
    target_modules_dit=["q_proj", "v_proj", "k_proj", "o_proj"],
)
model = VoxCPM.from_pretrained(
    hf_model_id="openbmb/VoxCPM1.5",  # 或本地路径
    load_denoiser=False,              # 可选：禁用降噪器以加快加载
    optimize=True,                    # 启用 torch.compile 加速
    lora_config=lora_cfg,
    lora_weights_path="/path/to/lora_checkpoint",
)

# 2. 生成音频
audio = model.generate(
    text="你好，这是 LoRA 微调的结果。",
    prompt_wav_path="/path/to/reference.wav",  # 可选：用于声音克隆
    prompt_text="参考音频的文本内容",            # 可选：用于声音克隆
)

# 3. 禁用 LoRA (仅使用基座模型)
model.set_lora_enabled(False)

# 4. 重新启用 LoRA
model.set_lora_enabled(True)

# 5. 卸载 LoRA (重置权重为零)
model.unload_lora()

# 6. 热切换到另一个 LoRA
loaded, skipped = model.load_lora("/path/to/another_lora_checkpoint")
print(f"Loaded {len(loaded)} params, skipped {len(skipped)}")

# 7. 获取当前 LoRA 权重
lora_state = model.get_lora_state_dict()
```

### 简化用法 (从 lora_config.json 加载)

如果你的检查点包含 `lora_config.json`（由训练脚本保存），你可以自动加载所有内容：

```python
import json
from voxcpm.core import VoxCPM
from voxcpm.model.voxcpm import LoRAConfig

# 从检查点加载配置
lora_ckpt_dir = "/path/to/checkpoints/finetune_lora/step_0002000"
with open(f"{lora_ckpt_dir}/lora_config.json") as f:
    lora_info = json.load(f)

base_model = lora_info["base_model"]
lora_cfg = LoRAConfig(**lora_info["lora_config"])

# 加载带 LoRA 的模型
model = VoxCPM.from_pretrained(
    hf_model_id=base_model,
    lora_config=lora_cfg,
    lora_weights_path=lora_ckpt_dir,
)
```

或者直接使用测试脚本：

```bash
python scripts/test_voxcpm_lora_infer.py \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --text "Hello world"
```

### 方法参考

| 方法 | 描述 | torch.compile 兼容性 |
|--------|-------------|--------------------------|
| `load_lora(path)` | 从文件加载 LoRA 权重 | ✅ |
| `set_lora_enabled(bool)` | 启用/禁用 LoRA | ✅ |
| `unload_lora()` | 将 LoRA 权重重置为初始值 | ✅ |
| `get_lora_state_dict()` | 获取当前 LoRA 权重 | ✅ |
| `lora_enabled` | 属性：检查是否配置了 LoRA | ✅ |

---

## 常见问题 (FAQ)

### 1. 显存溢出 (OOM)

- 增加 `grad_accum_steps` (梯度累积步数)
- 减小 `batch_size`
- 使用 LoRA 微调代替全量微调
- 减小 `max_batch_tokens` 以过滤长样本

### 2. LoRA 效果不佳

- 增加 `r` (LoRA rank)
- 调整 `alpha` (尝试 `alpha = r/2` 或 `alpha = r`)
- 增加训练步数
- 添加更多目标模块

### 3. 训练不收敛

- 减小 `learning_rate` (学习率)
- 增加 `warmup_steps`
- 检查数据质量

### 4. LoRA 在推理时未生效

- 检查检查点目录下是否存在 `lora_config.json`
- 检查 `load_lora()` 返回值 - `skipped_keys` 应该为空
- 确认调用了 `set_lora_enabled(True)`

### 5. 检查点加载错误

- 全量微调：检查点目录应包含 `model.safetensors` (或 `pytorch_model.bin`)、`config.json`、`audiovae.pth`
- LoRA：检查点目录应包含：
  - `lora_weights.safetensors` (或 `lora_weights.ckpt`) - LoRA 权重
  - `lora_config.json` - LoRA 配置和基座模型路径