本文面向有一定Linux基础的开发者，手把手带你完成VoxCPM2的本地部署，全程使用uv进行环境管理和依赖安装，不走弯路。

一、VoxCPM2 简介

VoxCPM2 是 OpenBMB 联合面壁智能、清华大学人机语音交互实验室开发的新一代开源TTS模型。核心亮点：

特性 说明
模型规模 2B 参数，基于 MiniCPM-4 骨干网络
训练数据 超 200 万小时多语言语音数据
语言支持 30 种语言 + 9 种中文方言
音频质量 48kHz 工作室级输出
核心功能 基础TTS、音色设计（Voice Design）、可控克隆、极致克隆
实时性能 RTF 低至 ~0.3（RTX 4090）
开源协议 Apache-2.0，可商用

音色设计（Voice Design） 是 VoxCPM2 最独特的功能——仅用一段自然语言描述（性别、年龄、语气、情感、语速等），即可凭空创造一个全新的声音，无需任何参考音频。

二、硬件与系统要求

项目 最低要求 推荐配置
操作系统 Ubuntu 22.04 / 24.04 Ubuntu 22.04 LTS
GPU NVIDIA GPU，8GB 显存 RTX 3080 / 4070 及以上
NVIDIA 驱动 ≥ 535 最新稳定版
CUDA ≥ 12.0 CUDA 12.8
Python 3.10 ~ 3.12 Python 3.12
内存 16GB 32GB+
存储 ~10GB（模型权重+依赖） 20GB+

⚠️ Python 3.13 暂不支持，请务必使用 3.10~3.12 版本。

🍏 Apple Silicon 用户：VoxCPM2 可自动检测 MPS 后端运行，但未做专项适配，速度较慢。推荐社区项目 VoxCPMANE（Apple Neural Engine 加速）。

三、uv 环境管理工具简介

uv 是 Astral 团队开发的极速 Python 包管理工具，使用 Rust 编写，比传统 pip + venv 快 10-100 倍。本文全程使用 uv 进行环境管理。

安装 uv：

curl-LsSfhttps://astral.sh/uv/install.sh|sh# 或pipinstalluv

验证安装：

uv--version

四、完整部署步骤

4.1 确认 GPU 环境

首先确认 NVIDIA 驱动和 CUDA 已正确安装：

nvidia-smi# 应显示 GPU 信息和 CUDA Versionnvcc--version# 应显示 CUDA 编译版本

如果 nvidia-smi 无法正常显示，说明驱动未安装或有问题，需要先解决驱动问题。

4.2 克隆项目仓库

# 克隆官方仓库gitclone https://github.com/OpenBMB/VoxCPM.gitcdVoxCPM# （可选）如果访问 GitHub 慢，可使用镜像gitclone https://mirror.ghproxy.com/https://github.com/OpenBMB/VoxCPM.gitcdVoxCPM

4.3 使用 uv 创建虚拟环境

# 使用 uv 创建 Python 3.12 虚拟环境uv venv .venv--python3.12# 激活虚拟环境（Ubuntu/Debian）source.venv/bin/activate# 确认 Python 版本python--version# 应显示 Python 3.12.x

📌 uv venv 会自动下载指定版本的 Python（如果系统中没有），非常方便。

4.4 安装 PyTorch（CUDA 版）

重要：VoxCPM2 要求 PyTorch ≥ 2.5.0。

# 使用 uv pip 安装 PyTorch CUDA 版uv pipinstalltorch torchaudio --index-url https://download.pytorch.org/whl/cu124# 如果 CUDA 版本是 12.8，可换用：uv pipinstalltorch torchaudio --index-url https://download.pytorch.org/whl/cu128

验证 PyTorch CUDA 是否可用：

python-c"import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"# 应输出 True 和 CUDA 版本号

4.5 安装 VoxCPM 及依赖

有两种安装方式，推荐方式一：

方式一：从 PyPI 安装（推荐）

uv pipinstallvoxcpm

这会自动安装所有核心依赖。

方式二：从源码安装（开发模式）

uv pipinstall-e.

适合需要修改源码或获取最新特性的开发者。

可选：安装额外音频格式支持

uv pipinstallpydub# 支持 mp3、opus、ogg、aac 等格式

4.6 配置 Hugging Face 镜像（国内用户）

由于模型权重约 4-5GB，从 Hugging Face 直接下载可能较慢，建议配置镜像：

# 方法一：使用 HF 镜像exportHF_ENDPOINT=https://hf-mirror.com# 方法二：使用 ModelScope（国内推荐）# 模型在首次运行时会自动下载，也可以手动从 ModelScope 下载后放到本地目录[reference:25]

4.7 运行第一个 TTS 示例

创建测试脚本 test_voxcpm.py：

importsoundfileassffromvoxcpmimportVoxCPM# 加载模型（首次运行会自动下载 ~4-5GB 权重，请耐心等待）model=VoxCPM.from_pretrained("openbmb/VoxCPM2",load_denoiser=False# 可加快加载速度)# 生成语音wav=model.generate(text="你好，欢迎使用 VoxCPM2 文本转语音系统。这是一个支持三十种语言的开源模型。",cfg_value=2.0,# 引导强度，越高越贴合 prompt，默认 2.0inference_timesteps=10,# 推理步数，越高质量越好，默认 10normalize=True,# 启用文本归一化)# 保存音频（采样率 16000Hz）sf.write("output.wav",wav,16000)print("✅ 音频已保存: output.wav")

