更新日志¶

本页记录各版 VoxCPM 对开发者可见 的变更——新 API、架构标记、CLI、配置字段、训练脚本与依赖。若在版本间迁移，请从你当前版本往后阅读。

VoxCPM 2.0 — 2026 年 3 月¶

重要

破坏性变更一览 — 从 1.x 升级前请先读：

VoxCPM.from_pretrained() 现默认 `` openbmb/VoxCPM2``。若依赖默认行为，代码会加载 2B 模型而非 VoxCPM 1.5。需要时请显式固定：`` VoxCPM.from_pretrained("openbmb/VoxCPM1.5")``。
输出采样率变更：44.1 kHz（1.5）→ ** 48 kHz** （2.0）。凡硬编码 sf.write(..., 44100) 的代码须改为 `` model.tts_model.sample_rate`` （V2 返回 `` 48000``）。
Gradio 依赖升至 >=6,<7。Gradio 5 应用无法与 VoxCPM 2 并存安装。`` app_old.py`` （1.5 Demo）也已适配 Gradio 6。
CLI 子命令设计：旧式扁平 voxcpm --text ... 仍可用，但会打印弃用警告。请优先使用 `` voxcpm design|clone|batch``。

30-Language Multilingual¶

VoxCPM 2 将语言支持从 2 种（中、英） 扩展到 ** 30 种语言**、8 个语系，训练数据约 236 万小时（180 万小时中英基础 + 56 万小时多语）。完整列表见 VoxCPM 2。

在代码层面，多语合成 无需改 API —— 直接传入任意支持语言的文本即可，语言检测由模型内部完成。

Model & Architecture¶

新模型类 VoxCPM2Model （model/voxcpm2.py）。既有 VoxCPMModel （model/voxcpm.py）不变，继续服务 1.0 / 1.5 检查点。
架构自动检测：通过 config.json 的 "architecture" 字段：
- "voxcpm2" → VoxCPM2Model
- "voxcpm" （或缺省）→ VoxCPMModel
参数量：2B（1.5 为 750M）。

残差 LM 融合：由加性改为拼接投影。新增 fusion_concat_proj 线性层（Linear(2h → h)）。

# 1.x
residual_input = lm_output + masked_audio_embed

# 2.0
residual_input = fusion_concat_proj(cat(lm_output, masked_audio_embed))

DiT 条件：单 token 相加 → 多 token 拼接。VoxCPMLocDiTV2 （modules/locdit/local_dit_v2.py）将拼接后的 LM + 残差投影重塑为多个前缀 token。
```
# 1.x DiT input
[ (mu + t) | cond | x ]       ← 1 conditioning token

# 2.0 DiT input
[ mu₁ | mu₂ | t | cond | x ]  ← 2 conditioning tokens + timestep
```
独立参考音频通道，特殊 token ref_audio_start_token = 103、ref_audio_end_token = 104。支持四种生成模式：zero-shot、continuation、reference-only、combined（参考 + 延续）。
默认配置变更：

字段

1.x

2.0

patch_size

2 / 4

4

residual_lm_num_layers

6

8

scalar_quantization_latent_dim

256

512

max_length

4096

8192
新配置项：residual_lm_no_rope （bool，默认 False）。
``dit_mean_mode`` 从根级 `` VoxCPMConfig`` （1.x）移至嵌套的 `` VoxCPMDitConfig`` （2.0）。

字段	1.x	2.0
`patch_size`	2 / 4	4
`residual_lm_num_layers`	6	8
`scalar_quantization_latent_dim`	256	512
`max_length`	4096	8192

AudioVAE V2¶

新模块 AudioVAEV2 （modules/audiovae/audio_vae_v2.py）。

属性	AudioVAE (v1)	AudioVAEV2
`decoder_dim`	1536	2048
`decoder_rates`	`[8, 8, 5, 2]`	`[8, 6, 5, 2, 2, 2]`
输出采样率	`sample_rate` （16 kHz / 44.1 kHz）	`out_sample_rate` （48 kHz 输出）
采样率条件化	No	Yes（`SampleRateConditionLayer`）

非对称编解码：编码端 16 kHz（640× 下采样，6.25 Hz token 率）→ 解码端 48 kHz（1920× 上采样）。

Python API (`core.py`)¶

