VoxCPM 完全指南:无分词器 TTS 的架构原理、Python API 与 CLI 实战

原创2026-10-24 12:44:411,751 阅读
文章标签:人工智能语音音频深度学习机器学习微调LoRA本地部署openBMB

VoxCPM 完全指南:无分词器 TTS 的架构原理、Python API 与 CLI 实战

VoxCPM 是 OpenBMB 开源的端到端语音合成系统,它绕开离散音频 token,直接在连续空间建模语音,从而实现上下文感知的富有表现力合成与零样本音色克隆。本文以仓库 README 为主线,完整梳理模型版本差异、安装与下载、Python 与命令行两种调用方式、参数调优逻辑、微调与常见限制,并结合 src/voxcpm 下的源码解释每个参数在实现层真正做了什么。

一、VoxCPM 是什么:从"分词"到"连续空间"的设计取舍

README 对 VoxCPM 的定位非常明确:一个 tokenizer-free 的 TTS 系统。主流方案通常先把语音离散成 token,再用语言模型建模 token 序列;VoxCPM 则将语音表示保持在连续空间,用端到端的 扩散自回归(diffusion autoregressive) 架构直接从文本生成连续语音表示。

它的技术骨架由三部分组成:

  1. MiniCPM-4 语言模型主干:负责文本理解与上下文建模,是"上下文感知"能力的来源;
  2. 层级语言建模 + FSQ 约束:通过分层建模实现语义与声学的隐式解耦,提升表现力与生成稳定性;
  3. AudioVAE + LocDiT 局部模块:AudioVAE 负责连续语音特征的编解码,LocDiT(基于 Flow Matching)负责在局部 patch 上做扩散生成。

README 中给出的模型架构图如下:

VoxCPM 模型架构图,展示文本经 MiniCPM-4 主干、FSQ 量化与 AudioVAE/LocDiT 局部模块生成连续语音表示

如果对照源码,这套结构在 model/voxcpm.py 的 VoxCPMModel.__init__ 中可以一一对上:

  • self.base_lm = MiniCPMModel(config.lm_config):文本-语义语言模型(Text-Semantic LM);
  • self.residual_lm:层数由 residual_lm_num_layers(默认 6)控制的残差声学语言模型(Residual Acoustic LM);
  • self.feat_encoder / self.feat_decoder:分别对应局部编码器 VoxCPMLocEnc 与局部扩散解码器 UnifiedCFM + VoxCPMLocDiT;
  • self.fsq_layer:ScalarQuantizationLayer,即 README 所说的 FSQ 约束;
  • self.audio_vae:连续语音的编码/解码器,sample_rate 直接由它决定。

配置类 VoxCPMConfig(同文件 L68-L83)把关键超参暴露出来:patch_size、feat_dim、residual_lm_num_layers、scalar_quantization_latent_dim、scalar_quantization_scale、max_length、device、dtype 等,说明这些量是模型级配置而非运行时随意指定。

二、两个旗舰能力与效率指标

README 将能力归纳为三点,理解它们有助于后续选参数:

能力 README 描述 实现层面的支撑
上下文感知的表达性合成 依据文本内容推断合适的韵律与语气,在 180 万小时中英双语语料上训练 文本经 base_lm 编码后与音频特征拼接(combined_embed),由 LM 主干承担"读文本、定风格"
逼真的零样本音色克隆 仅需一段短参考音频,即可复刻音色、口音、情绪、节奏与语速 build_prompt_cache() 把参考音频编码成 latent 特征,与参考文本一起作为 prompt 前置
高效流式合成 消费级 NVIDIA RTX 4090 上 RTF 可低至 0.17 generate_streaming() 逐 patch 解码并立即返回音频块

需要强调:RTF 0.17(VoxCPM-0.5B)与约 0.15(VoxCPM1.5)是 README 在 单张 RTX 4090 上给出的参考值,硬件与文本长度不同会显著变化,不应直接外推到 CPU 或其他 GPU。

三、模型版本对比:VoxCPM1.5 与 VoxCPM-0.5B

README 与 发布说明 给出了两代权重的差异,这是选择权重时最关键的一张表:

项目 VoxCPM1.5(Latest) VoxCPM-0.5B(Original)
模型参数量 800M 640M
AudioVAE 采样率 44100 16000
LM 主干 token 速率 6.25Hz(patch-size=4) 12.5Hz(patch-size=2)
单卡 RTX 4090 RTF 约 0.15 0.17

