VoxCPM2 语音生成 — 最简推理项目

从 OpenBMB/VoxCPM 抽出的 VoxCPM2 最简推理子项目，只保留运行 Gradio 界面所需的代码。

模型下载

运行前需先下载以下模型文件到 models/ 目录：

1. VoxCPM2 主模型（必选）

首次启动后会自动从 ModelScope 下载 OpenBMB/VoxCPM2，也可以直接手动下载并放入 models/VoxCPM2/ 目录，结构如下：

models/VoxCPM2/
├── config.json
├── model.safetensors          # 或 pytorch_model.bin
├── audiovae.safetensors       # 或 audiovae.pth
├── tokenizer.json
└── ...（其他 tokenizer 相关文件）

2. ASR 模型（可选 — 极致克隆模式需要）

首次使用极致克隆模式时会自动下载。也可以直接手动从 ModelScope 下载 iic/SenseVoiceSmall，放入 models/SenseVoiceSmall/。

3. 降噪模型（可选 — 参考音频降噪增强需要）

首次使用参考音频降噪增强功能时会自动下载。也可以直接手动从ModelScope下载iic/speech_zipenhancer_ans_multiloss_16k_base，放入 models/ZipEnhancer/。

快速启动

# 1. 创建 Python 环境（推荐使用 Conda）
conda create -n voxcpm python=3.11 -y

# 2. 激活环境
conda activate voxcpm

# 3. 安装项目
pip install -e .

# 4. 启动
python app.py

启动后打开浏览器访问 http://localhost:8808。启动时会预加载 VoxCPM2 和 ASR 模型，加载完成后才能使用。

命令行参数

python app.py --port 8808 --device cuda --model-dir models/VoxCPM2

参数	默认值	说明
--port	8808	服务端口号
--device	auto	运行设备：auto / cpu / cuda / cuda:0
--model-dir	models/VoxCPM2	VoxCPM2 模型目录
--asr-model-dir	models/SenseVoiceSmall	ASR 模型目录
--denoiser-model-dir	models/ZipEnhancer	降噪模型目录

使用说明

三种生成模式

🎨 声音设计（Voice Design） 无需参考音频。在"控制指令"中描述目标音色特征（性别、年龄、语气、情绪、语速等），VoxCPM2 即可从零为你创造独特的声音。

🎛️ 可控克隆（Controllable Cloning） 上传参考音频，同时可选地使用"控制指令"来指定情绪、语速、风格等表达方式，在保留原始音色的基础上灵活控制说话风格。

🎙️ 极致克隆（Ultimate Cloning） 开启"极致克隆模式"并提供参考音频（系统会自动识别文字内容）。模型会将参考音频视为已说出的前文，以音频续写的方式完整还原参考音频中的声音细节。此模式将禁用控制指令。

控制指令（Control Instruction）

支持中英文描述，用于控制声音特征。中英文示例：

• 年轻女性，温柔甜美，语速缓慢，略带忧郁 — 温柔的少女音
• 暴躁的中年男声，语速快，充满愤怒 — 暴躁老哥
• A warm young woman with a soft, sweet voice — 温暖的女声
• Relaxed male voice, lazy drawl, casual and chill — 慵懒的男声

方言生成提示： 要生成地道的方言语音，请在"目标文本"中直接使用方言词汇，并在"控制指令"中描述方言特征。例如：

• 粤语：控制指令写 粤语，中年男性，语气平淡，目标文本写 伙記，唔該一個A餐，凍奶茶少甜！
• 河南话：控制指令写 河南话，接地气的大叔，目标文本写 恁这是弄啥嘞？晌午吃啥饭？

高级设置

设置项	默认值	说明
CFG 引导强度	2.0	越高越贴合提示/参考音色，越低生成风格越自由
LocDiT 迭代步数	10	步数越多可能生成质量更好，但速度变慢
参考音频降噪增强	关闭	克隆前对参考音频进行降噪处理
文本规范化	关闭	自动规范化数字、日期及缩写（基于 wetext）

项目结构

├── app.py                  # Gradio 界面入口（中文版）
├── pyproject.toml          # 项目配置
├── README.md
├── models/                 # 模型文件目录
│   ├── VoxCPM2/            #   VoxCPM2 主模型
│   ├── SenseVoiceSmall/    #   ASR 模型（极致克隆用）
│   └── ZipEnhancer/        #   降噪模型
└── src/                    # 源代码（voxcpm 包）
    ├── __init__.py          #   导出 VoxCPM
    ├── core.py              #   VoxCPM 核心类
    ├── zipenhancer.py       #   音频降噪增强
    ├── model/
    │   ├── voxcpm2.py       #   VoxCPM2 模型（MiniCPM4 + LocDiT + AudioVAE）
    │   └── utils.py         #   工具函数
    ├── modules/
    │   ├── minicpm4/        #   MiniCPM4 语言模型
    │   ├── locenc/          #   局部编码器
    │   ├── locdit/          #   局部扩散变压器
    │   ├── audiovae/        #   音频 VAE 编解码器
    │   └── layers/          #   标量量化层
    └── utils/
        └── text_normalize.py # 文本规范化

依赖环境

• Python 3.10 ~ 3.12
• PyTorch >= 2.5.0（推荐 CUDA 版本）
• 详见 pyproject.toml 中的 dependencies

许可

本项目代码基于 OpenBMB/VoxCPM 提取和精简，遵循原项目的 Apache 2.0 许可。

src/utils/text_normalize.py 中的部分函数改编自 FunAudioLLM/CosyVoice，同样基于 Apache 2.0 许可。