VoxCPM 完整教學

一句話定位：OpenBMB（清華大學 NLP / 面壁智能 ModelBest 主導）旗下旗艦 TTS (text-to-speech; 文字轉語音) 開源項目；採 tokenizer-free + diffusion autoregressive 架構、基於 MiniCPM-4 language model + AudioVAE V2 latent space，最新版 VoxCPM 2 以 2B 參數支援 30 種語言、48 kHz 高保真合成、voice design（純文字描述生聲）、voice cloning（參考音複製）、controllable cloning（風格調整）、streaming，Apache-2.0 可商用。

適合：想做 production TTS 服務、做語音內容生成（podcast / 旁白 / 有聲書）、做 voice agent 後端、研究 latent diffusion TTS 架構的人。

不適合：低資源 edge device（< 4 GB VRAM）— 改看 VoxCPM.cpp / ONNX 衍生版；不想處理 PyTorch 環境的人 — 改用 vLLM-Omni OpenAI-compatible HTTP API。

⚠️ 重要倫理提醒：voice cloning 技術可能被用於 deepfake、impersonation、詐騙、disinformation；專案明確禁止用於這些用途，任何 AI 生成語音建議顯著標示來源。

目錄

1. 專案定位
2. 安裝指南
3. 核心架構解析
4. Helper Scripts 詳細用法
5. 應用場景：5 大用法 + 進階模式
6. 資安掃描報告
7. FAQ
8. 進階技巧
9. 整合進其他工作流
10. 重點摘要 Checklist
11. 進一步閱讀

1. 專案定位

1.1 這是什麼

VoxCPM 是 OpenBMB 開源的 tokenizer-free diffusion autoregressive TTS 模型家族。它與 2023-2024 主流的「discrete audio codec（VALL-E / CosyVoice / Spark-TTS / IndexTTS 等）」TTS 路線分道揚鑣，不把語音切成固定 token，而是直接在 AudioVAE 連續 latent space 上做 diffusion 生成。

從技術圖譜來看，VoxCPM 屬於以下幾條最近兩年新興路線的綜合體：

• Diffusion AR：把 LLM 的逐 step 預測搭配 diffusion 連續生成；本支血脈來自 DiTAR（2025）
• Tokenizer-free TTS：取消 quantize → token 步驟，直接在 latent space 工作；對短句、極端 prosody（語調）、language code-switching 都更穩
• Decoder-only LM backbone：用 MiniCPM-4（OpenBMB 自家 LM）做文本端，避免重新訓 LM；context-aware 能力強

1.2 三個版本快速對照

選版本的快速建議：

• 多語言 / production 多角色：直接 VoxCPM 2，不用考慮其他選項
• 只做中英、要省顯存：VoxCPM 1.5 也夠用
• 學術復現 / 看論文對應實作：VoxCPM-0.5B（ICLR 2026 paper 對應版本）

1.3 在 TTS 開源生態系的位置

從 README 中的 Seed-TTS-eval 評測表可以看出 VoxCPM 2 在開源 TTS 模型中的相對位置：

解讀：VoxCPM 2 在 SIM（speaker similarity，音色相似度）上接近頂級閉源模型；WER（word error rate，字錯率）上不是第一，但在 2B 規模屬於合理表現。對「語音內容生成」這類用途，SIM 的重要性 ≫ WER 微小差距。

1.4 與其他開源 TTS 模型的工程取捨

結論：VoxCPM 2 的強項是 30 種語言、voice design、商用授權 + 完整生態系；F5 / CosyVoice2 / IndexTTS2 各有強項，視場景擇用。

1.5 統計資料快照（2026-06-02）

2. 安裝指南

2.1 最簡單：pip install

1# 主要依賴 PyTorch ≥ 2.5.0，CUDA ≥ 12.0
2pip install voxcpm

環境要求：Python ≥ 3.10（且 < 3.13）、PyTorch ≥ 2.5.0、CUDA ≥ 12.0。Mac Apple Silicon 走 MPS 也可（2026-05 後支援，效能比 CUDA 慢但堪用）。

2.2 從原始碼安裝（最新 main branch / 想 debug）

1git clone https://github.com/OpenBMB/VoxCPM.git
2cd VoxCPM
3pip install -e .

2.3 用 uv（專案 uv.lock 已提供）

1git clone https://github.com/OpenBMB/VoxCPM.git
2cd VoxCPM
3uv sync           # 從 uv.lock 還原完全相同的環境

2.4 下載模型權重

方式 1：自動從 HuggingFace（程式內首次 inference 時自動拉）

1from voxcpm import VoxCPM
2model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
3# 第一次跑會自動 snapshot_download 到 ~/.cache/huggingface/

方式 2：手動 ModelScope（中國地區更快）

1pip install modelscope

1from modelscope import snapshot_download
2snapshot_download("OpenBMB/VoxCPM2", local_dir='./pretrained_models/VoxCPM2')
3
4from voxcpm import VoxCPM
5model = VoxCPM.from_pretrained("./pretrained_models/VoxCPM2", load_denoiser=False)

2.5 啟動 Gradio WebUI

1# 推理用 WebUI
2python app.py          # http://localhost:7860
3
4# 微調 + 推理整合 WebUI（含 LoRA 訓練流程）
5python lora_ft_webui.py

2.6 安裝 vLLM-Omni 服務（OpenAI compatible API）

VoxCPM 2 已被官方納入 vLLM-Omni（vLLM 的 multi-modal 分支）：

1# 從 source 裝（vllm-omni 還在快速演進）
2pip install git+https://github.com/vllm-project/vllm-omni.git
3
4# 啟動 OpenAI-compatible TTS server（--omni 啟用 omni-modal）
5vllm serve openbmb/VoxCPM2 --omni
6
7# 然後從任何 OpenAI client 呼叫

1from openai import OpenAI
2client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
3response = client.audio.speech.create(
4    model="openbmb/VoxCPM2",
5    voice="alloy",
6    input="Hello from VoxCPM via vLLM!"
7)
8response.stream_to_file("out.mp3")

