凭空捏音色、一键极速克隆！VoxCPM2 部署、微调全能实战指南

最近，VoxCPM2 收到了社区的广泛关注与好评👏！作为新版本拥有 20 亿参数的模型，我们向社区伙伴解锁了多种让人惊艳的语音玩法：

🎨 音色设计：只需文字描述（如“年轻女性，温柔甜美”），就能凭空创造出全新的声音。

🎭 可控语音克隆：仅需 5-6 秒的参考音频，即可完美复刻音色，还能自由控制语速、情感等风格。

✨ 极致克隆（音频续写）：还原每一个声音细节，实现最高保真度的克隆。

随着模型在社区的影响力增加，后台也收到了大量开发者的留言：“想在本地跑起来，有没有保姆级教程？”“怎么自己微调专属声音？”

安排！今天，我们为大家准备了一份 面向零基础用户的本地部署与微调全攻略。无论你是想快速体验 Web Demo 的小白，还是想将模型应用于生产环境的极客，这篇教程都将手把手带你完成 VoxCPM2 的落地全流程。

准备好你的显卡，让我们开始吧！👇

➤ 参考部署环境

1. 系统： Ubuntu 22.04 / 24.04（Windows WSL2 / macOS 亦可参考）

2. 显卡

NVIDIA GPU，显存 ≥ 8 GB（如 RTX 3080、RTX 4070 及以上）；

Apple Silicon（M1/M2/M3/M4）可通过 MPS 后端运行，建议统一内存 ≥ 16 GB

3. 驱动： NVIDIA GPU 需 NVIDIA Driver ≥ 535，CUDA ≥ 12.0；Apple Silicon 无需额外驱动

4. Python： 3.10–3.12（3.13 暂不支持）

5. 参考文档： VoxCPM 官方文档（https://voxcpm.readthedocs.io/zh-cn/latest/）

了解 VoxCPM2：VoxCPM2 是一个 20 亿参数 的文本转语音（TTS）模型，支持 30 种语言、中国 9 种方言、音色设计（用文字描述创造新声音）、可控语音克隆 和 48kHz 高保真音频输出，基于 Apache-2.0 开源协议发布。：硬件需求速查

🍎 Apple Silicon（M1/M2/M3/M4）用户： VoxCPM 会自动检测 MPS 后端并使用，但未对 MPS 做专项适配，torch.compile 加速不可用，部分算子可能回退到 CPU，速度较 NVIDIA GPU 慢。如需更好的 Apple 芯片体验，推荐社区项目 VoxCPMANE（https://github.com/0seba/VoxCPMANE，Apple Neural Engine 加速）：模型下载链接：

➤ VoxCPM2（推荐）

HuggingFace：

🔗 https://huggingface.co/openbmb/VoxCPM2

ModelScope：

🔗 https://modelscope.cn/models/OpenBMB/VoxCPM2/summary

➤ VoxCPM1.5

HuggingFace：

🔗 https://huggingface.co/openbmb/VoxCPM1.5

ModelScope：

🔗 https://modelscope.cn/models/OpenBMB/VoxCPM1.5/summary

➤ VoxCPM-0.5B

HuggingFace：

🔗 https://huggingface.co/openbmb/VoxCPM-0.5B

ModelScope：

🔗 https://modelscope.cn/models/OpenBMB/VoxCPM-0.5B/summary

💡国内用户推荐从 ModelScope 下载，速度更快。使用 pip install voxcpm 安装后，模型会在首次运行时自动从 Hugging Face 下载；如需手动下载，可从上方链接获取后放到本地目录。：💡 如果你没有独立显卡也没有 Apple Silicon，也可以用 CPU 运行，但速度会慢很多。：最低配置要求：开始部署前，请确认你的电脑满足以下 任一方案 的最低要求：

❓如何判断我该选哪个方案？

Windows / Linux 用户：如果你有 NVIDIA 独显（如 GTX/RTX 系列），走方案 A。

Mac 用户：如果你的 Mac 是 2020 年末之后购买的（M1 及以上芯片），走方案 B。

都不满足？ 也可以用 CPU 跑，但会很慢。建议先去在线 Demo 体验。

环境准备：2.1 检查 GPU 和驱动

步骤 1：查看 NVIDIA 驱动版本

nvidia-smi

在输出的右上角可以看到 CUDA Version，确保 ≥ 12.0。如果命令不存在或版本过低，需要先安装/更新 NVIDIA 驱动（https://www.nvidia.com/en-us/drivers/）。

步骤 2：查看显存大小

同样在 nvidia-smi 输出中，关注 GPU 的 Memory 列，VoxCPM2 需要 ≥ 8 GB 显存。

2.2 安装 Python

