Voicebox Windows 原生部署：語音克隆、Qwen3-TTS、Whisper 與 MCP 整合

Voicebox 是一款本地優先的開源 AI 語音工作台，整合了語音複製、文字轉語音、Whisper 語音辨識、全域語音輸入、REST API 及 MCP 伺服器於單一桌面應用程式中。

它支援 Windows CUDA、macOS MLX、Linux、AMD ROCm、Intel Arc 及 Docker。Windows 使用者可直接安裝 MSI，無需先設定 Python 專案。模型、參考音訊及產生結果預設儲存在本地，適合不需上傳音效至第三方服務的情境。

快速回答

在 Windows 上最簡單的方法是從 Voicebox Releases 下載 MSI。首次執行後，只安裝一個適合 VRAM 的 TTS 引擎，先將一般文字轉為語音，然後加入語音複製的參考音訊。當你需要讓 Claude Code、Cursor或其他代理程式發出聲音時，請在 Voicebox 的 MCP 設定中啟用該服務，並依介面產生的位址設定客戶端。

不要一次下載所有模型。Qwen3-TTS、Chatterbox、TADA 和 Whisper 分別會佔用硬碟和顯示記憶體，太多模型會讓初期故障排除變得困難。

Voicebox 能做什麼？

目前專案結合了輸入與輸出的兩個語音連結：

利用幾秒鐘的參考音訊建立音效配置;
產生語音引擎，如 Qwen3-TTS、Chatterbox、Kokoro;
使用 Whisper 將麥克風或音訊檔案轉換為文字;
使用全域捷徑在其他應用程式中進行語音輸入;
啟用 AI 代理透過 REST API 或 MCP 呼叫語音;
在故事編輯器中結合多角色對話、播客或旁白;
在產生的結果中加入混響、音高變化和壓縮等效果。

README 專案目前列出 7 個 TTS 引擎和 23 種語言，但每個引擎支援不同的語言、記憶體需求與效能。因此，「支援 23 種語言的應用程式」不能理解為支援所有模型的所有語言。

Windows 安裝步驟

1.檢查顯示卡和驅動程式

NVIDIA 使用者先執行：

1

nvidia-smi

若指令不存在或無法顯示驅動程式資訊，請先修復顯示卡驅動程式。成功安裝 Voicebox 不一定代表 CUDA 推理可行。

沒有 NVIDIA 顯示卡的話，你也可以嘗試 CPU 或專案支援的其他後端，但世代速度和可用型號都會受到影響。

2.下載 MSI

從官方發佈頁面下載最新的 Windows 安裝程式：

1

https://github.com/jamiepine/voicebox/releases/latest

安裝後，從開始選單啟動。若 Windows SmartScreen 提示未知發佈者，請先確認下載連結、版本檔名及專案儲存庫;不要尋找第三方雲端硬碟的所謂綠色版本。

3.僅下載了一款模型進行測試

第一個測試可由硬體選擇：

劇本	推薦起始點
CPU 或顯示記憶體非常小	Kokoro 或 LuxTTS
需要中文、多語言及語音複製	Qwen3-TTS 0.6B
強調表情控制	Qwen3-TTS 1.7B 或 Qwen CustomVoice
需要更多語言覆蓋	多語言者

具體可用的模型是根據應用程式目前的模型管理頁面。下載模型後，先輸入一段簡短文字以產生預設語音，確認後端正常，然後建立音效設定。

建立語音複製設定

參考音訊會直接影響結果。建議：

使用無背景音樂或混響的單人錄音;
保持自然的語速與穩定的音量;
消除長時間的寂靜和明顯的噪音;
只使用你授權的聲音;
先用短句測試;不要直接生成長篇文章。

在 Voice Profile 上傳或錄製參考音訊，選擇支援零鏡頭複製的引擎，然後輸入測試文字。不同引擎對參考音訊長度和轉錄準確度有不同要求。如果某個引擎表現不佳，你可以切換引擎進行比較，而不只是增加音量。

使用耳語進行口述與轉錄

Voicebox 的語音輸入使用 Whisper，你可以選擇基本、小、中、大或渦輪等尺寸。通常：

小型模型下載快速且使用率低，適合日常口述;
大型模型較重，適合重音、噪音或複雜內容;
渦輪適合在保持良好品質的前提下提升速度的任務。

全域語音輸入需要系統麥克風權限。如果你看到「可錄音但無法貼上」，請檢查麥克風權限、Voicebox 快捷鍵衝突，以及目標應用程式是否允許自動輸入。

整合MCP代理

Voicebox 內建 MCP 伺服器，允許支援 MCP 的用戶端呼叫voicebox.speak。建議的流程如下：

