Hugging Face's logo

bluryar
/
VoxCPM-GGUF

Text-to-Speech
GGUF
Model card Files
xet
 Community
VoxCPM-GGUF / README_zh.md
bluryar's picture
bluryar
Update README_zh.md
0e83de5 verified
preview code
|
Raw
History Blame Contribute Delete
9.68 kB

VoxCPM.cpp

License

基于 ggml 构建的 VoxCPM 模型独立 C++ 推理项目。

English

状态

此目录现作为 VoxCPM.cpp 独立仓库的根目录。

  • third_party/ggml 作为供应商子树维护。
  • third_party/json、third_party/llama.cpp、third_party/whisper.cpp 和 third_party/SenseVoice.cpp 仅作为本地参考，被仓库忽略。
  • CMakeLists.txt 已支持在 third_party/json 缺失时通过 FetchContent 下载 nlohmann_json。

构建

CPU 构建 

cmake -B build
cmake --build build

CUDA 构建

在配置阶段启用 ggml 的 CUDA backend：

cmake -B build-cuda -DVOXCPM_CUDA=ON
cmake --build build-cuda

如果你希望同时保留 CPU 和 CUDA 两套构建，建议使用不同的构建目录，例如 build 和 build-cuda。

推理用法

基础 CPU 推理 

./build/examples/voxcpm_tts \
  --model-path ./models/quantized/voxcpm1.5-q8_0-audiovae-f16.gguf \
  --prompt-audio ./examples/tai_yi_xian_ren.wav \
  --prompt-text "对，这就是我，万人敬仰的太乙真人。" \
  --text "大家好，我现在正在大可奇奇体验AI科技。" \
  --output ./out.wav \
  --backend cpu \
  --threads 8

带 Prompt 的推理 

./build/examples/voxcpm_tts \
  --model-path ./models/quantized/voxcpm1.5-q8_0-audiovae-f16.gguf \
  --prompt-audio ./examples/tai_yi_xian_ren.wav \
  --prompt-text "对，这就是我，万人敬仰的太乙真人。" \
  --text "大家好，我现在正在大可奇奇体验AI科技。" \
  --output ./out.wav \
  --backend cpu \
  --threads 8 \
  --inference-timesteps 10 \
  --cfg-value 2.0

CUDA 推理 

./build-cuda/examples/voxcpm_tts \
  --model-path ./models/quantized/voxcpm1.5-q8_0-audiovae-f16.gguf \
  --prompt-audio ./examples/tai_yi_xian_ren.wav \
  --prompt-text "对，这就是我，万人敬仰的太乙真人。" \
  --text "大家好，我现在正在大可奇奇体验AI科技。" \
  --output ./out.wav \
  --backend cuda \
  --threads 8 \
  --inference-timesteps 10 \
  --cfg-value 2.0

voxcpm_tts 当前支持 --backend {cpu|cuda|vulkan|auto}。

Benchmark 脚本

导出量化权重 

./scripts/export_quantized_weights.sh

这个脚本会导出：

  • Q4_K
  • Q8_0
  • F16
  • 对应的 +AudioVAE-F16 变体
  • F32 baseline 拷贝

并生成类似 logs/quantized_weights_manifest_*.tsv 的 manifest 文件。

对导出权重做 Benchmark

CPU：

./scripts/benchmark_exported_weights.sh \
  --weights-file ./logs/quantized_weights_manifest_*.tsv \
  --backend cpu

CUDA：

./scripts/benchmark_exported_weights.sh \
  --weights-file ./logs/quantized_weights_manifest_*.tsv \
  --backend cuda

如果不传 --weights-file，脚本会自动选取 logs/ 下最新的 manifest。

测试 

cd build
ctest --output-on-failure

测试模型/trace 路径配置和开源协作说明请见 docs/TEST_SETUP.md。

ggml 维护