2.7 安裝流程圖

flowchart TD
    A[需求是什麼?] --> B{場景}
    B -->|Python 內 inference| C[pip install voxcpm]
    B -->|本地 WebUI demo| D[clone + pip install -e .
python app.py]
    B -->|微調自己的聲音| E[clone + pip install -e .
python lora_ft_webui.py]
    B -->|HTTP API production| F[pip install vllm-omni
vllm serve openbmb/VoxCPM2 --omni]
    B -->|CPU only edge| G[改用衍生：
VoxCPM.cpp 或 VoxCPM-ONNX]
    C --> H[自動拉 HF 權重]
    D --> H
    E --> H
    F --> H
    H --> I{中國地區?}
    I -->|是| J[改用 ModelScope]
    I -->|否| K[直接用 HuggingFace]
    J --> L[開跑]
    K --> L
    G --> L

2.8 已知環境踩坑

3. 核心架構解析

3.1 四段 pipeline：LocEnc → TSLM → RALM → LocDiT

VoxCPM 的 inference path 由四個模組串接：

flowchart LR
    A[Input text
+ optional ref audio] --> B[LocEnc
Local Encoder]
    B --> C[TSLM
Text Side LM
MiniCPM-4]
    C --> D[RALM
ResidualAR
Language Model]
    D --> E[LocDiT
Local Diffusion
Transformer]
    E --> F[AudioVAE V2
Decoder]
    F --> G[Waveform 48 kHz]
    H[Reference audio] -.->|optional| B
    H -.->|optional| E

四段角色：

Tokenizer-free 是什麼意思？ 傳統 codec-based TTS 中間有一步 audio → discrete codec token（VAE quantize / HuBERT cluster / SoundStream token），把連續訊號離散化。VoxCPM 完全跳過這步，RALM 預測連續 latent vector，LocDiT 把這些 latent 還原成波形。優點：保留連續度、對短句穩、不被 codebook 容量限制；代價：訓練比 discrete 更難收斂、需要更多資料 + 更好的 backbone。

3.2 條件機制：cloning 與 voice design 在架構上是什麼

sequenceDiagram
    participant T as Text
    participant R as Reference Audio
optional
    participant LE as LocEnc
    participant LM as TSLM+RALM
    participant LD as LocDiT
    participant V as AudioVAE
    R->>LE: encode reference
    LE->>LM: speaker embedding
cond ref latent
    T->>LM: text token
    LM->>LD: hidden state
per step
    LD->>LD: CFM denoise
flow matching
    LD->>V: predicted latent
    V->>V: decode to waveform
    Note over T: voice design:
text 以括號帶 description prompt
(A young woman gentle voice)Hello
    Note over R: voice cloning:
reference_wav_path 傳入
    Note over T,R: ultimate cloning:
reference_wav_path + prompt_wav_path
+ prompt_text 三者並用

• Voice design：把 (自然語言聲音描述) 寫在 text 開頭；模型 LM 端把這段當 condition 控制 RALM 生成出對應風格的 latent。不需要 reference audio。
• Voice cloning：傳 reference_wav_path；LocEnc 編出 speaker embedding 注入 LM 與 LocDiT condition。
• Controllable cloning：同時傳 reference + text 內含括號描述；兩個 condition 一起作用。
• Ultimate cloning：傳 reference_wav_path + prompt_wav_path + prompt_text，做 audio continuation（把 reference 當作待續的前文，比單純 speaker embedding 抓更細的韻律細節）。

3.3 目錄樹

 1VoxCPM/
 2├── app.py                        # 主 Gradio WebUI（推理 demo）
 3├── app_old.py                    # 舊版 WebUI（保留參考）
 4├── lora_ft_webui.py              # LoRA 微調 + 推理整合 WebUI（45 KB）
 5├── pyproject.toml                # PEP 621 metadata；只裝 voxcpm package
 6├── uv.lock                       # uv 鎖檔（1.1 MB）
 7├── LICENSE                       # Apache-2.0
 8├── README.md / README_zh.md      # 中英文 README
 9├── assets/                       # README 用圖
10├── conf/                         # Fine-tune YAML 配置
11│   ├── voxcpm_v1/
12│   │   ├── voxcpm_finetune_all.yaml      # 全量微調
13│   │   └── voxcpm_finetune_lora.yaml     # LoRA 微調
14│   ├── voxcpm_v1.5/  ...
15│   └── voxcpm_v2/    ...
16├── examples/                     # demo 用音訊 + 訓練 jsonl 範例
17│   ├── example.wav (1.4 MB)
18│   ├── reference_speaker.wav (1.2 MB)
19│   └── train_data_example.jsonl  # jsonl format 範例
20├── scripts/                      # 訓練與 inference 測試腳本
21│   ├── train_voxcpm_finetune.py        # 31 KB 主訓練入口
22│   ├── test_voxcpm_ft_infer.py
23│   ├── test_voxcpm_lora_infer.py
24│   └── test_pick_runtime_dtype.py
25├── src/voxcpm/                   # 套件本體
26│   ├── __init__.py
27│   ├── cli.py                    # `voxcpm` CLI entry
28│   ├── core.py                   # VoxCPM 高層 wrapper class
29│   ├── zipenhancer.py            # ZipEnhancer denoiser 整合
30│   ├── model/                    # 高層 model 容器
31│   │   ├── voxcpm.py             # VoxCPMModel  (1.x / 1.5)
32│   │   ├── voxcpm2.py            # VoxCPM2Model (v2 旗艦)
33│   │   └── utils.py
34│   ├── modules/
35│   │   ├── audiovae/             # AudioVAE v1 + v2
36│   │   ├── layers/               # 共用 layer：LoRA、scalar quantization
37│   │   ├── locdit/               # LocDiT v1/v2 + CFM
38│   │   ├── locenc/               # LocEnc
39│   │   └── minicpm4/             # MiniCPM-4 配置 + model + KV cache
40│   ├── training/                 # 訓練核心
41│   │   ├── accelerator.py        # HuggingFace accelerate 整合
42│   │   ├── config.py             # dataclass 設定容器
43│   │   ├── data.py               # dataset / collator / packer
44│   │   ├── packers.py            # token packing 提升 GPU 利用率
45│   │   ├── state.py              # checkpoint state
46│   │   ├── tracker.py            # tensorboard tracker
47│   │   └── validate.py           # 訓練資料健檢
48│   └── utils/text_normalize.py   # 文字正規化
49└── tests/                        # pytest 單元測試（4 個檔案）

