VoxCPM 是一个无分词器的端到端语音合成系统，通过扩散自回归架构直接生成连续语音表示。其最新版本 VoxCPM2 是一个 2B 参数模型，在超过 200 万小时 的多语言语音数据上训练，支持 30 种语言、语音设计（Voice Design）、可控语音克隆，并输出 48kHz 录音室级音频。

1. 系统要求

1.1 硬件要求

  • GPU：强烈推荐使用 NVIDIA GPU（至少 8GB 显存，推荐 24GB 用于高吞吐部署）。
  • 内存：建议 16GB 以上。
  • 存储：模型文件大小约 8-12 GB。

1.2 软件前提

  • Python：版本 3.10 或 3.11（不支持 3.13）。
  • PyTorch：版本 ≥ 2.5.0，需与 CUDA 版本匹配（CUDA ≥ 12.0）。
  • CUDA：版本 ≥ 12.0（用于 GPU 加速）。
  • FFmpeg：用于音频处理（可选，但推荐安装）。

2. 安装步骤

2.1 基础安装

使用 pip 直接安装 voxcpm 包：

1
pip install voxcpm

此命令会安装核心依赖。如果需要生成带有时间戳的音频（用于字幕对齐），可以安装可选依赖：

1
pip install "voxcpm[timestamps]"

2.2 从 ModelScope 下载模型（国内用户推荐）

由于 Hugging Face 在某些地区访问不稳定，您可以通过 ModelScope 下载模型权重：

1
2
3
4
5
pip install modelscope
python -c "
from modelscope import snapshot_download
snapshot_download('OpenBMB/VoxCPM2', local_dir='./pretrained_models/VoxCPM2')
"

3. 基本使用

3.1 Python API：文本到语音（TTS）

这是最基础的用法，将文本直接合成为语音。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from voxcpm import VoxCPM
import soundfile as sf

# 加载模型（第一次运行时会自动从 Hugging Face 下载权重，约 8GB）
model = VoxCPM.from_pretrained(
    "openbmb/VoxCPM2",
    load_denoiser=False,  # 可加快推理速度，轻微影响质量
)

# 合成语音
wav = model.generate(
    text="VoxCPM2 is the current recommended release for realistic multilingual speech synthesis.",
    cfg_value=2.0,        # 分类器自由引导强度，越高语音越清晰
    inference_timesteps=10, # 推理步数，步数越多质量越高但速度越慢
    seed=42,              # 随机种子，确保可复现性
)

# 保存音频文件（采样率 48000 Hz）
sf.write("demo.wav", wav, model.tts_model.sample_rate)

3.2 语音设计（Voice Design）

无需参考音频，仅通过自然语言描述创建新声音。

1
2
3
4
5
wav = model.generate(
    text="(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM2!",
    # 描述放在括号内，后面紧跟要合成的文本
)
sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

3.3 可控语音克隆（Controllable Voice Cloning）

提供参考音频克隆音色，并可额外添加风格控制指令。

1
2
3
4
wav = model.generate(
    text="(slightly faster, cheerful tone)This is a cloned voice with style control.",
    reference_wav_path="path/to/voice.wav",  # 参考音频路径
)

3.4 终极克隆（Ultimate Cloning）

同时提供参考音频和其精确的文字转录，实现最高保真度的克隆，再现每一个声音细节（音色、节奏、情感和风格）。

1
2
3
4
5
6
wav = model.generate(
    text="This is an ultimate cloning demonstration using VoxCPM2.",
    prompt_wav_path="path/to/voice.wav",           # 参考音频
    prompt_text="The transcript of the reference audio.", # 参考音频的文字转录
    reference_wav_path="path/to/voice.wav",        # 可选，进一步提高相似度
)

3.5 流式生成（Streaming）

适用于需要实时响应的场景，如语音助手。

1
2
3
4
5
6
7
8
9
import numpy as np

chunks = []
for chunk in model.generate_streaming(
    text="Streaming text to speech is easy with VoxCPM!",
):
    chunks.append(chunk)
wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)

4. 命令行工具（CLI）

VoxCPM 也提供了命令行接口，方便快速生成。

  • 语音设计：

    1
    voxcpm design --text "VoxCPM2 brings studio-quality multilingual speech synthesis." --output out.wav

  • 带风格控制的语音设计：

    1
    2
    3
    voxcpm design --text "VoxCPM2 brings studio-quality multilingual speech synthesis." \
                  --control "Young female voice, warm and gentle, slightly smiling" \
                  --seed 42 --output out.wav

  • 语音克隆：

    1
    2
    3
    voxcpm clone --text "This is a voice cloning demo." \
                 --reference-audio path/to/voice.wav \
                 --output out.wav

  • 终极克隆：

    1
    2
    3
    4
    voxcpm clone --text "This is a voice cloning demo." \
                 --prompt-audio path/to/voice.wav \
                 --prompt-text "reference transcript" \
                 --output out.wav

  • 批量处理：

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