项目保持当前 ggml 导入和补丁流程的本地溯源：

  • 上游：https://github.com/ggerganov/ggml.git
  • 仓库拆分前的本地基础提交：4773cde162a55f0d10a6a6d7c2ea4378e30e0b01
  • 当前本地补丁：src/ggml-vulkan/ggml-vulkan.cpp 中的 Vulkan 头文件兼容性调整

详见 docs/ggml_subtree_maintenance_strategy.md。

TODO

  1. 准备添加一个 WASM 用例，让用户可以直接在网页上试用 VoxCPM 模型。
  2. 继续优化推理性能。根据 https://github.com/DakeQQ/Text-to-Speech-TTS-ONNX 的报告，我们和它们当前展示的性能表现相比仍然有一段差距。
  3. 添加一个 voxcpm-server 程序，提供 OpenAI 格式的接口服务。

预告

接下来我也计划为 https://huggingface.co/fishaudio/s2-pro 单独创建一个 GGML 推理仓库。

基准测试

模型大小与压缩比

Model Quant Size (MB) Compression
voxcpm1.5 F32 3392 1.00x (基准)
voxcpm1.5 F16 1700 1.99x
voxcpm1.5 Q8_0 942 3.60x
voxcpm1.5 Q4_K 582 5.82x
voxcpm-0.5b F32 2779 1.00x (基准)
voxcpm-0.5b F16 1394 1.99x
voxcpm-0.5b Q8_0 766 3.62x
voxcpm-0.5b Q4_K 477 5.82x

CPU 推理性能 (RTF - 越低越好)

Model Quant Model Only Without Encode Full Pipeline
voxcpm1.5 Q4_K 2.395 3.395 5.598
voxcpm1.5 Q4_K+AudioVAE-F16 1.873 2.848 4.433
voxcpm1.5 Q8_0 2.086 2.982 4.291
voxcpm1.5 Q8_0+AudioVAE-F16 2.285 3.321 5.248
voxcpm1.5 F16 3.257 4.366 6.263
voxcpm1.5 F16+AudioVAE-F16 2.980 3.915 5.374
voxcpm1.5 F32 4.820 5.737 7.494
voxcpm-0.5b Q4_K 1.826 2.219 3.609
voxcpm-0.5b Q4_K+AudioVAE-F16 1.895 2.295 3.915
voxcpm-0.5b Q8_0 2.155 2.546 3.873
voxcpm-0.5b Q8_0+AudioVAE-F16 1.913 2.284 3.638
voxcpm-0.5b F16 2.558 2.931 4.086
voxcpm-0.5b F16+AudioVAE-F16 2.685 3.057 4.409
voxcpm-0.5b F32 3.691 4.055 5.260

CUDA 推理性能 (RTF - 越低越好)

Model Variant AudioVAE Model Only Without Encode Full Pipeline Total Time (s)
voxcpm1.5 Q4_K mixed 0.342 0.432 0.622 2.189
voxcpm1.5 Q4_K+AudioVAE-F16 f16 0.336 0.426 0.596 2.192
voxcpm1.5 Q8_0 mixed 0.320 0.411 0.596 2.002
voxcpm1.5 Q8_0+AudioVAE-F16 f16 0.308 0.397 0.559 2.148
voxcpm1.5 F16 mixed 0.352 0.442 0.648 1.970
voxcpm1.5 F16+AudioVAE-F16 f16 0.347 0.438 0.655 1.885
voxcpm1.5 F32 (baseline) original 0.414 0.503 0.686 2.305
voxcpm-0.5b Q4_K mixed 0.401 0.442 0.550 2.067
voxcpm-0.5b Q4_K+AudioVAE-F16 f16 0.396 0.437 0.555 1.953
voxcpm-0.5b Q8_0 mixed 0.430 0.470 0.623 1.644
voxcpm-0.5b Q8_0+AudioVAE-F16 f16 0.417 0.456 0.595 1.809
voxcpm-0.5b F16 mixed 0.390 0.428 0.567 1.678
voxcpm-0.5b F16+AudioVAE-F16 f16 0.392 0.430 0.565 1.718
voxcpm-0.5b F32 (baseline) original 0.500 0.539 0.680 1.903

