Bug_Factory_w/VoxCPM2
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

VoxCPM2 昇腾 NPU 迁移与推理部署指南

VoxCPM2 是 OpenBMB 开源的 tokenizer-free 扩散自回归 TTS 模型 (Apache-2.0,2B 参数,30 种语言,48kHz 音频输出,训练数据 200 万+ 小时), 支持零样本语音克隆、语音设计(自然语言描述生成音色)与可控克隆。 本仓库将 VoxCPM2 迁移适配到华为昇腾 NPU,提供 HTTP 服务化推理 与完整测试用例。


1. 目录结构

VoxCPM2-npu/
├── README.md                  # 本文档 (中文部署指引)
├── requirements.txt           # 昇腾 NPU 运行环境依赖
├── inference.py               # ★ 服务化推理脚本 (Flask HTTP 服务)
├── test_inference.py          # ★ 测试用例 (英文/中文 TTS + HTTP 端到端)
├── LICENSE                    # Apache-2.0 许可证
├── voxcpm/                    # VoxCPM 源码 (已适配 NPU)
│   ├── core.py                #   VoxCPM 主类 (from_pretrained 支持本地路径)
│   ├── model/
│   │   ├── voxcpm2.py         #   VoxCPM2 模型 (LocEnc→TSLM→RALM→LocDiT)
│   │   └── utils.py           #   设备选择 (auto_select_device 已适配 NPU)
│   └── modules/
│       ├── minicpm4/          #   MiniCPM-4 骨干 (2B)
│       ├── locdit/            #   LocDiT 扩散解码器
│       └── audiovae/          #   AudioVAE V2 (16kHz入→48kHz出)
├── scripts/
│   ├── gen_screenshots.py     #   交付截图生成脚本
│   └── adaptation_log.txt     #   适配过程记录
├── output/                    # 测试生成的音频 (test_en.wav / test_zh.wav)
└── assets/                    # 交付截图
    ├── npu_device_call.png    #   NPU 设备调用截图
    ├── model_result.png       #   测试结果截图
    └── agent_workflow.png     #   适配过程截图

2. 环境要求

项目要求本机实测
硬件Ascend910 系列 (Atlas 800), ≥1 卡12x Ascend910 (61 GB HBM)
OSopenEuler / Ubuntu / KylinOS (aarch64)openEuler 22.03 SP4 aarch64
CANN≥ 8.08.5.1
Python3.10 – 3.113.11.14
PyTorch≥ 2.5.02.9.0
torch_npu与 PyTorch 配套2.9.0.post1+gitee7ba04
显存~8 GB (bf16)实测 5.19 GB

2.1 环境初始化

# 1) 加载 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 2) 指定可见 NPU 卡
export ASCEND_RT_VISIBLE_DEVICES=0

# 3) 安装依赖 (建议使用华为镜像源)
pip install -r requirements.txt \
    -i https://repo.huaweicloud.com/repository/pypi/simple/

# 4) 校验 NPU 可用
python3 -c "import torch; import torch_npu; \
a = torch.randn(3, 4).npu(); print(a + a)"   # 输出 device='npu:0' 即正常

权重文件位置:/mnt/old_data/whl/models/3/OpenBMB/VoxCPM2/

  • model.safetensors — 主模型权重(2B 参数,bf16)
  • audiovae.pth — AudioVAE V2 声码器(16kHz 输入 → 48kHz 输出)
  • tokenizer.json / config.json — tokenizer 与模型配置

3. 模型结构与昇腾 NPU 迁移说明

3.1 模型架构

输入文本 (30 种语言自动识别, 无需语言标签)
  → 文本编码 LocEnc (tokenizer-free)
  → TSLM (自回归语音 token 生成, MiniCPM-4 骨干 2B)
  → RALM (残差自回归细化)
  → LocDiT (扩散解码, 流匹配采样)
  → AudioVAE V2 (16kHz 潜码 → 48kHz 音频)
  → 输出 wav 音频

3.2 适配点(使用 ascend-model-agent-plugin 的 ai4s-basic skill)

适配点问题修复方式
voxcpm/model/utils.py 设备选择auto_select_device/resolve_runtime_device 仅支持 cuda/mps/cpu,传入 npu 会报错增加 npu 分支:优先级 NPU→CUDA→MPS→CPU;支持 'npu'/'npu:N' 显式指定
dtype 选择bf16 仅对 MPS 降级为 fp32NPU 保留 bf16(Ascend910 原生支持,与 CUDA 一致),无需修改
torch.compileVoxCPMModel.optimize() 仅 CUDA 可用内部已有 try/except 保护,NPU 上自动禁用并打印警告,无需修改
权重加载from_pretrained() 支持本地路径(os.path.isdir 判断)直接传本地权重目录,无需联网下载

详细适配过程见 scripts/adaptation_log.txt 与 assets/agent_workflow.png。

4. 服务化推理

4.1 启动服务

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0

