VoxCPM/docs/finetune.md

# VoxCPM 微调指南

本文档介绍如何对 VoxCPM 模型进行微调，支持全量微调和 LoRA 微调两种方式。

## 目录

- [数据准备](#数据准备)
- [全量微调](#全量微调)
- [LoRA 微调](#lora-微调)
- [推理测试](#推理测试)
- [LoRA 热切换](#lora-热切换)
- [常见问题](#常见问题)

---

## 数据准备

训练数据需要准备为 JSONL 格式的 manifest 文件，每行包含一条训练样本：

```json
{"audio_path": "/path/to/audio1.wav", "text": "对应的文本内容"}
{"audio_path": "/path/to/audio2.wav", "text": "另一条文本"}
```

**要求**：
- 音频格式：WAV，采样率 16kHz
- 文本：与音频对应的转录文本

---

## 全量微调

全量微调会更新模型的所有参数，适合数据量较大、需要显著改变模型行为的场景。

### 配置文件

创建配置文件 `conf/voxcpm/voxcpm_finetune_all.yaml`：

```yaml
pretrained_path: /path/to/VoxCPM-0.5B/          # 预训练模型路径
train_manifest: /path/to/train_manifest.jsonl   # 训练数据
val_manifest: null                               # 验证数据（可选）

sample_rate: 16000
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
python scripts/train_voxcpm_finetune.py --config_path conf/voxcpm/voxcpm_finetune_all.yaml
```

---

## LoRA 微调

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

### 配置文件

创建配置文件 `conf/voxcpm/voxcpm_finetune_lora.yaml`：

```yaml
pretrained_path: /path/to/VoxCPM-0.5B/
train_manifest: /path/to/train_manifest.jsonl
val_manifest: null

sample_rate: 16000
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: 200
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        # 对 Language Model 加 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           # LoRA dropout
  
  # 目标模块
  target_modules_lm: ["q_proj", "v_proj", "k_proj", "o_proj"]
  target_modules_dit: ["q_proj", "v_proj", "k_proj", "o_proj"]
```

### LoRA 参数说明

| 参数 | 说明 | 建议值 |
|------|------|--------|
| `enable_lm` | 对 LM（语言模型）加 LoRA | `true` |
| `enable_dit` | 对 DiT（扩散模型）加 LoRA | `true`（音色克隆必须） |
| `r` | LoRA 秩，越大容量越大 | 16-64 |
| `alpha` | 缩放因子，`scaling = alpha / r` | 通常设为 `r/2` 或 `r` |
| `target_modules_*` | 要添加 LoRA 的层名 | attention 层 |

### 启动训练

```bash
python scripts/train_voxcpm_finetune.py --config_path conf/voxcpm/voxcpm_finetune_lora.yaml
```

### Checkpoint 结构

LoRA 训练保存的 checkpoint 只包含 LoRA 参数：

```
checkpoints/finetune_lora/
└── step_0002000/
    └── generator.pth    # 仅包含 lora_A, lora_B 参数
```

---

## 推理测试

### 全量微调推理

```bash
python scripts/test_voxcpm_ft_infer.py \
    --pretrained_path /path/to/VoxCPM-0.5B/ \
    --ft_ckpt /path/to/checkpoints/finetune_all/step_0002000 \
    --text "你好，这是微调后的效果。" \
    --output output.wav
```

### LoRA 推理

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

### 带参考音频（音色克隆）

```bash
python scripts/test_voxcpm_lora_infer.py \
    --config_path conf/voxcpm/voxcpm_finetune_lora.yaml \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --text "这是带参考音色的合成效果。" \
    --prompt_audio /path/to/reference.wav \
    --prompt_text "参考音频对应的文本" \
    --output cloned_output.wav
```

---

## LoRA 热切换

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

### API 说明

```python
from voxcpm.model import VoxCPMModel
from voxcpm.model.voxcpm import LoRAConfig

# 1. 加载模型（包含 LoRA 结构）
lora_cfg = LoRAConfig(enable_lm=True, enable_dit=True, r=32, alpha=16, ...)
model = VoxCPMModel.from_local(
    pretrained_path,
    optimize=True,       # 启用 torch.compile 加速
    lora_config=lora_cfg
)

# 2. 加载 LoRA 权重（支持 compile 后调用）
model.load_lora_weights("/path/to/lora_checkpoint")

# 3. 禁用 LoRA（使用基础模型）
model.set_lora_enabled(False)

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

# 5. 卸载 LoRA（重置权重为 0）
model.reset_lora_weights()

# 6. 热切换到另一个 LoRA
model.load_lora_weights("/path/to/another_lora_checkpoint")
```

### 方法说明

| 方法 | 功能 | 兼容 torch.compile |
|------|------|-------------------|
| `load_lora_weights(path)` | 从文件加载 LoRA 权重 | ✅ |
| `set_lora_enabled(bool)` | 启用/禁用 LoRA | ✅ |
| `reset_lora_weights()` | 重置 LoRA 权重为初始值 | ✅ |
| `get_lora_state_dict()` | 获取当前 LoRA 权重 | ✅ |

---

## 常见问题

### 1. 显存不足

- 增大 `grad_accum_steps`（梯度累积）
- 减小 `batch_size`
- 使用 LoRA 微调代替全量微调

### 2. LoRA 效果不好

- 增大 `r`（LoRA 秩）
- 调整 `alpha`（建议 `alpha = r/2` 或 `alpha = r`）
- 确保 `enable_dit: true`（音色克隆必须）
- 增加训练步数

### 3. 训练不收敛

- 降低 `learning_rate`
- 增加 `warmup_steps`
- 检查数据质量

### 4. 推理时 LoRA 不生效

- 确保推理配置与训练配置的 LoRA 参数一致
- 检查 `load_lora_weights` 返回的 `skipped_keys` 是否为空