Communitygithub.com

VoxCPM 文本转语音

使用 OpenBMB 的 VoxCPM 模型,将中文、英文及多语言文本合成为自然语音。支持两种模型规模、三种输入模式、三十种语言和九种中文方言。Apache-2.0 许可。

VoxCPM 文本转语音 是什么?

VoxCPM 是一款由 OpenBMB 开发的高性能文本转语音(TTS)技能,专为 AI Agent 工具(如 Claude Code、Cursor、Codex 等)设计。它支持中文、英文及三十种语言,并提供九种中文方言(包括四川话、粤语、东北话等),通过扩散模型生成 24kHz 的高质量音频。技能提供三种输入模式:基于自然语言描述的语音风格控制(如“年轻女声,温柔甜美”)、零样本语音克隆(需 3-30 秒参考音频和文本)、以及两者结合的混合模式。它还支持流式合成长文本,并可通过 OpenAI 兼容的 vLLM Omni 服务器实现高并发部署。VoxCPM 在无 GPU 环境下可作为备选方案(如使用 edge-tts),但强烈建议在配备 CUDA 或 Apple Silicon 的机器上运行,以获得最佳性能。该技能解决了 PilotDeck 生态系统中中文和多语言高质量语音合成的空白,适用于播客生成、多语言内容制作、AI 新闻播报等场景。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add AaronAust1n/china-productivity-skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 ...

参考

相关技能