Ascend-SACT/ViiTor-voice-2.0-base
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

ViiTor-voice-2.0-base 运行手册

模型概述

ViiTor-voice-2.0-base 是 ViiTor 团队开发的语音合成(TTS)模型,支持中英文跨语言语音克隆,采用"文本 + 参考音频 → 语义 Token → 声学 Token → 波形"三阶段架构:用 Qwen2 LLM 生成语义 token,再由 SoundStorm + DualCodec 转换为波形。

本次适配将 ViiTor-voice-2.0 接入 vllm-omni 框架,使其能在 Ascend A2(910B3,每卡 64GB HBM)上通过 vllm serve --omni 方式提供 OpenAI 兼容的语音合成(/v1/audio/speech)服务,支持基于参考音频的音色克隆和响度匹配。

1. 快速开始

1.1 环境准备与补丁

项目说明
基础镜像quay.nju.edu.cn/ascend/vllm-omni:v0.26.0
vllm 路径/vllm-workspace/vllm (v0.26.0)
vllm-omni 路径/vllm-workspace/vllm-omni(镜像内置,tag v0.26.0)
LLM 模型目录/models/viitor_checkpoints/viitor/llm/zh-en
双 codec 目录/models/viitor_checkpoints/dualcodec、/models/viitor_checkpoints/w2v
SoundStorm ONNX/models/viitor_checkpoints/viitor/soundstorm/model.onnx(ATC 离线编译为 dynamic om,见 1.4 节)
0001-vllm.patch子进程 inspect 容错
0002-vllm-omni.patch模型适配 + pipeline 双 stage 拓扑 + warmup
0003-dualcodec.patch本地路径跳过 cached_path 避免重依赖;增加 NPU 设备检测

apply 顺序(先 vllm,再 vllm-omni,dualcodec 补丁在 1.2 节应用):

export PATCH_DIR=/path/to/patches   # 3 个 patch 的放置目录

# vllm 侧补丁
cd /vllm-workspace/vllm
git apply --check "$PATCH_DIR/0001-vllm.patch"
git apply "$PATCH_DIR/0001-vllm.patch"

# vllm-omni 侧补丁
cd /vllm-workspace/vllm-omni
git apply --check "$PATCH_DIR/0002-vllm-omni.patch"
git apply "$PATCH_DIR/0002-vllm-omni.patch"

说明:

  • 0001-vllm.patch:vllm 子进程 inspect 容错——让 inspect 结果从输出文件恢复,避免首次运行触发崩溃,NPU 通用问题。
  • 0002-vllm-omni.patch:模型适配 5 个新增文件(viitor_talker/code2wav/pipeline/adapter/yaml/config/processor)+ 8 个 vllm-omni 既有文件修改(pipeline 注册、arg_utils、serving_speech warmup 分支等)。
  • 无需升级 transformers,cann 和 torch/torch_npu 均使用基础镜像里的原始版本。
  • 如果当前 shell 尚未预置 Ascend 环境变量,先执行 source /usr/local/Ascend/ascend-toolkit/set_env.sh。

1.2 安装依赖

# 1. clone dualcodec (指定 v0.4.2 版本)
export DUALCODEC_DIR=/path/to/third_party/dualcodec
git clone --branch v0.4.2 https://github.com/jiaqili3/DualCodec.git $DUALCODEC_DIR

# 2. dualcodec 0.4.2 editable 安装 (--no-deps 避免引入冲突依赖)
pip install -e $DUALCODEC_DIR --no-deps

# 3. 打 dualcodec 补丁
cd $DUALCODEC_DIR
git apply --check "$PATCH_DIR/0003-dualcodec.patch"
git apply "$PATCH_DIR/0003-dualcodec.patch"

# 4. descript-audiotools安装 (dualcodec 运行依赖, --no-deps 是必须项)
pip install descript-audiotools --no-deps

# 5. adapter + dualcodec 运行时依赖 (不依赖 protobuf, 正常装; 若镜像已自带可跳过)
pip install pyloudnorm einops omegaconf soundfile easydict hydra-core

0003-dualcodec.patch:get_model.py等引入的模块级 import cached_path 依赖 google-cloud-storage等数十个包。ViiTor 仅使用本地 dualcodec,不涉及 dualcodec 权重的远程下载。patch 将模块级 import 改为延迟 import,本地路径直接跳过 cached_path,避免安装上述重依赖。此外还增加 NPU 设备检测,避免 W2V-BERT 等退化到 CPU 运行。

