hmisaki/voicebox - 新增 TTS 引擎

新增 TTS 引擎

目標

端到端地將新的文字轉語音引擎整合至 Voicebox：包含依賴研究、後端協定實作、前端 UI 連接、PyInstaller 打包以及凍結建置驗證。使用者只需在本機測試最終建置結果。

參考文件

完整的階段性指南位於 docs/content/docs/developer/tts-engines.mdx。開始前請完整閱讀此檔案。 其中包含：

• 第 0 階段：依賴研究（寫程式碼前強制執行）
• 第 1 階段：後端實作（TTSBackend 協定）
• 第 2 階段：路由與服務整合（通常不需變更）
• 第 3 階段：前端整合（5 個檔案）
• 第 4 階段：依賴（requirements.txt、justfile、CI、Docker）
• 第 5 階段：PyInstaller 打包（build_binary.py + server.py）
• 第 6 階段：常見上游問題的暫時解決方案
• 實作檢查清單（各階段之間的關卡）

工作流程

1. 閱讀指南

# 讀取完整的 TTS 引擎文件
cat docs/content/docs/developer/tts-engines.mdx

內化所有階段，尤其是第 0 階段與第 5 階段。v0.2.3 版本因為跳過第 0 階段而經歷了三次修補版本。

2. 依賴研究（第 0 階段）

將模型庫複製到暫存目錄並進行審計。切勿跳過此步驟。

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <model-library-url>

針對克隆的原始碼及其傳遞依賴項，執行指南中第 0.2 階段的 grep 搜尋。產出一份書面依賴審計報告，涵蓋：

1. PyPI 與非 PyPI 套件
2. 所需的 PyInstaller 指示詞（--collect-all、--copy-metadata、--hidden-import）
3. 必須打包的執行時期資料檔
4. 需要在凍結建置中覆寫環境變數的原生函式庫路徑
5. 需要的猴子修補（torch.load、float64、MPS、HF token）
6. 取樣率
7. 模型下載方式（from_pretrained 與 snapshot_download + from_local）

在可拋棄的虛擬環境中，於 CPU 上測試模型載入與生成，確認無誤後再繼續。

3. 實作（第 1–4 階段）

按照指南中的階段順序進行。需要修改的關鍵檔案：

後端（第 1 階段）：

• 建立 backend/backends/<engine>_backend.py
• 在 backend/backends/__init__.py 中註冊（ModelConfig + TTS_ENGINES + factory）
• 更新 backend/models.py 中的正規表達式

前端（第 3 階段）：

• app/src/lib/api/types.ts — 引擎聯集型別
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS、ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — Zod schema、模型名稱映射
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

依賴（第 4 階段）：

• backend/requirements.txt
• justfile（setup-python、setup-python-release 目標）
• .github/workflows/release.yml
• Dockerfile（如適用）

4. PyInstaller 打包（第 5 階段）

在 backend/build_binary.py 中註冊引擎：

• --hidden-import 用於後端模組與模型套件
• --collect-all 用於使用 inspect.getsource、包含資料檔或原生函式庫的套件
• --copy-metadata 用於使用 importlib.metadata 的套件

如果引擎有原生資料路徑，請在 backend/server.py 中 if getattr(sys, 'frozen', False): 區塊內加入 os.environ.setdefault()。

5. 在開發模式中驗證

just dev

測試完整流程：模型下載 → 載入 → 生成 → 語音複製。

6. 使用檢查清單

仔細檢查 tts-engines.mdx 底部的實作檢查清單。在將建置結果交給使用者之前，每一項都必須確認無誤。

關鍵經驗（來自 v0.2.3）

以下是最常見的失敗模式。第 0 階段的研究可以發現所有這些問題：

模式	凍結建置中的症狀	修正方式
@typechecked / inspect.getsource()	"could not get source code"	--collect-all <package>
套件包含預訓練模型檔案	FileNotFoundError，找不到 .pth.tar、.yaml	--collect-all <package>
C 函式庫具有硬編碼的系統路徑	FileNotFoundError，找不到 /usr/share/...	--collect-all + 在 server.py 中設定環境變數
importlib.metadata.version()	"No package metadata found"	--copy-metadata <package>
未指定 map_location 的 torch.load	CUDA 裝置在 CPU 建置中不可用	猴子修補 torch.load
對 float64 資料執行 torch.from_numpy	dtype 不符的 RuntimeError	轉換為 .float()
HF 下載呼叫中的 token=True	因未儲存 HF token 導致認證失敗	使用 snapshot_download(token=None) + from_local()

備註

• 路由與服務層沒有每個引擎的調度點。main.py 不需要任何變更。
• backends/__init__.py 中的模型配置註冊表會自動處理所有調度。
• 請使用 backends/base.py 中的 get_torch_device() 和 model_load_progress()，不要重新實作裝置檢測或進度追蹤。
• 務必使用乾淨的 HuggingFace 快取（沒有任何從開發環境預先下載的模型）進行測試。
• 不要推送或建立版本。將建置結果交給使用者進行本機測試。