---
slug: voxcpm2-local-tts-model
status: published
title: VoxCPM2 本地語音模型怎麼用？從安裝、聲音複製到硬體需求
excerpt: VoxCPM2 是一款 2B 參數、30 語言、48 kHz 輸出的本地 TTS 模型。本文拆解它的安裝方式、Voice Design、聲音複製、串流使用、Apple Silicon 路徑與同類模型差異。
category: AI
tags: [VoxCPM2, TTS, voice-cloning, local-ai, speech-generation, open-source]
author: Seer
author_role: Author
read_time: 14 min
cover: "/static/voxcpm2-local-tts-model-cover.png"
published_at: "2026-08-09T12:07:20Z"
updated_at: "2026-08-09T12:07:20Z"
---

## 先講 VoxCPM2 的定位

[VoxCPM2](https://github.com/OpenBMB/VoxCPM) 是 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，只要把聲音描述放在文字開頭的括號裡：

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

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

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

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

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

```python
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`：

```python
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()`：

```python
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 的最短路徑是：

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

如果使用 `uv`，可以改成：

```bash
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：

```bash
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：

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

或：

```bash
pip install -e .
```

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

```bash
python app.py --port 8808
```

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

### macOS 需要補 FFmpeg 嗎？

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

```bash
brew install ffmpeg
```

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

## Python API 完整範例

### 一般 TTS

```python
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

```python
from voxcpm import VoxCPM

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

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

```python
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：

```bash
# 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 文件](https://voxcpm.readthedocs.io/en/latest/deployment/mlx_audio.html)仍寫明目前支援 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 生成聲音，也應依使用情境標示合成來源。

## 來源

- [OpenBMB/VoxCPM 官方 repository](https://github.com/OpenBMB/VoxCPM)
- [VoxCPM2 Hugging Face model card](https://huggingface.co/openbmb/VoxCPM2)
- [VoxCPM2 Installation](https://voxcpm.readthedocs.io/en/latest/installation.html)
- [VoxCPM2 Quick Start](https://voxcpm.readthedocs.io/en/latest/quickstart.html)
- [VoxCPM2 Usage Guide](https://voxcpm.readthedocs.io/en/latest/usage_guide.html)
- [VoxCPM2 Model Guide](https://voxcpm.readthedocs.io/en/latest/models/voxcpm2.html)
- [VoxCPM2 FAQ／VRAM／MPS](https://voxcpm.readthedocs.io/en/latest/faq.html)
- [VoxCPM2 Technical Report](https://arxiv.org/abs/2606.06928)
- [Qwen3-TTS 官方 repository](https://github.com/QwenLM/Qwen3-TTS)
- [CosyVoice 官方 repository](https://github.com/QwenAudio/CosyVoice)
- [F5-TTS 官方 repository](https://github.com/SWivid/F5-TTS)
- [IndexTTS 官方 repository](https://github.com/index-tts/index-tts)
- [Fish Speech 官方 repository](https://github.com/fishaudio/fish-speech)