3.4 套件依賴關鍵點

pyproject.toml 鎖死的關鍵版本：

 1requires-python = ">=3.10,<3.13"
 2dependencies = [
 3    "torch>=2.5.0",
 4    "torchaudio>=2.5.0",
 5    "torchcodec",                       # 新 PyTorch audio codec API
 6    "transformers>=4.36.2",
 7    "einops",
 8    "gradio>=6,<7",                     # 新一代 Gradio 6.x
 9    "wetext",                           # 文字正規化（含中文）
10    "modelscope>=1.22.0",               # 國內模型下載
11    "datasets>=3,<4",
12    "huggingface-hub",
13    "soundfile", "librosa",             # 音訊 IO
14    "funasr",                           # ASR 工具鏈（驗證用）
15    "spaces",                           # HF Spaces SDK
16    "safetensors",
17]

• torch>=2.5.0：因為要用 torch.compile（VoxCPM 預設 optimize=True 會 compile）
• gradio>=6,<7：跟主流 Gradio 5 不相容；安裝環境要乾淨
• funasr：依賴重；如果只做 inference 不做 fine-tune，可以考慮 fork 出來剝掉
• spaces：HuggingFace Spaces 部署 SDK；本地 inference 不會用到，但被列為硬依賴

4. Helper Scripts 詳細用法

4.1 voxcpm CLI

pyproject.toml 註冊了 voxcpm 命令，主入口在 src/voxcpm/cli.py：

 1# Voice design（無 reference）
 2voxcpm design \
 3    --text "(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM2!" \
 4    --output design.wav
 5
 6# Controllable cloning（reference + 風格描述）
 7voxcpm clone \
 8    --text "(slightly faster, cheerful tone)This is a cloned voice with style control." \
 9    --reference path/to/voice.wav \
10    --output clone.wav
11
12# Voice cloning（純參考音）
13voxcpm clone \
14    --text "This is a cloned voice generated by VoxCPM2." \
15    --reference path/to/voice.wav \
16    --output clone.wav
17
18# Ultimate cloning（reference + prompt audio + prompt text）
19voxcpm ultimate \
20    --text "..." \
21    --prompt-audio path/to/voice.wav \
22    --prompt-text "exact transcript of the reference" \
23    --reference path/to/voice.wav \
24    --output ultimate.wav
25
26# Batch 處理（JSONL 輸入）
27voxcpm batch --manifest input.jsonl --output-dir outputs/
28
29# 通用 help
30voxcpm --help

CLI 數值範圍守則（from cli.py:validate_ranges）

4.2 Python API：VoxCPM 類別

主要 entry：from voxcpm import VoxCPM（定義在 src/voxcpm/core.py）。

4.2.1 建構參數

1VoxCPM(
2    voxcpm_model_path: str,           # 本地模型權重路徑
3    zipenhancer_model_path: str | None = "iic/speech_zipenhancer_ans_multiloss_16k_base",
4    enable_denoiser: bool = True,     # 是否載入 denoiser
5    optimize: bool = True,            # 是否 torch.compile（預設 True）
6    device: str | None = None,        # None/auto：CUDA → MPS → CPU
7    lora_config: LoRAConfig | None = None,    # LoRA 配置
8    lora_weights_path: str | None = None,     # LoRA 權重路徑
9)

4.2.2 from_pretrained 工廠方法

1VoxCPM.from_pretrained(
2    "openbmb/VoxCPM2",
3    load_denoiser=False,    # 通常設 False 省記憶體
4    device="cuda",
5)

模型架構自動從 config.json 的 architecture 欄位判斷（值為 voxcpm 或 voxcpm2）→ 載對應的 VoxCPMModel / VoxCPM2Model。

4.2.3 generate(...)：主要 inference API

1wav = model.generate(
2    text="Hello world",
3    reference_wav_path=None,           # voice cloning 用
4    prompt_wav_path=None,              # ultimate cloning 用（audio continuation）
5    prompt_text=None,                  # 對應 prompt_wav_path 的逐字稿
6    cfg_value=2.0,                     # CFG (classifier-free guidance) 強度
7    inference_timesteps=10,            # diffusion 步數
8)
9# 回傳 numpy ndarray，採樣率為 model.tts_model.sample_rate（VoxCPM 2 是 48000）

4.2.4 generate_streaming(...)：streaming 版

1import numpy as np
2chunks = []
3for chunk in model.generate_streaming(text="..."):
4    chunks.append(chunk)
5wav = np.concatenate(chunks)

streaming 適合做 realtime 對話、低延遲場景（first chunk 延遲 < 1s on RTX 4090）。

4.3 train_voxcpm_finetune.py

主訓練入口（31 KB / scripts/train_voxcpm_finetune.py）。設計上接 YAML 配置：

1# LoRA fine-tune（推薦：5-10 分鐘音檔就能跑）
2python scripts/train_voxcpm_finetune.py \
3    --config_path conf/voxcpm_v2/voxcpm_finetune_lora.yaml
4
5# 全量 SFT
6python scripts/train_voxcpm_finetune.py \
7    --config_path conf/voxcpm_v2/voxcpm_finetune_all.yaml

conf/voxcpm_v2/voxcpm_finetune_lora.yaml 關鍵欄位

 1pretrained_path: /path/to/VoxCPM2/    # 基礎模型路徑
 2train_manifest: /path/to/train.jsonl
 3val_manifest: null                     # 可選
 4sample_rate: 16000                     # AudioVAE encoder 輸入率（注意：要跟模型 config 對齊）
 5out_sample_rate: 48000                 # 輸出率（用於 TensorBoard 音訊 log）
 6batch_size: 2
 7grad_accum_steps: 8                    # 等效 batch = 2 * 8 = 16
 8num_iters: 1000
 9log_interval: 10