RTF 定义：

  • Model Only：纯模型推理（prefill + decode loop），不含 AudioVAE
  • Without Encode：模型 + AudioVAE decode（离线预计算 prompt 特征的部署场景）
  • Full Pipeline：端到端完整流程，包含 AudioVAE encode + 模型 + decode

关键发现

CPU

  1. CPU 最优配置现在取决于模型和指标：voxcpm1.5 Q4_K+AudioVAE-F16 在 model-only 和 without-encode 指标上最好，voxcpm1.5 Q8_0 在完整流水线指标上最好，而 voxcpm-0.5b Q4_K 仍然是整体最稳妥的 CPU 选择。
  2. 1.5B 在 CPU 上明显受益于 AudioVAE-F16：Q4_K+AudioVAE-F16 在 voxcpm1.5 上拿到了最好的 Model Only 和 Without Encode RTF，而 Q8_0 拿到了最好的完整流水线 RTF。
  3. 0.5B 的 CPU 最优仍然是 Q4_K：voxcpm-0.5b Q4_K 的整体 CPU RTF 最好，Q8_0+AudioVAE-F16 在完整流水线指标上非常接近。
  4. 这台 CPU 上 F32 最慢：无论是 voxcpm1.5 还是 voxcpm-0.5b，F32 baseline 都是最慢的 CPU 配置。

CUDA

  1. CUDA 明显快于 CPU：在本轮测试中，完整流水线 RTF 从 CPU 的 3.83-15.02 下降到 CUDA 的 0.55-0.69。
  2. CUDA 下最佳配置取决于评价指标：对 voxcpm1.5，Q8_0+AudioVAE-F16 的 RTF 最好，而 F16+AudioVAE-F16 的总耗时最短；对 voxcpm-0.5b，Q4_K 的完整流水线 RTF 最好，而 Q8_0 的总耗时最短。
  3. CUDA 不再明显偏爱 Q4_K：和 CPU 不同，Q4_K 在 CUDA 上并不总是最快，Q8_0 和 F16 经常同样有竞争力，甚至更好。
  4. AudioVAE F16 在 CUDA 上有帮助：把 AudioVAE 强制导出为 F16 后，多组 CUDA 测试结果变好，尤其是 voxcpm1.5 Q8_0 和 voxcpm-0.5b Q8_0。

部署建议

场景 推荐配置
生产部署 voxcpm-0.5b Q4_K (477 MB, RTF 3.609)
平衡精度 voxcpm1.5 Q8_0 (942 MB, RTF 4.291)
1.5B 离线 prompt 场景 voxcpm1.5 Q4_K+AudioVAE-F16 (647 MB, Without Encode RTF 2.848)
最高精度基线 voxcpm1.5 F32 (3392 MB, RTF 7.494)

CUDA 部署建议

场景 推荐配置
最低完整流水线 RTF voxcpm-0.5b Q4_K (477 MB, RTF 0.550)
1.5B 最佳延迟/RTF 平衡 voxcpm1.5 Q8_0+AudioVAE-F16 (984 MB, RTF 0.559)
1.5B 较小且适合 CUDA 的模型 voxcpm1.5 Q4_K+AudioVAE-F16 (647 MB, RTF 0.596)
最高精度基线 voxcpm1.5 F32 (3392 MB, RTF 0.686)

CPU 测试环境：

  • CPU：12th Gen Intel(R) Core(TM) i5-12600K
  • 线程：8
  • 后端：CPU
  • 基准结果来源：logs/benchmark_summary_cpu_20260318_092142.txt

CUDA 测试环境：

  • 后端：CUDA
  • GPU：NVIDIA GeForce RTX 4060 Ti
  • CUDA 设备：CUDA0
  • Compute capability：8.9
  • CUDA VMM：yes
  • 主机 CPU：12th Gen Intel(R) Core(TM) i5-12600K
  • 线程：8
  • Inference timesteps：10
  • CFG value：2.0
  • 基准结果来源：logs/benchmark_summary_cuda_20260318_092028.txt