模型介绍
中文整理VoxCPM ONNX
Github Repo
VoxCPM ONNX 是对 OpenBMB/VoxCPM 开源模型的 ONNX 导出与推理扩展项目。支持将 VoxCPM 文本转语音模型导出为 ONNX 格式并提供高效的推理服务,支持 CPU 和 GPU 部署,提供 REST API 接口。
⚠️ **重要声明**
- 本项目代码与本文档完全由生成式AI驱动生成!
- 使用本项目需遵守VoxCPM以及相关方面的版权规定
- 当前导出代码因为将所有Decode步骤合并到一个模块中,不得不把固定求解欧拉方程的 timesteps 参数(默认为10,但经过测试timesteps=5也是可用的,并且解码速度可大大提升)
- 当前导出代码重复导出了两份VoxCPM的权重(Prefill和Decode)
项目背景
本项目基于 OpenBMB 团队的 VoxCPM 模型,该模型是一个无需分词器的文本转语音系统,具有以下特点:
- *上下文感知语音生成**: 能够理解文本内容并生成适当的韵律
- *真实声音克隆**: 仅需短参考音频即可实现零样本声音克隆
- *高效合成**: 支持流式合成,适用于实时应用场景
我们的扩展工作专注于 ONNX 导出和推理优化,使模型更易于部署和使用。
功能特性
原始 VoxCPM 模型能力
🎯 **无需分词器的 TTS**: 直接在连续空间中建模语音,克服离散分词限制
🗣️ **上下文感知语音生成**: 理解文本内容并生成适当的韵律和表达
🎭 **真实声音克隆**: 仅需短参考音频即可实现零样本声音克隆
⚡ **高效合成**: 支持流式合成,适用于实时应用场景
ONNX 扩展功能
🚀 **ONNX 导出**: 将 PyTorch 模型导出为 ONNX 格式
🔧 **模型优化**: 自动优化导出的 ONNX 模型
🐳 **容器化部署**: 支持 Docker Compose 一键部署
🎯 **REST API**: 提供 OpenAI 兼容的 TTS API
💻 **多平台支持**: 支持 CPU 和 GPU 推理
🎙️ **高质量语音**: 支持多种语音风格和参考音频
项目结构
快速开始
- 环境准备
系统要求
Python 3.10+
CUDA 11.8+ (GPU 版本)
Docker 和 Docker Compose (可选)
环境管理
本项目使用 uv 进行环境管理,确保依赖的一致性和可重现性。
使用 uv 创建开发环境:**
安装依赖:**
开发环境 (完整功能):**
CPU 推理环境:**
GPU 推理环境:**
- 获取预训练模型
从官方 VoxCPM 仓库下载预训练模型(VoxCPM-0.5B):
自动下载(推荐):**
手动下载:**
可选增强模型(用于语音增强和提示处理):**
- 导出 ONNX 模型
使用一键导出脚本将 PyTorch 模型导出为 ONNX 格式:
导出过程将生成以下模型文件:
audio vae encoder.onnx - 音频 VAE 编码器
audio vae decoder.onnx - 音频 VAE 解码器
voxcpm prefill.onnx - VoxCPM 预填充模型
voxcpm decode step.onnx - VoxCPM 解码步骤模型
- 优化 ONNX 模型
使用优化脚本对导出的模型进行进一步优化:
优化后的模型将保存在 onnx models processed/ 目录中。
- 启动服务
使用 Docker Compose (推荐)
GPU 版本:**
CPU 版本:**
服务启动后,API 将在以下地址可用:
主服务: http://localhost:8100
健康检查: http://localhost:8100/health
- *📚 交互式API文档**: http://localhost:8100/docs (Swagger UI界面,可在线测试所有接口)
手动启动
GPU 版本:**
CPU 版本:**
API 使用
可用端点
📚 API文档**: 部署Docker服务后,访问 http://:/docs 即可查看所有接口的交互式文档(Swagger UI)!
健康检查:**
GET /health - 检查服务状态和模型加载情况
参考音频管理:**
POST /ref feat - 上传参考音频并编码存储特征到数据库
文本转语音:**
POST /tts - TTS语音生成(POST方式,支持文件上传)
GET /tts - TTS语音生成(GET方式,仅URL参数)
接口详细说明
- 健康检查 (GET /health)
响应示例:**
- 上传参考音频 (POST /ref feat)
功能说明**: 上传参考音频文件,系统会提取音频特征并持久化存储到 SQLite 数据库中。上传后的参考音频可以通过 feat id 在后续的 TTS 请求中重复使用。
使用场景**:
创建个性化的语音克隆
保存特定说话人的声音特征
避免重复上传相同的参考音频
请求参数**:
feat id (必填): 参考音频的唯一标识符,后续通过此 ID 引用该音频
prompt audio (必填): 参考音频文件 (支持 WAV、MP3 等格式)
prompt text (可选): 参考音频对应的文本内容,有助于提高合成质量
使用示例**:
响应示例:**
持久化存储**: 上传的参考音频特征会永久保存在 SQLite 数据库中(路径由 VOX SQLITE PATH 环境变量配置),服务重启后仍然可用。
- 文本转语音 - POST方式
voice 参数作用说明**:
"default" : 使用系统默认的参考音频进行语音合成
自定义 feat id : 使用通过 /ref feat 上传的参考音频进行语音克隆
留空或不传: 不使用参考音频,仅基于文本进行基础合成
使用场景**:
- *默认声音**: 快速测试或基础语音合成
- *自定义声音**: 个性化语音克隆,复现已上传的说话人声音
- *声音切换**: 在同一服务中使用多个不同的说话人声音
请求示例**:
- 文本转语音 - GET方式
voice 参数说明**: 与 POST 方式相同,支持 "default" 、自定义 feat id 或留空。
使用示例**:
参数说明
通用参数:**
input (必填): 要转换的文本内容
voice : 参考音频ID,支持 "default" 或自定义ID
response format : 输出格式 (mp3, wav, opus, aac, flac, pcm),默认 mp3
speed : 语速 (占位符,暂不支持变速)
prompt text : 参考音频对应的文本内容
min len : 最小音频长度,默认 2
max len : 最大音频长度,默认 2000
cfg value : CFG系数,默认 2.0
完整工作流程示例
步骤 1: 上传参考音频(一次性操作)
步骤 2: 使用上传的参考音频进行语音合成
步骤 3: 验证参考音频是否可用
Python 客户端示例
基础TTS请求
上传参考音频
使用自定义参考音频进行TTS
环境变量配置
变量名 说明 默认值
- ------- ------ --------
VOX OUTPUT DIR 输出音频文件目录 ./outputs
VOX SQLITE PATH 参考特征数据库路径 ./ref feats.db
VOX DEVICE 推理设备 (cpu/cuda) cuda
VOX DEVICE ID GPU 设备 ID 0
VOX MODELS DIR ONNX 模型目录 ./models/onnx models quantized
VOX TOKENIZER DIR 分词器目录 ./models/onnx models quantized
VOX KEEP AUDIO FILES 是否保留生成的音频文件 false
PYTHONPATH Python 模块路径 ./src
高级配置
导出参数
在运行 export.sh 时,可以通过环境变量自定义以下参数:
变量名 说明 默认值
- ------- ------ --------
MODEL PATH 原始模型路径 ./VoxCPM-0.5B
OUTPUT DIR ONNX 模型输出目录 ./onnx models
OPSET VERSION ONNX 算子集版本 20
AUDIO LENGTH 音频长度 16000
LATENT LENGTH 潜变量长度 100
LATENT DIM 潜变量维度 64
TIMESTEPS 扩散步数 10
CFG VALUE CFG 系数 2.0
RTOL 验证相对容差 1e-3
ATOL 验证绝对容差 1e-4
NUM TESTS 验证测试次数 5
自定义参考音频
- 准备参考音频文件(WAV 格式,16kHz)
- 使用 infer.py 脚本提取特征:
技术说明与限制
当前实现限制
- **Timesteps 参数固定**: 由于将所有 Decode 步骤合并到一个 ONNX 模块中,求解欧拉方程的 timesteps 参数被固定。默认值为 10,但测试表明 timesteps=5 也可用,且能显著提升解码速度。
- **权重重复导出**: 当前导出代码会重复导出两份 VoxCPM 权重(Prefill 和 Decode),这会增加模型文件大小。
- **模型优化**: 建议使用 opt.sh 脚本对导出的模型进行优化,以减少模型大小并提升推理性能。
性能优化建议
- *调整 Timesteps**: 对于速度敏感的应用,可以尝试 timesteps=5 以提升性能
- *模型量化**: 使用 ONNX 量化工具进一步优化模型大小
- *批处理**: 对于批量推理场景,考虑使用动态批处理提升吞吐量
故障排除
常见问题
- ONNX 导出失败**
检查 PyTorch 和 ONNX 版本兼容性
确保模型文件完整且路径正确
验证 CUDA 驱动版本(GPU 版本)
- Docker 容器启动失败**
检查 NVIDIA Container Toolkit 安装(GPU 版本)
验证端口是否被占用
检查卷挂载路径是否正确
- 推理速度慢**
GPU 版本:检查 CUDA 和 cuDNN 版本
CPU 版本:尝试调整 OMP NUM THREADS 环境变量
确保模型已优化 ( opt.sh )
- 音频质量差**
检查输入文本质量
尝试不同的 cfg value 参数
验证参考音频质量(如使用参考音频)
性能优化
GPU 优化:**
CPU 优化:**
开发指南
与原始 VoxCPM 项目的关系
本项目是 VoxCPM 的 ONNX 导出和推理扩展,专注于:
将 PyTorch 模型导出为 ONNX 格式以提高部署效率
提供基于 ONNX Runtime 的高性能推理引擎
添加 REST API 服务接口
支持容器化部署
原始 VoxCPM 项目专注于模型训练和 PyTorch 推理,而本项目专注于生产环境的 ONNX 部署。
本地开发
- 克隆仓库
- 使用 uv 创建开发环境
- 安装开发依赖
- 运行测试
添加新功能
- 在 src/onnx infer/ 中添加新的推理模块
- 更新 src/server/app.py 中的 API 接口
- 添加相应的测试用例
- 更新文档
许可证与免责声明
版权说明
本项目基于原始 VoxCPM 模型的许可证
使用本项目需遵守 VoxCPM 以及相关方面的版权规定
请确保在使用前阅读并理解相关许可证条款
AI 生成声明
重要**: 本项目代码与本文档完全由生成式AI驱动生成!
使用限制
本项目仅供学习和研究用途
商业使用需获得相关授权
使用者需自行承担使用风险
致谢
VoxCPM 原始模型和团队
ONNX Runtime 项目
FastAPI 框架
支持
如遇到问题,请:
- 查看本 README 的故障排除部分
- 检查 GitHub Issues
- 提交新的 Issue 并提供详细信息
注意**: 本项目专注于 ONNX 推理部署,如需原始 PyTorch 模型训练,请参考 VoxCPM 官方仓库。
优先采用原作者提供的中文模型卡片;仅有英文说明时由闲社AI翻译整理。重要参数、许可证和商用范围请以原文为准。
你将获得什么
完整仓库方式包含该固定版本中的权重、配置、分词器及说明文件;指定版本方式只下载所选文件或整组分片。多模态模型的投影文件、配置等依赖,请按作者说明配齐。
完整仓库可能包含多个权重格式,因此需要的磁盘空间可能大于单一格式的模型大小。下载文件不等于完成模型部署。
使用前须知
运行模型需要的设备、工具与依赖,以原作者说明为准。
是否允许商用、修改和分发,请查看模型许可证。
闲社提供资料与镜像下载方法,不代表已运行模型或完成安全审计。下载的代码应先检查,再执行。
资料或下载有问题?
登录后可提交反馈。
