VoxCPM.cpp¶

VoxCPM.cpp 是基于 ggml 的 VoxCPM 独立 C++ 推理引擎，支持 GGUF 模型。

仓库：bluryar/VoxCPM.cpp
GGUF 权重：bluryar/VoxCPM-GGUF
上游：OpenBMB/VoxCPM

提供用于离线合成的 CLI（voxcpm_tts），以及支持流式输出的、兼容 OpenAI 的 HTTP 服务（`` voxcpm-server``）。

支持的 VoxCPM 版本¶
VoxCPM 1.0（0.5B）	✅ 支持
VoxCPM 1.5	✅ 支持
VoxCPM 2	❌ 不支持

可选多种量化格式：Q4_K、Q8_0、F16、F32。

主要特性¶

CLI 后端：CPU、** CUDA**、** Vulkan** （通过 --backend {cpu|cuda|vulkan|auto}）
GGUF 量化模型（Q4_K、Q8_0、F16、F32），可在速度与质量间灵活取舍
兼容 OpenAI 的 HTTP 服务，支持流式（音频 / SSE 模式）
通过 API 注册与管理音色
可选 Bearer token 认证（--api-key）
用于性能分析的基准脚本
实验性 WASM/Emscripten Web 试用环境（见仓库 docs/wasm_playground.md）

性能表现¶

在 NVIDIA RTX 4060 Ti（CUDA）与 Intel i5-12600K（CPU，8 线程）上测得，推理步数 = 10：

CUDA 推理（RTF，越小越好）¶
模型	量化	仅模型	不含 Encode	完整流水线
VoxCPM 1.5	Q8_0	0.320	0.411	0.596
VoxCPM 1.5	F16	0.352	0.442	0.648
VoxCPM-0.5B	F16	0.390	0.428	0.567

CPU 推理（RTF，越小越好）¶
模型	量化	仅模型	不含 Encode	完整流水线
VoxCPM 1.5	Q8_0	2.086	2.982	4.291
VoxCPM-0.5B	Q4_K	1.826	2.219	3.609

准备工作¶

CMake >= 3.14
支持 C++17 的 C++ 编译器
（可选）CUDA toolkit 用于 GPU 加速
（可选）Vulkan SDK 用于 Vulkan 后端

安装¶

从源码构建：

git clone https://github.com/bluryar/VoxCPM.cpp.git
cd VoxCPM.cpp

# CPU build
cmake -B build
cmake --build build

# CUDA build
cmake -B build-cuda -DVOXCPM_CUDA=ON \
    -DCMAKE_CUDA_ARCHITECTURES=89 \
    -DVOXCPM_BUILD_BENCHMARK=OFF \
    -DVOXCPM_BUILD_TESTS=OFF
cmake --build build-cuda

从 Hugging Face 下载 GGUF 权重：

# Example: download VoxCPM 1.5 Q8_0 with AudioVAE F16
huggingface-cli download bluryar/VoxCPM-GGUF \
    --include "voxcpm1.5-q8_0-audiovae-f16.gguf" \
    --local-dir models/

基本用法（命令行）¶

voxcpm_tts 可执行文件支持文本转语音与声音克隆：

# Basic TTS
./build/examples/voxcpm_tts \
    --model-path models/voxcpm1.5-q8_0-audiovae-f16.gguf \
    --backend auto \
    --threads 8 \
    --text "Hello, this is VoxCPM running in C++." \
    --output output.wav

# Voice cloning
./build/examples/voxcpm_tts \
    --model-path models/voxcpm1.5-q8_0-audiovae-f16.gguf \
    --backend auto \
    --prompt-audio ref_voice.wav \
    --prompt-text "Reference transcript" \
    --text "Cloned voice speaking new text." \
    --output output.wav \
    --inference-timesteps 10 \
    --cfg-value 2.0

HTTP 服务¶

voxcpm-server 提供兼容 OpenAI 的 /v1/audio/speech 端点：

./build/examples/voxcpm-server \
    --model-path models/voxcpm1.5-q8_0-audiovae-f16.gguf \
    --model-name voxcpm-1.5 \
    --voice-dir voices/ \
    --disable-auth \
    --host 0.0.0.0 --port 8080

注册音色并合成：

# Register a voice
curl -X POST http://localhost:8080/v1/voices \
    -F "id=my_voice" \
    -F "audio=@ref_voice.wav" \
    -F "text=Reference transcript"

# Synthesize with registered voice
curl http://localhost:8080/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{"model":"voxcpm-1.5","voice":"my_voice","input":"Hello world"}' \
    --output speech.wav

备注

上文示例使用 --disable-auth。若启用认证，请为所有请求添加 -H "Authorization: Bearer <your-key>"。

主要服务选项：

--api-key — 设置用于认证的 Bearer token
--disable-auth — 关闭 Bearer token 认证
--max-queue — 最大排队请求数（满时返回 503）
--model-name — API 请求中使用的模型标识

警告

该 HTTP 服务面向开发与测试。暴露到不可信网络前请使用 --api-key。

问题排查¶

构建后找不到可执行文件¶

构建产物位于 build/examples/，而非 `` build/bin/。CUDA 构建请查看 `` build-cuda/examples/。

模型加载报错¶

请确保向 --model-path 传入单个 .gguf 文件路径（而非目录）。