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 VRAM | VoxCPM-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 ... |
參考資料
- 儲存庫: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 金鑰、無複製功能