安装¶

本页涵盖 VoxCPM 的所有受支持安装方式。如果你只想最快开始使用，请查看快速开始。

环境要求¶

依赖项	说明
PyTorch	2.5.0 或更高
CUDA	可选。若使用 NVIDIA GPU 加速，建议 12.0 或更高版本
Python	推荐 3.10–3.12（其中 3.10–3.11 测试最充分）
磁盘空间	模型权重需要数 GB 空间，具体取决于你使用的 checkpoint

备注

如果你使用 CPU 推理或 Apple Silicon MPS，则不需要 CUDA。有关 Mac / MPS 的说明请参阅常见问题与故障排查。

运行时设备选择¶

VoxCPM 在 Python API 和 CLI 中都支持自动选择设备，以及显式强制指定设备。

自动选择

device=None 或 device="auto" 会使用自动回退逻辑
回退顺序为 cuda -> mps -> cpu
CLI 通过 --device auto 使用相同的行为

显式指定

device="cpu" 会强制使用 CPU 推理
device="mps" 会强制使用 Apple Silicon MPS
device="cuda" 或 device="cuda:N" 会强制使用 CUDA
显式指定设备时**不会**自动回退；如果所请求的后端不可用，VoxCPM 会直接抛错，以便明确暴露问题。

from voxcpm import VoxCPM

model = VoxCPM.from_pretrained("openbmb/VoxCPM2", device="auto")
cpu_model = VoxCPM.from_pretrained("openbmb/VoxCPM2", device="cpu", optimize=False)

voxcpm design --text "Hello" --device auto --output out.wav
voxcpm design --text "Hello" --device cpu --no-optimize --output out.wav

备注

optimize=True 会启用 torch.compile 加速，主要对 CUDA 场景有意义。在 CPU、MPS、ROCm 或其它非标准环境中，为了兼容性你可能需要使用 optimize=False 或 CLI 的 --no-optimize。

使用 pip 安装（推荐）¶

pip 是安装 VoxCPM 的首选方式。它配置简单，也最符合常见的 Python 使用习惯。

从 PyPI 安装：

pip install voxcpm

从源码安装：

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

使用 uv 安装（备选）¶

uv 也是一个不错的次选方案，适合希望用工具统一管理环境、并获得更快依赖解析速度的用户。

从 PyPI 安装：

uv pip install voxcpm

从源码安装（运行 Web Demo 或本地开发时需要）：

git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
uv sync

小技巧

如果你通过 uv sync 安装，请使用 uv run 运行脚本，以确保使用 uv 管理的环境。例如：uv run python app.py、uv run python scripts/train_voxcpm_finetune.py ...。

如果你想进行以下操作，则需要从源码安装：

运行本地 Web Demo（python app.py）
修改 VoxCPM 源代码
参与项目贡献

Hugging Face 镜像¶

如果你无法直接访问 Hugging Face（某些地区较常见），请在运行任何脚本前先设置镜像：

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

之后模型权重会自动通过镜像下载。

验证安装是否成功¶

安装完成后，运行一个快速检查：

python -c "from voxcpm import VoxCPM; print('VoxCPM is ready')"

如果这条命令能够无报错输出，说明你的安装已正常工作。