# cosyvoice3_yq_cpp

**Repository Path**: yang-qi1222/cosyvoice3_yq_cpp

## Basic Information

- **Project Name**: cosyvoice3_yq_cpp
- **Description**: 对cosyvoice3的大模型部分进行剪枝等优化，是一个自己学习的项目，参考cosyvoice.cpp进行流式播放，感谢大佬的分享，欢迎大家指正
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cosyvoice3_yq_cpp

`cosyvoice3_yq_cpp` 是一个面向部署的 CosyVoice3 C++/GGML 流式推理仓库。它在
[Lourdle/cosyvoice.cpp](https://github.com/Lourdle/cosyvoice.cpp) 基础上保留完整
CLI/server 能力，并加入本项目已验证的 resident CUDA streaming、请求级审计、
采样终止修复和边缘部署配置。

本仓库放推理源码和少量用于试听的公开样例音频。模型、ONNX 前端和
`prompt_speech.gguf` 参考特征通过 Hugging Face 分发：

- 源码：[Gitee / yang-qi1222/cosyvoice3_yq_cpp](https://gitee.com/yang-qi1222/cosyvoice3_yq_cpp)
- 模型：[Hugging Face / yang-qi1222/cosyvoice3_stream.cpp](https://huggingface.co/yang-qi1222/cosyvoice3_stream.cpp)

## 支持范围

- `cosyvoice-server`：OpenAI Speech 兼容 HTTP API，WAV/PCM 分块流式输出。
- `cosyvoice-cli`：直接使用已有 prompt 特征，或从参考音频执行 zero-shot 合成。
- 两种构建：不含 ONNX 的轻量 feature build；包含 speech tokenizer 和 CampPlus
  的 audio build。
- CPU 和 CUDA 后端；CUDA architecture 必须按目标 GPU 显式指定。
- 自然 EOS、首 token、首 PCM、chunk gap、RTF、RSS 和 GPU 显存审计。

不提供模型训练、剪枝或蒸馏代码。训练研究与 100 GB 以上实验资产不属于这个
inference-only 仓库。

## 推理路径

```text
已有参考特征：
model.gguf + prompt_speech.gguf -> resident server -> streaming WAV

参考音频：
reference.wav + transcript + frontend ONNX -> prompt_speech.gguf
                                                |
model.gguf -------------------------------------+-> resident server -> streaming WAV
```

生产使用建议先把参考音频编码为 `prompt_speech.gguf`，之后复用特征路径。这样能
避免每次请求加载和执行 ONNX frontend。

## 目录

```text
include/ src/ common/       C/C++ 推理核心
tools/cli/                  本地合成与 prompt 特征提取
tools/server/               resident 流式 API server
tools/stream-audit/         原生流式审计
scripts/                    下载、编译和两种输入路径
configs/                    已验收硬件配置
manifests/                  Hugging Face 资产清单示例
tests/                      发布卫生和工具测试
docs/                       资产、基准与发布说明
examples/audio_examples/    男/女参考音频、合成音频与文本（仅试听）
```

## 依赖

- Linux、Windows 或 macOS；本项目的正式性能数据来自 Linux。
- CMake `3.28+` 和支持 C++20 的编译器；有 Ninja 时构建脚本自动使用 Ninja，
  否则退回 CMake 默认生成器。
- Linux 推荐 GCC `14+`，或其他提供 C++20 `<format>` 的编译器与标准库；正式
  验证使用 GCC `14.3`。可通过 `CC=... CXX=... scripts/build_runtime.sh ...`
  选择工具链。
- CUDA build 需要可用的 NVIDIA driver、CUDA toolkit 和正确的 compute capability。
- audio build 需要 ONNX Runtime；CMake 会按上游规则解析依赖。
- Python 3.10+ 仅用于 HF 下载和发布测试。

安装下载工具：

```bash
python3 -m pip install -r requirements-tools.txt
```

## 下载模型资产

仓库已经提供指向正式 Hugging Face 资产并包含完整 SHA-256 的
[manifest](manifests/assets.example.json)，直接执行：

```bash
python3 scripts/download_assets.py \
  --manifest manifests/assets.example.json \
  --asset-root assets
```

资产目录规范和发布要求见 [docs/ASSETS.md](docs/ASSETS.md)。`assets/` 默认被 Git
忽略，下载器只有在 SHA 校验通过后才会替换目标文件。

## 路径 A：直接使用参考特征

CPU build：

```bash
scripts/build_runtime.sh \
  --mode feature \
  --backend cpu \
  --build-dir build/feature-cpu
```

RTX5880 Ada 的已验收 CUDA build 使用 architecture 89：

```bash
scripts/build_runtime.sh \
  --mode feature \
  --backend cuda \
  --cuda-arch 89 \
  --build-dir build/feature-cuda-sm89
```

其他 GPU 不要照抄 `89`。查询目标卡 compute capability 后重新编译并重跑质量与
资源门禁。

启动 resident server：

```bash
scripts/start_server.sh \
  --build-dir build/feature-cuda-sm89 \
  --backend cuda \
  --model assets/models/student12_mlp_inner_q8_flow4_hift_f16.gguf \
  --prompt-speech assets/prompts/control10_01.gguf \
  --voice control10_01 \
  --threads 16 \
  --chunk-tokens 75 \
  --flow-flash-attn 1 \
  --port 8080
```

请求流式 WAV：

```bash
curl --fail-with-body --no-buffer \
  -X POST http://127.0.0.1:8080/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/wav' \
  --data '{"model":"cosyvoice3-streaming","input":"你好，这是流式语音合成。","voice":"control10_01","response_format":"wav","stream":true,"chunk_tokens":75}' \
  --output output.wav
```

HTTP 200 只表示流已建立。成功请求还必须自然 EOS、连接正常结束并产生有限非空
PCM。

## 路径 B：选择参考音频

构建带 ONNX frontend 的版本：

```bash
scripts/build_runtime.sh \
  --mode audio \
  --backend cuda \
  --cuda-arch 89 \
  --build-dir build/audio-cuda-sm89
```

在离线环境或 CMake 找不到 ONNX Runtime C/C++ 开发包时，追加
`--ort-prebuilt-dir /path/to/onnxruntime`；目录中需要存在
`include/onnxruntime_c_api.h`。这个依赖与 Hugging Face 上的 speech tokenizer、
CampPlus 模型是两类不同文件。

一次性从参考音频合成：

```bash
scripts/synthesize_from_audio.sh \
  --build-dir build/audio-cuda-sm89 \
  --backend cuda \
  --model assets/models/student12_mlp_inner_q8_flow4_hift_f16.gguf \
  --speech-tokenizer assets/frontend/speech_tokenizer_v3.onnx \
  --campplus assets/frontend/campplus.onnx \
  --reference-audio reference.wav \
  --prompt-text '参考音频对应的准确文本' \
  --text '这是要合成的目标文本。' \
  --output output.wav \
  --flow-flash-attn 1
```

将音频预编码成可复用特征：

```bash
scripts/prepare_prompt.sh \
  --build-dir build/audio-cuda-sm89 \
  --speech-tokenizer assets/frontend/speech_tokenizer_v3.onnx \
  --campplus assets/frontend/campplus.onnx \
  --reference-audio reference.wav \
  --prompt-text '参考音频对应的准确文本' \
  --output assets/prompts/my_voice.gguf
```

生成后改用路径 A 启动服务。zero-shot 的参考转录应与音频内容一致，且参考音频应
尽量无混响、无背景音乐、单人说话。

## 已验收基线

正式 profile 仅覆盖 NVIDIA RTX5880 Ada：Student12 + Flow4 + HiFT、16 host
threads、串行、`chunk_tokens=75`、LLM FlashAttention off、Flow FlashAttention on。

- Control10 重复中位 RTF：`0.104273`
- 首 token：约 `9.1 ms`
- 首 PCM 中位：约 `223.2 ms`
- 自然 EOS：`10/10`
- Soak：`100/100`
- RSS：约 `1181 MiB`
- 设备级 GPU used memory：约 `2461 MiB`

详细口径、CPU 对照和失败边界见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md)。这些
数据不能外推到 RTX4060、AGX、其他 GPU、并发服务或长文本。

## 文字质量冒烟结果（Stage45）

下面是同一 Whisper-small 解码器、同一 5 男 5 女 Control10 文本的四路对照。
它用于定位问题，不是 WER100 正式质量门：当前样本只有 10 条，参考音频和目标
文本来自工程测试集，仍需人工复核 spoken reference、补齐中英混合集合，并固定
ASR 模型 SHA 后再作发布结论。中文集合以 CER 为主，表中 WER 只作为中文 token
化的辅助值。

| 路径 | CER micro | CER macro | 相对教师 Python（配对 macro） |
|---|---:|---:|---:|
| Teacher Python offline | `25.540%` | `26.494%` | 基线 |
| Student Python offline | `23.772%` | `25.073%` | `-1.421 pp` |
| Student C++ Flow6（历史构建） | `31.041%` | `32.937%` | `+6.442 pp` |
| Student C++ Flow4 CUDA（当前 resident） | `34.774%` | `36.702%` | `+10.208 pp` |

配对 bootstrap 的 95% 区间较宽（Flow4 约 `[-3.275, +23.230] pp`），因此不能
把这次冒烟结果写成“Flow4 已显著降低识别质量”。它能确认的工程事实是：当前
C++/Flow4 路径需要优先做同构复测和文本前端检查；不能用一次听感或 HTTP 200
替代自然 EOS、有限 WAV、Mel 和 ASR 质量门。详细失败记录、统计脚本和正式
WER100 计划见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md)。

## 试听样例

[examples/audio_examples/README.md](examples/audio_examples/README.md) 提供中文男声、
女声各两组：呼吸/停顿标签和情绪表达各一组。每组包含参考音频、当前 CUDA
Flow4 合成音频以及完整目标文本和指令；网页不支持内嵌播放时可直接下载 WAV。
样例来自本地 Emilia 50-speaker 合成数据，仅用于工程试听，不代表真实人物声音。
发布或克隆其他人的声音前必须确认授权。文件哈希见
[examples/audio_examples/SHA256SUMS](examples/audio_examples/SHA256SUMS)。

## 后续优化优先级

1. **WER/CER 正式门禁**：扩展到 WER100（50 男/50 女）和 Mixed20，中英文、数字、
   日期、单位、标点分别分组；固定 ASR 模型与 SHA，人工审核 spoken reference，
   使用配对 bootstrap 和预注册阈值（中文 CER +1.0 pp、英文/混合 WER +2.0 pp、
   任一类别 +3.0 pp）。
2. **中英混合与文本规范化**：统一 Unicode/繁简、英文大小写、数字日期单位读法和
   标点停顿；比较 CosyVoice frontend/tokenizer 与服务端直通文本，避免把前端差异
   误判成 Flow 或 C++ 回归。
3. **GPU 同构 A/B**：在同一 commit、模型、token 和音频 SHA 下复测 resident
   Flow6/Flow4，记录首 token、首 PCM、chunk gap、underrun、EOS、RTF、RSS、
   GPU used memory；当前正式最快路径仍以 Flow4 为候选，质量门未通过前不宣称
   全面优于 Flow6。
4. **Flow/HiFT 算子画像**：先定位 CUDA kernel、内存搬运和线程切分热点；已拒绝
   的 converted-RHS/packing 微调不重新打开。少步蒸馏必须以固定 token + Mel +
   听感门禁重新训练和验收，不能直接截断步数。
5. **端侧复测**：RTX4060、AGX（aarch64/CUDA）和 R6S（无 CUDA，需单独后端）
   必须按 compute capability、驱动、量化格式重新编译和验收，不能复制 RTX5880
   的 architecture 89 或 RTF。
6. **缓存与服务化**：只有长文本切分后仍证明 KV 是瓶颈，才评估 KV 量化/复用；
   短句 Stage44 约 19 MiB 的 KV 占比和复用收益不足以优先于 Flow profile。随后再
   评估 prompt 特征复用、流式并发和慢客户端 back-pressure。
7. **听感与安全**：固定 5 男/5 女、呼吸/停顿/情绪标签做盲听 ABX/MOS，记录音色、
   韵律、数字和标点错误；公开音频仅使用有授权或合成数据。

## 测试

```bash
python3 -m unittest discover -s tests -v
bash -n scripts/*.sh
```

发布前步骤见 [docs/RELEASING.md](docs/RELEASING.md)。上游完整使用文档保存在
[docs/upstream/README_zh.md](docs/upstream/README_zh.md)。

## 参考项目与论文

本项目建立在以下开源实现和研究工作之上：

- [Lourdle/cosyvoice.cpp](https://github.com/Lourdle/cosyvoice.cpp)：C++/GGML 推理
  实现基础。本仓库在其上完成面向本项目模型的流式服务、审计和部署验证。
- [QwenAudio/CosyVoice](https://github.com/QwenAudio/CosyVoice)：CosyVoice 官方训练、
  推理与模型定义。CosyVoice3 论文见
  [arXiv:2505.17589](https://arxiv.org/abs/2505.17589)。
- [SPADE: Structured Pruning and Adaptive Distillation for Efficient LLM-TTS](https://arxiv.org/abs/2509.20802)：
  本项目 Student LLM 的结构化剪枝和蒸馏流程参考了 SPADE 的研究思路；论文的
  [项目页面](https://mm.kaist.ac.kr/projects/SPADE/) 提供原作者实验与样例。本项目是
  面向 CosyVoice3 的独立工程实现，不是 SPADE 作者发布的官方模型或官方复现。

本项目的 RTF、首包延迟和资源占用均来自本仓库自己的 RTX5880 验收，不引用或
替代 SPADE 论文中的实验结果。

## 致谢

感谢以下项目及其维护者：

- [ggml](https://github.com/ggml-org/ggml) 与
  [llama.cpp](https://github.com/ggml-org/llama.cpp)：张量运行时、后端与 tokenizer
  实现参考。
- [ONNX Runtime](https://github.com/microsoft/onnxruntime)：参考音频前端模型执行。
- [miniaudio](https://github.com/mackron/miniaudio)、
  [PCRE2](https://github.com/PCRE2Project/pcre2)、
  [KissFFT](https://github.com/mborgerding/kissfft)、
  [cpp-httplib](https://github.com/yhirose/cpp-httplib) 和
  [nlohmann/json](https://github.com/nlohmann/json)：音频、文本、FFT、HTTP 与 JSON
  基础组件。

各组件的具体使用边界和许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## 引用

若在研究工作中使用本项目，请同时引用对应的 CosyVoice3 与 SPADE 原始论文：

```bibtex
@article{du2025cosyvoice3,
  title={CosyVoice 3: Towards In-the-wild Speech Generation via Scaling-up and Post-training},
  author={Du, Zhihao and Gao, Changfeng and Wang, Yuxuan and others},
  journal={arXiv preprint arXiv:2505.17589},
  year={2025}
}

@article{nguyen2025spade,
  title={SPADE: Structured Pruning and Adaptive Distillation for Efficient LLM-TTS},
  author={Nguyen, Tan Dat and Kim, Jaehun and Kim, Ji-Hoon and Choi, Shukjae and Lim, Youshin and Chung, Joon Son},
  journal={arXiv preprint arXiv:2509.20802},
  year={2025}
}
```

## 许可证与归属

代码沿用 MIT License。模型可能受不同许可证约束，使用和再分发前必须阅读
[MODEL_LICENSE.md](MODEL_LICENSE.md)。第三方组件见
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [FFmpeg-NOTICE.md](FFmpeg-NOTICE.md)。

本项目是社区 C++ 移植和工程优化，与 CosyVoice 官方团队无隶属关系，也不代表
官方背书。