VoxCPM2 本地語音模型怎麼用？從安裝、聲音複製到硬體需求

先講 VoxCPM2 的定位

VoxCPM2 是 OpenBMB 最新一代的本地文字轉語音（Text-to-Speech，TTS）模型。它不是一個聊天模型加上語音輸出的外掛，而是一套直接把文字與聲音條件轉成語音的生成系統。

官方模型卡把 VoxCPM2 定位成 2B 參數、30 語言、48 kHz 輸出的 tokenizer-free diffusion autoregressive TTS。它提供一般 TTS、自然語言 Voice Design、參考音檔聲音複製，以及帶有逐字稿的高相似度 continuation cloning。模型權重、推理工具與微調程式以 Apache-2.0 發布。

這個定位很重要：VoxCPM2 的價值不是只有「把一句話念出來」，而是把「誰在說、怎麼說、說什麼語言、要不要保留參考聲音細節」放進同一個本地模型。對配音、短影音旁白、角色聲線、離線 TTS 與本地 agent 來說，它比單純的固定聲線 TTS 更有操作空間。

不過，官方公開的 VRAM、RTF 與 benchmark 都是特定測試條件下的參考，不代表每台電腦、每種文字長度或每個語言都會得到相同結果。本文先以官方 repository、模型卡、文件與 technical report 為主，沒有把未實測的速度寫成保證。

VoxCPM2 能做什麼？

一般文字轉語音

輸入文字，模型直接生成語音。不需要先指定固定 speaker；沒有參考音檔時，模型會生成一個聲音，但每次呼叫的音色不一定一致。

Voice Design：用文字描述聲音

Voice Design 不需要 reference audio，只要把聲音描述放在文字開頭的括號裡：

wav = model.generate(
    text="(溫柔、偏低沉、語速稍慢的成年女性聲線)歡迎來到今天的節目。",
    cfg_value=2.0,
    inference_timesteps=10,
)

描述可以包含年齡、性別、音高、速度、情緒與聲音質地。這種方式適合先做角色聲線探索，也適合短影音在還沒有固定配音員時快速測試方向。

Voice Design 不是傳統意義上的聲音複製。它是依照文字描述產生一個符合條件的新聲音；如果下一次沒有保存 reference audio，音色不會自動成為固定 speaker。

Controllable Voice Cloning：複製音色，再控制說話方式

VoxCPM2 可以用一段 reference audio 提取說話者的音色，再用括號中的文字指示調整說話風格：

