VoxCPM2 首发教程：从零开始完成本地部署与体验

VoxCPM2 首发教程：从零开始完成本地部署与体验

📋 参考部署环境

• 系统： Ubuntu 22.04 / 24.04（Windows WSL2 / macOS 亦可参考）
• 显卡：
  • NVIDIA GPU，显存 ≥ 8 GB（如 RTX 3080、RTX 4070 及以上）
  • Apple Silicon（M1/M2/M3/M4）可通过 MPS 后端运行，建议统一内存 ≥ 16 GB
• 驱动： NVIDIA GPU 需 NVIDIA Driver ≥ 535，CUDA ≥ 12.0；Apple Silicon 无需额外驱动
• Python： ≥ 3.10
• 参考文档： VoxCPM 官方文档

本教程面向 零基础用户，从环境准备到运行第一句语音合成，手把手带你完成 VoxCPM2 的本地部署。

一、了解 VoxCPM2

VoxCPM2 是一个 20 亿参数 的文本转语音（TTS）模型，支持 30 种语言、音色设计（用文字描述创造新声音）、可控语音克隆 和 48kHz 高保真音频输出，基于 Apache-2.0 开源协议发布。你可以用它来：

• 输入任意文本，生成自然语音
• 用一段文字描述（如"年轻女性，温柔甜美"）凭空创建声音
• 上传一段参考音频，克隆该声音并控制语速、情感等风格
• 提供参考音频及其文本，实现极致克隆（完美还原每一个声音细节）

硬件需求速查：

模型	参数量	显存需求	推荐显卡
VoxCPM2	2B	~8 GB	RTX 4070 / RTX 3080
VoxCPM1.5	0.6B	~6 GB	RTX 4060 / RTX 3060
VoxCPM-0.5B	0.5B	~5 GB	RTX 4060 / RTX 3060

🍎 Apple Silicon（M1/M2/M3/M4）用户

VoxCPM 会自动检测 MPS 后端并使用，但未对 MPS 做专项适配，torch.compile 加速不可用，部分算子可能回退到 CPU，速度较 NVIDIA GPU 慢。如需更好的 Apple 芯片体验，推荐社区项目 VoxCPMANE（Apple Neural Engine 加速）。

模型下载链接：

模型	Hugging Face	ModelScope
VoxCPM2（推荐）	openbmb/VoxCPM2	OpenBMB/VoxCPM2
VoxCPM1.5	openbmb/VoxCPM1.5	OpenBMB/VoxCPM1.5
VoxCPM-0.5B	openbmb/VoxCPM-0.5B	OpenBMB/VoxCPM-0.5B

💡 提示

国内用户推荐从 ModelScope 下载，速度更快。使用 pip install voxcpm 安装后，模型会在首次运行时自动从 Hugging Face 下载；如需手动下载，可从上方链接获取后放到本地目录。

💡 额外说明

如果你没有独立显卡也没有 Apple Silicon，也可以用 CPU 运行，但速度会慢很多。

---

最低配置要求

开始部署前，请确认你的电脑满足以下 任一方案 的最低要求：

	方案 A：NVIDIA 独立显卡	方案 B：Apple Silicon
处理器	无特殊要求	Apple Silicon（M1/M2/M3/M4）
内存	≥ 8 GB	—
统一内存	—	≥ 16 GB
显卡	NVIDIA 独立显卡（推荐显存 ≥ 8 GB）	无需独立显卡，使用芯片内置 GPU

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

• 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 驱动。

步骤 2：查看显存大小
同样在 nvidia-smi 输出中，关注 GPU 的 Memory 列，VoxCPM2 需要 ≥ 8 GB 显存。

2.2 安装 Python

推荐使用 Miniconda 管理 Python 环境：

# 创建一个 Python 3.10 的虚拟环境
conda create -n voxcpm python=3.10 -y

# 激活环境（后续所有操作都在这个环境中进行）
conda activate voxcpm

💡 提示

