All systems operationalAI Agent Automation Platform
English
Language简体中文EnglishSelected

Choose your language

voxcpm-onnx

bluryar/voxcpm-onnx

Publisherbluryar

Download access requirementsModelScope source

VoxCPM ONNX 是对 OpenBMB/VoxCPM 开源模型的 ONNX 导出与推理扩展项目。支持将 VoxCPM 文本转语音模型导出为 ONNX 格式并提供高效的推理服务,支持 CPU 和 GPU 部署,提供 REST API 接口。 1. 本项目代码与本文档完全由生成式AI驱动生成! 2. 使用本项目需遵守VoxCPM以及相关方面的版权规定

Speech & Audio
Model details

模型介绍

中文整理

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 推理

🎙️ **高质量语音**: 支持多种语音风格和参考音频

项目结构

Quick start

  • 环境准备

系统要求

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 量化工具进一步优化模型大小
  • *批处理**: 对于批量推理场景,考虑使用动态批处理提升吞吐量

故障排除

Frequently Asked Questions

  • 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翻译整理。重要参数、许可证和商用范围请以原文为准。

你将获得什么

完整仓库方式包含该固定版本中的权重、配置、分词器及说明文件;指定版本方式只下载所选文件或整组分片。多模态模型的投影文件、配置等依赖,请按作者说明配齐。

完整仓库可能包含多个权重格式,因此需要的磁盘空间可能大于单一格式的模型大小。下载文件不等于完成模型部署。

使用前须知

运行环境

运行模型需要的设备、工具与依赖,以原作者说明为准。

授权范围

是否允许商用、修改和分发,请查看模型许可证。

闲社提供资料与镜像下载方法,不代表已运行模型或完成安全审计。下载的代码应先检查,再执行。

Back to top