在 Voicebox 中完成一次手動語音生成;
開啟 MCP →設定;
啟用 MCP 並複製介面提供的連接資訊;
在 Claude Code、Cursor、Cline 或其他 MCP 用戶端中新增服務;
讓代理人只說一句簡短的話來確認連結與聲音配置;
然後將不同的語音設定檔綁定到不同的代理。

該專案提供 HTTP 與 stdio 傳輸方法。不要依賴舊有的手寫埠與二進位路徑教學;優先使用目前版本設定頁面產生的配置。

代理語音適合用於完成通知、核准問題及簡短狀態提示。請勿讓它大聲朗讀完整日誌，因為這會佔用生成佇列，且難以從語音中發現技術錯誤。

運行 Docker

專案 README 提供的 Docker 入口點為：

1

docker compose up

Docker 更適合 Linux 伺服器或想隔離相依的使用者。如果你需要 Windows 上的 GPU，請確保 Docker Desktop、WSL2、NVIDIA 驅動程式和容器 GPU 支援都是正常的。桌面語音輸入和全域捷徑更適合原生 MSI 版本。

官方docker-compose.yml預設使用 CPU 組裝，且不會自動使用 NVIDIA GPU。它限制服務僅限於本地迴圈位址：

1

127.0.0.1:17600 -> container:17493

因此，Docker 版本的健康檢查應該存取主機的17600，而非桌面版本常用的17493：

1

Invoke-RestMethod http://127.0.0.1:17600/health

Compose 檔案也定義了三種類型的持久資料：

資料	預設位置	功能
產生音訊	`./output`	方便直接從主持人讀取結果
`voicebox-data`	Docker 命名磁碟區	儲存設定檔、資料庫及應用程式資料
`huggingface-cache`	Docker 命名磁碟區	重建後避免重新下載模型

停止容器時請勿添加-v：

1

docker compose down

docker compose down -v也會刪除命名的卷，這可能導致模型快取和應用程式資料同時消失。

理解為什麼第一代人會比較慢

官方故障排除說明指出，第一代可能需要 2 至 5 分鐘，因為應用程式需要下載並初始化模型。型號大小因引擎而異：Kokoro 約為 350 MB，而 TADA 3B 則可達約 8 GB。

在第一次測試中，請依照以下順序觀察：

型號→設定是否顯示下載進度;
網路是否能存取 Hugging Face;
模型下載完成後，GPU 或 CPU 是否已開始運作;
檢查第二代是否明顯更快。

如果第一次很慢，第二次正常，那就不是故障。只有當下載進度長時間不變、日誌有錯誤，或每次啟動時下載都會重啟，才需要檢查網路和快取目錄。

對於頻寬較低或只是想確認安裝成功，官方建議先使用 Kokoro 或 LuxTTS，兩者下載容量約在 300–350 MB 之間，然後再決定是否安裝較大的克隆模型。

查看服務狀態與日誌

桌面應用程式的後端預設為 17493。如果左下角出現紅色狀態或Failed to connect to server訊息，請先檢查埠口：

1

Get-NetTCPConnection -LocalPort 17493 -State Listen

若有其他程序回傳，請記錄 PID：

1

Get-Process -Id (Get-NetTCPConnection -LocalPort 17493 -State Listen).OwningProcess

確認程序可停止後，正常關閉。不要因為未知系統程序看到埠口佔用就直接關閉。

Windows 服務日誌位於：

1

type %APPDATA%\sh.voicebox.app\logs\server.log

PowerShell 允許即時查看尾部：

1

Get-Content "$env:APPDATA\sh.voicebox.app\logs\server.log" -Tail 100 -Wait

日誌可區分至少四種問題類型：服務啟動失敗、模型下載失敗、CUDA/記憶體錯誤，以及音訊或資料庫錯誤。

`flash-attn is not installed` 應該修理嗎？

Windows 日誌可能會重複出現：

1

Warning: flash-attn is not installed. Will only run the manual PyTorch version.

官方文件明確指出此點通常可忽略。Windows 沒有穩定的官方 flash-attn 支援;Voicebox 使用 PyTorch 內建的 SDPA，語音仍可正常產生。請勿將此警告視為服務啟動失敗，也不建議安裝不匹配的社群輪盤來清除日誌。

只有當 Linux、CUDA 和 PyTorch 版本完全相容且效能確實受到限制時，才會考慮：

1

pip install flash-attn --no-build-isolation

編譯可能需要超過二十分鐘，且失敗不會影響預設後端的持續使用。

如何在 VRAM 與 CPU 模式間選擇

