VoxCPM/docs/finetune.md

VoxCPM 微调指南

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

目录

• 数据准备
• 全量微调
• LoRA 微调
• 推理测试
• LoRA 热切换
• 常见问题

---

数据准备

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

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

要求：

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

---

全量微调

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

配置文件

创建配置文件 conf/voxcpm/voxcpm_finetune_all.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

启动训练

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：

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 层

启动训练

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 参数

---

推理测试

全量微调推理

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 推理

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

带参考音频（音色克隆）

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 说明

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 是否为空