3651 字
18 分钟
VoxCPM2 部署使用教程:多语言语音合成、声音设计与克隆

VoxCPM2 是什么#

VoxCPM2 是 OpenBMB 社区联合清华大学人机语音交互实验室发布的新一代 TTS(文本转语音)模型。它基于 MiniCPM-4 主干,采用无 tokenizer 的扩散自回归架构,直接从文本生成连续语音表征,跳过离散化步骤,实现端到端语音合成。

核心特性:

特性说明
参数量2B
训练数据200 万+ 小时多语言语音
语言支持30 种语言 + 9 种中文方言
输出音质48kHz 影棚级(AudioVAE V2 内置超分辨率)
开源协议Apache-2.0,商用免费

四大核心能力:多语言 TTS语音设计(Voice Design,用文字描述创造新音色)、可控克隆(Controllable Cloning)、终极克隆(Ultimate Cloning,最高保真度)。

系统要求#

项目最低要求推荐配置
Python≥ 3.10,< 3.133.10 或 3.11
PyTorch≥ 2.5.02.5.0–2.8.x
CUDA≥ 12.012.8+
GPU 显存~8 GB(VoxCPM2)12 GB+(RTX 3060/4070+)
磁盘空间~10 GB20 GB+

VoxCPM 系列有多档模型:

模型显存要求说明
VoxCPM-0.5B~5 GB轻量版,适合低配显卡
VoxCPM1.5~6 GB均衡版
VoxCPM2~8 GB最新旗舰,音质最佳

流式生成可能额外需要 1–2 GB 显存,语音克隆建议 10 GB+ 以获得最佳体验。

社区反馈 Python 3.10 和 3.11 推理速度更优,建议优先选择。

PyTorch 推荐使用 2.5.0–2.8.x;v2.9+ 存在兼容性问题,暂不推荐。

环境准备(推荐)#

建议使用虚拟环境隔离依赖,避免与其他项目冲突:

Terminal window
python -m venv voxcpm_env
source voxcpm_env/bin/activate # Linux / macOS
voxcpm_env\Scripts\activate # Windows

安装前请验证环境:

Terminal window
python --version # 应为 3.10 - 3.12
nvcc --version # 确认 CUDA 可用
python -c "import torch; print(torch.cuda.is_available())" # 应为 True

安装#

pip 安装(推荐)#

Terminal window
pip install voxcpm

一行命令完成。voxcpm 包会自动安装 PyTorch 以外的依赖。

源码安装#

Terminal window
git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
pip install -e .

适合需要修改源码或开发自定义功能的用户。

模型下载#

模型通过 from_pretrained 自动从 Hugging Face 下载,首次使用时会缓存到本地。

Hugging Face(自动下载)#

from voxcpm import VoxCPM
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)

模型大小约 4.96 GB(bf16 safetensors 格式,含 AudioVAE V2 约 5 GB),首次加载需等待下载完成。

ModelScope(国内镜像,速度更快)#

国内网络访问 Hugging Face 可能较慢,推荐用 ModelScope 下载:

Terminal window
pip install modelscope
from modelscope import snapshot_download
snapshot_download("OpenBMB/VoxCPM2", local_dir="./pretrained_models/VoxCPM2")
# 从本地加载
from voxcpm import VoxCPM
model = VoxCPM.from_pretrained("./pretrained_models/VoxCPM2", load_denoiser=False)

Python API 使用#

基础文本转语音#

from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
wav = model.generate(
text="VoxCPM2 是目前推荐的多语言逼真语音合成版本。",
cfg_value=2.0, # CFG 引导强度
inference_timesteps=10, # 扩散步数
)
sf.write("demo.wav", wav, model.tts_model.sample_rate)

参数说明:

  • inference_timesteps:扩散步数,取值范围 4–20。值越小速度越快但音质略降,默认 10 为平衡点。
  • cfg_value:CFG 引导强度,取值范围 1.0–5.0。值越高语音越有表现力,但过高可能导致失真。推荐 1.5–3.0。

语音设计(Voice Design)#

用文字描述创造全新音色,无需参考音频。在文本前加括号描述即可:

wav = model.generate(
text="(一位年轻女性,温柔甜美的声音)你好,欢迎使用 VoxCPM2!",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

描述支持自然语言,可以指定性别、年龄、语气、情绪等。结果存在随机性,建议生成 1–3 次选择最佳。

可控语音克隆#

提供参考音频 + 可选风格描述:

# 基础克隆
wav = model.generate(
text="这是 VoxCPM2 生成的克隆语音。",
reference_wav_path="speaker.wav",
)
# 克隆 + 风格控制
wav = model.generate(
text="(语速稍快,欢快语调)这是带风格控制的克隆语音。",
reference_wav_path="speaker.wav",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("clone.wav", wav, model.tts_model.sample_rate)

参考音频建议 5–15 秒,干净无背景音乐,任意采样率均可(内部自动重采样到 16kHz)。

终极克隆(Ultimate Cloning)#

提供参考音频 + 对应文本,最高保真度:

wav = model.generate(
text="这是 VoxCPM2 的终极克隆演示。",
prompt_wav_path="speaker.wav",
prompt_text="参考音频对应的文本转录内容。",
reference_wav_path="speaker.wav", # 可选,提升相似度
)
sf.write("hifi_clone.wav", wav, model.tts_model.sample_rate)

为获得更好的相似度,可将同一音频同时传给 reference_wav_pathprompt_wav_path。同时,prompt_text 须与参考音频的文本内容严格对应,这是提升保真度的关键。

流式生成#

适用于需要低延迟的场景(如实时对话):

import numpy as np
chunks = []
for chunk in model.generate_streaming(
text="流式文本转语音非常简单!",
):
chunks.append(chunk)
wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)

CLI 命令行使用#

安装后可直接在终端使用 voxcpm 命令。

语音设计#

Terminal window
voxcpm design \
--text "今天是个好天气。" \
--output out.wav

带风格控制:

Terminal window
voxcpm design \
--text "今天是个好天气。" \
--control "年轻的男声,温暖沉稳,带着微笑" \
--output out.wav

语音克隆#

Terminal window
# 可控克隆
voxcpm clone \
--text "这是克隆演示。" \
--reference-audio path/to/voice.wav \
--output out.wav
# 终极克隆
voxcpm clone \
--text "这是终极克隆演示。" \
--prompt-audio path/to/voice.wav \
--prompt-text "参考音频的文本内容" \
--reference-audio path/to/voice.wav \
--output out.wav

批量处理#

Terminal window
voxcpm batch --input examples/input.txt --output-dir outs

input.txt 每行一个要合成的句子。

查看所有命令#

Terminal window
voxcpm --help

Web 演示界面#

启动本地 Web UI,在浏览器中交互式使用:

Terminal window
python app.py --port 8808

浏览器打开 http://localhost:8808,可在界面中选择模型、输入文本、上传参考音频、调整参数并试听结果。

生产环境部署#

vLLM-Omni(多租户、OpenAI 兼容接口)#

适合需要高并发、API 化部署的场景:

Terminal window
# 安装 vLLM-Omni(vllm-omni 为独立 PyPI 包,自动检测硬件后端)
uv pip install vllm --torch-backend=auto
uv pip install vllm-omni
# 启动服务
vllm serve openbmb/VoxCPM2 --omni --port 8000

请参考 vLLM-Omni 官方文档 获取最新版本信息。vLLM 与 vLLM-Omni 需保持相同 major.minor 版本。

Python 版本注意:如果计划使用 vLLM-Omni 进行生产部署,官方推荐使用 Python 3.12 环境。这与前文通用的 3.10/3.11 推荐不同,请注意隔离环境。

调用 API:

Terminal window
curl http://localhost:8000/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{"model":"openbmb/VoxCPM2","input":"你好,这是 VoxCPM2!","voice":"default"}' \
--output out.wav

多节点部署提示:多节点部署时,请确保将 audios/ 等输出目录设置为共享存储(如 NFS、CephFS),以保证所有节点可访问生成的音频文件。

Nano-vLLM(低延迟推理加速)#

标准 PyTorch 推理 RTF 约 0.3,Nano-vLLM 可将 RTF 降至约 0.13(RTX 4090):

Terminal window
pip install nano-vllm-voxcpm
from nanovllm_voxcpm import VoxCPM
import numpy as np
import soundfile as sf
server = VoxCPM.from_pretrained(model="/path/to/VoxCPM", devices=[0])
chunks = list(server.generate(target_text="你好,VoxCPM!"))
sf.write("out.wav", np.concatenate(chunks), 48000)
server.stop()

其他部署方案#

除上述方案外,社区还维护了以下备选部署路径,适合不同硬件环境:

方案适用场景官方仓库

| VoxCPM.cpp | GGUF 量化,纯 CPU 推理,边缘设备(树莓派/低功耗服务器) | bluryar/VoxCPM.cpp | | VoxCPMANE | Apple Neural Engine 加速,macOS + Apple Silicon | 0seba/VoxCPMANE |

| OpenVINO | Intel CPU / iGPU / Arc 独显推理 | openvino_notebooks/voxcpm2-tts |

VoxCPM.cpp 目前仅支持 VoxCPM1.5,暂不支持 VoxCPM2。基于 ggml,与 llama.cpp/whisper.cpp 同技术栈,支持 GGUF 量化格式。Q4_K 量化后 VoxCPM-0.5B 仅 477 MB,RTF 约 3.6(Intel i5-12600K),纯 CPU 可运行。支持 CUDA/Vulkan 后端。

Terminal window
# CPU 推理示例
./build/examples/voxcpm_tts \
--model-path ./models/voxcpm1.5-q8_0.gguf \
--prompt-audio reference.wav \
--prompt-text "参考音频文本" \
--text "要合成的文本。" \
--output out.wav \
--backend cpu \
--threads 8

VoxCPMANE 利用 Apple Neural Engine 进行推理加速,提供 Web 界面和 REST API 服务器:

Terminal window
pip install voxcpmane
uv run voxcpmane-server # 启动在 http://localhost:8000

OpenVINO 将 PyTorch 模型导出为 IR 格式,可在 Intel CPU / iGPU / Arc 独显上高效推理,适合没有 NVIDIA 显卡的用户。

微调(Fine-tuning)#

VoxCPM2 支持端到端 LoRA 和全参数微调(SFT),仅需 5–10 分钟干净语音即可适配特定说话人。

微调方式选择#

方式显存要求适用场景
LoRA(推荐入门)~8 GB+数据量少(< 1 小时),快速适配新说话人
全参数微调(SFT)~16 GB+数据充足(> 1 小时),追求最高音质

训练数据准备#

训练数据使用 JSONL 格式的 manifest 文件,每行包含音频路径和对应文本:

{"audio": "/path/to/audio_001.wav", "text": "这是第一段训练文本。"}
{"audio": "/path/to/audio_002.wav", "text": "这是第二段训练文本。"}

数据准备要点:

  • 音频格式:WAV,VoxCPM2 使用 48kHz 采样率(VoxCPM1.5 使用 44.1kHz),确保匹配模型
  • 切片长度:建议每段 3–15 秒,整句切分,不要从词中间截断
  • 音频质量:干净无背景音乐,无明显噪声
  • 文本对应:确保文本与音频内容严格一致

LoRA 超参数建议#

按语音时长自动调整(来源:官方微调文档):

干净语音时长目标 Epochr / α学习率
< 2 分钟2532/321e-4
2–5 分钟2032/321e-4
5–10 分钟(最佳区间)1532/321e-4
10–20 分钟1232/321e-4
20–60 分钟832/321e-4
60–120 分钟564/645e-5
120 分钟以上364/645e-5

梯度累积步数建议:< 200 条音频设 4,< 500 条设 8,500+ 条设 16。

快速启动命令#

Terminal window
git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
# LoRA 微调(推荐入门)
python scripts/train_voxcpm_finetune.py \
--config_path conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml
# 全参数微调
python scripts/train_voxcpm_finetune.py \
--config_path conf/voxcpm_v1.5/voxcpm_finetune_all.yaml

训练前需在对应的 YAML 配置文件中设置 pretrained_pathtrain_manifestsave_path 等路径。

常见微调问题#

Q:LoRA 微调后输出杂音

检查音频采样率是否与模型匹配(VoxCPM2 需 48kHz),采样率不匹配会导致输出异常。

Q:微调后音色相似度低

确保训练数据在 5 分钟以上,且音频为干净单人语音。数据量过少或含噪声会显著影响相似度。

使用微调模型#

LoRA 微调完成后,可通过 VoxCPM.from_pretrained() 加载 LoRA 权重进行推理:

import json
from voxcpm import VoxCPM
from voxcpm.model.voxcpm import LoRAConfig
import soundfile as sf
base_model_path = "openbmb/VoxCPM2"
lora_ckpt_dir = "/path/to/checkpoints/lora/step_0002000"
# 加载 LoRA 配置
with open(f"{lora_ckpt_dir}/lora_config.json") as f:
lora_info = json.load(f)
lora_info["base_model"] = base_model_path
lora_cfg = LoRAConfig(**lora_info["lora_config"])
# 加载基础模型 + LoRA 适配器
model = VoxCPM.from_pretrained(
hf_model_id=base_model_path,
lora_config=lora_cfg,
lora_weights_path=lora_ckpt_dir,
)
# 正常推理
wav = model.generate(
text="这是我微调后的声音。",
cfg_value=2.0,
inference_timesteps=10,
)
sf.write("finetuned_output.wav", wav, model.tts_model.sample_rate)

VoxCPM 的 LoRA 权重以适配器形式加载,无需单独的合并步骤。训练产生的 .safetensors LoRA 文件可直接用于推理。

对于追求极致推理速度的场景,建议将 LoRA 权重合并到基础模型中(可减少适配器计算开销)。VoxCPM 官方目前未提供独立的合并脚本,具体合并方法请参考官方文档最新进展。

此外,官方提供了 LoRA 微调 WebUI,可在浏览器中可视化操作:

Terminal window
python lora_ft_webui.py # 浏览器打开 http://localhost:7860

详见 官方微调文档

调优建议#

参数说明建议
inference_timesteps扩散步数默认 10,降到 6 可提速 ~40%,高频细节略有损失
cfg_valueCFG 引导强度默认 2.0,越低越平淡,越高越有感情但可能过激
参考音频克隆音源5–15 秒,干净无背景音乐
Voice Design 描述音色控制自然语言描述性别、年龄、语气、情绪,结果有随机性

支持的语言和方言#

30 种语言:阿拉伯语、缅甸语、中文、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、印地语、印尼语、意大利语、日语、高棉语、韩语、老挝语、马来语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰语、土耳其语、越南语

9 种中文方言:四川话、粤语、吴语、东北话、河南话、陕西话、山东话、天津话、闽南话

无需手动指定语言标签,模型自动检测输入文本的语种。

常见问题#

Q:pip 安装时提示 PyTorch 版本不兼容

确保 PyTorch ≥ 2.5.0 且 CUDA ≥ 12.0:

Terminal window
pip install torch>=2.5.0 --extra-index-url https://download.pytorch.org/whl/cu121

Q:CUDA out of memory

按优先级依次尝试以下方案:

  1. 启用降噪器节省部分显存VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=True)
  2. 减少显存碎片:在 import torch 之前设置环境变量:
    Terminal window
    export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
  3. 使用 FP8 量化(需官方支持):FP8 量化可将显存需求从 ~8 GB 降至 ~2 GB,音质损失 < 3%。
    model = VoxCPM.from_pretrained("openbmb/VoxCPM2", quantization="fp8")
  4. 降低 inference_timesteps:从 10 降到 6 可节省部分显存,速度提升 ~40%。
  5. 换用更小的模型(VoxCPM1.5 约 ~6 GB,VoxCPM-0.5B 约 ~5 GB)。

Q:国内 Hugging Face 下载很慢

使用 ModelScope 下载(见上文模型下载章节),或设置 HF 镜像:

Terminal window
export HF_ENDPOINT=https://hf-mirror.com

Q:生成的语音有杂音

尝试设置 load_denoiser=True 启用内置降噪器:

model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=True)

Q:Voice Design 效果不稳定

这是正常现象。Voice Design 结果存在随机性,建议同一描述生成 2–3 次选择最佳效果。

使用限制与伦理声明#

VoxCPM2 严禁用于冒充、欺诈或虚假信息传播。使用时请遵守当地法律法规,在声音克隆场景中应获得被克隆者的明确同意。

参考资源#

VoxCPM2 部署使用教程:多语言语音合成、声音设计与克隆
https://blog.syomega.top/posts/voxcpm2-deploy-guide/
作者
酱w
发布于
2026-05-18
许可协议
CC BY-NC-SA 4.0