本文面向有一定Linux基础的开发者手把手带你完成VoxCPM2的本地部署全程使用uv进行环境管理和依赖安装不走弯路。一、VoxCPM2 简介VoxCPM2 是 OpenBMB 联合面壁智能、清华大学人机语音交互实验室开发的新一代开源TTS模型。核心亮点特性 说明模型规模 2B 参数基于 MiniCPM-4 骨干网络训练数据 超 200 万小时多语言语音数据语言支持 30 种语言 9 种中文方言音频质量 48kHz 工作室级输出核心功能 基础TTS、音色设计Voice Design、可控克隆、极致克隆实时性能 RTF 低至 ~0.3RTX 4090开源协议 Apache-2.0可商用音色设计Voice Design 是 VoxCPM2 最独特的功能——仅用一段自然语言描述性别、年龄、语气、情感、语速等即可凭空创造一个全新的声音无需任何参考音频。二、硬件与系统要求项目 最低要求 推荐配置操作系统 Ubuntu 22.04 / 24.04 Ubuntu 22.04 LTSGPU NVIDIA GPU8GB 显存 RTX 3080 / 4070 及以上NVIDIA 驱动 ≥ 535 最新稳定版CUDA ≥ 12.0 CUDA 12.8Python 3.10 ~ 3.12 Python 3.12内存 16GB 32GB存储 ~10GB模型权重依赖 20GB⚠️ Python 3.13 暂不支持请务必使用 3.10~3.12 版本。 Apple Silicon 用户VoxCPM2 可自动检测 MPS 后端运行但未做专项适配速度较慢。推荐社区项目 VoxCPMANEApple Neural Engine 加速。三、uv 环境管理工具简介uv 是 Astral 团队开发的极速 Python 包管理工具使用 Rust 编写比传统 pip venv 快 10-100 倍。本文全程使用 uv 进行环境管理。安装 uvcurl-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.gitcdVoxCPM4.3 使用 uv 创建虚拟环境# 使用 uv 创建 Python 3.12 虚拟环境uv venv .venv--python3.12# 激活虚拟环境Ubuntu/Debiansource.venv/bin/activate# 确认 Python 版本python--version# 应显示 Python 3.12.x uv venv 会自动下载指定版本的 Python如果系统中没有非常方便。4.4 安装 PyTorchCUDA 版重要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-cimport 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_ENDPOINThttps://hf-mirror.com# 方法二使用 ModelScope国内推荐# 模型在首次运行时会自动下载也可以手动从 ModelScope 下载后放到本地目录[reference:25]4.7 运行第一个 TTS 示例创建测试脚本 test_voxcpm.pyimportsoundfileassffromvoxcpmimportVoxCPM# 加载模型首次运行会自动下载 ~4-5GB 权重请耐心等待modelVoxCPM.from_pretrained(openbmb/VoxCPM2,load_denoiserFalse# 可加快加载速度)# 生成语音wavmodel.generate(text你好欢迎使用 VoxCPM2 文本转语音系统。这是一个支持三十种语言的开源模型。,cfg_value2.0,# 引导强度越高越贴合 prompt默认 2.0inference_timesteps10,# 推理步数越高质量越好默认 10normalizeTrue,# 启用文本归一化)# 保存音频采样率 16000Hzsf.write(output.wav,wav,16000)print(✅ 音频已保存: output.wav)运行python test_voxcpm.py首次运行会自动下载模型权重约 4-5GB请耐心等待。后续运行会使用缓存启动约 30 秒。五、核心功能实战5.1 基础 TTS文本转语音fromvoxcpmimportVoxCPMimportsoundfileassf modelVoxCPM.from_pretrained(openbmb/VoxCPM2,load_denoiserFalse)wavmodel.generate(textVoxCPM2 brings multilingual support, creative voice design, and controllable voice cloning.,cfg_value2.0,inference_timesteps10,)sf.write(tts_output.wav,wav,16000)5.2 音色设计Voice Design—— 核心亮点无需任何参考音频仅用文字描述即可创造全新音色wavmodel.generate(text(温暖稳重的男中音语速稍慢适合纪录片旁白)在浩瀚的历史长河中每一个文明都留下了独特的印记。,cfg_value2.0,inference_timesteps12,# 音色设计可适当增加步数)sf.write(voice_design.wav,wav,16000)风格描述示例· “年轻女性温柔甜美语速偏快”· “成熟男性低沉有磁性冷静专业”· “中性播报声平稳清晰不带感情”5.3 可控克隆Controllable Cloning使用一段参考音频克隆音色同时可控制情感和语速wavmodel.generate(text今天我们要聊一个非常有趣的话题。,prompt_wav_path./reference.wav,# 参考音频路径prompt_text参考音频对应的文本,# 提供可提升效果cfg_value2.0,inference_timesteps10,)sf.write(clone_output.wav,wav,16000)5.4 极致克隆Ultimate Cloning提供参考音频 其文本转录实现最完美的音色还原wavmodel.generate(text接续参考音频之后的新的文本内容,prompt_wav_path./reference.wav,prompt_text参考音频中的完整文本内容,cfg_value2.0,inference_timesteps10,) prompt_text 参数对于极致克隆至关重要——它告诉模型参考音频中说的是什么从而实现音频续写式的精准克隆。六、常见踩坑与解决方案6.1 模型下载慢或失败现象首次运行卡在下载进度条或报连接超时。解决方案# 使用 HF 镜像exportHF_ENDPOINThttps://hf-mirror.com# 或从 ModelScope 手动下载后放到缓存目录# 缓存目录通常在 ~/.cache/huggingface/hub/6.2 CUDA out of memory现象RuntimeError: CUDA out of memory解决方案· 降低 inference_timesteps如从 10 降到 8· 使用 load_denoiserFalse 减少显存占用· 关闭其他占用显存的进程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/cu1246.4 Python 版本不兼容现象安装时提示 Python 版本不支持解决方案# VoxCPM2 要求 Python 3.10-3.12[reference:40]uv venv .venv--python3.12source.venv/bin/activate6.5 生成音频有杂音或静音现象输出的 WAV 文件无法播放或声音异常解决方案· 检查 sf.write() 的采样率参数应为 16000· 尝试调整 cfg_value1.5-3.0 之间调试· 确认 normalizeTrue 已启用七、进阶部署为 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_DEVICES0-vvoxcpmtts_data:/app/persistent hangrylabs/voxcpmtts:latest 版权提示VoxCPM2 基于 Apache-2.0 协议发布可免费商用。服务中生成的音色资产可通过电子协议将著作财产权转让给客户全程本地离线处理数据不出硬盘。 不想自己折腾部署或定制服务可私信沟通。欢迎在评论区交流部署问题。