10valid_interval: 500
11save_interval: 500
12learning_rate: 0.0001
13weight_decay: 0.01
14warmup_steps: 100
15max_steps: 1000
16max_batch_tokens: 8192                 # 樣本級長度上限（OOM 防線）
17max_grad_norm: 1.0
18save_path: /path/to/checkpoints/finetune_lora
19tensorboard: /path/to/logs/finetune_lora
20
21lambdas:                               # 多任務 loss 權重
22  loss/diff: 1.0                       # diffusion (latent reconstruction) loss
23  loss/stop: 1.0                       # stop token loss
24
25lora:
26  enable_lm: true                      # MiniCPM-4 LM 側加 LoRA
27  enable_dit: true                     # LocDiT 側加 LoRA
28  enable_proj: false                   # projection 層不加
29  r: 32
30  alpha: 32
31  dropout: 0.0

Training data 格式（JSONL）

1{"audio": "examples/example.wav", "text": "transcript here."}
2{"audio": "/abs/path/to/audio1.wav", "text": "支援絕對路徑"}
3{"audio": "relative/path/to/audio2.wav", "text": "或相對於工作目錄的相對路徑"}
4{"audio": "data/audio3.wav", "text": "...", "duration": 3.5}
5{"audio": "data/audio4.wav", "text": "...", "duration": 2.8}
6{"audio": "data/audio5.wav", "text": "...", "dataset_id": 1}

可選欄位：

• duration（秒）— 預先填入可跳過 filter 階段的音檔載入，加速資料準備
• dataset_id — 多資料集訓練時做 weighting / sampling

4.4 lora_ft_webui.py：整合式微調 + 推理 WebUI

最大的 helper（46 KB），提供完整 Gradio 介面：

• 上傳音檔 + 逐字稿 → 自動生 manifest
• 啟動 LoRA 訓練 → 即時看 loss / mel spec
• 訓完直接切到 inference tab，跑 cloning demo
• LoRA hot-swap：runtime 切換不同 LoRA 權重，免重 load 基礎模型

對非工程背景的內容創作者：這個 WebUI 是最容易上手的路徑。

4.5 其他 scripts

5. 應用場景：5 大用法 + 進階模式

5.1 用法 A：Voice Design — 純文字描述生語音（VoxCPM 2 限定）

場景：不想找參考音、想要全新虛擬角色聲音。

格式：把聲音描述寫在 text 開頭的括號內：

 1from voxcpm import VoxCPM
 2import soundfile as sf
 3
 4model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
 5
 6wav = model.generate(
 7    text="(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM2!",
 8    cfg_value=2.0,
 9    inference_timesteps=10,
10)
11sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

描述語常用 prompt 範例：

穩定性提醒（從 README 「Risks and Limitations」）：voice design 與 controllable cloning 的結果在 run 之間會浮動，建議跑 1-3 次取最滿意的版本。

5.2 用法 B：Voice Cloning — 參考音色克隆

場景：已有目標說話者的音訊（哪怕只是幾秒鐘），複製其音色說新內容。

1wav = model.generate(
2    text="This is a cloned voice generated by VoxCPM2.",
3    reference_wav_path="path/to/voice.wav",
4)
5sf.write("clone.wav", wav, model.tts_model.sample_rate)

參考音建議：

• 長度：3~30 秒
• 內容：乾淨人聲、少背景噪音（可用 enable_denoiser=True 啟用 ZipEnhancer 去噪）
• 格式：常見 .wav / .mp3 / .flac 都可（透過 soundfile + librosa 處理）

5.3 用法 C：Controllable Voice Cloning — 克隆 + 風格控制

場景：克隆音色但要改說話情緒、語速、口吻。

1wav = model.generate(
2    text="(slightly faster, cheerful tone)This is a cloned voice with style control.",
3    reference_wav_path="path/to/voice.wav",
4    cfg_value=2.0,
5    inference_timesteps=10,
6)
7sf.write("controllable_clone.wav", wav, model.tts_model.sample_rate)

風格指令範例：slightly faster / slower / cheerful / sad / angry / whispering / shouting / excited。

5.4 用法 D：Ultimate Cloning — audio-continuation 雙音同入

場景：對音色重現有極高要求（如 audiobook 旁白、虛擬人配音）。

1wav = model.generate(
2    text="This is an ultimate cloning demonstration using VoxCPM2.",
3    prompt_wav_path="path/to/voice.wav",
4    prompt_text="The transcript of the reference audio.",
5    reference_wav_path="path/to/voice.wav",   # 可選；同時傳更穩
6)
7sf.write("hifi_clone.wav", wav, model.tts_model.sample_rate)

prompt_wav 跟 reference_wav 雖然可以是同一個檔案，但模型內部把它們當作不同 condition 處理：

• reference_wav_path → 經 LocEnc 編 speaker embedding（音色）
• prompt_wav_path + prompt_text → 當作 audio continuation 的前文（韻律 + 細節）

兩者並用得到的相似度最高。

5.5 用法 E：Streaming — realtime 對話 / 低延遲

 1import numpy as np
 2
 3chunks = []
 4for chunk in model.generate_streaming(
 5    text="Streaming text to speech is easy with VoxCPM!",
 6):
 7    chunks.append(chunk)
 8
 9wav = np.concatenate(chunks)
10sf.write("streaming.wav", wav, model.tts_model.sample_rate)

• 首 chunk 延遲：RTX 4090 上 < 1 s（VoxCPM 2 預設參數）
• 適合：voice agent、即時翻譯、現場字幕轉語音

5.6 進階：HTTP API（OpenAI-compatible）

透過 vLLM-Omni 把 VoxCPM 變成 OpenAI TTS-style HTTP 服務：