VoxCPM.from_pretrained() 的 默认 Hub 模型 由 `` openbmb/VoxCPM1.5`` 改为 `` openbmb/VoxCPM2``。

``generate()`` 参数对照 （1.x 与 2.0）：

参数	1.x	2.0	说明
`text`	yes	yes	2.0 中在文本前加 `(instruction)` 用于 Voice Design / 风格控制
`prompt_wav_path`	yes	yes	延续式克隆（与 1.x 相同）
`prompt_text`	yes	yes	须与 `prompt_wav_path` 配对
`reference_wav_path`	no	new	独立音色克隆；在 1.x 模型上会抛出 `ValueError`
`cfg_value`	yes	yes
`inference_timesteps`	yes	yes
`normalize`	yes	yes
`denoise`	yes	yes	2.0：同时可对 `reference_wav_path` 降噪
`streaming`	yes	yes

四种生成模式 （仅 V2）—— 由传入的音频参数决定：

模式	`prompt_wav_path`	`reference_wav_path`	适用场景
Zero-shot	`None`	`None`	纯文本合成（或带 `(instruction)` 前缀的 Voice Design）
Continuation	set	`None`	自 prompt 音频无缝延续（与 1.x 相同）
Reference-only	`None`	set	仅凭参考片段做独立克隆
Combined	set	set	参考定音色 + prompt 定上下文（克隆相似度最佳）

# Reference-only cloning (V2 only)
wav = model.generate(
    text="Hello world.",
    reference_wav_path="speaker.wav",
)

# Voice Design (V2 only) — describe a voice in parentheses
wav = model.generate(
    text="(Warm female voice, mid-30s, calm tone) Welcome to VoxCPM 2.",
)

# Style Control (V2 only) — reference for timbre, instruction for style
wav = model.generate(
    text="(Whispering, mysterious) The secret lies in the ancient library.",
    reference_wav_path="speaker.wav",
)

内层模型的 ``sample_rate`` 属性 现返回 ** 输出** 采样率：V1 用 `` audio_vae.sample_rate`` （16 kHz / 44.1 kHz），V2 用 `` audio_vae.out_sample_rate`` （** 48 kHz**）。保存音频时请始终使用 `` model.tts_model.sample_rate``：
```
sf.write("output.wav", wav, model.tts_model.sample_rate)
```
参考音频 VAD 裁剪 （仅 V2）：VoxCPM2Model 中的 `` _trim_audio_silence_vad`` 基于 librosa 能量检测，自动裁掉参考音频尾部静音。
``build_prompt_cache`` 分发：
- V2：接受 prompt_text、prompt_wav_path、reference_wav_path。返回含 `` mode`` 的字典（"reference" / "continuation" / "ref_continuation"）。
- V1：仅接受 prompt_text、prompt_wav_path。无 mode 键。
VoxCPM 上的 LoRA 接口：load_lora()、unload_lora()、set_lora_enabled()、get_lora_state_dict()、lora_enabled 属性。
降噪器：denoise=True 时可对 prompt_wav_path 与 reference_wav_path 同时降噪。

CLI (`cli.py`)¶

全面重写 —— 以 VoxCPM2 为先的子命令设计。
新子命令：
- voxcpm design —— 文本转语音，可选 --control 指令。
- voxcpm clone —— 通过 --reference-audio 和/或 --prompt-audio + --prompt-text 克隆声音。
- voxcpm batch —— 从文本文件批处理。

新参数：

标志	说明
`--control`	音色设计 / 风格控制指令（前置为 `(control)text`）
`--reference-audio` / `-ra`	独立克隆用参考音频（仅 VoxCPM2）
`--prompt-file`	从文件加载 prompt 文本
`--denoise`	增强 prompt / 参考音频
`--no-optimize`	禁用 `torch.compile`
`--no-denoiser`	跳过加载降噪模型
`--zipenhancer-path`	自定义降噪模型路径
`--lora-path`	推理时 LoRA 权重
`--lora-r` / `--lora-alpha` / `--lora-dropout`	推理阶段 LoRA 配置覆盖
`--lora-disable-lm`	在 LM 层禁用 LoRA
`--lora-disable-dit`	在 DiT 层禁用 LoRA
`--lora-enable-proj`	在投影层启用 LoRA

