Communitygithub.com

VoxCPM 語音合成技能

使用 OpenBMB 的 VoxCPM 模型,從中文/英文/多語言文字合成自然語音,支援兩種模型規模、三種輸入模式、30 種語言及 9 種中文方言。

VoxCPM 語音合成技能 是什麼?

此技能整合了 OpenBMB 開發的 VoxCPM 文字轉語音模型,讓使用者能從中英文或多語言文字生成高品質語音。它提供三種輸入模式:透過自然語言描述控制語音風格(如「年輕女聲,溫柔甜美」)、零樣本語音複製(需提供 3-30 秒參考音頻),以及結合兩者的混合模式。支援 30 種語言與 9 種中文方言(包括四川話、粵語、吳語等),並提供 CLI 命令列工具、Python SDK 及串流合成功能,適合長文本處理。技能也說明了在無 GPU 或無法直連 Hugging Face 的環境(如 QoderWork 沙箱)中語音生成無法作用,並建議在有 CUDA 或 Apple Silicon 的機器上部署。若完全無法使用 VoxCPM,技能提供 Microsoft Edge TTS 作為無 GPU 的備案,但功能有限(無語音複製)。

相容平台~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 VRAMVoxCPM-0.5B 需 5 GB,VoxCPM2(2B)需 8 GB
磁碟空間每個模型約 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)

多語言播客

將同一腳本翻譯成英文、日文、韓文、法文版本輸入;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 可能達到 VRAM 上限。
  • 僅英文複製:可行但樣本品質略低於中文原生。
  • 方言需使用前綴格式 — 使用 (粵語) 早晨。 而非 粵語:早晨。。
  • 無字層級時間輸出 — 如需卡拉 OK 功能,請在產生的 WAV 上另外使用 Whisper 進行語音辨識對齊。
  • 取樣率固定為 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 ...

參考資料

相關技能