推荐使用 Miniconda（https://docs.conda.io/en/latest/miniconda.html）管理 Python 环境：

## 创建一个 Python 3.10 的虚拟环境conda create -n voxcpm python=3.10 -y# 激活环境（后续所有操作都在这个环境中进行）conda activate voxcpm

如果你不使用 conda，也可以用 python3 -m venv 创建虚拟环境，只要确保 Python 版本 3.10–3.12（3.13 暂不支持）。

步骤 3：验证 Python 版本

python --version

输出应为 Python 3.10.x、3.11.x 或 3.12.x。

2.3 安装 PyTorch

注意： pip install voxcpm 会自动安装 PyTorch，但默认可能安装到 CPU 版本。如果你使用 NVIDIA GPU，建议 先手动安装匹配 CUDA 版本的 PyTorch，再安装 VoxCPM，这样可以确保 GPU 加速正常工作。Apple Silicon 用户和 CPU 用户可以跳过此步，直接进入第三节安装 VoxCPM。

前往 PyTorch 官方安装页（https://pytorch.org/get-started/locally/）选择匹配你 CUDA 版本的命令，例如：

## CUDA 12.4 示例（请根据你的实际 CUDA 版本调整）pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124

步骤 4：验证 PyTorch 和 CUDA

python -c "import torch; print(f'PyTorch {torch.__version__}, CUDA {torch.version.cuda}, GPU available: {torch.cuda.is_available}')"

输出应显示 GPU available: True。

安装 VoxCPM

有两种安装方式，任选其一。

方式 A：pip 安装（推荐，最简单）

pip install voxcpm

步骤 5：验证安装

python -c "from voxcpm import VoxCPM; print('VoxCPM 安装成功！')"

方式 B：从源码安装（需要运行 Web Demo 或微调时使用）

## 克隆项目代码git clone https://github.com/OpenBMB/VoxCPM.gitcd VoxCPM# 以可编辑模式安装（自动安装所有依赖）pip install -e .

🎁注意： 项目的依赖管理使用 pyproject.toml，而不是 requirements.txt。使用 pip install -e . 即可自动安装所有必需依赖。

启动 Web Demo（最快体验）

Web Demo 提供了一个可视化的网页界面，不需要写任何代码就能体验所有功能。

4.1 从源码启动

确保你已经按照方式 B 克隆了项目代码：

cd VoxCPM# 启动 Web Demopython app.py

启动后会自动从 HuggingFace 下载模型权重（约数 GB，首次启动需要稳定网络），然后在终端看到类似输出：

Running on local URL: http://0.0.0.0:8808

步骤 6：打开浏览器访问在浏览器中打开 http://localhost:8808 即可使用。

4.2 可选参数

## 指定本地已下载的模型目录（跳过自动下载python app.py --model-id /path/to/your/VoxCPM2# 指定端口python app.py --port 9000

你也可以通过环境变量指定模型目录：

export VOXCPM_MODEL_DIR=/path/to/your/VoxCPM2python app.py

4.3 欢迎前往 Huggingface & Modelscope 体验在线 Demo ，无需任何安装

在线免安装 Demo（国外）：https://huggingface.co/spaces/openbmb/VoxCPM-Demo

在线免安装 Demo（国内）：https://voxcpm.modelbest.cn/

另外，为了能够让更多对人工智能感兴趣测小白真正触摸使用 VoxCPM2，OpenBMB 小钢炮开源大使开源了本地版本app👍，双击下载即可使用啦，欢迎社区伙伴们下载直接体验！❤️

➤ 下载链接

🔗 https://github.com/ZMXJJ/Voca/releases

Python API 用法：如果你想在自己的 Python 程序中调用 VoxCPM2，以下是几种核心用法。：5.1 基础文本转语音

from voxcpm import VoxCPMimport soundfile as sf# 加载模型（首次会自动从 HuggingFace 下载）model = VoxCPM.from_pretrained( "openbmb/VoxCPM2", load_denoiser=False,)# 生成语音wav = model.generate( text="欢迎使用 VoxCPM2，这是一个强大的语音合成系统。", cfg_value=2.0, inference_timesteps=10,)# 保存为 WAV 文件sf.write("demo.wav", wav, model.tts_model.sample_rate)print("已保存: demo.wav")

💡参数说明：

cfg_value：引导强度，值越高生成越贴合文本，推荐范围 1.5–3.0

inference_timesteps：扩散步数，值越高音质越好但速度越慢，推荐范围 10–32

5.2 音色设计（无需参考音频）

用一段自然语言描述来"设计"一个全新的声音，格式为在文本开头用括号包裹描述：