如果你不使用 conda，也可以用 python3 -m venv 创建虚拟环境，只要确保 Python 版本 ≥ 3.10。

步骤 3：验证 Python 版本

python --version

输出应为 Python 3.10.x 或更高。

2.3 安装 PyTorch

💡 注意

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

前往 PyTorch 官方安装页 选择匹配你 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.git
cd VoxCPM

# 以可编辑模式安装（自动安装所有依赖）
pip install -e .

🎁 注意

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

---

四、启动 Web Demo（最快体验）

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

4.1 从源码启动

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

cd VoxCPM

# 启动 Web Demo
python app.py

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

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

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

4.2 可选参数

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

# 指定端口
python app.py --port 9000

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

export VOXCPM_MODEL_DIR=/path/to/your/VoxCPM2
python app.py

4.3 不想本地部署？

直接访问在线 Demo，无需任何安装：VoxCPM Live Playground

五、Python API 用法

如果你想在自己的 Python 程序中调用 VoxCPM2，以下是几种核心用法。

5.1 基础文本转语音

from voxcpm import VoxCPM
import 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 np

chunks = []
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 --help
voxcpm design --help
voxcpm 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.jsonl
val_manifest: null
sample_rate: 48000
batch_size: 2
grad_accum_steps: 8
num_workers: 8
num_iters: 1000
log_interval: 10
valid_interval: 500
save_interval: 500
learning_rate: 0.0001
weight_decay: 0.01
warmup_steps: 100
max_steps: 1000
max_batch_tokens: 8192
save_path: /path/to/checkpoints/finetune_lora
tensorboard: /path/to/logs/finetune_lora
lambdas:
  loss/diff: 1.0
  loss/stop: 1.0

lora:
  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，可以在网页上完成数据配置、训练启动和推理测试。

📘 更多说明

微调的详细指南请参考 官方微调文档。

---

八、生产部署（Nano-vLLM 加速）

如果你需要在生产环境中高吞吐地提供 TTS 服务，推荐使用 Nano-vLLM-VoxCPM 推理引擎：

pip install nano-vllm-voxcpm

from nanovllm_voxcpm import VoxCPM
import 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 仓库。

---

九、常见问题与排错

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

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

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

如果版本有问题，前往 PyTorch 安装页 选择匹配你 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-dir 或 --model-path 指定本地路径
python app.py --model-dir /path/to/downloaded/VoxCPM2

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

项目	要求
格式	WAV（推荐）
采样率	16kHz
声道	单声道
时长	5–15 秒效果最佳
质量	尽量清晰无背景噪音

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

• 调高 cfg_value（推荐 1.5–3.0），值越大越贴合文本
• 调高 inference_timesteps（推荐 10–32），音质更好但速度更慢
• 克隆场景下确保参考音频清晰无噪音

Q6：支持 macOS / Apple Silicon 吗？

VoxCPM 支持 CPU 推理（但速度慢），Apple Silicon 用户可尝试社区项目 VoxCPMANE 以获得 Apple Neural Engine 加速。

Q7：如何指定使用哪张 GPU？

# 只使用 0 号 GPU
CUDA_VISIBLE_DEVICES=0 python app.py

# 使用 1 号 GPU
CUDA_VISIBLE_DEVICES=1 python app.py

---

环境变量速查表

变量	说明	示例
VOXCPM_MODEL_DIR	指定本地模型目录（app.py 使用）	/data/models/VoxCPM2
HF_REPO_ID	指定 HuggingFace 模型 ID（app.py 使用）	openbmb/VoxCPM2
CUDA_VISIBLE_DEVICES	指定使用哪张 GPU	0
HF_ENDPOINT	HuggingFace 镜像地址（国内加速）	https://hf-mirror.com
ZIPENHANCER_MODEL_PATH	降噪模型路径（CLI 使用）	/path/to/zipenhancer

---

📚 更多用法和高级功能

请参考：快速开始指南 | 使用指南 | Cookbook