5. 生产环境部署（高性能服务）

对于需要高并发、低延迟的生产场景，VoxCPM 提供了两种专门的推理引擎。

5.1 使用 Nano-vLLM-VoxCPM（高性能）

这是一个基于 Nano-vLLM 的专用推理引擎，支持并发请求和异步API。

1
pip install nano-vllm-voxcpm

Python 调用示例：

1
2
3
4
5
6
7
from nanovllm_voxcpm import VoxCPM
import soundfile as sf

server = VoxCPM.from_pretrained(model="/path/to/VoxCPM", devices=[0]) # 使用 GPU 0
chunks = list(server.generate(target_text="Hello from VoxCPM!"))
sf.write("out.wav", np.concatenate(chunks), 48000)
server.stop()

性能：在 NVIDIA RTX 4090 上，RTF（实时因子）可低至 ~0.13，即生成 1 秒音频仅需约 0.13 秒。

5.2 使用 vLLM-Omni（官方生产级服务）

基于 vLLM 项目的全模态扩展，提供 OpenAI 兼容的 API 端点。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 安装 vLLM 和 vLLM-Omni
pip install vllm==0.19.0
git clone https://github.com/vllm-project/vllm-omni.git && cd vllm-omni
pip install -e .

# 启动 OpenAI 兼容的 TTS 服务器
vllm serve openbmb/VoxCPM2 --omni --port 8000

# 通过 curl 调用
curl http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"openbmb/VoxCPM2","input":"Hello from VoxCPM2!","voice":"default"}' \
  --output out.wav

5.3 启动 Web 演示界面

1
2
python app.py --port 8808
# 然后打开浏览器访问 http://localhost:8808

6. 微调（Fine-tuning）

VoxCPM 支持全量微调（SFT）和参数高效微调（LoRA）。仅需 5-10 分钟 的音频数据即可适配特定说话人、语言或领域。

LoRA 微调（推荐）：

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

启动微调 WebUI：

1
python lora_ft_webui.py  # 然后访问 http://localhost:7860

7. 常见问题排查

问题 可能原因 解决方案
torch 或 cuda 相关错误 PyTorch 版本不匹配或 CUDA 未正确安装 根据您的 CUDA 版本，从 PyTorch 官网 重新安装 PyTorch。确保 torch.cuda.is_available() 返回 True。
ModuleNotFoundError: No module named 'voxcpm' voxcpm 包未安装 执行 pip install voxcpm。
模型下载失败（网络问题） 无法访问 Hugging Face 1. 使用 ModelScope 下载（见上文 2.2 节）。 2. 设置代理环境变量 export HTTP_PROXY=...。
显存不足（CUDA Out of Memory） GPU 显存小于 8GB 1. 使用更小的模型（如 VoxCPM-0.5B）。 2. 在加载模型时设置 load_denoiser=False 以减少显存占用。 3. 考虑使用 CPU 推理（速度慢）。
生成的音频有杂音或质量低 cfg_value 或 inference_timesteps 设置不当 尝试调整参数：增加 cfg_value（如 2.0-4.0）和 inference_timesteps（如 10-20）。
语音克隆相似度不高 参考音频质量差或语言不匹配 使用时长至少 3-5 秒、清晰、无背景噪音的参考音频。确保参考音频的语言与目标文本语言一致。

8. 总结

VoxCPM 是一个功能强大、性能优越的多语言语音合成与克隆系统。

核心使用路径：

  1. 环境准备：安装 Python 3.10/3.11、PyTorch 2.5+ 和 CUDA 12+。
  2. 安装包：pip install voxcpm。
  3. 加载模型：通过 VoxCPM.from_pretrained("openbmb/VoxCPM2") 下载并加载模型（首次需下载 ~8GB 权重）。
  4. 生成语音：使用 Python API 或 CLI 进行 TTS、语音设计或克隆。
  5. 生产部署：对于高并发场景，使用 Nano-vLLM 或 vLLM-Omni 部署为服务。

建议：首次使用前，请检查 GPU 可用性。对于大多数个人用户，直接从 Python API 或 CLI 开始即可。如果需要集成到生产环境，推荐使用 vLLM-Omni 部署为 OpenAI 兼容的 API 服务。请务必遵守使用条款，不将语音克隆技术用于欺诈或误导性用途。

项目地址：https://github.com/OpenBMB/VoxCPM