默认 HF 模型：openbmb/VoxCPM2 （常量 DEFAULT_HF_MODEL_ID）。
架构检测 （detect_model_architecture）：读取本地 config.json 或从 HF id 推断。1.x 模型上拒绝 --reference-audio。
旧版根参数 （voxcpm --text ...）仍可用，但通过 warn_legacy_mode() 打印弃用警告。
控制指令拼接：build_final_text(text, control) 生成 "(control)text" —— VoxCPM 2 中 Voice Design 与风格控制的约定。

Controllable Generation¶

两项能力共用同一约定：在目标文本前的括号 () 内写自然语言指令。

Voice Design：无参考音频，由自然语言描述生成语音。文本用 (description) 前缀，或 CLI 使用 --control。

# CLI
voxcpm design \
  --text "Welcome to VoxCPM 2." \
  --control "Young female voice, warm and gentle" \
  --output out.wav

# Python — the control instruction is part of the text string
wav = model.generate(
    text="(Young female voice, warm and gentle) Welcome to VoxCPM 2.",
)

风格控制：参考音频决定谁在说，指令控制怎样说。

voxcpm clone \
  --text "The secret lies hidden in the ancient library." \
  --control "Speaking slowly with a whispering tone" \
  --reference-audio ref.wav \
  --output out.wav

Training Script¶

scripts/train_voxcpm_finetune.py 现可根据预训练检查点的 config.json 自动识别 VoxCPMModel 与 VoxCPM2Model。无需单独的 VoxCPM2 训练脚本。
新训练参数 grad_accum_steps —— 梯度累积，在不增加显存的情况下等效更大 batch。
验证改进：每个 valid_interval 向 TensorBoard 写入样本音频与 mel 频谱图。
信号处理：捕获 SIGTERM / SIGINT，退出前保存检查点。
DDP：配合 DistributedSampler.set_epoch() 手动管理 epoch，保证跨 epoch 洗牌正确。
检查点格式：
- LoRA：lora_weights.safetensors （或 .ckpt）、含 base_model 与 lora_config 字段的 lora_config.json。
- 全量 SFT：model.safetensors （或 pytorch_model.bin），外加复制的 config.json、audiovae.pth/audiovae.safetensors 与分词器文件。
- 二者均含：optimizer.pth、scheduler.pth、training_state.json。
- 每次保存都会更新 latest/ 目录，便于续训。
LoRA 分发标记：YAML 中 distribute: true + hf_model_id 会把 HF id（而非本地路径）写入 lora_config.json 的 base_model，便于分享。

LoRA¶

V2 LoRA 目标模块：target_proj_modules 现包含 fusion_concat_proj （另含 enc_to_lm_proj、lm_to_dit_proj、res_to_dit_proj）。
``LoRALinear`` 将 scaling 存为非持久 buffer，避免切换 LoRA 时触发 torch.compile 重编译。

`torch.compile` Optimization¶

``VoxCPMModel`` 与 ``VoxCPM2Model`` 均支持 optimize()：
- 以 mode="reduce-overhead"、fullgraph=True 编译 base_lm.forward_step、residual_lm.forward_step、feat_encoder、feat_decoder.estimator。
- 需要 CUDA + Triton；其他后端会静默跳过。
VoxCPM.__init__ / from_pretrained 默认 optimize=True。CLI 可用 --no-optimize 关闭。
模型加载后通过 warm-up 调用触发首次编译。

Dependencies (`pyproject.toml`)¶

gradio>=6,<7 （原为 gradio<6）。
torch>=2.5.0、torchaudio>=2.5.0 （最低版本上调）。
新增 torchcodec、safetensors、argbind。
开发依赖中移除 mypy。
包版本现由 setuptools_scm 按 git 标签管理，源码中无硬编码 __version__。
入口点：voxcpm = "voxcpm.cli:main"。

Demo App (`app.py`)¶

面向 VoxCPM 2 的全面重写：
- 默认模型 openbmb/VoxCPM2。
- 通过 control_instruction 字段支持 Voice Design + 风格控制。
- 参考音频 + 可选延续（Hi-Fi）路径。
- i18n（English / 中文）支持。
- Gradio 6 用法（theme/css 传给 launch()）。
原版 1.5 Demo 保留为 app_old.py。

VoxCPM 1.5.0 — December 5, 2025¶

Model & Architecture¶

