VoxCPM2

VoxCPM 语音系列

按应用内集成、批量生成、在线服务或端侧运行的需要，选择适合的部署方式。这里收录 Python SDK、CLI、Web Demo，以及 Nano-vLLM-VoxCPM、vLLM-Omni 和 llama.cpp-omni 等生态入口；各后端的支持范围与运行条件请分别核对。

VoxCPM2 的部署路径分为 OpenBMB 核心仓库提供的 Python SDK、CLI 与 Web Demo，以及独立维护的生态推理后端。选择后端前先明确目标：应用内集成、离线批处理、高吞吐 API 或无 Python 端侧运行。

部署路径

路径	维护与定位	适用场景	接口
Python SDK / CLI	OpenBMB/VoxCPM 核心仓库	本地集成、脚本、离线批处理	Python / CLI
Web Demo	OpenBMB/VoxCPM 核心仓库	内部试听、参数验证	Gradio
Nano-vLLM-VoxCPM	社区独立项目，列入官方生态	NVIDIA GPU 高吞吐与异步请求	Python；项目提供 FastAPI 服务
vLLM-Omni	vLLM 官方全模态扩展	OpenAI 兼容、多租户与批量并发	/v1/audio/speech
llama.cpp-omni	社区独立项目，列入官方生态	CPU、Metal、CUDA、Vulkan 端侧运行	C++ CLI，GGUF

生态项目的安装命令、模型格式和兼容版本由各项目维护。生产部署前应固定 commit、权重校验值和镜像依赖，并在目标硬件上回归；不要只依赖本文的参考命令。

Python SDK 集成

Bash

pip install voxcpm soundfile

Python

from pathlib import Path
from voxcpm import VoxCPM
import soundfile as sf

model = VoxCPM.from_pretrained(
    "openbmb/VoxCPM2",
    load_denoiser=False,
)

def synthesize(text: str, output_path: str) -> str:
    wav = model.generate(
        text=text,
        cfg_value=2.0,
        inference_timesteps=10,
    )
    sf.write(output_path, wav, model.tts_model.sample_rate)
    return str(Path(output_path).resolve())

服务进程应在启动时加载一次模型，不要在每个请求内重复调用 from_pretrained。并发、请求排队、超时、音频缓存与输出文件生命周期需由应用层处理。

Web Demo

Bash

git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
pip install -e .
python app.py --port 8808 --device auto

--device 支持 auto、cpu、mps、cuda 和 cuda:N。Web Demo 还会下载 SenseVoice-Small 用于提示音频转写。该入口适合体验和内部验证，不等同于具备鉴权、限流与监控的生产服务。

Nano-vLLM-VoxCPM

Bash

pip install nano-vllm-voxcpm

Python

from nanovllm_voxcpm import VoxCPM
import numpy as np
import soundfile as sf

server = VoxCPM.from_pretrained(
    model="/path/to/VoxCPM2",
    devices=[0],
)
chunks = list(server.generate(target_text="你好，我来自 VoxCPM2。"))
sf.write("out.wav", np.concatenate(chunks), 48000)
server.stop()

官方 README 引用的 RTX 4090 参考 RTF 约为 0.13，标准 PyTorch 路径约为 0.30。该数字是特定硬件和实现下的参考值，不代表你的文本长度、并发和参数设置。

vLLM-Omni

Bash

uv pip install vllm==0.19.0 --torch-backend=auto
git clone https://github.com/vllm-project/vllm-omni.git
cd vllm-omni
uv pip install -e .

vllm serve openbmb/VoxCPM2 --omni --port 8000

Bash

curl http://localhost:8000/v1/audio/speech   -H "Content-Type: application/json"   -d '{"model":"openbmb/VoxCPM2","input":"你好，欢迎使用 VoxCPM2。","voice":"default"}'   --output out.wav

vLLM-Omni 正在快速迭代。部署前请核对其 VoxCPM2 在线服务示例与安装文档，确认 vLLM、PyTorch 和设备后端版本。

llama.cpp-omni 端侧路径

该路径使用社区转换的 VoxCPM2 GGUF，需要一个 BaseLM 文件和一个 Acoustic 文件。

Bash

git clone https://github.com/tc-mb/llama.cpp-omni.git
cd llama.cpp-omni
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target voxcpm2-cli -j

./build/bin/voxcpm2-cli   -t "你好，我正在端侧运行 VoxCPM2。"   -o output.wav   VoxCPM2-BaseLM-Q8_0.gguf   VoxCPM2-Acoustic-F16.gguf

支持 CPU、Metal、CUDA 与 Vulkan。GGUF 权重由社区维护，不是 OpenBMB 官方模型仓库中的原始权重；转换精度、量化影响和文件来源需单独验证。

其他社区项目部署与集成

ReadTheDocs 同时收录了以下第三方项目入口。它们由各自社区独立维护，不等同于 OpenBMB 官方 Python 实现；实际采用前应在对应项目中确认支持的 VoxCPM 版本、模型文件来源、许可证、硬件要求、功能覆盖和精度影响。

社区项目	ReadTheDocs 入口
VoxCPM.cpp	部署文档
VoxCPM-ONNX	部署文档
VoxCPMANE	部署文档
MLX-Audio	部署文档
VoxCPM-RKNN2	部署文档
voxcpm_rs	部署文档
ComfyUI-VoxCPM	集成文档
ComfyUI_RH_VoxCPM	集成文档
ComfyUI-VoxCPMTTS	集成文档
TTS WebUI	集成文档

生产检查清单

维度	最低检查项
版本	记录模型仓库 revision、代码 commit、Python 包锁文件与容器镜像摘要。
质量	固定中英、多语言、长文本、数字符号、克隆与控制描述样例，做版本回归。
性能	同时记录 RTF、首包延迟、总延迟、并发、文本长度、采样步数、显存峰值和失败率。
音频输入	检查格式、时长、噪声、多人声及参考文本一致性；拒绝损坏文件。
安全	鉴权、限流、输入长度限制、文件隔离、说话人授权记录与 AI 生成标识。
可观测性	记录请求 ID、后端版本、参数、耗时与错误类型；不得在日志中长期保留未经授权的声音样本。

相关资源

主题	入口
OpenBMB/VoxCPM	核心仓库
Nano-vLLM-VoxCPM	社区推理后端
vLLM-Omni	vLLM 全模态扩展
llama.cpp-omni	端侧 C++ 后端