1# 啟動
2vllm serve openbmb/VoxCPM2 --omni

1from openai import OpenAI
2client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
3resp = client.audio.speech.create(
4    model="openbmb/VoxCPM2",
5    voice="alloy",
6    input="Hello from OpenAI-style API!",
7)
8resp.stream_to_file("out.mp3")

vLLM-Omni 的 PagedAttention 與 batching 對多 concurrent request 場景有顯著加速（社群實測：8 concurrent requests 比單獨 Gradio app 快 3-5 倍）。

5.7 進階：LoRA Fine-tune 自訂角色

準備資料：

1. 收集目標聲音 5-30 分鐘乾淨音檔
2. 切成 3-15 秒短段 + 對應逐字稿（可用 ASR 自動標然後人工校正）
3. 寫成 JSONL 格式（見 §4.3 訓練資料格式）

改 YAML：

1cp conf/voxcpm_v2/voxcpm_finetune_lora.yaml my_lora.yaml
2# 修改 pretrained_path、train_manifest、save_path

訓練：

1python scripts/train_voxcpm_finetune.py --config_path my_lora.yaml
2# 1000 iter 在 RTX 4090 上約 30-60 分鐘（資料量小時）

載入 LoRA 推理：

1from voxcpm import VoxCPM
2from voxcpm.model.voxcpm import LoRAConfig
3
4model = VoxCPM.from_pretrained(
5    "openbmb/VoxCPM2",
6    load_denoiser=False,
7    lora_weights_path="/path/to/checkpoints/finetune_lora/lora_weights.ckpt",
8)
9# 之後 model.generate(...) 就會用到 LoRA 微調的權重

LoRA hot-swap：可以準備多個 LoRA（不同角色），runtime 切換時不重新載基礎模型，省記憶體。

5.8 整套 inference 場景對照

flowchart TD
    A[手上有什麼?] --> B{場景}
    B -->|純文字 想生新聲音| C[Voice Design
text 內加括號描述]
    B -->|有目標說話者 短音檔| D[Voice Cloning
reference_wav_path]
    B -->|克隆 + 改情緒風格| E[Controllable Cloning
reference + 括號描述]
    B -->|要極致還原音色| F[Ultimate Cloning
reference + prompt_wav + prompt_text]
    B -->|realtime 低延遲| G[Streaming
generate_streaming]
    B -->|HTTP service| H[vLLM-Omni
OpenAI-compatible API]
    B -->|有 5-30 分鐘專屬語料| I[LoRA Fine-tune
train_voxcpm_finetune.py]
    C --> Z[output 48 kHz wav]
    D --> Z
    E --> Z
    F --> Z
    G --> Z
    H --> Z
    I --> J[LoRA ckpt] --> D
    I --> J --> E
    I --> J --> F

6. 資安掃描報告

掃描時間：2026-06-02 / 掃描範圍：*.py *.yaml *.yml + LICENSE / pyproject

6.1 🟢 低風險項目（OpenBMB 工程品質高）

• Apache-2.0 license：LICENSE 檔完整，可商用、可再散佈、可改製。
• 無 eval() / exec() / os.system / shell=True：所有 grep 命中是 model.eval()（PyTorch 模式切換）、tokenizer(...)（HF tokenizer）、或 test subprocess.run（合法 CLI 測試）。
• 無硬編碼 secret：完全沒有 token / API key / 密碼字串。
• 無 pickle.load / joblib.load 載入不信任資料：只用 PyTorch state_dict + safetensors 載入模型權重。
• HTTP 抓資料只走 HuggingFace 與 ModelScope 官方 endpoint：snapshot_download 從 trusted hub 拉，不會跳到任意 URL。
• pyproject.toml 依賴鎖定合理：torch / transformers / gradio 等都有明確版本邊界。

6.2 🟡 中度風險項目（需要使用者了解）

6.2.1 Voice cloning 倫理 / 法律風險（最高優先）

README.md 的 Risks and Limitations 章節已明確警告：

Potential for Misuse: VoxCPM’s voice cloning can generate highly realistic synthetic speech. It is strictly forbidden to use VoxCPM for impersonation, fraud, or disinformation. We strongly recommend clearly marking any AI-generated content.

實務考量：

強烈建議：production 服務端做以下事情：

1. 限制 reference audio 的來源（如限定使用者上傳自己的、或來自 license 確認過的 dataset）
2. 對生成的音檔嵌入 audio watermark（如 AudioSeal 或 WavMark）
3. 明顯標示 AI 生成（語音前後加 disclaimer / metadata ai_generated: true）
4. 記錄 audit log，發生爭議時可追溯

6.2.2 ZipEnhancer denoiser 預設從 ModelScope 拉模型

1zipenhancer_model_path: str | None = "iic/speech_zipenhancer_ans_multiloss_16k_base"

• 預設啟用會 background download iic/speech_zipenhancer_ans_multiloss_16k_base
• 來源是 ModelScope 上的阿里 DAMO Academy 維護的模型（信任度高，但屬第三方）
• 若 corporate 環境禁止 outbound 連 ModelScope，會卡住

建議：在 air-gapped 環境或對外網有限制的情境，明示傳 load_denoiser=False 跳過。

6.2.3 funasr

funasr 是 ModelScope ASR 工具鏈，會拉一大堆 transitive dependency（PaddlePaddle / kaldi-fbank 等等）。

• 對純 inference 用戶：funasr 主要用在訓練 data 驗證階段，inference 不會載
• 對 production 服務：建議 fork 後剝掉 funasr 依賴重新 build

6.2.4 Training data 走 JSONL 接外部 audio path

1# scripts/train_voxcpm_finetune.py
2# data 從 JSONL 讀 "audio" 欄位、用 soundfile.read / librosa.load 載音檔

• 風險：JSONL 可被 user 控；音檔路徑指向任意位置
• 但只用 soundfile / librosa 載音訊（不是 pickle / 任意執行）
• 攻擊面有限：最壞情況是讀到不應該讀的音檔，或載入損壞的音檔 crash

