Create README.md

README.md

@@ -0,0 +1,646 @@
+---
+base_model:
+- openbmb/VoxCPM-0.5B
+---
+# VoxCPM ONNX
+
+[Github Repo](https://github.com/bluryar/VoxCPM-ONNX)
+
+VoxCPM ONNX 是对 [OpenBMB/VoxCPM](https://github.com/OpenBMB/VoxCPM) 开源模型的 ONNX 导出与推理扩展项目。支持将 VoxCPM 文本转语音模型导出为 ONNX 格式并提供高效的推理服务，支持 CPU 和 GPU 部署，提供 REST API 接口。
+
+> ⚠️ **重要声明**
+> 1. 本项目代码与本文档完全由生成式AI驱动生成！
+> 2. 使用本项目需遵守VoxCPM以及相关方面的版权规定
+> 3. 当前导出代码因为将所有Decode步骤合并到一个模块中，不得不把固定求解欧拉方程的`timesteps`参数（默认为10，但经过测试timesteps=5也是可用的，并且解码速度可大大提升）
+> 4. 当前导出代码重复导出了两份VoxCPM的权重（Prefill和Decode）
+
+## 项目背景
+
+本项目基于 OpenBMB 团队的 VoxCPM 模型，该模型是一个无需分词器的文本转语音系统，具有以下特点：
+- **上下文感知语音生成**: 能够理解文本内容并生成适当的韵律
+- **真实声音克隆**: 仅需短参考音频即可实现零样本声音克隆
+- **高效合成**: 支持流式合成，适用于实时应用场景
+
+我们的扩展工作专注于 ONNX 导出和推理优化，使模型更易于部署和使用。
+
+## 功能特性
+
+### 原始 VoxCPM 模型能力
+- 🎯 **无需分词器的 TTS**: 直接在连续空间中建模语音，克服离散分词限制
+- 🗣️ **上下文感知语音生成**: 理解文本内容并生成适当的韵律和表达
+- 🎭 **真实声音克隆**: 仅需短参考音频即可实现零样本声音克隆
+- ⚡ **高效合成**: 支持流式合成，适用于实时应用场景
+
+### ONNX 扩展功能
+- 🚀 **ONNX 导出**: 将 PyTorch 模型导出为 ONNX 格式
+- 🔧 **模型优化**: 自动优化导出的 ONNX 模型
+- 🐳 **容器化部署**: 支持 Docker Compose 一键部署
+- 🎯 **REST API**: 提供 OpenAI 兼容的 TTS API
+- 💻 **多平台支持**: 支持 CPU 和 GPU 推理
+- 🎙️ **高质量语音**: 支持多种语音风格和参考音频
+
+## 项目结构
+
+```
+VoxCPM-ONNX/
+├── onnx/                    # ONNX 导出脚本
+│   ├── export_audio_vae_encoder.py
+│   ├── export_audio_vae_decoder.py
+│   ├── export_voxcpm_prefill.py
+│   └── export_voxcpm_decode.py
+├── src/
+│   ├── onnx_infer/          # ONNX 推理引擎
+│   └── server/              # FastAPI 服务
+├── export.sh               # ONNX 导出主脚本
+├── opt.sh                  # 模型优化脚本
+├── docker-compose.yml      # Docker 部署配置
+├── pyproject.toml          # 项目配置和依赖管理
+├── uv.lock                 # uv 依赖锁定文件
+└── infer.py               # 独立推理脚本
+```
+
+## 快速开始
+
+### 1. 环境准备
+
+#### 系统要求
+- Python 3.10+
+- CUDA 11.8+ (GPU 版本)
+- Docker 和 Docker Compose (可选)
+
+#### 环境管理
+
+本项目使用 [uv](https://docs.astral.sh/uv/) 进行环境管理，确保依赖的一致性和可重现性。
+
+**使用 uv 创建开发环境:**
+```bash
+# 克隆项目后，使用 uv 同步环境
+uv sync
+
+# 激活虚拟环境
+uv run bash
+# 或
+source .venv/bin/activate
+```
+
+**安装依赖:**
+
+**开发环境 (完整功能):**
+```bash
+uv pip install -e .
+# 或
+pip install -r pyproject.toml
+```
+
+**CPU 推理环境:**
+```bash
+uv pip install -r requirement.txt
+# 或
+pip install -r requirement.txt
+```
+
+**GPU 推理环境:**
+```bash
+uv pip install -r requirement-gpu.txt
+# 或
+pip install -r requirement-gpu.txt
+```
+
+### 2. 获取预训练模型
+
+从官方 VoxCPM 仓库下载预训练模型（VoxCPM-0.5B）：
+
+**自动下载（推荐）:**
+```python
+from huggingface_hub import snapshot_download
+snapshot_download("openbmb/VoxCPM-0.5B")
+```
+
+**手动下载:**
+```bash
+# 创建模型目录
+mkdir -p VoxCPM-0.5B
+
+# 下载模型文件到该目录
+# 访问 https://huggingface.co/openbmb/VoxCPM-0.5B 获取模型文件
+```
+
+**可选增强模型（用于语音增强和提示处理）:**
+```python
+from modelscope import snapshot_download
+snapshot_download('iic/speech_zipenhancer_ans_multiloss_16k_base')
+snapshot_download('iic/SenseVoiceSmall')
+```
+
+### 3. 导出 ONNX 模型
+
+使用一键导出脚本将 PyTorch 模型导出为 ONNX 格式：
+
+```bash
+# 基本用法
+bash export.sh
+
+# 自定义参数
+MODEL_PATH=./VoxCPM-0.5B OUTPUT_DIR=./onnx_models TIMESTEPS=10 CFG_VALUE=2.0 bash export.sh
+```
+
+导出过程将生成以下模型文件：
+- `audio_vae_encoder.onnx` - 音频 VAE 编码器
+- `audio_vae_decoder.onnx` - 音频 VAE 解码器  
+- `voxcpm_prefill.onnx` - VoxCPM 预填充模型
+- `voxcpm_decode_step.onnx` - VoxCPM 解码步骤模型
+
+### 4. 优化 ONNX 模型
+
+使用优化脚本对导出的模型进行进一步优化：
+
+```bash
+bash opt.sh
+```
+
+优化后的模型将保存在 `onnx_models_processed/` 目录中。
+
+### 5. 启动服务
+
+#### 使用 Docker Compose (推荐)
+
+**GPU 版本:**
+```bash
+# 确保已安装 NVIDIA Container Toolkit
+docker-compose up voxcpm-gpu
+```
+
+**CPU 版本:**
+```bash
+# 取消 docker-compose.yml 中 voxcpm-cpu 服务的注释
+docker-compose up voxcpm-cpu
+```
+
+服务启动后，API 将在以下地址可用：
+- 主服务: http://localhost:8100
+- 健康检查: http://localhost:8100/health
+- **📚 交互式API文档**: http://localhost:8100/docs (Swagger UI界面，可在线测试所有接口)
+
+#### 手动启动
+
+**GPU 版本:**
+```bash
+# 设置环境变量
+export VOX_OUTPUT_DIR=./outputs
+export VOX_SQLITE_PATH=./ref_feats.db
+export VOX_DEVICE=cuda
+export VOX_DEVICE_ID=0
+export VOX_MODELS_DIR=./models/onnx_models_quantized
+export VOX_TOKENIZER_DIR=./models/onnx_models_quantized
+export PYTHONPATH=./src
+
+# 启动服务
+python -m uvicorn src.server.app:app --host 0.0.0.0 --port 8000
+
+# 服务启动后访问
+# 📚 交互式API文档: http://localhost:8000/docs
+```
+
+**CPU 版本:**
+```bash
+# 设置环境变量
+export VOX_OUTPUT_DIR=./outputs
+export VOX_SQLITE_PATH=./ref_feats.db
+export VOX_DEVICE=cpu
+export VOX_DEVICE_ID=0
+export VOX_MODELS_DIR=./models/onnx_models_quantized
+export VOX_TOKENIZER_DIR=./models/onnx_models_quantized
+export PYTHONPATH=./src
+
+# 启动服务
+python -m uvicorn src.server.app:app --host 0.0.0.0 --port 8000
+```
+
+## API 使用
+
+### 可用端点
+
+**📚 API文档**: 部署Docker服务后，访问 `http://<HOST>:<PORT>/docs` 即可查看所有接口的交互式文档（Swagger UI）！
+
+**健康检查:**
+- `GET /health` - 检查服务状态和模型加载情况
+
+**参考音频管理:**
+- `POST /ref_feat` - 上传参考音频并编码存储特征到数据库
+
+**文本转语音:**
+- `POST /tts` - TTS语音生成（POST方式，支持文件上传）
+- `GET /tts` - TTS语音生成（GET方式，仅URL参数）
+
+### 接口详细说明
+
+#### 1. 健康检查 (GET /health)
+```bash
+curl http://localhost:8100/health
+```
+**响应示例:**
+```json
+{
+  "status": "ok",
+  "initialized": true,
+  "models_dir": "/root/code/VoxCPM/onnx_models",
+  "device_type": "cuda",
+  "device_id": 0
+}
+```
+
+#### 2. 上传参考音频 (POST /ref_feat)
+
+**功能说明**: 上传参考音频文件，系统会提取音频特征并持久化存储到 SQLite 数据库中。上传后的参考音频可以通过 `feat_id` 在后续的 TTS 请求中重复使用。
+
+**使用场景**: 
+- 创建个性化的语音克隆
+- 保存特定说话人的声音特征
+- 避免重复上传相同的参考音频
+
+**请求参数**:
+- `feat_id` (必填): 参考音频的唯一标识符，后续通过此 ID 引用该音频
+- `prompt_audio` (必填): 参考音频文件 (支持 WAV、MP3 等格式)
+- `prompt_text` (可选): 参考音频对应的文本内容，有助于提高合成质量
+
+**使用示例**:
+```bash
+curl -X POST http://localhost:8100/ref_feat \
+  -F "feat_id=my_voice" \
+  -F "prompt_audio=@reference.wav" \
+  -F "prompt_text=这是参考文本内容，可以帮助模型更好地理解声音特征"
+```
+
+**响应示例:**
+```json
+{
+  "feat_id": "my_voice",
+  "patches_shape": [1, 100, 64]
+}
+```
+
+**持久化存储**: 上传的参考音频特征会永久保存在 SQLite 数据库中（路径由 `VOX_SQLITE_PATH` 环境变量配置），服务重启后仍然可用。
+
+#### 3. 文本转语音 - POST方式
+
+**voice 参数作用说明**: 
+- `"default"`: 使用系统默认的参考音频进行语音合成
+- 自定义 `feat_id`: 使用通过 `/ref_feat` 上传的参考音频进行语音克隆
+- 留空或不传: 不使用参考音频，仅基于文本进行基础合成
+
+**使用场景**:
+- **默认声音**: 快速测试或基础语音合成
+- **自定义声音**: 个性化语音克隆，复现已上传的说话人声音
+- **声音切换**: 在同一服务中使用多个不同的说话人声音
+
+**请求示例**:
+```bash
+# 使用默认声音
+curl -X POST http://localhost:8100/tts \
+  -F "input=你好，这是一个测试文本。" \
+  -F "voice=default" \
+  -F "response_format=mp3"
+
+# 使用自定义参考声音（需要先通过 /ref_feat 上传）
+curl -X POST http://localhost:8100/tts \
+  -F "input=使用自定义声音合成这段文本。" \
+  -F "voice=my_custom_voice" \
+  -F "response_format=mp3"
+
+# 完整参数示例
+curl -X POST http://localhost:8100/tts \
+  -F "input=你好，这是一个测试文本。" \
+  -F "voice=my_voice" \
+  -F "response_format=mp3" \
+  -F "speed=1.0" \
+  -F "min_len=2" \
+  -F "max_len=2000" \
+  -F "cfg_value=2.0" \
+  --output output.mp3
+```
+
+#### 4. 文本转语音 - GET方式
+
+**voice 参数说明**: 与 POST 方式相同，支持 `"default"`、自定义 `feat_id` 或留空。
+
+**使用示例**:
+```bash
+# 使用默认声音
+curl "http://localhost:8100/tts?input=你好，世界！&voice=default&response_format=mp3" \
+  --output output.mp3
+
+# 使用自定义参考声音
+curl "http://localhost:8100/tts?input=使用自定义声音合成这段文本��&voice=my_custom_voice&response_format=wav" \
+  --output custom_output.wav
+
+# 不使用参考音频（基础合成）
+curl "http://localhost:8100/tts?input=基础语音合成测试&response_format=mp3" \
+  --output basic_output.mp3
+```
+
+### 参数说明
+
+**通用参数:**
+- `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: 上传参考音频（一次性操作）
+```python
+import requests
+
+# 上传参考音频文件
+with open("my_reference_audio.wav", "rb") as f:
+    files = {"prompt_audio": f}
+    data = {
+        "feat_id": "speaker_john",  # 自定义标识符
+        "prompt_text": "这是参考音频的文本内容"
+    }
+    response = requests.post("http://localhost:8100/ref_feat", files=files, data=data)
+
+if response.status_code == 200:
+    print(f"参考音频上传成功: {response.json()}")
+    # 输出: {'feat_id': 'speaker_john', 'patches_shape': [1, 100, 64]}
+else:
+    print(f"上传失败: {response.text}")
+```
+
+#### 步骤 2: 使用上传的参考音频进行语音合成
+```python
+import requests
+
+# 使用已上传的参考音频进行语音合成
+response = requests.post(
+    "http://localhost:8100/tts",
+    data={
+        "input": "使用约翰的声音合成这段文本。",
+        "voice": "speaker_john",  # 使用步骤1中上传的参考音频ID
+        "response_format": "mp3",
+        "cfg_value": 2.0
+    }
+)
+
+if response.status_code == 200:
+    with open("john_voice_output.mp3", "wb") as f:
+        f.write(response.content)
+    print("语音合成成功，文件已保存为 john_voice_output.mp3")
+else:
+    print(f"合成失败: {response.text}")
+```
+
+#### 步骤 3: 验证参考音频是否可用
+```python
+import requests
+
+# 检查服务状态和已上传的参考音频
+response = requests.get("http://localhost:8100/health")
+health_info = response.json()
+
+if health_info["initialized"]:
+    print("服务正常运行")
+    print(f"模型目录: {health_info['models_dir']}")
+    print(f"设备类型: {health_info['device_type']}")
+else:
+    print(f"服务未初始化: {health_info.get('error', '未知错误')}")
+```
+
+### Python 客户端示例
+
+#### 基础TTS请求
+```python
+import requests
+
+# GET方式简单请求
+response = requests.get(
+    "http://localhost:8100/tts",
+    params={
+        "input": "欢迎使用 VoxCPM ONNX 文本转语音服务。",
+        "voice": "default",
+        "response_format": "wav"
+    }
+)
+
+# 保存音频文件
+with open("output.wav", "wb") as f:
+    f.write(response.content)
+```
+
+#### 上传参考音频
+```python
+import requests
+
+# 上传参考音频
+with open("reference.wav", "rb") as f:
+    files = {"prompt_audio": f}
+    data = {
+        "feat_id": "my_custom_voice",
+        "prompt_text": "这是参考音频的文本内容"
+    }
+    response = requests.post("http://localhost:8100/ref_feat", files=files, data=data)
+
+print(response.json())
+```
+
+#### 使用自定义参考音频进行TTS
+```python
+import requests
+
+# 使用已上传的参考音频
+response = requests.post(
+    "http://localhost:8100/tts",
+    data={
+        "input": "使用自定义声音合成这段文本。",
+        "voice": "my_custom_voice",
+        "response_format": "mp3"
+    }
+)
+
+with open("custom_voice_output.mp3", "wb") as f:
+    f.write(response.content)
+```
+
+## 环境变量配置
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `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` |
+
+### 自定义参考音频
+
+1. 准备参考音频文件（WAV 格式，16kHz）
+2. 使用 `infer.py` 脚本提取特征：
+
+```bash
+python infer.py \
+  --model_dir ./models/onnx_models_quantized \
+  --ref_audio ./reference.wav \
+  --ref_text "参考文本内容" \
+  --feat_id custom_voice
+```
+
+## 技术说明与限制
+
+### 当前实现限制
+
+1. **Timesteps 参数固定**: 由于将所有 Decode 步骤合并到一个 ONNX 模块中，求解欧拉方程的 `timesteps` 参数被固定。默认值为 10，但测试表明 timesteps=5 也可用，且能显著提升解码速度。
+
+2. **权重重复导出**: 当前导出代码会重复导出两份 VoxCPM 权重（Prefill 和 Decode），这会增加模型文件大小。
+
+3. **模型优化**: 建议使用 `opt.sh` 脚本对导出的模型进行优化，以减少模型大小并提升推理性能。
+
+### 性能优化建议
+
+- **调整 Timesteps**: 对于速度敏感的应用，可以尝试 timesteps=5 以提升性能
+- **模型量化**: 使用 ONNX 量化工具进一步优化模型大小
+- **批处理**: 对于批量推理场景，考虑使用动态批处理提升吞吐量
+
+## 故障排除
+
+### 常见问题
+
+**1. ONNX 导出失败**
+- 检查 PyTorch 和 ONNX 版本兼容性
+- 确保模型文件完整且路径正确
+- 验证 CUDA 驱动版本（GPU 版本）
+
+**2. Docker 容器启动失败**
+- 检查 NVIDIA Container Toolkit 安装（GPU 版本）
+- 验证端口是否被占用
+- 检查卷挂载路径是否正确
+
+**3. 推理速度慢**
+- GPU 版本：检查 CUDA 和 cuDNN 版本
+- CPU 版本：尝试调整 `OMP_NUM_THREADS` 环境变量
+- 确保模型已优化 (`opt.sh`)
+
+**4. 音频质量差**
+- 检查输入文本质量
+- 尝试不同的 `cfg_value` 参数
+- 验证参考音频质量（如使用参考音频）
+
+### 性能优化
+
+**GPU 优化:**
+```bash
+export CUDA_VISIBLE_DEVICES=0
+export OMP_NUM_THREADS=4
+export ONNXRUNTIME_SESSION_OPTIONS_INTRA_OP_NUM_THREADS=4
+```
+
+**CPU 优化:**
+```bash
+export OMP_NUM_THREADS=$(nproc)
+export ONNXRUNTIME_SESSION_OPTIONS_INTRA_OP_NUM_THREADS=$(nproc)
+```
+
+## 开发指南
+
+### 与原始 VoxCPM 项目的关系
+
+本项目是 VoxCPM 的 ONNX 导出和推理扩展，专注于：
+- 将 PyTorch 模型导出为 ONNX 格式以提高部署效率
+- 提供基于 ONNX Runtime 的高性能推理引擎
+- 添加 REST API 服务接口
+- 支持容器化部署
+
+原始 VoxCPM 项目专注于模型训练和 PyTorch 推理，而本项目专注于生产环境的 ONNX 部署。
+
+### 本地开发
+
+1. 克隆仓库
+2. 使用 uv 创建开发环境
+3. 安装开发依赖
+4. 运行测试
+
+```bash
+# 使用 uv 创建开发环境
+uv sync
+
+# 激活虚拟环境
+uv run bash
+# 或
+source .venv/bin/activate
+
+# 安装开发依赖
+uv pip install -e .
+
+# 运行测试
+pytest tests/
+
+# 代码格式化
+black src/
+isort src/
+```
+
+### 添加新功能
+
+1. 在 `src/onnx_infer/` 中添加新的推理模块
+2. 更新 `src/server/app.py` 中的 API 接口
+3. 添加相应的测试用例
+4. 更新文档
+
+## 许可证与免责声明
+
+### 版权说明
+- 本项目基于原始 VoxCPM 模型的许可证
+- 使用本项目需遵守 VoxCPM 以及相关方面的版权规定
+- 请确保在使用前阅读并理解相关许可证条款
+
+### AI 生成声明
+**重要**: 本项目代码与本文档完全由生成式AI驱动生成！
+
+### 使用限制
+- 本项目仅供学习和研究用途
+- 商业使用需获得相关授权
+- 使用者需自行承担使用风险
+
+## 致谢
+
+- VoxCPM 原始模型和团队
+- ONNX Runtime 项目
+- FastAPI 框架
+
+## 支持
+
+如遇到问题，请：
+1. 查看本 README 的故障排除部分
+2. 检查 GitHub Issues
+3. 提交新的 Issue 并提供详细信息
+
+---
+
+**注意**: 本项目专注于 ONNX 推理部署，如需原始 PyTorch 模型训练，请参考 VoxCPM 官方仓库。