wav = model.generate( text="(年轻女性，温柔甜美的声音)你好，欢迎来到 VoxCPM2 的世界！", cfg_value=2.0, inference_timesteps=10,)sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

5.3 可控语音克隆

上传一段参考音频，克隆音色后还能用指令控制语速、情感等：

基础克隆wav = model.generate( text="这是一段克隆语音。", reference_wav_path="/path/to/voice.wav",)sf.write("clone.wav", wav, model.tts_model.sample_rate)# 带风格控制的克隆wav = model.generate( text="(语速稍快，愉悦的语气)这是一段带风格控制的克隆语音。", reference_wav_path="/path/to/voice.wav", cfg_value=2.0, inference_timesteps=10,)sf.write("controllable_clone.wav", wav, model.tts_model.sample_rate)

🎁参考音频要求： WAV 格式，16kHz 采样率，单声道，时长 5–15 秒，避免背景噪音。

5.4 极致克隆（音频续写）

同时提供参考音频和对应的文本转录，实现最高保真度的克隆：

wav = model.generate( text="这是极致克隆的演示效果。", prompt_wav_path="/path/to/voice.wav", prompt_text="参考音频的文本转录内容。", reference_wav_path="/path/to/voice.wav",)sf.write("ultimate_clone.wav", wav, model.tts_model.sample_rate)

5.5 流式生成

import numpy as npchunks = []for chunk in model.generate_streaming( text="VoxCPM2 支持流式语音生成，边生成边播放！",): chunks.append(chunk)wav = np.concatenate(chunks)sf.write("streaming.wav", wav, model.tts_model.sample_rate)

命令行 CLI 用法：安装 VoxCPM 后，你可以直接在终端使用 voxcpm 命令。音色设计：

voxcpm design \\ --text "VoxCPM2 带来了工作室级别的多语种语音合成。" \\ --output out.wav

带描述的音色设计：

voxcpm design \\ --text "VoxCPM2 带来了工作室级别的多语种语音合成。" \\ --control "年轻女性声音，温暖柔和，略带微笑" \\ --output out.wav

语音克隆：

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

极致克隆：

voxcpm clone \\ --text "这是一段语音克隆的演示。" \\ --prompt-audio /path/to/voice.wav \\ --prompt-text "参考音频的转录文本" \\ --reference-audio /path/to/voice.wav \\ --output out.wav

批量处理：

voxcpm batch --input examples/input.txt --output-dir outs

查看帮助：

voxcpm --helpvoxcpm design --helpvoxcpm clone --help

💡默认参数： --cfg-value 默认 2.0，--inference-timesteps 默认 10。模型默认从 HuggingFace 下载 openbmb/VoxCPM2。如需使用本地模型，添加 --model-path /path/to/VoxCPM2。

LoRA 微调入门

只需 5–10 分钟的音频数据，就可以让模型适配特定说话人、语言或领域。

7.1 准备训练数据

训练数据格式为 JSONL 文件，每行一条数据：

{"audio": "data/audio1.wav", "text": "音频对应的文本转录。"}{"audio": "data/audio2.wav", "text": "另一条转录文本。", "duration": 3.5}

项目中有示例文件供参考：examples/train_data_example.jsonl

7.2 修改配置文件

以 LoRA 微调为例，编辑 conf/voxcpm_v2/voxcpm_finetune_lora.yaml：最小配置（只需修改以下三项）：

pretrained_path: /path/to/VoxCPM2/ # 改成你的模型目录train_manifest: /path/to/train.jsonl # 改成你的训练数据路径save_path: /path/to/checkpoints/my_lora # 改成你想保存 checkpoint 的路径

完整配置参考：

pretrained_path: /path/to/VoxCPM2/train_manifest: /path/to/train.jsonlval_manifest: nullsample_rate: 48000batch_size: 2grad_accum_steps: 8num_workers: 8num_iters: 1000log_interval: 10valid_interval: 500save_interval: 500learning_rate: 0.0001weight_decay: 0.01warmup_steps: 100max_steps: 1000max_batch_tokens: 8192save_path: /path/to/checkpoints/finetune_loratensorboard: /path/to/logs/finetune_loralambdas: loss/diff: 1.0 loss/stop: 1.0lora: enable_lm: true enable_dit: true enable_proj: false r: 32 alpha: 32 dropout: 0.0

7.3 开始训练

python scripts/train_voxcpm_finetune.py \\ --config_path conf/voxcpm_v2/voxcpm_finetune_lora.yaml

7.4 使用 WebUI 训练和推理

如果你更喜欢图形界面：

python lora_ft_webui.py

打开浏览器访问 http://localhost:7860，可以在网页上完成数据配置、训练启动和推理测试。

微调的详细指南请参考 官方微调文档（https://voxcpm.readthedocs.io/zh-cn/latest/finetuning/finetune.html）。