descript-audiotools安装用 --no-deps:descript-audiotools 声明依赖 protobuf(<3.20),默认安装会把镜像自带的 protobuf 7.x 降级到 3.19.x,导致 ImportError。

1.3 安装模型权重

权重可使用上游 viitor-ai/viitor-voice 仓库的 download_checkpoints.sh来下载(用 hf download 拉取 Hugging Face 上的 ZzWater/ViiTor-voice-2.0-base、facebook/w2v-bert-2.0、amphion/dualcodec)。

# 下载 download_checkpoints.sh 脚本并执行
bash download_checkpoints.sh

国内网络建议:下载脚本内置了镜像提示,打开 download_checkpoints.sh 取消注释这一行即可走 hf-mirror:

export HF_ENDPOINT=https://hf-mirror.com

下载完成后,权重结构如下(checkpoints/ 下):

checkpoints/
├── viitor/llm/zh-en   — LLM + speaker_condition (6层) 权重,语义生成主干 + 说话人编码器,分别生成语义 token 和说话人音色特征向量
├── viitor/soundstorm  — SoundStorm (ckpt.pt + model.onnx + model.yaml),MaskGIT 迭代扩散,语义 token → 声学 token
├── dualcodec          — DualCodec 25Hz (dualcodec_25hz_16384_1024.safetensors),声学编解码器,音频 ↔ token 互转
└── w2v                — W2V-BERT (model.safetensors),前端语音特征提取,从参考音频提取 speaker 向量

说明:本手册启动命令中的路径 /models/viitor_checkpoints/ 即代表上述 checkpoints/ 的实际路径,按实际路径进行调整(启动命令和请求里的模型路径一并替换)。

1.4 转换 SoundStorm om(Stage1 推理用)

Stage1 的 SoundStorm 用 ATC 离线编译的 .om 进行推理。om 与硬件绑定,需用 soundstorm_dynamic_convert.sh(源 onnx 是 checkpoints/viitor/soundstorm/model.onnx)生成支持可变帧数的 om(soundstorm_dynamic.om,覆盖 1 ~ 1024 帧 ≈ 1 ~ 40 秒):

# 需在容器内运行
bash soundstorm_dynamic_convert.sh
# 产物: $OUT_DIR/soundstorm_dynamic.om (默认 OUT_DIR=脚本所在目录, 如有需要,执行脚本前可以用 OUT_DIR=<可写目录> 覆盖默认值)

SoC 自动检测:脚本自动检测 A2(Ascend910B3)/A3(Ascend910_9382 等)/A5(Ascend950DT_9582 等)的 SoC,也可显式传 SOC_VERSION=<合法值> 覆盖自动检测值。

om 硬件绑定:om 只适用于编译时的 SoC 版本和 CANN 大版本,芯片或 CANN 大版本不同时需重新编译。

1.5 启动服务

# 关键:不要在 /vllm-workspace 目录下启动(详见下方说明)
cd /tmp
# vllm-omni 适配代码默认加载 /disk1/models/soundstorm_dynamic.om, 若 om 不是该路径,启动时通过 SOUNDSTORM_OM_PATH 设置实际路径
# export SOUNDSTORM_OM_PATH=/path/to/soundstorm_dynamic.om
ASCEND_RT_VISIBLE_DEVICES=0 \
vllm serve /models/viitor_checkpoints/viitor/llm/zh-en \
  --omni \
  --host 0.0.0.0 --port 8091 \
  --trust-remote-code \
  --allowed-local-media-path /

说明:

  • --omni 必选,启用 vllm-Omni 模式,自动加载双 stage 拓扑配置(vllm_omni/deploy/viitor_voice.yaml)。
  • --trust-remote-code 必选。
  • --allowed-local-media-path / 必选(音色克隆的参考音频用 file:// URI 读取)。
  • 必须在非 /vllm-workspace 的目录下启动:该目录含 vllm 源码,在其下会直接导入源码,绕过 editable finder 的正常解析逻辑,import vllm 报 ImportError。
  • 启动时会自动预热:服务在 Application startup complete 前会自动跑一次合成请求预热 Stage1(SoundStorm 首次推理 + DualCodec 首次 decode + 算子库加载),预热完成后才开始接受请求,首个用户请求无预热开销(与稳态一致)。
  • 启动日志会输出 [viitor] estimated duration=X.Xs,提示当前估算的目标语音时长;如需调整,在请求里传类似 "extra_params": {"duration": 10.0} 的参数(单位:s)。
  • 默认已启用 cudagraph(Stage0 LLM AR FULL 模式),若需关闭,把 vllm_omni/deploy/viitor_voice.yaml 里 Stage0 的 enforce_eager 改回 true。

1.6 启动后快速验证

# 检查模型就绪
curl -sf http://127.0.0.1:8091/v1/models

# 语音合成 + 音色克隆 (ref_audio 是参考音频的 file:// URI)
curl -sf -X POST http://127.0.0.1:8091/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "/models/viitor_checkpoints/viitor/llm/zh-en",
    "input": "welcome to china, the weather is nice today",
    "ref_audio": "file:///path/to/djh_welcome.wav",
    "ref_text": "welcome",
    "task_type": "Base",
    "response_format": "wav"
  }' --output output.wav

