CosyVoice3 ONNX 模型

为 Fun-CosyVoice3-0.5B 导出的 ONNX 模型，支持无 PyTorch 推理。

模型描述

CosyVoice3 是一个具有零样本语音克隆能力的多语言文本转语音（TTS）系统。本仓库包含经过 ONNX 转换的模型，可使用纯 ONNX Runtime 进行推理，无需 PyTorch 依赖。

支持的语言

CosyVoice3 会自动从文本内容检测语言。支持的语言包括：

• 英语、中文、日语、韩语
• 德语、西班牙语、法语、意大利语、俄语
• 粤语和其他中文方言

重要提示：不要使用 <|en|> 或 <|ja|> 等语言标签 - 它们会被作为字面文本朗读出来。

仓库内容

本仓库包含推理所需的所有内容（无需额外下载）：

.
├── *.onnx                              # ONNX 模型文件（14个文件，总计约3.8GB）
├── vocab.json                          # Qwen2 分词器词表
├── merges.txt                          # Qwen2 分词器合并文件
├── tokenizer_config.json               # Qwen2 分词器配置
├── scripts/
│   └── onnx_inference_pure.py          # 推理脚本
└── prompts/
    ├── en_female_nova_greeting.wav     # 示例女声
    └── en_male_onyx_greeting.wav       # 示例男声

模型文件

ONNX 模型（本仓库）

分词器文件（已包含）

Qwen2 分词器文件已包含在本仓库中：

• vocab.json - 词表（3.54MB）
• merges.txt - BPE 合并文件（1.54MB）
• tokenizer_config.json - 配置

无需额外下载。

架构

1. 提示音频处理
   ├── campplus.onnx → 说话人嵌入（192维）
   ├── speech_tokenizer_v3.onnx → 语音 token（用于 LLM 上下文）
   └── librosa → Mel 频谱图（用于 Flow 条件）

2. LLM 推理（零样本模式）
   ├── text_embedding → [提示文本 + TTS 文本] 嵌入
   ├── llm_speech_embedding → 提示语音 token 嵌入
   ├── llm_backbone_initial → 初始传递（KV 缓存）
   ├── llm_backbone_decode → 解码步骤（循环）
   └── llm_decoder → Logits → Token 采样

3. Flow 推理（Mel 生成）
   ├── flow_token_embedding → Token 嵌入
   ├── flow_pre_lookahead → 特征提取
   ├── flow_speaker_projection → 说话人投影
   └── flow.decoder.estimator → DiT（10步 Euler）

4. HiFT 推理（波形）
   ├── hift_f0_predictor → F0 预测
   ├── hift_source_generator → 源信号
   ├── STFT → 频谱分解
   ├── hift_decoder → 幅度/相位预测
   └── ISTFT → 波形重建

快速开始

1. 创建环境

uv init cosyvoice-onnx --python 3.10
cd cosyvoice-onnx
uv add \"onnxruntime==1.18.0\" \"numpy==1.26.4\" \"soundfile==0.12.1\" \"librosa==0.10.2\" \"transformers==4.51.3\" \"scipy==1.13.1\" \"huggingface_hub>=0.30.0\"

注意：需要使用 --python 3.10 标志，因为 onnxruntime 1.18.0 仅支持 Python 3.8-3.12。

2. 下载模型

# 下载所有内容（ONNX 模型 + 分词器 + 推理脚本 + 示例提示）
uv run python -c \"from huggingface_hub import snapshot_download; snapshot_download('ayousanz/cosy-voice3-onnx', local_dir='pretrained_models/Fun-CosyVoice3-0.5B/onnx')\"

注意：所有必需的文件（包括 Qwen2 分词器）都已包含在本仓库中。无需额外下载。

3. 运行推理

# 英语
uv run python pretrained_models/Fun-CosyVoice3-0.5B/onnx/scripts/onnx_inference_pure.py \
    --text \"Hello, this is a test.\" \
    --prompt_wav pretrained_models/Fun-CosyVoice3-0.5B/onnx/prompts/en_female_nova_greeting.wav \
    --prompt_text \"Hello, my name is Sarah. I'm excited to help you with your project today. Let me know if you have any questions.\" \
    --output output.wav

# 日语
uv run python pretrained_models/Fun-CosyVoice3-0.5B/onnx/scripts/onnx_inference_pure.py \
    --text \"こんにちは、今日はいい天気ですね。\" \
    --prompt_wav pretrained_models/Fun-CosyVoice3-0.5B/onnx/prompts/en_female_nova_greeting.wav \
    --prompt_text \"Hello, my name is Sarah. I'm excited to help you with your project today. Let me know if you have any questions.\" \
    --output output_ja.wav

详细设置

版本要求

重要：原始 CosyVoice（PyTorch 版本）也有相同的版本约束。这不是 ONNX 推理特有的。

GPU 支持（可选）

uv remove onnxruntime && uv add \"onnxruntime-gpu==1.18.0\"

注意：需要 CUDA 11.8 或 12.x 以及 cuDNN 8.x。

命令行参数

重要：零样本语音克隆

CosyVoice3 使用零样本语音克隆。提示音频和提示文本都是必需的：

• 提示音频：参考语音样本（建议 3-10 秒）
• 提示文本：提示音频中说话内容的转录文本

这比跨语言模式提供更好的语音克隆质量。

性能

注意：CPU-only 推理。GPU（CUDA）可显著提升性能。

技术说明

纯 ONNX 推理（无 PyTorch）

此推理脚本完全不依赖 PyTorch 运行。所有处理都使用 ONNX Runtime 和 NumPy/SciPy 实现：

• 神经网络推理：ONNX Runtime
• STFT/ISTFT：NumPy + SciPy（非 PyTorch）
• 音频处理：librosa

HiFT 参数（CosyVoice3 特定）

注意：CosyVoice2 使用 upsample_rates=[8, 8]（64 倍），但 CosyVoice3 使用 [8, 5, 3]（120 倍）。

预期 STFT 帧数 = mel 帧数 × 120 + 1

精度选择

• FP16：LLM 和 Flow 组件（节省内存）
• FP32：HiFT 组件（需要数值稳定性）、文本嵌入、说话人模型

KV 缓存

LLM 使用分离的 KV 缓存架构：

• llm_backbone_initial：从完整上下文生成初始 KV 缓存
• llm_backbone_decode：每步用单个 token 更新 KV 缓存

故障排除

ONNX Runtime 版本错误与 FP16 模型

RuntimeException: Attempting to get index by a name which does not exist

解决方案：使用 onnxruntime==1.18.0。较新版本（1.19+）与 FP16 模型存在兼容性问题。

NumPy 2.x 不兼容

A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x

解决方案：使用 numpy==1.26.4。这是与原始 CosyVoice 共有的约束。

分词器加载问题

如果遇到分词器加载错误，请确保下载了完整的仓库，包括：

• vocab.json
• merges.txt
• tokenizer_config.json

使用以下命令重新下载：

huggingface-cli download ayousanz/cosy-voice3-onnx --local-dir pretrained_models/Fun-CosyVoice3-0.5B/onnx

语言标签被朗读

如果您听到 <|en|> 或类似内容被读出来，请从文本中移除语言标签。CosyVoice3 会自动检测语言。

许可证

Apache 2.0（与原始 CosyVoice 相同）

致谢

• 原始模型：FunAudioLLM/Fun-CosyVoice3-0.5B-2512
• CosyVoice 仓库：FunAudioLLM/CosyVoice

相关链接

• CosyVoice GitHub
• ModelScope 模型
• 论文：CosyVoice