运行：

python test_voxcpm.py

首次运行会自动下载模型权重（约 4-5GB），请耐心等待。后续运行会使用缓存，启动约 30 秒。

五、核心功能实战

5.1 基础 TTS（文本转语音）

fromvoxcpmimportVoxCPMimportsoundfileassf model=VoxCPM.from_pretrained("openbmb/VoxCPM2",load_denoiser=False)wav=model.generate(text="VoxCPM2 brings multilingual support, creative voice design, and controllable voice cloning.",cfg_value=2.0,inference_timesteps=10,)sf.write("tts_output.wav",wav,16000)

5.2 音色设计（Voice Design）—— 核心亮点

无需任何参考音频，仅用文字描述即可创造全新音色：

wav=model.generate(text="(温暖稳重的男中音，语速稍慢，适合纪录片旁白)在浩瀚的历史长河中，每一个文明都留下了独特的印记。",cfg_value=2.0,inference_timesteps=12,# 音色设计可适当增加步数)sf.write("voice_design.wav",wav,16000)

风格描述示例：

· “年轻女性，温柔甜美，语速偏快”
· “成熟男性，低沉有磁性，冷静专业”
· “中性播报声，平稳清晰，不带感情”

5.3 可控克隆（Controllable Cloning）

使用一段参考音频克隆音色，同时可控制情感和语速：

wav=model.generate(text="今天我们要聊一个非常有趣的话题。",prompt_wav_path="./reference.wav",# 参考音频路径prompt_text="参考音频对应的文本",# 提供可提升效果cfg_value=2.0,inference_timesteps=10,)sf.write("clone_output.wav",wav,16000)

5.4 极致克隆（Ultimate Cloning）

提供参考音频 + 其文本转录，实现最完美的音色还原：

wav=model.generate(text="接续参考音频之后的新的文本内容",prompt_wav_path="./reference.wav",prompt_text="参考音频中的完整文本内容",cfg_value=2.0,inference_timesteps=10,)

💡 prompt_text 参数对于极致克隆至关重要——它告诉模型参考音频中说的是什么，从而实现音频续写式的精准克隆。

六、常见踩坑与解决方案

6.1 模型下载慢或失败

现象：首次运行卡在下载进度条，或报连接超时。

解决方案：

# 使用 HF 镜像exportHF_ENDPOINT=https://hf-mirror.com# 或从 ModelScope 手动下载后放到缓存目录# 缓存目录通常在 ~/.cache/huggingface/hub/

6.2 CUDA out of memory

现象：RuntimeError: CUDA out of memory

解决方案：

· 降低 inference_timesteps（如从 10 降到 8）
· 使用 load_denoiser=False 减少显存占用
· 关闭其他占用显存的进程

6.3 PyTorch CUDA 不可用

现象：torch.cuda.is_available() 返回 False

解决方案：

# 确认 CUDA 版本nvcc--version# 重新安装匹配的 PyTorch 版本uv pip uninstall torch torchaudio uv pipinstalltorch torchaudio --index-url https://download.pytorch.org/whl/cu124

6.4 Python 版本不兼容

现象：安装时提示 Python 版本不支持

解决方案：

# VoxCPM2 要求 Python 3.10-3.12[reference:40]uv venv .venv--python3.12source.venv/bin/activate

6.5 生成音频有杂音或静音

现象：输出的 WAV 文件无法播放或声音异常

解决方案：

· 检查 sf.write() 的采样率参数（应为 16000）
· 尝试调整 cfg_value（1.5-3.0 之间调试）
· 确认 normalize=True 已启用

七、进阶：部署为 HTTP API 服务

如需将 VoxCPM2 部署为可供其他应用调用的 API 服务，可参考社区方案：

使用 vLLM-Omni（官方推荐） ：

vllm bench serve--omni\--hostlocalhost--port8000\--modelopenbmb/VoxCPM2\--trust-remote-code

支持 PagedAttention 和 OpenAI 兼容 API。

使用 Docker 一键部署（社区方案）：

dockerrun-d--gpusall-p7860:7860 hangrylabs/voxcpmtts

提供浏览器 UI 和 HTTP API。

前几天收到目前负责维护 VoxCPMTTS 项目的开发者Hangry Labs的邮件提示，目前使用 Docker 一键部署（社区方案）的镜像使用 8808 端口，建议使用以下命令进行部署：

dockerrun--namevoxcpmtts--restartunless-stopped-p8808:8808--gpusall-eCUDA_VISIBLE_DEVICES=0-vvoxcpmtts_data:/app/persistent hangrylabs/voxcpmtts:latest

💡 版权提示：VoxCPM2 基于 Apache-2.0 协议发布，可免费商用。服务中生成的音色资产可通过电子协议将著作财产权转让给客户，全程本地离线处理，数据不出硬盘。

📌 不想自己折腾部署或定制服务，可私信沟通。欢迎在评论区交流部署问题。