快速开始与部署指南

VoxCPM2 文档

面向开发者和产品集成的本地文档页，整理自 VoxCPM README：安装、推理 API、CLI、Web Demo、生产服务与商业部署路径。

开始安装在线体验

2B 参数规模，基于 MiniCPM-4 构建

30+ 全球语言与 9 种中文方言

48kHz 高质量语音输出

安装

VoxCPM2 推荐使用 Python 3.10 到 3.12、PyTorch 2.5 或以上版本，以及 CUDA 12 或以上版本。

pip install voxcpm

如果需要从 ModelScope 下载权重到本地，可先安装 ModelScope：

pip install modelscope

Python API

最小文本转语音示例：加载 openbmb/VoxCPM2，生成音频并保存为 demo.wav。

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,
    inference_timesteps=10,
)

sf.write("demo.wav", wav, model.tts_model.sample_rate)

音色设计

在文本开头用括号描述声音特征，即可无需参考音频生成全新音色。

wav = model.generate(
    text="(年轻女性，声音温柔甜美)你好，欢迎使用 VoxCPM2！",
    cfg_value=2.0,
    inference_timesteps=10,
)

可控声音克隆

传入参考音频后，可以克隆音色，并用风格指令控制语速、情绪或表达。

wav = model.generate(
    text="(稍快一点，欢快的语气)这是带风格控制的克隆语音。",
    reference_wav_path="path/to/voice.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)

命令行

CLI 适合快速试验、批量处理和把常见生成流程放进脚本。

# 音色设计
voxcpm design \
  --text "VoxCPM2 带来全新语音合成体验。" \
  --output out.wav

# 声音克隆
voxcpm clone \
  --text "这是一个声音克隆的演示。" \
  --reference-audio path/to/voice.wav \
  --output out.wav

# 批量处理
voxcpm batch --input examples/input.txt --output-dir outs

Web Demo

本地启动 Web Demo 后，在浏览器打开对应端口即可体验模型能力。

python app.py --port 8808

# 可选设备
python app.py --device auto

--device 支持 auto、cpu、mps、cuda 和 cuda:N。Apple Silicon Mac 可在可用时自动选择 MPS。

生产部署

高吞吐推理推荐使用 Nano-vLLM-VoxCPM 或 vLLM-Omni，适合并发请求、异步 API 和产品侧集成。

部署建议

宣传页适合托管在 Cloudflare Pages；真实推理服务建议部署到 GPU 主机，再通过 API 网关或业务后端调用。

pip install nano-vllm-voxcpm

vllm serve openbmb/VoxCPM2 --omni --port 8000

curl http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"openbmb/VoxCPM2","input":"企业级语音生成服务","voice":"default"}' \
  --output out.wav

模型版本

版本	定位	适用场景
VoxCPM2	最新推荐版本，2B 参数，48kHz 输出	多语言合成、音色设计、可控克隆、商业集成
VoxCPM1.5	稳定版本，支持 SFT 与 LoRA 微调	需要微调或稳定复现实验的团队
VoxCPM-0.5B	轻量版本	快速验证和资源受限环境

风险与局限

合成语音技术应当负责任地使用。涉及公开发布、客服、教育、广告或角色语音时，建议明确标注 AI 合成，并遵守相关平台与地区规范。

不要冒充真实个人或绕过身份验证。
对敏感场景保留审核、授权和水印策略。
生产服务需要针对延迟、并发、GPU 显存和音频质量做压测。