适用场景:AutoDL 算力云 GPU(Ubuntu 22.04 / 基础镜像带 PyTorch 2.8 + CUDA 12.8 / miniconda base 环境),目标是从零部署 VoxCPM(1.5 和 2 两个版本并存),可推理、可全量微调、可 LoRA 微调。
本指南使用独立 conda 环境(名为 voxcpm,Python 3.11),不修改 AutoDL 的 base 环境——Jupyter、TensorBoard 等预装工具完全不受影响。
| 位置 | 内容 |
|---|---|
/root/miniconda3/ |
conda 管理器 + base 环境(Python 3.12,AutoDL 默认) |
/root/miniconda3/envs/voxcpm/ |
voxcpm 独立环境(Python 3.11,VoxCPM 专用) |
/root/VoxCPM/ |
VoxCPM 源码(editable 安装,支持 v1.5 和 v2) |
/root/models/VoxCPM2/ |
VoxCPM2 基础模型权重(~10 GB) |
/root/models/VoxCPM1.5/ |
VoxCPM1.5 基础模型权重(~3 GB,可选) |
/root/autodl-tmp/ |
训练数据、checkpoint、TensorBoard 日志等大件 |
两套 Python 并存:
conda activate base → Python 3.12(Jupyter / TensorBoard / AutoDL 内置工具)conda activate voxcpm → Python 3.11(VoxCPM 推理 / 训练 / 数据处理)三个 sh 脚本(1-run-webui.sh、2-run-train.sh、3-run-infer.sh)开头会自动 conda activate voxcpm,你不需要手动切环境。
开代理:
source /etc/network_turbo
关代理:
unset http_proxy && unset https_proxy
验证代理状态的命令:
env | grep -i proxy
输出里不能有 http_proxy 和 https_proxy 才算”关”。no_proxy=... 是代理豁免清单。
python --version
期望:Python 3.12.x(AutoDL 基础镜像默认)
conda --version
期望:conda 24.x.x 或类似版本号
如果 conda activate 报 Run 'conda init' before 'conda activate':
conda init
source ~/.bashrc
AutoDL 新开机后 conda activate 可能报 Run 'conda init' before 'conda activate',需要先初始化:
conda init
source ~/.bashrc
执行完后提示符前面会出现 (base),说明 conda shell 集成已生效。
conda create -n voxcpm python=3.11 -y
大约 1–3 分钟。完成后激活:
conda activate voxcpm
python --version
which python pip
期望:
Python 3.11.x
/root/miniconda3/envs/voxcpm/bin/python
/root/miniconda3/envs/voxcpm/bin/pip
提示符变成 (voxcpm) 说明你已经在 voxcpm 环境里了。
从这一步开始到第 10 步结束,所有操作都在 (voxcpm) 环境里执行。
apt 安装的是系统级别的工具,跟 conda 环境无关,在哪个环境里跑都一样:
apt update
apt install -y ffmpeg libsndfile1 git build-essential screen
voxcpm 环境是全新的,里面没有 PyTorch,需要手动装。
PyTorch 轮子托管在 download.pytorch.org(境外),需要代理:
source /etc/network_turbo
pip install torch==2.8.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
约 1 GB,2–5 分钟。
python -c "import torch; print('torch:', torch.__version__); print('cuda:', torch.cuda.is_available(), torch.version.cuda); print('gpu:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'NO GPU')"
期望:
torch: 2.8.0+cu128
cuda: True 12.8
gpu: NVIDIA GeForce RTX 5090
代理保持开启,继续往下走第 4–7 步(都需要境外访问)。
cd /root
git clone https://github.com/OpenBMB/VoxCPM.git
cd /root/VoxCPM
pip install -e .
大约 10–15 分钟。
注意:pip install -e . 可能自动把 torchaudio 升级到 2.11.0(pyproject 写的是 torchaudio>=2.5.0 没有上限),同时装上 torchcodec 0.11.0。下一步检查并修复。
pip show torch torchaudio 2>/dev/null | grep -E "^Name|^Version"
两种可能的结果:
情况 A(正常):torchaudio 没被升级
Name: torch
Version: 2.8.0+cu128
Name: torchaudio
Version: 2.8.0+cu128 ← 已对齐,不用动
→ 跳到第 7 步,无需修复。
情况 B(需修复):torchaudio 被升到了 2.11.0 或更高版本
Name: torch
Version: 2.8.0+cu128
Name: torchaudio
Version: 2.11.0 ← 错误!新版要 CUDA 13,会报 libcudart.so.13 找不到
pip uninstall -y torchaudio
pip install torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
pip show torch torchaudio 2>/dev/null | grep -E "^Name|^Version"
期望:
Name: torch
Version: 2.8.0+cu128
Name: torchaudio
Version: 2.8.0+cu128
关于 torchcodec:pip install -e . 会同时装上 torchcodec,这是 VoxCPM 的正式依赖,不需要卸载。
pip install tensorboardX tensorboard
pip install -U modelscope
unset http_proxy && unset https_proxy
从这里开始到部署结束,代理都是关的。
python -c "import torch, torchaudio; from voxcpm import VoxCPM; from tensorboardX import SummaryWriter; import argbind, transformers, einops, soundfile, librosa, funasr; import sys; print('OK'); print('python:', sys.version.split()[0]); print('torch:', torch.__version__); print('torchaudio:', torchaudio.__version__); print('cuda:', torch.cuda.is_available()); print('device:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"
期望:
OK
python: 3.11.x
torch: 2.8.0+cu128
torchaudio: 2.8.0+cu128
cuda: True
device: NVIDIA GeForce RTX 5090
建议用 screen 挂后台:screen -S dl
mkdir -p /root/models
python -c "from modelscope import snapshot_download; snapshot_download('OpenBMB/VoxCPM2', local_dir='/root/models/VoxCPM2')"
约 10 GB,5–15 分钟。下载完验证:
ls -lh /root/models/VoxCPM2/
应至少有 model.safetensors(~10 GB)和 audiovae.pth。
python -c "from modelscope import snapshot_download; snapshot_download('OpenBMB/VoxCPM1.5', local_dir='/root/models/VoxCPM1.5')"
约 3 GB,2–5 分钟。下载完验证:
ls -lh /root/models/VoxCPM1.5/
推理 WebUI 内置了语音识别功能(上传参考音频时自动转写)。这个 ASR 模型约 893 MB,不提前下好首次启动 WebUI 会很慢。
python -c "from funasr import AutoModel; AutoModel(model='iic/SenseVoiceSmall', disable_update=True)"
| 项目 | VoxCPM2 | VoxCPM1.5 |
|---|---|---|
| 参数量 | 2B | 0.8B |
| 模型大小 | ~10 GB | ~3 GB |
| 训练数据采样率 | 16 kHz(yaml: sample_rate: 16000) |
44.1 kHz(yaml: sample_rate: 44100) |
| 推理显存占用 | ~8 GB | ~6 GB |
| ModelScope ID | OpenBMB/VoxCPM2 |
OpenBMB/VoxCPM1.5 |
采样率不需要手动处理:segment_audio.py 保留母带原采样率,训练时 dataloader 自动重采样到 yaml 指定的目标。
确保当前在 voxcpm 环境里:conda activate voxcpm
python -c "from voxcpm import VoxCPM; import soundfile as sf; m = VoxCPM.from_pretrained('/root/models/VoxCPM2', load_denoiser=False); wav = m.generate(text='Hello, this is VoxCPM2 running on AutoDL.', cfg_value=2.0, inference_timesteps=10); sf.write('/root/autodl-tmp/smoke_v2.wav', wav, m.tts_model.sample_rate); print('OK:', len(wav), 'samples')"
期望看到 OK: XXXXXX samples。第一次运行约 60–100 秒(torch.compile 预热)。
python -c "from voxcpm import VoxCPM; import soundfile as sf; m = VoxCPM.from_pretrained('/root/models/VoxCPM1.5', load_denoiser=False); wav = m.generate(text='Hello, this is VoxCPM 1.5 running on AutoDL.', cfg_value=2.0, inference_timesteps=10); sf.write('/root/autodl-tmp/smoke_v1_5.wav', wav, m.tts_model.sample_rate); print('OK:', len(wav), 'samples')"
用 WinSCP 把 smoke_v2.wav(和 smoke_v1_5.wav)下到本地听——应该是清晰的英文朗读。
推理冒烟测试通过后,将以下 4 个文件通过 WinSCP 上传到 AutoDL 的 /root/ 目录下:
1-run-webui.sh — WebUI 启动脚本(VoxCPM2 推理 / VoxCPM1.5 推理 / LoRA 训练与推理,三选一)2-run-train.sh — 微调训练启动脚本3-run-infer.sh — 微调后推理脚本VoxCPM使用指南.txt — 日常使用速查手册上传后执行权限和换行符修复:
chmod +x /root/1-run-webui.sh /root/2-run-train.sh /root/3-run-infer.sh
sed -i 's/\r$//' /root/1-run-webui.sh /root/2-run-train.sh /root/3-run-infer.sh
所有脚本会自动激活 voxcpm conda 环境,不需要手动切换。
VoxCPM-main 项目下有三个不同的 WebUI 入口,分别对应不同版本和功能:
| 选项 | 入口文件 | 用途 |
|---|---|---|
| 1) VoxCPM2 推理 | app.py |
VoxCPM2 专属界面(Voice Design / Controllable Cloning / Hi-Fi Cloning 三种模式) |
| 2) VoxCPM1.5 推理 | app_old.py |
VoxCPM1.5 专属界面(基础 TTS + Voice Cloning) |
| 3) LoRA 训练与推理 | lora_ft_webui.py |
LoRA 训练配置 + LoRA checkpoint 推理(支持 v1.5 和 v2) |
脚本统一端口为 6006(AutoDL 预开放端口),同时自动建符号链接解决模型路径问题。
#!/bin/bash
# VoxCPM 推理 WebUI 一键启动脚本(交互式菜单版)
#
# 用法:
# bash /root/1-run-webui.sh
# 激活 voxcpm conda 环境(Python 3.11)
eval "$(conda shell.bash hook 2>/dev/null)"
conda activate voxcpm
echo "=========================================="
echo " VoxCPM WebUI 启动器"
echo "=========================================="
echo ""
echo "请选择要启动的界面:"
echo " 1) VoxCPM2 推理 WebUI"
echo " 2) VoxCPM1.5 推理 WebUI"
echo " 3) LoRA 训练与推理 WebUI"
echo ""
read -p "请输入编号 [默认 1]: " CHOICE
CHOICE="${CHOICE:-1}"
cd /root/VoxCPM
case "$CHOICE" in
1)
# ===== VoxCPM2 推理 WebUI (app.py) =====
MODEL_PATH="/root/models/VoxCPM2"
if [ ! -d "$MODEL_PATH" ]; then
echo ""
echo "❌ 模型目录不存在: $MODEL_PATH"
echo "请先下载: python -c \"from modelscope import snapshot_download; snapshot_download('OpenBMB/VoxCPM2', local_dir='$MODEL_PATH')\""
exit 1
fi
echo ""
echo ">>> 启动 VoxCPM2 推理 WebUI"
echo ">>> 模型: $MODEL_PATH"
echo ">>> 端口: 6006"
echo ">>> 按 Ctrl+C 退出"
echo ""
python app.py --model-id "$MODEL_PATH" --port 6006
;;
2)
# ===== VoxCPM1.5 推理 WebUI (app_old.py) =====
MODEL_PATH="/root/models/VoxCPM1.5"
if [ ! -d "$MODEL_PATH" ]; then
echo ""
echo "❌ 模型目录不存在: $MODEL_PATH"
echo "请先下载: python -c \"from modelscope import snapshot_download; snapshot_download('OpenBMB/VoxCPM1.5', local_dir='$MODEL_PATH')\""
exit 1
fi
# app_old.py 查找 ./models/VoxCPM1.5(相对路径),建符号链接指向真实位置
mkdir -p /root/VoxCPM/models
[ ! -e /root/VoxCPM/models/VoxCPM1.5 ] && ln -s "$MODEL_PATH" /root/VoxCPM/models/VoxCPM1.5
echo ""
echo ">>> 启动 VoxCPM1.5 推理 WebUI"
echo ">>> 模型: $MODEL_PATH"
echo ">>> 端口: 6006"
echo ">>> 按 Ctrl+C 退出"
echo ""
# app_old.py 没有 CLI 参数,用 python -c 调用 run_demo() 传入端口和监听地址
python -c "from app_old import run_demo; run_demo(server_name='0.0.0.0', server_port=6006)"
;;
3)
# ===== LoRA 训练与推理 WebUI (lora_ft_webui.py) =====
# 建符号链接让默认路径生效(可选,用户也可以在 UI 里手动填路径)
mkdir -p /root/VoxCPM/models
[ ! -e /root/VoxCPM/models/openbmb__VoxCPM2 ] && [ -d /root/models/VoxCPM2 ] && \
ln -s /root/models/VoxCPM2 /root/VoxCPM/models/openbmb__VoxCPM2
[ ! -e /root/VoxCPM/models/openbmb__VoxCPM1.5 ] && [ -d /root/models/VoxCPM1.5 ] && \
ln -s /root/models/VoxCPM1.5 /root/VoxCPM/models/openbmb__VoxCPM1.5
mkdir -p /root/VoxCPM/lora
echo ""
echo ">>> 启动 LoRA 训练与推理 WebUI"
echo ">>> 端口: 6006"
echo ">>> 预训练模型路径可在 UI 界面中修改"
echo ">>> 按 Ctrl+C 退出"
echo ""
# lora_ft_webui.py 默认端口 7860,用 python -c 改成 6006
python -c "
import os, sys
os.makedirs('lora', exist_ok=True)
sys.path.insert(0, '.')
from lora_ft_webui import app
app.queue().launch(server_name='0.0.0.0', server_port=6006)
"
;;
*)
echo "❌ 无效选择: $CHOICE"
exit 1
;;
esac
echo ""
echo '------------------------ WebUI 已退出'
#!/bin/bash
# VoxCPM 通用微调启动脚本(交互式菜单版,支持 VoxCPM1.5 / VoxCPM2,全量 / LoRA)
# 激活 voxcpm conda 环境(Python 3.11)
eval "$(conda shell.bash hook 2>/dev/null)"
conda activate voxcpm
#
# 数据目录约定: /root/autodl-tmp/datasheet/
# - train_data.jsonl (训练清单,必须)
# - val_data.jsonl (验证清单,可选,yaml 里可写 null)
# - 一个或多个 yaml 配置文件
#
# 用法:
# bash /root/2-run-train.sh
#
# 前置条件:
# 1. yaml 里的 train_manifest / pretrained_path / save_path / tensorboard 等已填好真实路径
# 2. 建议在 screen 会话里跑:
# screen -S train
# bash /root/2-run-train.sh
# # Ctrl+A 然后 D 放后台
DATASHEET_DIR="/root/autodl-tmp/datasheet"
echo "=========================================="
echo " VoxCPM 微调训练启动器"
echo "=========================================="
echo ""
# ---------- 检查数据目录 ----------
if [ ! -d "$DATASHEET_DIR" ]; then
echo "❌ 数据目录不存在: $DATASHEET_DIR"
echo ""
echo "请先创建并上传训练数据:"
echo " mkdir -p $DATASHEET_DIR"
echo " # 然后用 WinSCP 上传 train_data.jsonl 和 yaml 到该目录"
exit 1
fi
# ---------- 扫描 yaml 文件 ----------
mapfile -t YAML_FILES < <(ls "$DATASHEET_DIR"/voxcpm_finetune_*.yaml 2>/dev/null)
if [ ${#YAML_FILES[@]} -eq 0 ]; then
echo "❌ 在 $DATASHEET_DIR 下找不到任何 voxcpm_finetune_*.yaml 配置文件"
echo ""
echo "请上传一个配置文件到该目录后重试。支持的文件名格式:"
echo " voxcpm_finetune_all_v2.yaml"
echo " voxcpm_finetune_all_v1_5.yaml"
echo " voxcpm_finetune_lora_v2.yaml"
echo " voxcpm_finetune_lora_v1_5.yaml"
exit 1
fi
# ---------- 让用户选择 yaml ----------
echo "在 $DATASHEET_DIR 下找到以下配置文件:"
echo ""
for i in "${!YAML_FILES[@]}"; do
FNAME=$(basename "${YAML_FILES[$i]}")
if [[ "$FNAME" == *"all"* ]]; then
MODE_LABEL="全量微调"
elif [[ "$FNAME" == *"lora"* ]]; then
MODE_LABEL="LoRA 微调"
else
MODE_LABEL="未知模式"
fi
if [[ "$FNAME" == *"v1_5"* ]] || [[ "$FNAME" == *"v1.5"* ]]; then
VER_LABEL="VoxCPM1.5"
elif [[ "$FNAME" == *"v2"* ]]; then
VER_LABEL="VoxCPM2"
else
VER_LABEL="未知版本"
fi
printf " %d) %-40s [ %s / %s ]\n" "$((i+1))" "$FNAME" "$MODE_LABEL" "$VER_LABEL"
done
echo ""
read -p "请选择要使用的配置 [默认 1]: " CHOICE
CHOICE="${CHOICE:-1}"
if ! [[ "$CHOICE" =~ ^[0-9]+$ ]] || [ "$CHOICE" -lt 1 ] || [ "$CHOICE" -gt "${#YAML_FILES[@]}" ]; then
echo "❌ 无效选择: $CHOICE"
exit 1
fi
YAML_PATH="${YAML_FILES[$((CHOICE-1))]}"
YAML_BASENAME=$(basename "$YAML_PATH")
# ---------- 从 yaml 里读关键字段(只读两版都有的字段) ----------
get_yaml_field() {
local key="$1"
grep "^${key}:" "$YAML_PATH" | head -1 | sed "s/^${key}:[[:space:]]*//" | sed 's/[[:space:]]*#.*$//' | tr -d '"' | sed 's/[[:space:]]*$//'
}
PRETRAINED=$(get_yaml_field "pretrained_path")
TRAIN_MANIFEST=$(get_yaml_field "train_manifest")
VAL_MANIFEST=$(get_yaml_field "val_manifest")
SAVE_PATH=$(get_yaml_field "save_path")
TENSORBOARD=$(get_yaml_field "tensorboard")
# 识别模式(有没有 lora: 块)
if grep -q "^lora:" "$YAML_PATH"; then
MODE_TAG="LoRA 微调"
else
MODE_TAG="全量微调"
fi
# 识别版本
if [[ "$YAML_BASENAME" == *"v1_5"* ]] || [[ "$YAML_BASENAME" == *"v1.5"* ]]; then
VERSION_TAG="VoxCPM1.5"
elif [[ "$YAML_BASENAME" == *"v2"* ]]; then
VERSION_TAG="VoxCPM2"
else
VERSION_TAG="(依赖 pretrained_path 自动判断)"
fi
# 格式化 val_manifest 展示
if [ -z "$VAL_MANIFEST" ] || [ "$VAL_MANIFEST" = "null" ]; then
VAL_MANIFEST_DISPLAY="(未启用)"
else
VAL_MANIFEST_DISPLAY="$VAL_MANIFEST"
fi
echo ""
echo "=========================================="
echo ">>> 配置确认"
echo "=========================================="
echo " 模式: $MODE_TAG"
echo " 版本: $VERSION_TAG"
echo " 配置文件: $YAML_PATH"
echo " 基础模型: $PRETRAINED"
echo " 训练数据: $TRAIN_MANIFEST"
echo " 验证数据: $VAL_MANIFEST_DISPLAY"
echo " 输出目录: $SAVE_PATH"
echo " 日志目录: $TENSORBOARD"
echo "=========================================="
echo ""
read -p "确认启动训练? [y/N]: " CONFIRM
CONFIRM="${CONFIRM:-N}"
if [[ ! "$CONFIRM" =~ ^[Yy]$ ]]; then
echo "已取消。"
exit 0
fi
echo ""
echo ">>> 启动训练..."
echo ""
cd /root/VoxCPM
python scripts/train_voxcpm_finetune.py \
--config_path "$YAML_PATH"
echo ""
echo '------------------------ 训练结束'
#!/bin/bash
# VoxCPM 微调后推理脚本(交互式菜单版)
# 激活 voxcpm conda 环境(Python 3.11)
eval "$(conda shell.bash hook 2>/dev/null)"
conda activate voxcpm
#
# 自动识别:
# - checkpoint 类型 (LoRA / 全量微调)
# - 模型版本 (VoxCPM1.5 / VoxCPM2)
#
# 用法:
# bash /root/3-run-infer.sh
#
# 脚本会引导你完成:
# 1. 选择 checkpoint
# 2. 输入合成文本
# 3. 选择是否启用 voice cloning
# 4. (可选) 提供参考音频和转写
#
# 输出自动保存到 /root/autodl-tmp/outputs/<train_name>_<step_name>_<timestamp>.wav
CKPT_ROOT="/root/autodl-tmp/checkpoints"
echo "=========================================="
echo " VoxCPM 微调后推理启动器"
echo "=========================================="
echo ""
# ---------- 第 1 步:选 checkpoint ----------
if [ ! -d "$CKPT_ROOT" ]; then
echo "❌ checkpoint 根目录不存在: $CKPT_ROOT"
echo "请先完成训练,或手动指定 checkpoint 路径。"
exit 1
fi
# 扫描 CKPT_ROOT 下所有 step_* 目录
mapfile -t CKPT_LIST < <(find "$CKPT_ROOT" -maxdepth 2 -type d -name "step_*" 2>/dev/null | sort)
if [ ${#CKPT_LIST[@]} -eq 0 ]; then
echo "❌ 在 $CKPT_ROOT 下找不到任何 step_* checkpoint"
echo ""
echo "请先完成一次训练,或检查 yaml 里的 save_path 设置。"
echo "当前 $CKPT_ROOT 下的内容:"
ls -la "$CKPT_ROOT" 2>/dev/null
exit 1
fi
echo "在 $CKPT_ROOT 下找到以下 checkpoint:"
echo ""
for i in "${!CKPT_LIST[@]}"; do
CKPT="${CKPT_LIST[$i]}"
REL_PATH="${CKPT#$CKPT_ROOT/}"
if [ -f "$CKPT/lora_weights.safetensors" ] || [ -f "$CKPT/lora_weights.ckpt" ]; then
TYPE_TAG="LoRA"
elif [ -f "$CKPT/model.safetensors" ] || [ -f "$CKPT/pytorch_model.bin" ]; then
TYPE_TAG="全量"
else
TYPE_TAG="未知"
fi
printf " %2d) [%s] %s\n" "$((i+1))" "$TYPE_TAG" "$REL_PATH"
done
echo ""
read -p "请选择 checkpoint 编号 [默认 1]: " CHOICE
CHOICE="${CHOICE:-1}"
if ! [[ "$CHOICE" =~ ^[0-9]+$ ]] || [ "$CHOICE" -lt 1 ] || [ "$CHOICE" -gt "${#CKPT_LIST[@]}" ]; then
echo "❌ 无效选择: $CHOICE"
exit 1
fi
CKPT_DIR="${CKPT_LIST[$((CHOICE-1))]}"
# ---------- 识别 checkpoint 类型 ----------
if [ -f "$CKPT_DIR/lora_config.json" ] \
|| [ -f "$CKPT_DIR/lora_weights.safetensors" ] \
|| [ -f "$CKPT_DIR/lora_weights.ckpt" ]; then
MODE="LoRA"
SCRIPT="scripts/test_voxcpm_lora_infer.py"
CKPT_ARG_NAME="--lora_ckpt"
elif [ -f "$CKPT_DIR/model.safetensors" ] \
|| [ -f "$CKPT_DIR/pytorch_model.bin" ]; then
MODE="full"
SCRIPT="scripts/test_voxcpm_ft_infer.py"
CKPT_ARG_NAME="--ckpt_dir"
else
echo ""
echo "❌ 无法识别 checkpoint 类型: $CKPT_DIR"
echo " 既没有 lora_weights.* 也没有 model.safetensors"
ls -la "$CKPT_DIR"
exit 1
fi
# ---------- 识别版本 ----------
VERSION_TAG="unknown"
if [ -f "$CKPT_DIR/config.json" ]; then
if grep -q '"architecture"[[:space:]]*:[[:space:]]*"voxcpm2"' "$CKPT_DIR/config.json" 2>/dev/null; then
VERSION_TAG="VoxCPM2"
else
VERSION_TAG="VoxCPM1.5"
fi
elif [ "$MODE" = "LoRA" ] && [ -f "$CKPT_DIR/lora_config.json" ]; then
BASE_MODEL=$(grep -o '"base_model"[[:space:]]*:[[:space:]]*"[^"]*"' "$CKPT_DIR/lora_config.json" | sed 's/.*"\([^"]*\)"$/\1/')
if [ -n "$BASE_MODEL" ] && [ -f "$BASE_MODEL/config.json" ]; then
if grep -q '"architecture"[[:space:]]*:[[:space:]]*"voxcpm2"' "$BASE_MODEL/config.json" 2>/dev/null; then
VERSION_TAG="VoxCPM2"
else
VERSION_TAG="VoxCPM1.5"
fi
fi
fi
echo ""
echo ">>> 已选择: $CKPT_DIR"
echo ">>> 类型: $MODE ($VERSION_TAG)"
echo ""
# ---------- 第 2 步:输入合成文本 ----------
echo "请输入要合成的文本(可以是任意语言,支持多种语言):"
read -p "> " TEXT
if [ -z "$TEXT" ]; then
echo "❌ 文本不能为空"
exit 1
fi
# ---------- 第 3 步:是否 voice cloning ----------
echo ""
echo "是否启用 voice cloning (用一段参考音频指定说话人音色)?"
echo " - 不启用: 仅依靠 checkpoint 的音色"
echo " - 启用: 需要额外提供一段参考音频 + 它的文字转写"
echo ""
read -p "启用 voice cloning? [y/N]: " USE_CLONING
USE_CLONING="${USE_CLONING:-N}"
PROMPT_AUDIO=""
PROMPT_TEXT=""
if [[ "$USE_CLONING" =~ ^[Yy]$ ]]; then
echo ""
read -p "请输入参考音频的完整路径: " PROMPT_AUDIO
if [ ! -f "$PROMPT_AUDIO" ]; then
echo "❌ 参考音频文件不存在: $PROMPT_AUDIO"
exit 1
fi
echo ""
read -p "请输入参考音频的文字转写: " PROMPT_TEXT
if [ -z "$PROMPT_TEXT" ]; then
echo "❌ 参考音频转写不能为空"
exit 1
fi
fi
# ---------- 准备输出路径 ----------
STEP_NAME=$(basename "$CKPT_DIR")
TRAIN_NAME=$(basename "$(dirname "$CKPT_DIR")")
mkdir -p /root/autodl-tmp/outputs
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
OUTPUT_PATH="/root/autodl-tmp/outputs/${TRAIN_NAME}_${STEP_NAME}_${TIMESTAMP}.wav"
# ---------- 展示最终配置并确认 ----------
echo ""
echo "=========================================="
echo ">>> 推理配置确认"
echo "=========================================="
echo " Checkpoint: $CKPT_DIR"
echo " 类型: $MODE ($VERSION_TAG)"
echo " 合成文本: $TEXT"
if [ -n "$PROMPT_AUDIO" ]; then
echo " 参考音频: $PROMPT_AUDIO"
echo " 参考转写: $PROMPT_TEXT"
echo " 推理模式: Voice Cloning"
else
echo " 推理模式: 普通推理"
fi
echo " 输出路径: $OUTPUT_PATH"
echo "=========================================="
echo ""
read -p "确认开始推理? [Y/n]: " CONFIRM
CONFIRM="${CONFIRM:-Y}"
if [[ ! "$CONFIRM" =~ ^[Yy]$ ]]; then
echo "已取消。"
exit 0
fi
# ---------- 执行推理 ----------
echo ""
echo ">>> 开始推理..."
echo ""
cd /root/VoxCPM
if [ -n "$PROMPT_AUDIO" ] && [ -n "$PROMPT_TEXT" ]; then
python $SCRIPT \
$CKPT_ARG_NAME "$CKPT_DIR" \
--text "$TEXT" \
--prompt_audio "$PROMPT_AUDIO" \
--prompt_text "$PROMPT_TEXT" \
--output "$OUTPUT_PATH" \
--cfg_value 2.0 \
--inference_timesteps 10
else
python $SCRIPT \
$CKPT_ARG_NAME "$CKPT_DIR" \
--text "$TEXT" \
--output "$OUTPUT_PATH" \
--cfg_value 2.0 \
--inference_timesteps 10
fi
echo ""
echo '------------------------ 推理完成'
echo "输出文件: $OUTPUT_PATH"
echo ""
echo "用 WinSCP 下载这个 wav 到本地听效果。"
将此文件上传到 /root/VoxCPM使用指南.txt,方便随时查阅。
================================================================================
VoxCPM 使用指南(VoxCPM1.5 + VoxCPM2 通用平台)
================================================================================
本平台支持 VoxCPM1.5 和 VoxCPM2 两个版本的推理、全量微调和 LoRA 微调。
所有操作通过 /root/ 下的三个 sh 脚本完成,脚本会自动激活 voxcpm conda 环境,
不需要手动切换环境。
--------------------------------------------------------------------------------
目录结构
--------------------------------------------------------------------------------
/root/
1-run-webui.sh WebUI 启动脚本(VoxCPM2 推理 / VoxCPM1.5 推理 / LoRA 训练与推理)
2-run-train.sh 微调训练启动脚本
3-run-infer.sh 微调后推理脚本
/root/VoxCPM/ VoxCPM 源码(支持 v1.5 和 v2)
/root/models/VoxCPM2/ VoxCPM2 基础模型
/root/models/VoxCPM1.5/ VoxCPM1.5 基础模型(可选)
/root/autodl-tmp/
datasheet/ 训练数据集 + yaml 配置文件
checkpoints/ 训练产出的 checkpoint
logs/ TensorBoard 日志
outputs/ 推理输出的 wav 文件
--------------------------------------------------------------------------------
脚本 1:WebUI 启动器(1-run-webui.sh)
--------------------------------------------------------------------------------
功能:启动 Gradio 界面,支持三种模式。
运行方式:
bash /root/1-run-webui.sh
脚本会显示菜单让你选择:
1) VoxCPM2 推理 WebUI — VoxCPM2 专属界面(Voice Design / Cloning 三种模式)
2) VoxCPM1.5 推理 WebUI — VoxCPM1.5 专属界面(基础 TTS + Voice Cloning)
3) LoRA 训练与推理 WebUI — LoRA 训练配置 + LoRA checkpoint 推理(支持 v1.5 和 v2)
选完后自动加载模型并启动 WebUI,端口统一为 6006。
访问 WebUI 的方法(二选一):
方法 A:AutoDL 控制台 -> 我的实例 -> 点"自定义服务"-> 自动打开浏览器
方法 B:本地电脑开 SSH 隧道转发 6006 端口
参考教程 https://www.autodl.com/docs/ssh_proxy/
代理成功后在本地浏览器访问 http://127.0.0.1:6006/
退出 WebUI:在启动脚本的终端按 Ctrl+C
注意事项:
- 首次启动约 1-2 分钟(加载模型 + torch.compile 预热),后续启动约 30 秒
- VoxCPM2 和 VoxCPM1.5 使用不同的界面(功能不同),不要混用
- LoRA WebUI 的预训练模型路径可以在界面中手动修改
--------------------------------------------------------------------------------
脚本 2:微调训练(2-run-train.sh)
--------------------------------------------------------------------------------
功能:启动 VoxCPM 微调训练,支持全量微调和 LoRA,支持 v1.5 和 v2。
运行方式:
bash /root/2-run-train.sh
前置条件:
1. 在 /root/autodl-tmp/datasheet/ 下准备好训练数据:
- train_data.jsonl 训练清单(必须)
- val_data.jsonl 验证清单(可选)
- 音频切片 wav 文件
- 一个 yaml 配置文件(以下四种选一个):
voxcpm_finetune_all_v2.yaml VoxCPM2 全量微调
voxcpm_finetune_lora_v2.yaml VoxCPM2 LoRA 微调
voxcpm_finetune_all_v1_5.yaml VoxCPM1.5 全量微调
voxcpm_finetune_lora_v1_5.yaml VoxCPM1.5 LoRA 微调
2. yaml 文件里的路径已填好真实值:
- pretrained_path 基础模型路径
- train_manifest 训练数据清单路径
- save_path checkpoint 输出路径
- tensorboard TensorBoard 日志路径
使用流程:
脚本自动扫描 datasheet 目录下的 yaml 文件,列出菜单让你选择。
选择后展示配置信息,确认后才会启动训练。
建议用 screen 会话跑,防止 SSH 断连:
screen -S train
bash /root/2-run-train.sh
# 按 Ctrl+A 然后 D 放后台
# screen -r train 回来看进度
监控训练(另开一个终端):
tensorboard --logdir /root/autodl-tmp/logs/<日志目录名> --port 6006
然后用 AutoDL"自定义服务"或 SSH 隧道打开 http://127.0.0.1:6006/
--------------------------------------------------------------------------------
脚本 3:微调后推理(3-run-infer.sh)
--------------------------------------------------------------------------------
功能:对训练产出的 checkpoint 做推理测试。
自动识别 LoRA / 全量微调类型,自动识别 v1.5 / v2 版本。
运行方式:
bash /root/3-run-infer.sh
使用流程(脚本会引导你完成):
1. 自动扫描 /root/autodl-tmp/checkpoints/ 下的 checkpoint,列出菜单
2. 输入要合成的文本
3. 选择是否启用 voice cloning(需要提供参考音频和转写)
4. 确认配置后开始推理
输出文件保存到 /root/autodl-tmp/outputs/ 目录。
文件名格式:<训练名>_<step号>_<时间戳>.wav
用 WinSCP 下载到本地听效果。
--------------------------------------------------------------------------------
日常使用速查
--------------------------------------------------------------------------------
想做什么 命令
------------------------------- -----------------------------------------------
听 VoxCPM2 原版音色 bash /root/1-run-webui.sh (选 1)
听 VoxCPM1.5 原版音色 bash /root/1-run-webui.sh (选 2)
LoRA 训练与推理界面 bash /root/1-run-webui.sh (选 3)
启动微调训练 bash /root/2-run-train.sh
测试训练出的 checkpoint bash /root/3-run-infer.sh
用 Jupyter 直接用(base 环境,不受影响)
用 TensorBoard tensorboard --logdir <日志目录> --port 6006
手动跑 VoxCPM Python 代码 conda activate voxcpm 然后 python
切回默认环境 conda activate base
--------------------------------------------------------------------------------
常见问题
--------------------------------------------------------------------------------
Q: 运行 sh 脚本报 "bad interpreter: /bin/bash^M"
A: Windows 换行符问题。执行:
sed -i 's/\r$//' /root/1-run-webui.sh /root/2-run-train.sh /root/3-run-infer.sh
Q: 运行 sh 脚本报 "Permission denied"
A: 没给执行权限。执行:
chmod +x /root/1-run-webui.sh /root/2-run-train.sh /root/3-run-infer.sh
Q: conda activate voxcpm 报错
A: 先执行 conda init && source ~/.bashrc
Q: WebUI 启动后本地浏览器打不开
A: 确认端口转发已设置。参考 https://www.autodl.com/docs/ssh_proxy/
Q: 模型目录不存在
A: 脚本会提示下载命令,按提示执行即可(用 ModelScope 下载,不需要开代理)。
Q: Jupyter 打不开了
A: 确认在 base 环境。执行 conda activate base 后再试。
Q: 训练时 SSH 断了,训练也停了
A: 下次用 screen 挂后台再跑。screen -S train && bash /root/2-run-train.sh
================================================================================
| 项 | 预期值 |
|---|---|
| conda base 环境 | Python 3.12.x(Jupyter/TensorBoard 正常) |
| conda voxcpm 环境 | Python 3.11.x(VoxCPM 专用) |
| PyTorch(voxcpm 环境内) | 2.8.0+cu128 |
| torchaudio(voxcpm 环境内) | 2.8.0+cu128 |
| CUDA | True, 12.8 |
| VoxCPM 源码位置 | /root/VoxCPM/(editable) |
| VoxCPM2 模型位置 | /root/models/VoxCPM2/(~10 GB) |
| VoxCPM1.5 模型位置 | /root/models/VoxCPM1.5/(~3 GB,可选) |
| SenseVoice-Small ASR | 已缓存到 ~/.cache/modelscope/ |
| ffmpeg / libsndfile | ✅ |
| tensorboardX / tensorboard | ✅(voxcpm 环境内) |
| 推理冒烟测试 | ✅ |
直接用 sh 脚本,脚本会自动激活 voxcpm 环境:
bash /root/1-run-webui.sh # WebUI(选 1=VoxCPM2 推理 / 2=VoxCPM1.5 推理 / 3=LoRA 训练与推理)
bash /root/2-run-train.sh # 启动训练
bash /root/3-run-infer.sh # 测试 checkpoint
手动跑 Python 命令时先切环境:
conda activate voxcpm
python -c "from voxcpm import VoxCPM; ..."
conda activate voxcpm # 切到 VoxCPM 专用环境
conda activate base # 切回 AutoDL 默认环境
conda deactivate # 退出当前环境(回到 base 或上一层)