python3 inference.py \
    --ckpt_dir /mnt/old_data/whl/models/3/OpenBMB/VoxCPM2 \
    --port 8080 --device npu:0

参数说明:

  • --ckpt_dir:本地权重目录
  • --device:推理设备,缺省自动选择 npu:0(无 NPU 时回退 cuda/cpu)
  • --port:HTTP 服务端口,默认 8080

注:load_denoiser=False(不加载降噪器,避免 ModelScope 联网下载), optimize=False(NPU 上自动禁用 torch.compile)。

4.2 接口定义

GET /health — 健康检查

curl http://127.0.0.1:8080/health
# {"status":"ok","device":"npu:0","load_time":14.14,"sr":48000}

POST /infer — 文本合成语音

{
  "text": "(一位年轻女性, 温柔甜美的声音)你好,欢迎使用VoxCPM2语音合成系统。",
  "cfg_value": 2.0,
  "inference_timesteps": 10,
  "max_len": 4096,
  "reference_wav_path": null
}

输出:base64 编码的 wav 音频(16-bit PCM, 48kHz 单声道):

{
  "status": "ok",
  "wav_b64": "UklGRiQAAABXQVZF...",
  "duration": 3.84,
  "sr": 48000,
  "elapsed": 2.023,
  "total_elapsed": 2.05
}

参数说明:

  • text:输入文本。语音设计:文本开头加 (自然语言描述) 括号即生成对应音色; 30 种语言自动识别,无需语言标签
  • cfg_value:CFG 引导强度(默认 2.0)
  • inference_timesteps:扩散推理步数(默认 10,越少越快)
  • reference_wav_path:参考音频路径(语音克隆),传 null 使用随机音色/语音设计

5. 测试验证

5.1 一键运行全部测试

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0

python3 test_inference.py \
    --ckpt_dir /mnt/old_data/whl/models/3/OpenBMB/VoxCPM2 \
    --device npu:0

测试覆盖:

  1. 环境检查 — torch / torch_npu 版本、NPU 数量与显存
  2. 模块级英文 TTS — 生成英文语音,校验音频时长/非静音/采样率
  3. 模块级中文 TTS — 验证中文 + 语音设计(自然语言音色描述)
  4. HTTP 服务化推理 — 启动 Flask 服务,通过 POST /infer 端到端验证 (生成的音频保存至 output/ 目录)

5.2 本机实测结果(Ascend910, npu:0)

[inference] VoxCPM2 模型加载完成: 2.38B 参数, 设备 npu:0, 耗时 14.14s, 采样率 48000Hz

[en] 推理耗时    : 2.912 s
[en] 音频时长    : 4.48s (sr=48000Hz)  RMS 能量: 4395.35  (PASS)

[zh] 推理耗时    : 2.023 s
[zh] 音频时长    : 3.84s (sr=48000Hz)  RMS 能量: 457.88  (PASS)

[http] HTTP 状态  : 200
[http] 推理耗时    : 1.625 s
[http] 音频时长    : 3.20s (sr=48000Hz)  RMS 能量: 2803.56  (PASS)
  • 中英文语音合成均正常输出非静音音频 ✓(48kHz 采样率)
  • 语音设计(音色描述)链路正常 ✓
  • 服务化推理端到端可用 ✓(HTTP 200)
  • NPU 显存占用 ~5.19 GB(bf16)

6. 使用建议与已知限制

  1. 性能:短文本(约 40 字符)NPU 推理 2~3s(5 步扩散), inference_timesteps 默认 10 步约 5s,可按需调低换取速度。 官方 RTF ~0.30(RTX 4090),本机 NPU 单卡可满足实时应用。
  2. CPU 运行限制:CPU(aarch64)上 bf16 的 AudioVAE conv1d 会报 illegal immediate parameter (range error),属 CPU 后端问题; NPU 上完全正常。如确需 CPU 调试,可设 VOXCPM_MPS_DTYPE=float32 强制 fp32(速度明显下降)。
  3. 语音设计/克隆:语音设计结果每次生成略有差异,建议生成 1~3 次挑选; 语音克隆传入 reference_wav_path(16kHz 参考音频即可,输出 48kHz)。
  4. 降噪器:默认 load_denoiser=False 关闭(需 ModelScope 下载模型)。 如需启用:VoxCPM.from_pretrained(..., load_denoiser=True) 并提前 下载 iic/speech_zipenhancer_ans_multiloss_16k_base。
  5. 多卡部署:2B 模型单卡即可;多实例可多进程部署(每进程一张卡)。

7. 引用

@article{voxcpm2_2026,
  title   = {VoxCPM2: Tokenizer-Free TTS for Multilingual Speech Generation,
             Creative Voice Design, and True-to-Life Cloning},
  author  = {VoxCPM Team},
  journal = {GitHub},
  year    = {2026},
}

模型来源:HuggingFace: OpenBMB/VoxCPM2 代码仓库:GitHub: OpenBMB/VoxCPM 许可证:Apache-2.0