AudioVAE 采样率：16 kHz → 44.1 kHz。保留更多高频细节，利于声音克隆。
LM token 率：12.5 Hz → 6.25 Hz （减半）。降低每秒音频的计算量。
Patch size：2 → ** 4** （LocEnc 与 LocDiT）。编解码处理更长 patch，需要更深的局部模块 → 总参数量略增（** 约 750M**）。
RTF：RTX 4090 上约 0.15（尽管模型更大，与 1.0 相当）。
config.json 中 architecture 取值："voxcpm" （与 1.0 同一代码路径）。
与 1.0 使用同一模型类 VoxCPMModel。1.0 → 1.5 的差异在检查点权重与配置值，并非单独 Python 类。

Fine-tuning¶

正式支持 SFT （全参微调）与 LoRA 微调。
新增训练脚本 scripts/train_voxcpm_finetune.py。
训练配置 conf/voxcpm_v1.5/：
- voxcpm_finetune_all.yaml —— 全量 SFT，`` sample_rate: 44100``，`` learning_rate: 1e-5``。
- voxcpm_finetune_lora.yaml —— LoRA，`` sample_rate: 44100``，`` learning_rate: 1e-4``，`` r: 8``，`` alpha: 16``。
新增 LoRA WebUI lora_ft_webui.py，浏览器内 LoRA 训练 / 推理。
推理测试脚本：
- scripts/test_voxcpm_ft_infer.py —— 全参微调检查点推理。
- scripts/test_voxcpm_lora_infer.py —— LoRA 检查点推理与热切换示例（load_lora / unload_lora / set_lora_enabled）。

Python 接口¶

VoxCPM.from_pretrained() 默认：openbmb/VoxCPM1.5。
新增流式 generate_streaming() API（返回音频块生成器）。

Stability Improvements¶

通过改进推理逻辑与清洗训练数据，减轻首尾伪音。
更低 token 率（6.25 Hz）提升长语音稳定性。

VoxCPM 1.0.0 — September 16, 2025¶

VoxCPM 首次公开发布。

Model¶

参数规模：600M（VoxCPM-0.5B）。
采样率：16 kHz（AudioVAE v1）。
LM token 率：12.5 Hz，patch size 2。
语言：中文与英文。

Python 接口¶

VoxCPM 类，提供 from_pretrained() / generate() 接口。
HF 模型 id：openbmb/VoxCPM-0.5B。
通过 prompt_wav_path + prompt_text 进行声音克隆（仅延续模式）。

Training Configs¶

conf/voxcpm_v1/voxcpm_finetune_all.yaml —— sample_rate: 16000。
conf/voxcpm_v1/voxcpm_finetune_lora.yaml —— sample_rate: 16000。

PyPI¶

包 voxcpm 已发布，标签自 1.0.0rc1 至 1.0.5。

Version Tags¶

版本由 git 标签经 setuptools_scm 管理，源码中无硬编码 __version__。

标签	日期	说明
`1.0.0rc1` – `1.0.0rc3`	2025-09-16	发布候选
`1.0.0`	2025-09-16	首次正式发布
`1.0.1`	2025-09-16	补丁
`1.0.2`	2025-09-17	补丁
`1.0.3`	2025-09-18	补丁
`1.0.4`	2025-09-22	补丁
`1.0.5`	2025-09-30	补丁（技术报告发布）
`1.5.0`	2025-12-05	VoxCPM 1.5

更新日志¶

VoxCPM 2.0 — 2026 年 3 月¶

30-Language Multilingual¶

Model & Architecture¶

AudioVAE V2¶

Python API (core.py)¶

CLI (cli.py)¶

Controllable Generation¶

Training Script¶

LoRA¶

torch.compile Optimization¶

Dependencies (pyproject.toml)¶

Demo App (app.py)¶

VoxCPM 1.5.0 — December 5, 2025¶

Model & Architecture¶

Fine-tuning¶

Python 接口¶

Stability Improvements¶

VoxCPM 1.0.0 — September 16, 2025¶

Model¶

Python 接口¶

Training Configs¶

PyPI¶

Version Tags¶

Python API (`core.py`)¶

CLI (`cli.py`)¶

`torch.compile` Optimization¶

Dependencies (`pyproject.toml`)¶

Demo App (`app.py`)¶