Y
YYPGD/VoxCPM2
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

VoxCPM2 昇腾NPU部署文档

1. 模型简介

模型名称: VoxCPM2(openbmb/VoxCPM2) 模型链接: https://ai.gitcode.com/hf_mirrors/openbmb/VoxCPM2 模型描述: VoxCPM2 是 openbmb 推出的 tokenizer-free 扩散自回归文本转语音(TTS)模型,支持 30 种语言(含中文方言)的零样本语音合成、声音设计(voice design)与声音克隆(voice cloning)。模型基于 MiniCPM-4 骨干,训练数据超 200 万小时多语种语音,输出 48kHz 录音棚级音质音频,属于音频-语音合成类模型。 模型架构: Tokenizer-free Diffusion Autoregressive(LocEnc → TSLM → RALM → LocDiT),骨干基于 MiniCPM-4;AudioVAE V2 实现 16kHz 输入 → 48kHz 输出的超分重建。 参数规模: 约 2B(model.safetensors 约 4.3GB + audiovae.pth 约 0.36GB)

2. 环境依赖

依赖项版本要求说明
Python>=3.10实测 3.11
torch / torch_npu>=2.5NPU 上需安装 torch_npu(系统已内置 torch 2.7.1+cpu + torch_npu)
voxcpm==2.0.3官方推理包(--no-deps 安装)
transformers>=5.xLlamaTokenizerFast 文本分词
librosa==0.11.0参考音频加载/重采样
soundfile==0.14.0wav 写出
einops最新版张量重排
huggingface_hub>=1.0voxcpm 依赖

安装命令:

pip install --target /mnt/workspace/VoxCPM2/libs -i https://pypi.tuna.tsinghua.edu.cn/simple --no-deps \
    voxcpm==2.0.3 einops "transformers>=5.15" "tokenizers==0.22.*" soundfile==0.14.0 librosa==0.11.0 \
    tqdm huggingface_hub safetensors regex httpx numba llvmlite pooch lazy_loader joblib audioread msgpack soxr

注意:不要把 torch/torch_npu/torchaudio 装入 libs(避免遮蔽系统 torch+torch_npu 组合);权重与 tokenizer.json 已随权重目录离线分发,推理全程无需联网。


3. 推理步骤

3.1 环境准备

# 检查 NPU 设备
npu-smi info
# 权重已就位
ls /home/developer/models/VoxCPM2/   # config.json model.safetensors audiovae.pth tokenizer.json ...

3.2 运行推理

PYTHONPATH=/mnt/workspace/VoxCPM2/libs python3 inference.py --model_path /home/developer/models/VoxCPM2

3.3 推理参数说明

参数类型默认值说明
--model_pathstr/home/developer/models/VoxCPM2本地权重目录
--devicestr自动(npu > cuda > cpu)推理设备
--textstr内置中英混排示例句待合成文本
--cfg_valuefloat2.0引导强度(classifier-free guidance)
--inference_timestepsint10扩散采样步数,越大音质越好、速度越慢
--outputstrassets/output.wav合成音频输出路径

4. 测试样例及输出结果

样例 1:内置零样本 TTS(voice design 风格描述 + 中英混排文本)

输入:

PYTHONPATH=/mnt/workspace/VoxCPM2/libs python3 inference.py --model_path /home/developer/models/VoxCPM2

示例文本:

你好,欢迎使用昇腾NPU。VoxCPM2 is a tokenizer-free text-to-speech model.

输出:

Using device: npu
Loaded VoxCPM2Model
Running on device: npu, dtype: bfloat16
Model loaded in xx.xx s
sample_rate: 48000
audio_duration: x.xx s
rtf: x.xxx
耗时/elapsed: x.xxx s
output: saved to .../assets/output.wav

模型适配结果

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

模型适配结果

6. 注意事项

  • 推理脚本通过 torch_npu 调用 NPU,设备自动选择 npu > cuda > cpu;
  • 权重仅从本地 --model_path 加载(脚本设置 HF_HUB_OFFLINE=1 与 TRANSFORMERS_OFFLINE=1,且传入本地目录路径直接加载),推理全程离线;
  • voxcpm 官方包的设备解析只认 cuda/mps/cpu,脚本在导入后 monkeypatch resolve_runtime_device 以支持 npu 设备;
  • 系统 torchaudio 与 torch 2.7.1 存在 ABI 不匹配问题,且 VoxCPM2 推理链路不使用 torchaudio,脚本在导入 voxcpm 前注入轻量 torchaudio stub 以通过顶层 import;
  • 脚本以 optimize=False 加载(跳过 torch.compile 预热),NPU 上不依赖 triton;注意力为 SDPA(scaled_dot_product_attention)实现,未使用 flash_attention_2;
  • 模型以 bfloat16 运行(官方 checkpoint 原生 dtype,昇腾 910B 原生支持 bf16);AudioVAE 固定 float32;
  • 如需声音克隆,可调用 model.generate(text=..., prompt_wav_path=..., prompt_text=...)(参考音频需 16kHz wav)。