生产部署（Nano-vLLM 加速）

如果你需要在生产环境中高吞吐地提供 TTS 服务，推荐使用 Nano-vLLM-VoxCPM （https://github.com/a710128/nanovllm-voxcpm）推理引擎：

pip install nano-vllm-voxcpm

from nanovllm_voxcpm import VoxCPMimport numpy as np, soundfile as sf# 启动服务（指定 GPU 设备）server = VoxCPM.from_pretrained(model="/path/to/VoxCPM2", devices=[0])# 生成语音chunks = list(server.generate(target_text="你好，来自 VoxCPM！"))sf.write("out.wav", np.concatenate(chunks), 48000)# 停止服务server.stop

在 RTX 4090 上 RTF 低至 ~0.13（标准 PyTorch 实现约为 ~0.3），支持批量并发请求和 FastAPI HTTP 服务。详见 Nano-vLLM-VoxCPM 仓库（https://github.com/a710128/nanovllm-voxcpm）

常见问题与排错

Q1：nvidia-smi 显示 CUDA 版本与 PyTorch 不匹配

nvidia-smi 显示的是驱动支持的最高 CUDA 版本，而 PyTorch 使用的是编译时的 CUDA 版本。两者不需要完全一致，只需驱动版本 ≥ PyTorch 所需的 CUDA 版本。验证方式：

python -c "import torch; print(torch.version.cuda)"

如果版本有问题，前往 PyTorch 安装页（https://pytorch.org/get-started/locally/） 选择匹配你 CUDA 驱动的版本重新安装。

Q2：GPU 显存不足（Out of Memory）

尝试较小的模型：VoxCPM-0.5B 只需 ~5 GB 显存

加载模型时使用半精度：torch_dtype=torch.float16

减少生成文本长度或降低 max_length

Q3：模型下载太慢或失败

HuggingFace 模型下载在国内可能较慢，你可以：

方法一：设置 HuggingFace 镜像export HF_ENDPOINT=https://hf-mirror.com# 方法二：手动从 ModelScope 下载模型# 访问 https://modelscope.cn/models/OpenBMB/VoxCPM2 下载后解压到本地目录# 然后用 --model-id 指定本地路径python app.py --model-id /path/to/downloaded/VoxCPM2

Q4：参考音频有什么要求？

Q5：生成质量不理想怎么调？

调高 cfg_value（推荐 1.5–3.0），值越大越贴合文本

调高 inference_timesteps（推荐 10–32），音质更好但速度更慢

克隆场景下确保参考音频清晰无噪音

Q6：支持 macOS / Apple Silicon 吗？：VoxCPM 支持 CPU 推理（但速度慢），Apple Silicon 用户可尝试社区项目 VoxCPMANE（https://github.com/0seba/VoxCPMANE） 以获得 Apple Neural Engine 加速。：Q7：如何指定使用哪张 GPU？

## 只使用 0 号 GPUCUDA_VISIBLE_DEVICES=0 python app.py# 使用 1 号 GPUCUDA_VISIBLE_DEVICES=1 python app.py

🧾 环境变量速查表

📚更多用法和高级功能请参考：

➤ 快速开始指南

🔗 https://voxcpm.readthedocs.io/zh-cn/latest/quickstart.html

➤ 使用指南

🔗 https://voxcpm.readthedocs.io/zh-cn/latest/usage_guide.html

➤ CookBook

🔗 https://voxcpm.readthedocs.io/zh-cn/latest/cookbook.html

从环境配置到第一句语音的成功生成，再到只需 5-10 分钟音频就能搞定的 LoRA 微调，相信你已经成功在本地唤醒了属于你的 VoxCPM2！

对于有高并发服务需求的开发者，也别忘了试试我们在文中提到的 Nano-vLLM-VoxCPM 推理引擎 ，让你的生产环境如虎添翼。如果在部署过程中遇到任何疑难杂症，或者跑出了令人惊艳的“神仙音色”，欢迎社区伙伴们加入 VoxCPM2 官方飞书群与我们分享和反馈任何问题！

🌟 如果你喜欢 VoxCPM2，快来 Hugging Face 给我们点个 Like💗支持一下！

➤ Hugging Face

🔗https://huggingface.openbmb.com/model/openbmb/VoxCPM2

➤ GitHub

🔗https://github.com/OpenBMB/VoxCPM/

➤ 魔搭社区

🔗 https://modelscope.cn/models/OpenBMB/VoxCPM2

➤ GitCode

🔗 https://ai.gitcode.com/OpenBMB/VoxCPM2

➤ 魔乐社区

🔗 https://modelers.cn/models/OpenBMB/VoxCPM2