建議：在多租戶 / 外部 user 提供訓練資料的場景，沙盒化 audio path（限制只讀指定目錄）。

6.2.5 spaces

1dependencies = ["spaces", ...]

• spaces 是 HuggingFace 為自家 Spaces 部署提供的 SDK
• 本地 inference / 自架服務 完全不會用到，但被列為硬依賴
• 影響：略增安裝體積，理論上若 spaces 套件被劫持有供應鏈風險

建議：可以 fork 後從 dependencies 移除 spaces，不影響本地功能。

6.2.6 app_old.py

app_old.py（12 KB）是舊版 Gradio app，已被 app.py 取代但保留作為歷史參考。code review 角度：兩份 app 並存讓使用者可能不知道用哪個（特別是直接 fork 後）。

建議：fork / 內部使用時刪掉 app_old.py 避免混淆。

6.3 🔴 高風險項目

無高風險 finding。整體工程品質 OpenBMB 維持得不錯。

6.4 結論

整體判定：🟢 工程上安全可用 production；🟡 倫理 / 法律風險須由 deploy 端負責（watermark、disclaimer、audit log、user consent）。

7. FAQ

Q1: VoxCPM 跟 CosyVoice 2 / IndexTTS 2 / F5-TTS 比，到底差在哪？

答：路線不同，各有強項。

• CosyVoice 2 / IndexTTS 2：discrete codec + AR/diffusion，技術成熟、生態大，但 codec 的固定 token 量會限制細節（短句 / 極端 prosody 容易掉）
• F5-TTS：純 flow matching、無 LM 端 AR，訓練成本低，但多語言支援與細粒度控制不及 VoxCPM 2
• VoxCPM 2：tokenizer-free + diffusion AR、有 LM backbone（MiniCPM-4），支援 30 種語言 + voice design，是少數有完整 voice design + controllable cloning + Apache-2.0 商用授權 + 完整生態系的開源 TTS

選法：要中英日韓乾淨場景用 CosyVoice 2 / F5；要多語言或自訂角色用 VoxCPM 2。

Q2: VoxCPM 1.5 與 VoxCPM-0.5B 還值得用嗎？

答：

• VoxCPM 1.5：中英場景、想省顯存（6 GB vs 8 GB）、不需 voice design 時還有用
• VoxCPM-0.5B：除了學術復現 ICLR 2026 paper，新專案直接跳 VoxCPM 2

Q3: voice design 的 prompt 怎麼寫才有效？

答：根據 README + 社群實證：

• 用英文描述比中文穩（模型訓練時英文 condition 樣本較多）
• 描述要明確：性別 + 年齡層 + 音色形容詞 + 語境
• 例：(A young Asian woman in her 20s, soft and bright voice, like a kindergarten teacher)
• 不要疊太多形容詞（3-5 個關鍵字最穩）
• 跑 1-3 次取最好的（穩定性還在改進中）

Q4: voice cloning 對 reference audio 的要求？

答：

• 長度：3-30 秒最穩；< 3 秒可能音色不夠資訊；> 30 秒模型可能只用前 30 秒
• 音質：建議 SNR > 20 dB；有噪音可開 enable_denoiser=True 走 ZipEnhancer
• 內容：人聲為主，少音樂 / 多人混雜
• 格式：.wav / .mp3 / .flac 任意；採樣率會自動 resample 到模型要求

Q5: 怎麼讓生成的語音更穩定（少走音、字錯）?

答：

• 增加 inference_timesteps（從 10 → 20 → 30，慢但穩）
• 調整 cfg_value（1.0-3.0，太大會過度引導變不自然，太小弱化條件）
• 拆長句：模型對短句更穩；長段落建議拆 2-3 句後串接
• 文字正規化：把數字、縮寫、特殊符號展開為文字（"$100" → "one hundred dollars"）— VoxCPM 內建 wetext 處理大部分中英常見場景

Q6: 30 種語言具體是哪些？

答：README 沒列出完整清單，但 CV3-eval / Minimax-Multilingual-Test 涵蓋的至少有：

• 中（zh）/ 英（en）/ 日（ja）/ 韓（ko）/ 德（de）/ 西（es）/ 法（fr）/ 義（it）/ 俄（ru）/ 阿拉伯（ar）/ 粵語（cantonese）/ 捷克（cs）/ 荷蘭（nl）/ 芬蘭（fi）/ 葡萄牙（pt）/ 土耳其（tr）/ 越南（vi）/ ……
• 不在訓練集的語言可以直接測，效果取決於該語言的音素 / 字母與 30 種訓練集的重疊度

Q7: LoRA 微調需要多少音檔？

答：根據官方說法 5-10 分鐘就能跑。實際經驗：

• 5-10 分鐘：能克隆音色基本特徵；對 voice design + style control 還不穩
• 30-60 分鐘：明顯改善；能處理較多語境
• 數小時：接近全量 SFT 效果；可作為個人化的 production-ready 配置

訓練時間（RTX 4090）：

• 1000 iter / batch 2 / grad accum 8 ≈ 30-60 分鐘（資料量 30 分鐘音檔時）

Q8: 為什麼 first inference 很慢？

答：optimize=True（預設）會跑 torch.compile warmup，第一次跑會編譯 graph。core.py:__init__ 結尾有 warm-up 邏輯（用 "Hello, this is the first test sentence." 跑一次）。

1# 想 debug / 開發時跳過：
2model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False, optimize=False)

Q9: 跟 vLLM-Omni 整合的效益是什麼？

答：

• PagedAttention：對長 prompt 記憶體效率高很多
• Continuous batching：多 concurrent request 一起跑，吞吐量 3-5 倍
• OpenAI-compatible API：任何 OpenAI SDK / Langchain / LiteLLM 都能直接接

代價：vLLM-Omni 還在快速演進，安裝有時要從 source；需要 GPU（不是 CPU 版）。

Q10: 想做 CPU only / edge deploy 怎麼辦？

答：用社群衍生版：