官方故障排除文件中，GPU產生的實際門檻使用超過6GB的顯存。不同引擎仍有差異，因此應以實際型號和文字長度作為標準。

當CUDA out of memory出現時，請依照以下順序處理：

關閉佔用 WebGL 的遊戲、影片編輯器及瀏覽器分頁;
在 Voicebox 中移除目前未使用的型號;
重新啟動應用程式並清除佔用但未釋放的顯存;
換成較小的型號;
分割長文;
最後，切換到 世代→設定 → 使用 CPU 而非 GPU。

CPU 模式使用系統記憶體，官方估計其速度可能是 GPU 的 5–10 倍。它適合驗證功能或低頻產生，而非為了持續批次任務而隱藏記憶體問題。

音質應該如何比較？

不要只根據一句話來評斷模型。準備一組固定的測試文本：

1
2
3
4
5


1. 普通陈述句：测试音色稳定性和自然停顿。
2. 数字与英文缩写：测试中英文混读。
3. 长句和逗号：测试呼吸与分句。
4. 专有名词：测试发音和文本规范化。
5. 情绪标签：只用于明确支持标签的引擎。

每個語音設定檔使用相同的文字集合、相同的輸出格式和相似的參數。官方建議使用10至30秒的清晰錄音作為參考音訊，並且可以加入多個來自同一喇叭的取樣片段。當音調相似但音調僵硬時，檢查參考取樣本身是否過於單調，而非僅僅增加取樣長度。

模型快取與資料備份

該應用程式提供模型目錄遷移及設定檔匯入與匯出功能。在升級、清理磁碟或重新安裝前，優先匯出應用程式中重要的設定檔並記錄模型目錄。

官方文件提供了直接刪除資料庫的復原方法，但這會導致語音設定檔和產生歷史遺失，因此無法作為一般故障排除的第一步。遇到 SQLite 鎖定時，先關閉所有 Voicebox 實例並備份資料，然後根據日誌處理鎖定檔案。

若模型版本異常，請勿直接刪除整個 Hugging Face 快取。首先，刪除 設定→模型中的特定模型;手動清理應限於模型目錄清晰，並確保應用程式已關閉。

請勿直接暴露埠口供遠端存取

Voicebox 後端提供健康檢查：

1

curl http://<server-ip>:17493/health

這僅驗證服務是否可達，並不代表適合直接暴露於公共網路。遠端使用至少需具備以下條件：

防火牆只允許受信任的來源;
透過 VPN、SSH 隧道或認證反向代理存取;
模型管理、設定檔及產生介面未公開;
檢查 MCP 用戶端是否將工具位址寫入同步設定中;
定期檢視你的訪視紀錄。

如果代理只在同一台電腦上被呼叫，127.0.0.1應該繼續綁定而不開啟 LAN 埠。

常見問題故障排除

模型下載卡住了

首先，檢查磁碟空間與網路，再確認 Hugging Face Hub 是否可存取。停用、清理及遷移 Voicebox 模型頁面時，優先使用內建功能，且不要直接刪除整個資料目錄。

當需要手動驗證時，你可以安裝 Hugging Face CLI，並嘗試單獨下載模型：

1
2


pip install huggingface_hub
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base

當 CLI 也無法下載時，問題通常出在網路、代理、磁碟或 Hugging Face 存取，而非 Voicebox 介面。

CUDA 可用，但在生成過程中缺乏影像記憶體

關閉其他 GPU 密集型程式、卸載未使用的模型、切換到較小的引擎或版本 0.6B，並縮短每次產生的文字量。雖然長文字可以自動分割，但仍會增加任務時間和快取使用量。

不自然的中文發音

確認目前引擎明確支援中文，並盡量將參考語音語言與生成的文字匹配。即使英文專用型號能讀中文，也不代表中文品質合格。

MCP 已設定好，但代理沒有聲音

首先，手動在語音盒內產生語音，然後檢查 MCP 用戶端是否找到voicebox.speak、語音設定檔名稱是否存在，以及語音盒是否仍在運行。將「工具未連接」與「語音產生失敗」分開進行調查。

隱私與語音授權

本地操作可降低上傳語音樣本的風險，但不會自動解決授權問題。請勿為冒充、詐騙或未經授權的公開內容複製他人聲音。公開發布產生音訊時，最好明確標示合成來源，並妥善保護參考音訊及匯出的語音設定檔。

參考資料

[Voicebox GitHub 倉庫]（https://github.com/jamiepine/voicebox）
[語音盒最新版本] （https://github.com/jamiepine/voicebox/releases/latest）
[Voicebox 官方文件]（https://docs.voicebox.sh/）