快速开始¶

本页会尽可能快速地带你从零完成可运行的 VoxCPM 安装。按顺序往下操作后，你就可以通过三种方式生成语音：Python API、CLI 和网页演示。

安装¶

pip install voxcpm

到这里就完成了。若你想了解其他安装方式（如 pip、从源码安装等），请参阅安装。

第 1 步：使用 Python API¶

从当前推荐版本 VoxCPM 2 开始：

from voxcpm import VoxCPM
import soundfile as sf

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

wav = model.generate(
    text="VoxCPM 2 is the current recommended release for realistic multilingual speech synthesis.",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("demo.wav", wav, model.tts_model.sample_rate)
print("saved: demo.wav")

首次运行会自动下载模型权重。如果你访问 Hugging Face 有困难，请查看安装中的镜像配置。

这个示例没有启用可选降噪器。只有当你想在声音克隆时增强 prompt 或 reference 音频时才需要它。详情见使用指南。

如果这段脚本可以正常运行并生成 demo.wav，说明你的安装已可正常工作。

小技巧

运行时设备选择默认是自动的。VoxCPM.from_pretrained(..., device="auto") 会按 cuda -> mps -> cpu 的顺序优先选择设备。你也可以显式指定 device="cpu"、device="mps"、device="cuda" 或 device="cuda:0"。如果你遇到平台相关的 torch.compile 问题，可以尝试 optimize=False。

备注

对于新项目，建议从当前版本 VoxCPM 2 开始。如果你需要较旧的 checkpoint，也可以在版本历史中找到早期版本。

第 2 步：使用命令行¶

VoxCPM 也提供命令行接口。CLI 默认使用 openbmb/VoxCPM2，因此除非你想通过 --hf-model-id 覆盖 checkpoint，否则可以直接使用推荐子命令：

# Direct synthesis
voxcpm design \
    --text "Hello from VoxCPM!" \
    --output out.wav

# Reference-only cloning (VoxCPM 2)
voxcpm clone \
    --text "This is a cloned voice sample." \
    --reference-audio path/to/voice.wav \
    --output out.wav \
    --denoise

# Force CPU or MPS explicitly when needed
voxcpm design --text "Hello from VoxCPM!" --device cpu --output out.wav
voxcpm design --text "Hello from VoxCPM!" --device mps --no-optimize --output out.wav

# Help
voxcpm --help

第 3 步：使用网页演示¶

网页演示需要克隆源码仓库。如果你在上一步通过 pip install voxcpm 完成安装，仍然需要克隆仓库：

git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
pip install -e .
python app.py

Web Demo 在首次使用时还会额外下载一个 ASR 模型（SenseVoice-Small），用于 prompt 音频转写。

接下来做什么？¶

继续阅读使用指南，了解 prompt 策略、声音克隆技巧和质量调优。
查看侧边栏 Models 下的页面，了解各版本特性与迁移说明。
通过微调指南微调模型，使其适配你的实际场景。
通过 NanoVLLM-VoxCPM 部署模型，以实现高吞吐服务。