• VoxCPM.cpp：GGUF 格式，CPU / CUDA / Vulkan 都跑
• VoxCPM-ONNX：ONNX runtime，純 CPU 場景
• VoxCPMANE：Apple Neural Engine，M 系列 Mac 最快
• voxcpm_rs：Rust 純實作

注意這些是社群維護、可能不全跟上 VoxCPM 2 的功能（特別是 voice design）。

Q11: 為什麼 streaming chunk 拼起來會有 click 聲？

答：streaming 邊界處可能有微小不連續。修補方法：

• 用 librosa 的 cross-fade：librosa.effects.split + 短 fade-in/out
• 或在 chunk 邊界用 raised cosine window 重疊融合

Q12: 我能訓 multi-speaker LoRA 嗎？

答：可以，jsonl 的 dataset_id 欄位就是為此設計。但 LoRA 容量有限，多 speaker 共用一份 LoRA 效果會稀釋；建議：

• 每個 speaker 訓一個獨立 LoRA
• 用 LoRA hot-swap 機制 runtime 切換

Q13: 商業使用要付錢嗎？

答：模型本體不用（Apache-2.0）。但：

• ZipEnhancer denoiser 是 DAMO Academy 釋出的，許可證需個別確認
• 你用的 reference audio 須有合法授權
• 衍生服務若涉及第三方人聲克隆，需取得當事人同意

Q14: 安裝失敗：error: Microsoft Visual C++ 14.0 or greater is required（Windows）

答：torchcodec 在 Windows 上需 MSVC build tools。

• 裝 Visual Studio Build Tools
• 或在 WSL2 跑（推薦）

Q15: macOS Apple Silicon 跑得起來嗎？

答：可以，2026-05 之後 Mac MPS 支援已合入：

• 升級到 v2.0.3+ / main branch
• 啟動時指定 device="mps"
• 效能：M3 Max 約 RTX 3080 一半左右

8. 進階技巧

8.1 提高 voice cloning 相似度的工程技巧

1. 同檔同入：reference_wav_path 與 prompt_wav_path 傳同一個檔案（ultimate cloning 模式）
2. clean reference：先用 ZipEnhancer 預先處理過的乾淨 reference 跑 cloning，比 raw 髒音檔好
3. 長 prompt_text：完整、逐字精確的 prompt_text 能讓 ultimate cloning 抓更細的韻律
4. 多次取最佳：voice cloning 結果有 run 間變異；同樣輸入跑 3-5 次選最好的（內部評測時可用 SIM score 自動選）

8.2 用 ASR 自動化 prompt_text 標註

訓練資料 / ultimate cloning 都需要逐字稿。建議走：

1from funasr import AutoModel
2asr = AutoModel(model="iic/SenseVoiceSmall")
3result = asr.generate(input="reference.wav")
4prompt_text = result[0]["text"]

funasr 已是 VoxCPM 依賴，所以這條路徑「免費」可用。

8.3 多 LoRA hot-swap pattern

production 場景常見「10 個角色語音」的需求：

 1# 載入基礎模型一次
 2model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
 3
 4# 預先準備角色 LoRA dict
 5LORAS = {
 6    "narrator": "/loras/narrator.ckpt",
 7    "character_a": "/loras/character_a.ckpt",
 8    "character_b": "/loras/character_b.ckpt",
 9}
10
11# 切換時不重 load base 模型
12def speak(role, text):
13    # 假設 tts_model 有 load_lora_weights / unload_lora 方法
14    model.tts_model.load_lora_weights(LORAS[role])
15    return model.generate(text=text)

具體 API 細節參考 src/voxcpm/model/voxcpm2.py 的 load_lora_weights 與 lora_ft_webui.py 內的實作。

8.4 用 audio watermark 標示 AI 生成內容

1# 範例（用 AudioSeal 為例）
2from audioseal import AudioSeal
3ws = AudioSeal.load_generator("audioseal_wm_16bits")
4watermarked = ws.get_watermark(wav, sample_rate=48000)
5final_wav = wav + watermarked   # 不可聽見、可由 detector 解出

production 服務在 generate 後固定 append watermark，是負責任的 deploy 行為。

8.5 用 vLLM-Omni 部署 production 服務的 Docker 範本

1FROM vllm/vllm-omni:latest
2RUN pip install voxcpm
3EXPOSE 8000
4CMD ["vllm", "serve", "openbmb/VoxCPM2", "--omni", "--host", "0.0.0.0"]

部署考量：

• GPU 至少 12 GB VRAM（VoxCPM 2 + vLLM batching overhead）
• 預熱 warmup 跑 2-3 個 dummy request 後再開放外部流量
• 設 --max-concurrent-requests（vLLM 參數）避免 OOM

8.6 跨多 GPU 切 batch

如果有多卡，最簡單的方式不是 model parallel，而是 data parallel + batch 分流：

1import torch
2# GPU 0 處理 batch[:N//2]，GPU 1 處理 batch[N//2:]
3# 用 torch.distributed 或簡單 multiprocessing.Pool 即可

VoxCPM 預設沒做 tensor parallel；要做的話走 vLLM-Omni 的 --tensor-parallel-size 參數。

8.7 Fine-tune debugging：哪些 metric 該看

scripts/train_voxcpm_finetune.py 寫到 TensorBoard 的關鍵：

異常徵兆：loss/diff 不下降 → 可能 LoRA r 太小、learning rate 太高、資料不乾淨；loss/stop 跳動劇烈 → batch 內句長分布太散，調整 max_batch_tokens。

9. 整合進其他工作流

9.1 整合進 AI knowledge template

9.2 應用情境模板

9.2.1 內部 podcast / 有聲書製作

1text 文件 → 拆段 → VoxCPM 2 voice design / cloning → 合成 → 後製剪輯 → 發布
2                                                       ↓
3                                                  audio watermark + metadata

預估產能：每分鐘最終音檔 1-2 分鐘 GPU 算力（RTX 4090）。

9.2.2 多語言客服 voice agent

