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.13 | 3.10 或 3.11 |
| PyTorch | ≥ 2.5.0 | 2.5.0–2.8.x |
| CUDA | ≥ 12.0 | 12.8+ |
| GPU 显存 | ~8 GB(VoxCPM2) | 12 GB+(RTX 3060/4070+) |
| 磁盘空间 | ~10 GB | 20 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+ 存在兼容性问题,暂不推荐。
环境准备(推荐)
建议使用虚拟环境隔离依赖,避免与其他项目冲突:
python -m venv voxcpm_envsource voxcpm_env/bin/activate # Linux / macOSvoxcpm_env\Scripts\activate # Windows安装前请验证环境:
python --version # 应为 3.10 - 3.12nvcc --version # 确认 CUDA 可用python -c "import torch; print(torch.cuda.is_available())" # 应为 True安装
pip 安装(推荐)
pip install voxcpm一行命令完成。voxcpm 包会自动安装 PyTorch 以外的依赖。
源码安装
git clone https://github.com/OpenBMB/VoxCPM.gitcd VoxCPMpip install -e .适合需要修改源码或开发自定义功能的用户。
模型下载
模型通过 from_pretrained 自动从 Hugging Face 下载,首次使用时会缓存到本地。
Hugging Face(自动下载)
from voxcpm import VoxCPMmodel = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)模型大小约 4.96 GB(bf16 safetensors 格式,含 AudioVAE V2 约 5 GB),首次加载需等待下载完成。
ModelScope(国内镜像,速度更快)
国内网络访问 Hugging Face 可能较慢,推荐用 ModelScope 下载:
pip install modelscopefrom modelscope import snapshot_downloadsnapshot_download("OpenBMB/VoxCPM2", local_dir="./pretrained_models/VoxCPM2")
# 从本地加载from voxcpm import VoxCPMmodel = VoxCPM.from_pretrained("./pretrained_models/VoxCPM2", load_denoiser=False)Python API 使用
基础文本转语音
from voxcpm import VoxCPMimport 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_path和prompt_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 命令。
语音设计
voxcpm design \ --text "今天是个好天气。" \ --output out.wav带风格控制:
voxcpm design \ --text "今天是个好天气。" \ --control "年轻的男声,温暖沉稳,带着微笑" \ --output out.wav语音克隆
# 可控克隆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批量处理
voxcpm batch --input examples/input.txt --output-dir outsinput.txt 每行一个要合成的句子。
查看所有命令
voxcpm --helpWeb 演示界面
启动本地 Web UI,在浏览器中交互式使用:
python app.py --port 8808浏览器打开 http://localhost:8808,可在界面中选择模型、输入文本、上传参考音频、调整参数并试听结果。
生产环境部署
vLLM-Omni(多租户、OpenAI 兼容接口)
适合需要高并发、API 化部署的场景:
# 安装 vLLM-Omni(vllm-omni 为独立 PyPI 包,自动检测硬件后端)uv pip install vllm --torch-backend=autouv 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:
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):
pip install nano-vllm-voxcpmfrom nanovllm_voxcpm import VoxCPMimport numpy as npimport 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 后端。
# 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 8VoxCPMANE 利用 Apple Neural Engine 进行推理加速,提供 Web 界面和 REST API 服务器:
pip install voxcpmaneuv run voxcpmane-server # 启动在 http://localhost:8000OpenVINO 将 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 超参数建议
按语音时长自动调整(来源:官方微调文档):
| 干净语音时长 | 目标 Epoch | r / α | 学习率 |
|---|---|---|---|
| < 2 分钟 | 25 | 32/32 | 1e-4 |
| 2–5 分钟 | 20 | 32/32 | 1e-4 |
| 5–10 分钟(最佳区间) | 15 | 32/32 | 1e-4 |
| 10–20 分钟 | 12 | 32/32 | 1e-4 |
| 20–60 分钟 | 8 | 32/32 | 1e-4 |
| 60–120 分钟 | 5 | 64/64 | 5e-5 |
| 120 分钟以上 | 3 | 64/64 | 5e-5 |
梯度累积步数建议:< 200 条音频设 4,< 500 条设 8,500+ 条设 16。
快速启动命令
git clone https://github.com/OpenBMB/VoxCPM.gitcd 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_path、train_manifest、save_path 等路径。
常见微调问题
Q:LoRA 微调后输出杂音
检查音频采样率是否与模型匹配(VoxCPM2 需 48kHz),采样率不匹配会导致输出异常。
Q:微调后音色相似度低
确保训练数据在 5 分钟以上,且音频为干净单人语音。数据量过少或含噪声会显著影响相似度。
使用微调模型
LoRA 微调完成后,可通过 VoxCPM.from_pretrained() 加载 LoRA 权重进行推理:
import jsonfrom voxcpm import VoxCPMfrom voxcpm.model.voxcpm import LoRAConfigimport 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_pathlora_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 权重以适配器形式加载,无需单独的合并步骤。训练产生的
.safetensorsLoRA 文件可直接用于推理。对于追求极致推理速度的场景,建议将 LoRA 权重合并到基础模型中(可减少适配器计算开销)。VoxCPM 官方目前未提供独立的合并脚本,具体合并方法请参考官方文档最新进展。
此外,官方提供了 LoRA 微调 WebUI,可在浏览器中可视化操作:
python lora_ft_webui.py # 浏览器打开 http://localhost:7860详见 官方微调文档。
调优建议
| 参数 | 说明 | 建议 |
|---|---|---|
inference_timesteps | 扩散步数 | 默认 10,降到 6 可提速 ~40%,高频细节略有损失 |
cfg_value | CFG 引导强度 | 默认 2.0,越低越平淡,越高越有感情但可能过激 |
| 参考音频 | 克隆音源 | 5–15 秒,干净无背景音乐 |
| Voice Design 描述 | 音色控制 | 自然语言描述性别、年龄、语气、情绪,结果有随机性 |
支持的语言和方言
30 种语言:阿拉伯语、缅甸语、中文、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、印地语、印尼语、意大利语、日语、高棉语、韩语、老挝语、马来语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰语、土耳其语、越南语
9 种中文方言:四川话、粤语、吴语、东北话、河南话、陕西话、山东话、天津话、闽南话
无需手动指定语言标签,模型自动检测输入文本的语种。
常见问题
Q:pip 安装时提示 PyTorch 版本不兼容
确保 PyTorch ≥ 2.5.0 且 CUDA ≥ 12.0:
pip install torch>=2.5.0 --extra-index-url https://download.pytorch.org/whl/cu121Q:CUDA out of memory
按优先级依次尝试以下方案:
- 启用降噪器节省部分显存:
VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=True) - 减少显存碎片:在
import torch之前设置环境变量:Terminal window export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True - 使用 FP8 量化(需官方支持):FP8 量化可将显存需求从 ~8 GB 降至 ~2 GB,音质损失 < 3%。
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", quantization="fp8")
- 降低
inference_timesteps:从 10 降到 6 可节省部分显存,速度提升 ~40%。 - 换用更小的模型(VoxCPM1.5 约 ~6 GB,VoxCPM-0.5B 约 ~5 GB)。
Q:国内 Hugging Face 下载很慢
使用 ModelScope 下载(见上文模型下载章节),或设置 HF 镜像:
export HF_ENDPOINT=https://hf-mirror.comQ:生成的语音有杂音
尝试设置 load_denoiser=True 启用内置降噪器:
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=True)Q:Voice Design 效果不稳定
这是正常现象。Voice Design 结果存在随机性,建议同一描述生成 2–3 次选择最佳效果。
使用限制与伦理声明
VoxCPM2 严禁用于冒充、欺诈或虚假信息传播。使用时请遵守当地法律法规,在声音克隆场景中应获得被克隆者的明确同意。