2. 请求参数

2.1 语音合成 + 音色克隆

curl -sf -X POST http://127.0.0.1:8091/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "/models/viitor_checkpoints/viitor/llm/zh-en",
    "input": "大家好, 今天天气真好, 我想去公园散步",
    "ref_audio": "file:///path/to/djh_welcome.wav",
    "ref_text": "welcome",
    "task_type": "Base",
    "response_format": "wav"
  }' --output output.wav
  • input:要合成的文本。建议加英文逗号/句号/空格作为停顿(中文逗号 , base 模型有 bug,会导致逗号后乱码)。
  • ref_audio:参考音频,用于音色克隆。支持 file:// URI。音色由 speaker_condition 从参考音频提取并注入 LLM。
  • ref_text:参考音频的转写文本(用于估算时长)。
  • task_type:Base 表示音色克隆。
  • response_format:wav / pcm / flac。
  • extra_params.duration(可选):覆盖自动估算的时长(秒,0.5 步进,0.5~30.0)。不传则按 0.12s/字符(英文)/0.3s/字符(中文)估算,日志会打印估算值。

2.2 无参考音频(默认音色)

不传 ref_audio 时,LLM 无 speaker 注入,输出为无特征默认音色(不推荐,音色克隆效果会丢失)。

3. 特性适配状态

特性状态说明
语音合成(TTS)✅ 已适配/v1/audio/speech,含 duration 估算 + 尾音截断
音色克隆✅ 已适配serving 层算 speaker 向量 + ref prompt,注入 LLM + SoundStorm
响度匹配✅ 已适配用参考音频 LUFS 匹配生成音频响度
尾音截断✅ 已适配去掉尾部连续静音
ACLGraph(cudagraph)✅ 已启用Stage0 LLM AR FULL 模式(yaml 配置 enforce_eager: false),稳态提速约 55%(8.9s→4.0s)。Stage1 SoundStorm 是 om 推理不走 cudagraph,保持 eager。
服务启动预热✅ 已启用serving 层 warmup hook,阻塞式(预热完才接受请求),首请求与稳态一致(3~4s)。

4. 性能参考

  • 开启 cudagraph + warmup 后,端到端单次请求约 3~4s(预热后稳态,含 LLM 生成 + SoundStorm 扩散 + DualCodec 解码)。
  • 显存占用约 33.8 GiB(Stage0 LLM + Stage1 SoundStorm/DualCodec,Stage1 只加载 DualCodec decode 部分、不加载 W2V-BERT)。cudagraph 需额外显存,/vllm-workspace/vllm-omni/vllm_omni/deploy/viitor_voice.yaml 里 Stage0 gpu_memory_utilization 已调低到 0.35 给 Stage1 腾空间。

5. 已知限制

  • 开头 artifact:音频开头是参考音频末尾和新生成声音的拼接,会有轻微声学突变(开头杂音),是上游设计特性,可用淡入(fade-in 50ms)消除。
  • 中文逗号(,)异常:base 模型对中文逗号映射有问题,逗号后第一个词语音乱码(CPU 上也错,非 NPU 适配问题)。可以用英文逗号 ,或空格替代。
  • duration 0.5 秒步进:duration token为 0.5 ~ 30.0(id 135931 ~ 135990),非步进值会被 tokenizer 拆碎,音频时长不可控。不传 extra_params.duration 时按 0.12s/字符(英文)/0.3s/字符(中文)估算,日志会打印估算值供二次调整。
  • duration 冗余/不足:LLM 按 duration token 填满生成,内容说完后多出的 codes 解码成乱音;duration 太短则内容没说完,duration 太长则末尾冗余乱音。中文无标点长文本冗余最明显,加标点(英文逗号/句号/空格)可让 LLM 在标点处生成自然停顿,冗余大幅减少。自带的尾音截断逻辑只能去掉末尾连续静音。