flowchart LR
    A[使用者語音] --> B[ASR：funasr / Whisper]
    B --> C[LLM 思考]
    C --> D[VoxCPM 2 streaming]
    D --> E[使用者]
    D -.->|LoRA 切角色| F[特定品牌 voice]

9.2.3 虛擬人 / VTuber 即時對話

• LoRA fine-tune 出固定角色 voice
• vLLM-Omni 提供 streaming HTTP API
• 上游接 LLM、下游接 lipsync / 動畫渲染

9.2.4 多媒體教育內容生成

• 從教案 markdown 抓段落 → VoxCPM 旁白
• 可隨時換語言版本（30 種支援）
• 配合投影片視覺化做 multi-modal 教材

9.3 與 OpenBMB 生態系串接

OpenBMB 旗下其他重要開源模型：

• MiniCPM 系列：VoxCPM backbone 來源、純文字 LLM
• MiniCPM-V / MiniCPM-o：multi-modal 視覺 / 音訊 LLM
• CPM-Bee：早期中英雙語 LLM

把 VoxCPM 與 MiniCPM-V 串起來可做：「圖片描述 → 文字 → 語音」三段 pipeline；都從 OpenBMB 的同一個 backbone 家族出來，整合風險低。

10. 重點摘要 Checklist

10.1 概念與架構

• 能解釋 tokenizer-free vs codec-based TTS 的差異
• 能畫出 LocEnc → TSLM → RALM → LocDiT → AudioVAE 四段 pipeline
• 能說明 voice design / cloning / controllable / ultimate cloning 四種模式的條件差異
• 能說出 VoxCPM 2 / 1.5 / 0.5B 三個版本的關鍵差異（30 種 vs 2 種語言、48 kHz vs 16 kHz、voice design 有無）
• 能說出 conditional flow matching（CFM）在 LocDiT 內的角色

10.2 安裝與環境

• 能成功 pip install voxcpm 並跑出第一個 .wav
• 知道何時用 HuggingFace、何時用 ModelScope 下載權重
• 能啟動 app.py Gradio WebUI
• 能啟動 lora_ft_webui.py 進入微調流程
• 知道如何切到 Mac MPS / CPU

10.3 API 與 CLI

• 能用 Python API 跑完所有 5 大用法（design / cloning / controllable / ultimate / streaming）
• 能用 voxcpm CLI 做 batch 處理
• 能調整 cfg_value 與 inference_timesteps 找到品質 / 速度甜蜜點
• 知道如何用 wetext 預先做文字正規化

10.4 進階 / Production

• 能寫 JSONL 並跑 LoRA fine-tune
• 能 hot-swap 多個 LoRA
• 能用 vLLM-Omni 開 HTTP service
• 在生成音檔加 audio watermark
• 在 deploy 服務側設 misuse 防護（user consent、audit log）

10.5 倫理與法律

• 對任何 AI 生成語音明顯標示
• 對第三方語音做 cloning 前取得當事人同意
• 知道 Apache-2.0 的權利與義務
• 對 production 使用者做 KYC（必要時）

11. 進一步閱讀

11.1 官方資源

• 官網：https://voxcpm.com
• 完整文件：https://voxcpm.readthedocs.io/en/latest/
  • Quick Start
  • User Guide / Cookbook
  • Architecture Design
  • Version History
  • Fine-tuning Guide
  • FAQ / Troubleshooting
• 論文：arXiv:2509.24650 / ICLR 2026 OpenReview
• Demo 頁：VoxCPM 2 / VoxCPM-0.5B

11.2 重要參考論文（書中明確致謝）

• DiTAR（2025）— diffusion autoregressive backbone：https://arxiv.org/abs/2502.03930
• MiniCPM-4（2024+）— language model 主幹：https://github.com/OpenBMB/MiniCPM
• CosyVoice（2024）— flow matching LocDiT 啟發：https://github.com/FunAudioLLM/CosyVoice
• DAC（2023）— Audio VAE 設計參考：https://github.com/descriptinc/descript-audio-codec

11.3 比較 / 競品

• F5-TTS：https://github.com/SWivid/F5-TTS（flow matching）
• CosyVoice2：https://github.com/FunAudioLLM/CosyVoice（codec + AR）
• IndexTTS2：https://github.com/index-tts/index-tts（codec + diffusion）
• FishAudio S2：https://github.com/fishaudio/fish-speech
• Spark-TTS：https://github.com/SparkAudio/Spark-TTS
• Qwen3-TTS：阿里巴巴新一代

11.4 生態系（社群維護衍生）

• Nano-vLLM：輕量高吞吐 serving
• vLLM-Omni：官方 vLLM multi-modal 服務（OpenAI compatible）
• VoxCPM.cpp：GGUF（CPU / CUDA / Vulkan）
• VoxCPM-ONNX：ONNX export
• VoxCPMANE：Apple Neural Engine
• voxcpm_rs：Rust 重寫
• ComfyUI 節點：wildminder/ComfyUI-VoxCPM / HM-RunningHub/ComfyUI_RH_VoxCPM / 1038lab/ComfyUI-VoxCPMTTS
• TTS WebUI extension：與 TTS WebUI 整合

11.5 倫理 / 法律參考

• AudioSeal — Meta 的音訊浮水印（可嵌入 SOTA 模型輸出）
• WavMark — 另一個 audio watermarking 框架
• C2PA — Content Authenticity 標準
• 各國對 deepfake 的立法狀況變動快，部署前查詢當地法規

11.6 機構

• ModelBest — OpenBMB 商業實體
• THUHCSI — 清華大學 Human-Computer Speech Interaction Lab

📅 教學文件版本：2026-06-02 / 對應 repo commit ≤ 2026-05-22 / 對應 release v2.0.3 / 由 AI Knowledge Template Layer 12（gh-tutorial-qd）自動產生

🔐 重要倫理提醒：voice cloning 屬高敏感技術。production 部署必須：1) 取得被克隆者書面同意；2) 對生成音檔嵌入 watermark；3) 明顯標示 AI 生成；4) 保留 audit log。