VoxCPM 文本转语音 是做什么的?
使用 OpenBMB 的 VoxCPM 将中文/英文/多语言文本合成为语音。提供两种模型规模、三种输入模式、三十种语言、九种中文方言。Apache-2.0 许可。
2026-07-04 验证:PyPI 上 voxcpm 2.0.3,依赖图解析正常(torch ≥ 2.5, transformers ≥ 4.36, gradio 6.x)。PyPI 可访问。模型权重托管在 Hugging Face(openbmb/VoxCPM2、openbmb/VoxCPM-0.5B)。
当前环境(QoderWork 沙箱)无 GPU,且无法直接访问 huggingface.co — 此处不进行音频生成。请部署到配备 CUDA / Apple Silicon 或 HF 镜像的机器上以实现合成。
前置条件
| 组件 | 要求 |
|---|---|
| Python | ≥ 3.10, < 3.13(官方测试) |
| PyTorch | ≥ 2.5.0 |
| CUDA | ≥ 12.0(推荐);MPS 或 CPU 也可使用(较慢) |
| GPU 显存 | 5 GB(VoxCPM-0.5B),8 GB(VoxCPM2 2B) |
| 磁盘 | 约 2 GB/模型(权重从 HF 自动下载) |
| 网络 | 可访问 huggingface.co(或设置 HF_ENDPOINT 为镜像) |
安装:
pip install voxcpm
对于 HF 访问较慢的中国部署,建议使用 ModelScope 镜像:
export HF_ENDPOINT=https://hf-mirror.com
# 或直接使用 ModelScope:
pip install modelscope
快速开始
CLI(最简单)
# 基础合成到 WAV
voxcpm design --text "你好,欢迎收听三分钟 AI 快报。" --output greeting.wav
# 带语音风格的自然语言描述
voxcpm design --text "(年轻女声,温柔甜美) 今天天气真好,我们来聊聊 AI。" --output warm.wav
# 英文
voxcpm design --text "Welcome to today's AI briefing." --output en.wav
# 批量处理
voxcpm batch --input-file lines.txt --output-dir out/
Python SDK(编程方式)
from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
wav = model.generate(
text="你好,这是一段测试语音。",
cfg_value=2.0, # 无分类器引导强度(越高越有表现力)
inference_timesteps=10, # 扩散步数(越多质量越好,但越慢)
seed=42 # 可复现性
)
sf.write("demo.wav", wav, model.tts_model.sample_rate) # 24 kHz 输出
流式合成(用于长文本)
for chunk in model.generate_streaming(text="很长的一段文本..."):
# chunk 是 np.ndarray 类型的 PCM 采样
process(chunk)
输入模式
1. 设计(自然语言语音控制)
在文本开头用 () 包裹语音描述:
"(年轻女声,语气甜美,稍快语速) 今天要给大家介绍一款有意思的 AI 工具。"
"(中年男声,稳重、专业) 欢迎收听本期节目。"
"(带四川口音的女生,轻松) 这个咋回事嘛!"
可用提示(可组合使用):
- 音色:男声 / 女声 / 童声 / 老年男声 / 中年女声 ...
- 语气:温柔 / 严肃 / 兴奋 / 平静 / 忧郁 / 慵懒 ...
- 语速:快语速 / 慢语速 / 稍快 / 稍慢
- 风格:播音腔 / 口语化 / 说书人 / 儿童剧 / 广告腔
- 方言:四川话 / 粤语 / 吴语 / 东北话 / 河南话 / 陕西话 / 山东话 / 天津话 / 闽南话
2. 语音克隆(零样本)
提供一段 3-30 秒的参考音频及其文本:
wav = model.generate(
text="要合成的新文本。",
prompt_wav_path="reference.wav",
prompt_text="参考音频对应的原文(准确抄写)"
)
生成的语音与参考说话人匹配。
3. 组合模式(克隆 + 风格微调)
wav = model.generate(
text="(稍快,兴奋) 要合成的新文本。",
reference_wav_path="reference.wav" # 较温和的克隆形式;保留音色但风格覆盖
)
常见工作流
端到端:脚本 → 音频
与 podcast-scriptwriter 配合使用。给定脚本:
A(轻松):欢迎收听《三分钟 AI 快报》。
B(认真):本周动作不小。
import re
from voxcpm import VoxCPM
import soundfile as sf, numpy as np
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
voices = {
'A': "reference_female.wav", # 或使用 "(年轻女声,语气理性犀利)" 作为前缀
'B': "reference_male.wav",
}
segments = []
for line in open('script.txt', encoding='utf-8'):
m = re.match(r'^([AB])(([^)]+)):(.+)$', line.strip())
if not m: continue
speaker, tone, text = m.groups()
styled = f"({tone}) {text}"
wav = model.generate(text=styled, prompt_wav_path=voices[speaker], cfg_value=2.0, inference_timesteps=10)
segments.append(wav)
segments.append(np.zeros(int(0.4 * model.tts_model.sample_rate))) # 0.4 秒停顿
full = np.concatenate(segments)
sf.write('episode.wav', full, model.tts_model.sample_rate)
多语言播客
将同一脚本翻译成 en/ja/ko/fr;VoxCPM 会自动检测每行的语言。保持相同的参考音频以保留主持人身份特征。
高吞吐量 vLLM 服务
对于大量请求,可使用 OpenAI 兼容的 vLLM Omni 服务器:
vllm serve openbmb/VoxCPM2 --omni --port 8000
然后像 OpenAI TTS 一样调用 /v1/audio/speech。
后备方案:edge-tts(无需 GPU)
如果环境中无法使用 VoxCPM(无 GPU、HF 被屏蔽、时间紧张),可回退到 Microsoft Edge TTS(免费,无需 API 密钥,400+ 种语音):
pip install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media hello.mp3
权衡:无语音克隆、语音池固定、依赖网络、非开源。可接受的临时方案。
局限性
- 强烈建议使用 GPU — CPU 也可工作但慢 10-50 倍。
- 首次运行下载约 2 GB 来自 HF;如果速度慢请使用
HF_ENDPOINT镜像。 - CUDA 12+ 需要较新的驱动 — 较旧驱动可能需要 CUDA 11 构建;请检查
torch.cuda.is_available()。 - 长文本(> 2 分钟):使用
generate_streaming并拼接片段;纯generate可能达到显存上限。 - 纯英文克隆:可工作但样本质量略低于中文原生。
- 方言需要前缀格式 —
(粤语) 早晨。而不是粤语:早晨。。 - 无词级时间戳输出 — 如需卡拉 OK 效果,请在生成的 WAV 上使用类似 whisper 的 STT 对齐。
- 采样率固定为 24 kHz — 如需其他采样率,请在后处理中重新采样。
- Python 3.13+ 未经测试 — 请固定使用 3.10-3.12。
故障模式
| 症状 | 原因 | 操作 |
|---|---|---|
torch.cuda.OutOfMemoryError | 模型对于 GPU 过大 | 切换到 openbmb/VoxCPM-0.5B,或使用 CPU |
| 模型下载卡住 | HF 连接问题 | 设置 HF_ENDPOINT=https://hf-mirror.com |
| 声音机械/金属感 | cfg_value 过高 | 尝试 1.5-2.5;最佳点为 2.0 |
| 语音克隆不匹配 | 参考音频过短/有噪声 | 使用 5-15 秒的干净样本;启用 load_denoiser=True |
| 语言自动检测错误 | 文本混合 | 按语言拆分,分段生成 |
CLI voxcpm: command not found | 不在虚拟环境 PATH 中 | 在激活的环境中运行 pip install voxcpm;或使用 python -m voxcpm ... |
参考
- 仓库:https://github.com/OpenBMB/VoxCPM ⭐ 32.4k
- 文档:https://voxcpm.readthedocs.io/
- HF 模型:https://huggingface.co/openbmb/VoxCPM2(2B)或 https://huggingface.co/openbmb/VoxCPM-0.5B(小型)
- 演示:https://openbmb.github.io/VoxCPM-demopage/
- 许可:Apache-2.0
- 后备方案:Microsoft Edge TTS(
pip install edge-tts)— 无需 API 密钥,不支持克隆