发布说明进一步解释了 1.5 的改动边界:

  • 核心架构未变,关键改动是把局部模块(LocEnc & LocDiT)的 patch size 从 2 调整为 4,使 LM 处理速率从 12.5Hz 降到 6.25Hz;由于局部模块需要处理更长上下文,网络深度增加,因此总参数略增。
  • "it/s 变慢"不等于更慢:1.5 每生成 1 秒音频只需 6.25 个 token(旧版 12.5 个),所以即使单步速度显示下降,按 RTF 衡量的实际速度不降甚至更快。
  • 44.1kHz 不等于必然高保真:输出质量取决于参考语音质量,高采样率只是打开了上限。

在源码里,这条"token 速率 = 采样率 ÷(hop_length × patch_size)"的关系可以验证:AudioVAE 的 hop_length 是编码器各层 stride 的乘积,chunk_size 与之一致(audiovae/audio_vae.py);而 patch_size 在 VoxCPMConfig 中定义,并在推理时作为每个 LM step 生成的帧数使用(model/voxcpm.py)。

四、安装与环境前提

4.1 从 PyPI 安装

pip install voxcpm

包的元数据定义在 pyproject.toml,几个值得注意的事实:

  • requires-python = ">=3.10",分类器标注支持 Python 3.10 / 3.11;
  • 核心依赖包含 torch>=2.5.0、torchaudio>=2.5.0、transformers>=4.36.2、modelscope>=1.22.0、huggingface-hub、safetensors、gradio<6、funasr、wetext 等;
  • 命令行入口注册为 voxcpm = "voxcpm.cli:main",因此安装后可直接使用 voxcpm,也可用 python -m voxcpm.cli;
  • 项目使用 src 布局(<a href="https://link.gitcode.com/i/6cbff34cd33d7eeff41269523f7f8a5d" target="_blank">tool.setuptools.package-dir] "" = "src"),从源码运行脚本时需要显式把 src 加入 sys.path——[scripts/train_voxcpm_finetune.py 就是这么做的。

4.2 模型下载(可选)

默认情况下首次运行会自动下载权重,也可以提前下载:

# VoxCPM1.5
from huggingface_hub import snapshot_download
snapshot_download("openbmb/VoxCPM1.5")

# 或 VoxCPM-0.5B
from huggingface_hub import snapshot_download
snapshot_download("openbmb/VoxCPM-0.5B")

Web Demo 还需要两个辅助模型:用 ZipEnhancer 增强参考语音、用 SenseVoice-Small 对参考语音做 ASR:

from modelscope import snapshot_download
snapshot_download('iic/speech_zipenhancer_ans_multiloss_16k_base')
snapshot_download('iic/SenseVoiceSmall')

这两者的用途在源码中很清楚:zipenhancer.py 封装了 ModelScope 的 acoustic_noise_suppression pipeline,并在增强后做响度归一化;app.py 初始化 SenseVoice-Small,用于在 UI 中把用户上传的参考音频自动转写成 prompt_text。

五、Python API:非流式与流式合成

5.1 最小可运行示例

import soundfile as sf
import numpy as np
from voxcpm import VoxCPM

model = VoxCPM.from_pretrained("openbmb/VoxCPM1.5")

# Non-streaming
wav = model.generate(
    text="VoxCPM is an innovative end-to-end TTS model from ModelBest, designed to generate highly expressive speech.",
    prompt_wav_path=None,      # optional: path to a prompt speech for voice cloning
    prompt_text=None,          # optional: reference text
    cfg_value=2.0,             # LM guidance on LocDiT, higher for better adherence to the prompt, but maybe worse
    inference_timesteps=10,    # LocDiT inference timesteps, higher for better result, lower for fast speed
    normalize=False,           # enable external TN tool, but will disable native raw text support
    denoise=False,             # enable external Denoise tool, but it may cause some distortion and restrict the sampling rate to 16kHz
    retry_badcase=True,        # enable retrying mode for some bad cases (unstoppable)
    retry_badcase_max_times=3, # maximum retrying times
    retry_badcase_ratio_threshold=6.0, # maximum length restriction for bad case detection
)
sf.write("output.wav", wav, model.tts_model.sample_rate)
print("saved: output.wav")

# Streaming
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("output_streaming.wav", wav, model.tts_model.sample_rate)
print("saved: output_streaming.wav")

注意写入文件时用的是 model.tts_model.sample_rate,而不是硬编码 16000 或 44100——这个值来自 AudioVAE 配置(model/voxcpm.py),切换权重版本时会自动变化。

5.2 generate 与 generate_streaming 的关系

core.py 中两者其实是同一个内部生成器的两种取用方式:

def generate(self, *args, **kwargs) -> np.ndarray:
    return next(self._generate(*args, streaming=False, **kwargs))

def generate_streaming(self, *args, **kwargs) -> Generator[np.ndarray, None, None]:
    return self._generate(*args, streaming=True, **kwargs)

也就是说,generate_streaming 接受与 generate 完全相同的参数。返回的都是 CPU 上的一维 float32 numpy 波形(_generate 中 yield wav.squeeze(0).cpu().numpy())。

5.3 参数含义与源码级影响

参数 默认值(_generate) 实际作用与源码依据
text 必填 空字符串或非字符串直接抛 ValueError;换行会被替换为空格并压缩连续空白(core.py)
prompt_wav_path None 参考音频路径,必须存在,否则 FileNotFoundError
prompt_text None 必须与 prompt_wav_path 同时提供或同时为 None,否则报错
cfg_value 2.0 传入 LocDiT 的 classifier-free guidance 强度;在 unified_cfm.py 中参与 dphi_dt = cfg_dphi_dt * st_star + cfg_value * (dphi_dt - cfg_dphi_dt * st_star)
inference_timesteps 10 欧拉求解器的离散步数,t_span = linspace(1, 0, n_timesteps + 1),步数越多越精细也越慢
min_len 2 早停保护:只有当步数 i > min_len 且停止头预测为 1 时才终止
max_len 4096 生成 token 上限,防止失控
normalize False 开启后走 TextNormalizer(WeTextProcessing),同时会关闭模型对原始文本的原生理解能力
denoise False 仅在存在参考音频且 denoiser 已加载时生效,用于增强参考语音
retry_badcase True 检测"音频长度/文本长度"比例异常并重试
retry_badcase_max_times 3 最多重试次数
retry_badcase_ratio_threshold 6.0 判定坏例的比例阈值,语速慢的素材可适当调高

关于 retry_badcase,源码里有两处容易踩坑的细节:

  1. 流式模式不支持重试。_generate 与 _generate_with_prompt_cache 都会在 retry_badcase and streaming 时发出 warnings.warn(...) 并强制把 retry_badcase 置为 False(model/voxcpm.py、L611-L613)。
  2. 阈值同时影响最大长度。每次尝试都会把上限收紧为 min(int(target_text_length * ratio + 10), max_len),因此比例阈值过小会让长句被提前截断(model/voxcpm.py)。

5.4 模型加载与 optimize 的实际收益

VoxCPM.from_pretrained 支持"本地目录或 Hub ID"两种来源:若 hf_model_id 指向一个已存在目录,就直接当本地路径用,否则调用 snapshot_download(core.py)。构造函数还有两个关键开关:

  • optimize=True(默认):先 torch.compile,再做一次 warm up(用一句 "Hello, this is the first test sentence." 跑一次 max_len=10 的生成),因此首次加载会明显更慢,但后续推理更快。
  • load_denoiser / zipenhancer_model_id:控制是否初始化去噪器;把 load_denoiser=False 可以跳过 ZipEnhancer 的加载。

optimize 并非在所有环境都生效。model/voxcpm.py 中明确要求设备为 CUDA 且安装了 triton,否则捕获异常并打印 Warning: torch.compile disabled - ...,模型仍可正常使用,只是没有编译加速。

六、命令行(CLI)实战

安装后入口为 voxcpm,参数解析集中在 cli.py。CLI 并非用子命令区分模式,而是根据参数组合自动路由(cli.py):

  • 给了 --input → 批量模式(必须同时给 --output-dir);
  • 给了 --text 且给了 --output → 单条模式;此时若还给了 --prompt-audio 或 --prompt-text → 克隆模式;
  • --input 与 --text 互斥,同时出现会直接 parser.error。

6.1 README 中的完整命令集

# 1) Direct synthesis (single text)
voxcpm --text "VoxCPM is an innovative end-to-end TTS model from ModelBest, designed to generate highly expressive speech." --output out.wav

# 2) Voice cloning (reference audio + transcript)
voxcpm --text "VoxCPM is an innovative end-to-end TTS model from ModelBest, designed to generate highly expressive speech." \
  --prompt-audio path/to/voice.wav \
  --prompt-text "reference transcript" \
  --output out.wav \
  # --denoise

# (Optional) Voice cloning (reference audio + transcript file)
voxcpm --text "..." \
  --prompt-audio path/to/voice.wav \
  --prompt-file "/path/to/text-file" \
  --output out.wav

# 3) Batch processing (one text per line)
voxcpm --input examples/input.txt --output-dir outs
# (optional) Batch + cloning
voxcpm --input examples/input.txt --output-dir outs \
  --prompt-audio path/to/voice.wav \
  --prompt-text "reference transcript"

# 4) Inference parameters (quality/speed)
voxcpm --text "..." --output out.wav \
  --cfg-value 2.0 --inference-timesteps 10 --normalize

# 5) Model loading
voxcpm --text "..." --output out.wav --model-path /path/to/VoxCPM_model_dir
voxcpm --text "..." --output out.wav \
  --hf-model-id openbmb/VoxCPM1.5 --cache-dir ~/.cache/huggingface --local-files-only

# 6) Denoiser control
voxcpm --text "..." --output out.wav \
  --no-denoiser --zipenhancer-path iic/speech_zipenhancer_ans_multiloss_16k_base

# 7) Help
voxcpm --help
python -m voxcpm.cli --help

两点需要按当前仓库实际情况修正或注意:

  • 批处理示例里的 examples/input.txt 在当前仓库中并不存在;仓库只提供了 examples/train_data_example.jsonl(微调用的 JSONL 清单)与 examples/example.wav。使用批量模式前需要自己准备一个"一行一条文本"的 txt 文件。批量输出会按 output_001.wav、output_002.wav 递增命名(cli.py)。
  • --prompt-file 在 README 中出现,但当前 cli.py 只定义了 --prompt-audio、--prompt-text、--denoise,并未注册 --prompt-file。以源码为准时,应使用 --prompt-text 直接传入参考文本(或自行读取文件内容后传入)。遇到 unrecognized arguments 报错即为此原因。

6.2 CLI 参数速查表

参数 默认值 约束 / 说明
--text, -t 无 单条/克隆模式的待合成文本
--output, -o 无 输出 wav 路径,父目录会自动创建
--input, -i 无 批量模式输入 txt,一行一条
--output-dir, -od 无 批量模式输出目录,自动创建
--prompt-audio, -pa 无 参考音频,克隆模式下必须存在
--prompt-text, -pt 无 参考音频对应文本,克隆模式下必须提供
--denoise False 只作用于参考音频;纯文本合成时被强制关闭
--cfg-value 2.0 校验区间 0.1 ~ 10.0(帮助文本建议 0.5–5.0)
--inference-timesteps 10 校验区间 1 ~ 100
--normalize False 开启外部文本归一化
--model-path 无 本地模型目录,优先于 Hub 下载
--hf-model-id openbmb/VoxCPM1.5 Hub 仓库 ID
--cache-dir 无 Hub 下载缓存目录
--local-files-only False 禁用网络,只用本地缓存
--no-denoiser False 不加载 ZipEnhancer
--zipenhancer-path 无 也可用环境变量 ZIPENHANCER_MODEL_PATH
--lora-path 无 LoRA 权重路径,触发 LoRA 结构注入
--lora-r / --lora-alpha 32 / 16 必须为正整数
--lora-dropout 0.0 区间 0.0 ~ 1.0
--lora-disable-lm / --lora-disable-dit False 关闭对应模块上的 LoRA
--lora-enable-proj False 是否给投影层加 LoRA

这些校验并非文档描述,而是硬编码在 cli.py 的 validate_ranges 里,越界会直接以 parser.error 退出。另有一个隐蔽但实用的点:--zipenhancer-path 未显式给出时,会回落到环境变量 ZIPENHANCER_MODEL_PATH(cli.py),适合在容器里统一配置。

七、语音克隆的工作机制与参考音频处理细节

README 强调"只需一段短参考音频",但要让克隆稳定,理解 prompt 在源码中如何被消费很有帮助。

7.1 Prompt Cache 的构建

build_prompt_cache(prompt_text, prompt_wav_path)(model/voxcpm.py)做了四件事:

  1. torchaudio.load 读取音频;
  2. 多声道时按通道求均值转为单声道;
  3. 采样率与模型不一致时用 torchaudio.functional.resample 重采样;
  4. 按 patch_len = patch_size * chunk_size 做 左侧填充(在开头补零,保证有效音频落在序列尾部),再送入 audio_vae.encode 得到 latent 特征。

缓存只保存 prompt_text 与 audio_feat 两项,文本 tokenize 留到生成时统一处理——这解释了为什么同一份 prompt 可以被多句文本复用而不会出现 token 化不一致。

7.2 去噪的代价

denoise=True 时,core._generate 会先把参考音频写进临时文件、调用 self.denoiser.enhance(...),用完在 finally 中删除临时文件(core.py)。这个流程的两个后果必须知情:

  • 采样率被限制在 16kHz:ZipEnhancer 使用的是 ..._16k_base 模型;去噪后的参考音频会拉低 VoxCPM1.5 的克隆上限。这与 使用指南 中的说明一致——追求 44.1kHz 高质量克隆时应关闭参考语音增强。
  • 环境音也被保留或改变:ZipEnhancer 做的是语音增强+响度归一化(目标响度 -20 LUFS,见 zipenhancer.py),因此背景氛围会被改写,而不是原样保留。

7.3 不给参考音频时会发生什么

prompt_wav_path=None 时,prompt_cache 为 None,模型只把目标文本与 audio_start_token 拼成输入(model/voxcpm.py)。此时风格完全由文本内容与 LM 主干推断,即 README 所说的"上下文感知"路径。这也是最适合用来验证模型是否正常工作的基线。

八、Web Demo

python app.py

app.py 的关键行为:

  • 设备自动选择:有 CUDA 用 cuda,否则 cpu;
  • 模型目录解析顺序为:优先本地 ./models/VoxCPM1.5,否则按环境变量 HF_REPO_ID(默认 openbmb/VoxCPM1.5)下载到 models/{repo};
  • TTS 模型是懒加载的(get_or_load_voxcpm),首次点击生成时才真正载入,避免启动即占显存;
  • UI 里 do_normalize、denoise 默认都是开启的(app.py),因此网页端默认走的是"归一化文本 + 去噪参考音频"的组合,与 Python 脚本默认值不同,这一点在对比试听时容易造成困惑。

九、微调:全参数 SFT 与 LoRA

README 指明 VoxCPM1.5 同时支持全参数微调与 LoRA 微调,详细流程见 微调指南。这里保留其可直接执行的最小路径,并补充配置项在训练脚本中的落点。

9.1 数据准备

训练清单为 JSONL,一行一个样本:

{"audio": "path/to/audio1.wav", "text": "Transcript of audio 1."}
{"audio": "path/to/audio2.wav", "text": "Transcript of audio 2.", "duration": 3.5}
{"audio": "path/to/audio3.wav", "text": "Optional dataset_id for multi-dataset.", "dataset_id": 1}
字段 必填 说明
audio 是 音频路径(绝对或相对)
text 是 对应转写文本
duration 否 秒数,加速样本过滤
dataset_id 否 多数据集训练时的数据集编号,默认 0

要求:WAV 格式;采样率与权重匹配(VoxCPM-0.5B 为 16kHz,VoxCPM1.5 为 44.1kHz)。完整示例见 examples/train_data_example.jsonl。

9.2 两条命令启动训练

# Full fine-tuning
python scripts/train_voxcpm_finetune.py \
    --config_path conf/voxcpm_v1.5/voxcpm_finetune_all.yaml

# LoRA fine-tuning
python scripts/train_voxcpm_finetune.py \
    --config_path conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml

多卡用 torchrun:

CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc_per_node=4 \
    scripts/train_voxcpm_finetune.py --config_path conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml

9.3 配置文件与参数

仓库已提供两份可直接改路径的配置:conf/voxcpm_v1.5/voxcpm_finetune_all.yaml 与 conf/voxcpm_v1.5/voxcpm_finetune_lora.yaml。LoRA 版本的核心内容:

pretrained_path: /path/to/VoxCPM1.5/
train_manifest: /path/to/train.jsonl
val_manifest: null
sample_rate: 44100
batch_size: 16
grad_accum_steps: 1
num_workers: 2
num_iters: 2000
log_interval: 10
valid_interval: 1000
save_interval: 1000
learning_rate: 0.0001
weight_decay: 0.01
warmup_steps: 100
max_steps: 2000
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: 16
  dropout: 0.0

全参数版本唯一的关键差异是学习率更小(0.00001)且没有 lora 段。这些字段全部对应 scripts/train_voxcpm_finetune.py 中 train() 的签名,通过 argbind 从 YAML 注入(配置加载逻辑见 src/voxcpm/training/config.py)。

LoRA 参数的建议取值(来自微调指南):

参数 含义 建议
enable_lm 给 LM 加 LoRA true
enable_dit 给 DiT 加 LoRA true(音色克隆依赖)
r 秩,越大容量越强 16–64
alpha 缩放系数,scaling = alpha / r 通常 r/2 或 r
target_modules_* 注入的线性层名 attention 的 q/v/k/o_proj

LoRA 的注入点在 model/voxcpm.py 的 _apply_lora:enable_lm 作用于 base_lm 与 residual_lm,enable_dit 作用于 feat_decoder.estimator,enable_proj 则把 enc_to_lm_proj、lm_to_dit_proj、res_to_dit_proj 三个 nn.Linear 替换为 LoRALinear。训练时 from_local(..., training=True, lora_config=...) 会冻结 AudioVAE,并在 LoRA 模式下只放开含 lora 的参数(model/voxcpm.py),这正是 LoRA 显存友好的原因。

max_batch_tokens 是一个防 OOM 的过滤器:配置中注释说明它按 max_batch_tokens // batch_size 估算单样本可接受的 token 上限,超长样本会被丢弃(scripts/train_voxcpm_finetune.py)。因此把它调小会牺牲长音频样本,而不是"压缩"它们。

9.4 产物结构与推理

全参数微调产出的是完整模型目录(model.safetensors、config.json、audiovae.pth、tokenizer 文件、optimizer.pth、scheduler.pth),可直接当模型路径使用;LoRA 只产出 lora_weights.safetensors + lora_config.json(内含 base_model 与 lora_config)。

# 全参数微调推理
python scripts/test_voxcpm_ft_infer.py \
    --ckpt_dir /path/to/checkpoints/finetune_all/step_0002000 \
    --text "Hello, this is the fine-tuned model." \
    --output output.wav

# LoRA 推理(自动读取 lora_config.json 中的基座路径)
python scripts/test_voxcpm_lora_infer.py \
    --lora_ckpt /path/to/checkpoints/finetune_lora/step_0002000 \
    --text "Hello, this is LoRA fine-tuned result." \
    --output lora_output.wav

两者都支持追加 --prompt_audio 与 --prompt_text 做克隆推理。

9.5 LoRA 热切换

core.py 提供了一组不重载基座的 LoRA 管理接口,等价于"同一进程内切换多个音色适配器":

from voxcpm.core import VoxCPM
from voxcpm.model.voxcpm import LoRAConfig

lora_cfg = LoRAConfig(enable_lm=True, enable_dit=True, r=32, alpha=16)
model = VoxCPM.from_pretrained(
    hf_model_id="openbmb/VoxCPM1.5",
    load_denoiser=False,
    lora_config=lora_cfg,
    lora_weights_path="/path/to/lora_checkpoint",
)

model.set_lora_enabled(False)   # 退回基座
model.set_lora_enabled(True)    # 重新启用
model.unload_lora()             # 把 LoRA 权重重置为初始值
loaded, skipped = model.load_lora("/path/to/another_lora_checkpoint")
print(len(loaded), len(skipped))

一个容易被忽略的便利设计:若只给 lora_weights_path 而不给 lora_config,构造函数会自动创建一个 enable_lm=True, enable_dit=True, enable_proj=False 的默认配置(core.py)。反过来说,如果你的 LoRA 训练用了自定义 r/alpha,就必须显式传入相同的 LoRAConfig,否则维度不匹配的键会被计入 skipped。

十、文本归一化:normalize 到底改了什么

normalize=True 会启用 utils/text_normalize.py 中的 TextNormalizer:

  • 先按是否含中文选择中文或英文 Normalizer(wetext 的 operator="tn");
  • clean_text 会先清掉 Markdown 语法(代码块、链接、标题符号)与 emoji,并统一引号;
  • 中文路径额外做数字/符号修补(如把 = 读作"等于"、处理 x-2 被误读为"x 负 2")、中文字符间空格清理、²/³/√/≈ 等符号转写;
  • 英文路径则对连续数字用 inflect 做拼读。

这也解释了 README 中那句注释的准确含义:开启 normalize 会关闭模型对原生原始文本(含音素标记)的理解能力。按 使用指南 的说明,若要输入 {HH AH0 L OW1}(英)或 {ni3}{hao3}(中)这类音素串做精确发音控制,应保持 normalize=False。

十一、性能表现与如何正确引用

性能文档 给出了 Seed-TTS-eval 与 CV3-eval 两个公开零样本 TTS 基准的对比表。以 Seed-TTS-eval 为例,VoxCPM(0.5B)报告的结果为 test-EN WER 1.85%、SIM 72.9%,test-ZH CER 0.93%、SIM 77.2%,test-Hard CER 8.87%、SIM 73.0%。在 CV3-eval 中,VoxCPM 报告 zh CER 3.40%、en WER 4.04%、hard-en WER 7.89%。

引用这些数字时需要注意边界:

  • 表中同时包含闭源与开源模型,部分单元格为 -(未报告),因此不能据此得出"全面领先"的结论;
  • 指标定义不同(WER/CER 越低越好,SIM/DNSMOS 越高越好),跨表比较没有意义;
  • 这些是仓库文档中的评测结果,复现实验条件(测试集、参考音频、解码参数)不在本仓库中给出,实际项目应以自有数据实测为准。

十二、风险、局限与已知边界

README 的 "Risks and limitations" 与发布说明的 FAQ 共同划定了使用边界,这部分在实际落地时比指标更重要:

  • 通用模型行为:即使训练数据规模很大,仍可能产生意外、带偏或含伪影的输出。
  • 克隆能力可被滥用:零样本克隆可生成高度逼真的合成语音,存在被用于冒充、诈骗、虚假信息的风险。README 明确要求不得用于侵犯他人权益的内容,并建议公开分享时显著标注为 AI 生成。
  • 长文本与强表现力输入仍不稳定:发布说明承认长语音稳定性问题"未被完全解决",自回归误差累积仍可能发生;官方已通过降低 LM 处理速率(12.5Hz → 6.25Hz)与推理逻辑优化改善首尾伪影。
  • 可控性有限:目前仅支持零样本克隆与上下文感知生成,对情绪、风格的细粒度指令控制尚不支持。
  • 双语为主:主要基于中英数据训练,其他语言效果不作保证。
  • 定位为研究与开发用途:README 不建议在未经严格测试与安全评估的情况下直接用于生产或商业场景。
  • 硬件适配有限:发布说明指出尚未适配昇腾 910B、XPU、NPU 等芯片,torch.compile 加速也仅限 CUDA + triton 环境。

此外,README 的 TO-DO 列表说明了路线图状态:技术报告、44.1kHz 采样率、SFT/LoRA 微调已完成;多语言支持与"人类指令可控语音生成"尚未完成。这些是计划而非现成能力,不应写进功能宣传。

十三、许可证与引用

VoxCPM 的模型权重与代码以 Apache-2.0 开源,许可证文件见 LICENSE。学术引用信息(BibTeX)如下,取自 README:

@article{voxcpm2025,
  title        = {VoxCPM: Tokenizer-Free TTS for Context-Aware Speech Generation and True-to-Life Voice Cloning},
  author       = {Zhou, Yixuan and Zeng, Guoyang and Liu, Xin and Li, Xiang and Yu, Renjie and Wang, Ziyang and Ye, Runchuan and Sun, Weiyue and Gui, Jiancheng and Li, Kehan and Wu, Zhiyong and Liu, Zhiyuan},
  journal      = {arXiv preprint arXiv:2509.24650},
  year         = {2025},
}

十四、下一步阅读路径

从工程角度看,VoxCPM 的调用面很窄:一个 VoxCPM 类、两个生成方法、一套 CLI;真正的复杂度被收敛在"如何构造 prompt 缓存"和"如何在连续空间里逐步采样"这两件事上。掌握本文给出的参数默认值、校验区间与源码位置,就足以在质量、速度与稳定性之间做出可解释的取舍,而不是靠反复试错。

登录后查看全文
VoxCPM