wav = model.generate(
    text="(語氣明亮、稍微加快、帶一點興奮)這是一段可控制風格的複製聲音。",
    reference_wav_path="speaker.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)

這裡可以把兩個條件分開理解：reference_wav_path 主要提供「誰在說」；括號中的 instruction 主要提供「怎麼說」。官方使用指南指出，這個模式不要求 reference audio 的逐字稿。

Hi-Fi／Continuation Cloning：音色相似度優先

如果手上有 reference audio 的精確逐字稿，可以同時傳入 prompt_wav_path 與 prompt_text：

wav = model.generate(
    text="這是接續參考聲音生成的新內容。",
    prompt_wav_path="speaker.wav",
    prompt_text="這裡填入 speaker.wav 的精確逐字稿。",
    reference_wav_path="speaker.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)

這條路徑利用 reference audio 與 transcript 對齊內容，官方文件把它列為追求最高聲音相似度的方式。逐字稿不準確時，結果可能出現尾端雜音、節奏不穩或音色漂移；實際工作流中可以先用 ASR 取得 transcript，再人工校對。

Streaming：邊生成邊取得 audio chunk

Python API 提供 generate_streaming()：

import numpy as np
import soundfile as sf

chunks = []
for chunk in model.generate_streaming(
    text="這是一段以串流方式產生的語音。"
):
    chunks.append(chunk)

wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)

官方建議把長文字按句切開，再逐句呼叫 streaming。把一整段越來越長的文字持續塞進同一個輸入，較容易遇到速度飄移、buzzing、KV cache 變大或生成不停止等問題。VoxCPM2 目前不是「文字 token 一進來，音訊就同步逐 token 輸出」的雙向串流系統；它的實務做法仍是句子級切分與 chunk 播放。

怎麼安裝？

路線一：PyPI 安裝，最適合先試跑

官方 Quick Start 的最短路徑是：

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install voxcpm

如果使用 uv，可以改成：

uv venv --python 3.11
source .venv/bin/activate
uv pip install voxcpm

官方文件目前建議 Python 3.10–3.12，PyTorch 2.5.0 以上。NVIDIA GPU 加速需要 CUDA 12.0 以上；CPU 與 Apple Silicon MPS 不需要 CUDA。

安裝後先驗證 Python package：

python -c "from voxcpm import VoxCPM; print('VoxCPM is ready')"

第一次載入模型時，from_pretrained("openbmb/VoxCPM2") 會自動從 Hugging Face 下載權重。如果網路環境無法穩定存取 Hugging Face，再依官方文件設定 mirror 或先手動下載到本機。

路線二：直接從 source 安裝

需要修改程式碼、跑 local Web UI 或研究微調流程時，再使用 source checkout：

git clone https://github.com/OpenBMB/VoxCPM.git
cd VoxCPM
uv sync

或：

pip install -e .

Web UI 需要 source checkout，官方 quick start 的入口是：

python app.py --port 8808

可用 --device auto、--device cpu、--device mps、--device cuda 或 --device cuda:N 指定執行裝置。

macOS 需要補 FFmpeg 嗎？

如果只做沒有 reference audio 的 Voice Design，未必會立刻碰到音檔讀取問題；只要進入聲音複製、參考音檔或 denoiser 流程，建議先裝 FFmpeg：

brew install ffmpeg

官方 FAQ 指出，新的 torchaudio 音訊路徑會用到 torchcodec，而 torchcodec 需要系統能找到相容的 FFmpeg。

Python API 完整範例

一般 TTS

from voxcpm import VoxCPM
import soundfile as sf

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

wav = model.generate(
    text="VoxCPM2 是一款可以在本地執行的多語言語音生成模型。",
    cfg_value=2.0,
    inference_timesteps=10,
    seed=42,
)

sf.write("output.wav", wav, model.tts_model.sample_rate)

load_denoiser=False 適合乾淨輸入、先確認主流程能否跑通的情境。Denoiser 主要作用在 prompt/reference audio，不是拿來修復已生成的輸出；如果參考音檔很乾淨，開啟它不一定會更好。

指定 Apple Silicon MPS

from voxcpm import VoxCPM

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

官方支援 MPS，但也提醒 MPS 後端不代表所有推理路徑都一定成功。遇到 runtime error 時，可以退回：

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

在 Mac 上，optimize=False 是比較保守的起點，因為 torch.compile 主要針對 CUDA 最有幫助，在 MPS、CPU 或非標準環境可能反而成為相容性問題。

CLI 怎麼用？

安裝 PyPI package 後，可以直接用 CLI：

# Voice Design
voxcpm design \
  --text "歡迎收看今天的節目。" \
  --control "溫暖、清楚、成熟的女性旁白聲線" \
  --output design.wav

# Reference-only cloning
voxcpm clone \
  --text "這是一段複製聲音測試。" \
  --reference-audio speaker.wav \
  --output clone.wav

# Hi-Fi／continuation cloning
voxcpm clone \
  --text "這是接續參考音檔的新句子。" \
  --prompt-audio speaker.wav \
  --prompt-text "speaker.wav 的精確逐字稿" \
  --reference-audio speaker.wav \
  --output hifi-clone.wav

# 批次處理
voxcpm batch --input examples/input.txt --output-dir outputs

如果要取得文字時間戳，官方另外提供 voxcpm[timestamps] 選配依賴，透過 stable-ts 做後處理。這不等於 VoxCPM2 原生輸出逐字對齊；中文 character timestamps 也只是從 word alignment 推導的 best-effort 結果。

硬體規格：什麼電腦跑得動？

官方直接給出的數字

VoxCPM2 模型卡列出：

Backbone：2B parameters
dtype：bfloat16
VRAM：約 8 GB
Max sequence length：8192 tokens
RTX 4090、inference_timesteps=10 的 standard inference RTF：約 0.30
NanoVLLM-VoxCPM、相同 RTX 4090 條件下的 RTF：約 0.13

RTF（Real-Time Factor）低於 1，代表生成速度快於音訊播放時間；但官方數字是在單張 RTX 4090、特定設定下測量，不能直接當成 RTX 3060、Mac M 系列或長文輸入的保證。

實際部署要預留什麼？

Hugging Face openbmb/VoxCPM2 repository 查核時約 4.62 GiB，主要檔案包括：

model.safetensors：約 4.27 GiB
audiovae.pth：約 0.35 GiB

這只是模型 repository 的檔案總量。實際部署還要加上 Python、PyTorch、音訊套件、Hugging Face cache、輸出 WAV，以及可能的 denoiser 資源。因此磁碟至少應預留 10 GB 級空間比較舒服。

官方沒有提供固定最低系統 RAM、CPU 核心數、每秒生成速度或每千字記憶體公式。不要把「約 8 GB VRAM」誤讀成「任何 8 GB 顯示卡都會穩定跑完整流程」：長文字、提高 diffusion timesteps、開啟 denoiser、使用較大的 KV cache 或多請求併發，都可能增加使用量。

NVIDIA GPU

如果目標是即時旁白、批次配音或服務化，NVIDIA CUDA 是官方最清楚、最有 benchmark 證據的路徑。8 GB VRAM 是官方參考起點；更大的 VRAM 可以為長文字、較高品質設定與併發留下餘裕。

Apple Silicon

官方 Python 文件支援 Apple Silicon MPS，device="auto" 的 fallback 順序是 cuda → mps → cpu。MPS 可以作為本地試跑與低併發工作流，但官方沒有提供 M 系列的 VoxCPM2 RTF 或最低 unified memory 數字，所以不能直接承諾「16 GB Mac 一定即時」。CPU 能跑，但官方也明確指出速度會慢。

要特別區分 MLX 路徑：VoxCPM 官方目前的 MLX-Audio 文件仍寫明目前支援 VoxCPM 1.0 與 1.5，VoxCPM2 尚未在該官方頁面提供 MLX-Audio backend。社群有 mlx-community/VoxCPM2-4bit port，能在 Apple Silicon 上提供另一條路，但它不是 OpenBMB 官方 runtime，應視為獨立 port 先自行驗證，不要與官方支援混寫。

同類模型怎麼選？

比較表

模型	核心定位	語言／控制能力	模型與硬體線索	適合誰
VoxCPM2	tokenizer-free、階層式 continuous latent、diffusion-autoregressive	30 語言、9 種中文方言；Voice Design；reference-only clone；transcript-based hi-fi clone；48 kHz	2B；官方約 8 GB VRAM；Apache-2.0	想要多語言、聲音設計與本地複製放在同一個模型的人
Qwen3-TTS	discrete multi-codebook LM，搭配自家 12 Hz tokenizer	10 語言；0.6B／1.7B；3 秒 voice clone、Voice Design、CustomVoice、streaming	HF Base repo 約 2.34／4.23 GiB；官方建議 FlashAttention 2，但未給固定 VRAM；Apache-2.0	重視較小模型、快速 cloning、低延遲與 Qwen 生態的人
CosyVoice 3	LLM-based multilingual TTS，含 streaming 與 instruct	0.5B；9 語言、18+ 中文方言；跨語言 cloning、發音修補、情緒／速度／音量指令	官方未在 README 給固定最低 VRAM；需要 git submodule、Conda、模型資源與可選文字正規化套件	中文方言、production-oriented streaming 與成熟服務腳本
F5-TTS	Flow matching TTS	reference audio cloning、chunk inference、多 speaker／style 工作流	0.3B；官方公布 L20 benchmark，但沒有固定最低 VRAM；code 是 MIT，預訓練模型是 CC-BY-NC	想先用較小模型做一般 cloning，且能接受模型授權限制的人
IndexTTS2	自回歸 TTS，將 speaker identity 與 emotion 分離	reference speaker、情緒 reference、emotion vector、文字情緒控制；主打 duration control，但目前 README 註明部分功能尚未開放	公開比較表常列 1.5B，但官方 main README 未以此給硬體保證；支援 FP16 降低 VRAM，使用 uv，CUDA 12.8+ 是 Linux／Windows 重要條件	情緒表演、角色配音與中文旁白優先的人
Fish Audio S2 Pro	4B slow AR + 400M fast AR，Dual-AR	80+ 語言、10–30 秒 cloning、inline emotion tags、多 speaker／multi-turn	官方建議至少 24 GB VRAM；Fish Audio Research License	有 24 GB 級 NVIDIA GPU，重視表演力與多 speaker 的人

VoxCPM2 對 Qwen3-TTS

兩者都把 Voice Design、voice cloning 與多語言放在本地模型裡，但設計方向不同。VoxCPM2 直接在連續音訊 latent 上做階層式 diffusion-autoregressive generation；Qwen3-TTS 使用自家的 12 Hz speech tokenizer 與離散 multi-codebook LM。

Qwen3-TTS 的優勢是有 0.6B 與 1.7B 尺寸、3 秒快速 cloning、預設 speaker 與 streaming；VoxCPM2 的優勢是支援範圍更寬、原生 48 kHz、reference-only cloning 不要求 transcript，另外保留帶 transcript 的高相似度 continuation 路徑。若只是要快速複製一個聲音，Qwen3-TTS 值得先試；若要同時做多語言、Voice Design、方言與高音質輸出，VoxCPM2 的產品面比較完整。

VoxCPM2 對 CosyVoice 3

CosyVoice3 的 0.5B 規模較小，官方主打 9 語言、18+ 中文方言、跨語言 cloning、發音 inpainting 與雙向 streaming。它的 repository 也提供 FastAPI、gRPC、vLLM、TensorRT-LLM 等部署路徑，服務化資料比較完整。

VoxCPM2 的差異在 30 語言、48 kHz、Voice Design 與 isolated reference channel。CosyVoice3 更像一套已經把中文方言、串流與服務部署考慮進去的 TTS 工具箱；VoxCPM2 則把多語言、聲音設計與兩種 cloning 邏輯整合得更集中。中文短影音要快速落地，兩者都該用同一組中文、方言、情緒與長文測試集實聽，而不是只看參數數量。

VoxCPM2 對 F5-TTS

F5-TTS 的核心是 flow matching，模型規模約 0.3B，安裝與 CLI 路徑相對直接，也有 Gradio、Docker、chunk inference 與多 speaker 工作流。它適合把 reference audio 與文字接進去，快速得到可用的 cloning 結果。

VoxCPM2 提供更完整的 Voice Design、style control、多語言與 48 kHz 路徑；F5-TTS 則在小模型與成熟社群工作流上有吸引力。商業導入要先看授權：F5-TTS 的程式碼是 MIT，但官方 README 明確寫預訓練模型因 Emilia training data 採 CC-BY-NC，不能只看到「開源」就直接當成可商用。

VoxCPM2 對 IndexTTS2 與 Fish S2 Pro

IndexTTS2 的重點是情緒與音色拆開控制，可以使用情緒參考音檔、emotion vector 或文字情緒描述，這對角色台詞與情緒旁白特別有用。它的安裝要求比 pip install voxcpm 更重，官方只支援 uv 的環境管理，Linux／Windows 還要注意 CUDA 12.8+ 與額外加速套件。

Fish Audio S2 Pro 則是另一個重量級選擇：4B slow AR 加上 400M fast AR，官方建議至少 24 GB VRAM，支援 80+ 語言、inline emotion tags、多 speaker 與 multi-turn。它的表演控制與語言覆蓋很有吸引力，但 Fish Audio Research License 與 VoxCPM2 的 Apache-2.0 不是同一種商業條件，部署前要先做授權審查。

我的選擇建議

有 8 GB 級 NVIDIA GPU，想先跑通多語言與複製聲音：先試 VoxCPM2。
Apple Silicon Mac：先走官方 Python + MPS，optimize=False；MLX 的 VoxCPM2 社群 port 另行測試，不要把它當官方支援。
只需要 10 語言內、3 秒快速 cloning、較小模型：比較 Qwen3-TTS 0.6B／1.7B。
中文方言、串流服務與部署腳本優先：比較 CosyVoice3。
小模型、一般 reference cloning、可接受 CC-BY-NC：F5-TTS。
情緒表演與角色台詞優先：IndexTTS2；若有 24 GB GPU 且要多 speaker／inline emotion，再看 Fish S2 Pro。

真正導入前，我會用同一套測試集比較：普通話、台灣常用詞、數字與英文夾雜、粵語／閩南語、情緒指令、30 秒以上長句、reference-only clone，以及 reference transcript 不完整時的容錯。最後再測輸出是否能接進現有的 ASR、字幕對齊、剪輯與短影音 pipeline。

限制與安全邊界

VoxCPM2 的 Voice Design 與 style control 結果可能因執行次數不同而變動；官方建議必要時生成 1–3 次挑選結果。長文字也可能觸發速度飄移、buzzing、OOM 或停止條件不穩定，因此生產流程應切句、重試、驗音，再合併輸出。

Voice cloning 只應使用自己擁有或取得明確授權的聲音。官方明確禁止冒充、詐騙與不實資訊用途；對外發布的 AI 生成聲音，也應依使用情境標示合成來源。