vox-tts
一個自託管的 TTS 服務,位於 https://vox.delo.sh,包裝了 VoxCPM2,並具有 PostgreSQL 支援的聲音設定檔儲存及多引擎支援。部署於 ~/code/voxxy(核心:compose.yml,GPU 引擎:compose.engines.yml——兩個引擎容器都必須啟動,否則複製的聲音會無聲退化,詳見下文)。
快速參考
| 動作 | 方式 |
|---|---|
| 一次性合成(內嵌 WAV 位元組) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| 為 Telegram / 瀏覽器 / HA / Discord 傳遞而合成 | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| MCP 工具:內嵌位元組(base64 WAV) | speak(text, voice?) |
| MCP 工具:傳遞 URL(OGG/Opus,Telegram 就緒) | speak_url(text, voice?) |
| MCP 工具:列出聲音 | list_voices_tool() |
| 列出聲音(HTTP) | GET /voices |
| 添加聲音 | POST /voices(multipart:name, display_name, audio) |
| 互動式聲音複製(使用者說「把我的聲音複製成…」) | 請見下方的 互動式聲音複製工作流程 |
| 升級引擎(VoxCPM / VibeVoice) | 請見下方的 引擎升級工作流程 |
| 從 Hermes 代理說話 | 原生 tts.provider: vox(fleet 基礎);fleet 不會載入 vox MCP |
| 從 shell / 任何具有終端的代理說話 | voxxy speak "text"(參閱 voxxy speak --help) |
| 向沒有原生 vox 路徑的 MCP 客戶端註冊 | MCP 伺服器位於 https://vox.delo.sh/mcp/(需要尾隨斜線) |
| Node-RED | node-red-contrib-vox 位於 ~/docker/stacks/utils/vox/node-red-contrib-vox/ |
| 健康狀況 + 引擎狀態 | GET /healthz |
/mcp/ 上的尾隨斜線是強制性的。 沒有它,FastAPI 會進行 307 重新導向,而 HTTPX 會丟棄 POST 主體。
speak 與 speak_url:選擇正確的
| 如果音訊將會... | 使用 | 原因 |
|---|---|---|
| 發送到 Telegram / Discord / Slack | speak_url | 頻道 API 接受 URL;它們的伺服器會擷取它。代理線上路上零位元組膨脹。 |
傳送到瀏覽器 <audio> 標籤 | speak_url | 瀏覽器串流 URL;無需 base64 往返。 |
交給 Home Assistant media_player.play_media | speak_url | HA 想要 media_content_id 的 URL。 |
| 由代理內聯處理(拼接、分析、循環) | speak | 位元組已經在本機;擷取 URL 會增加一次躍點。 |
| 在 shell 腳本中寫入本地檔案 | 任一者 | speak_url + curl -o 比 base64 + base64 -d 更容易。 |
預設使用 speak_url。 它不會花費代理任何 token(回應是很小的 JSON),並且在除原始內聯位元組處理之外的所有傳遞表面上都能運作。
引擎降級
GET /healthz 會回報哪些引擎已註冊以及每個引擎是否可用:
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
協調器會依序嘗試它們。每個 speak_url / speak 回應都包含 engine: "voxcpm" 或 engine: "elevenlabs",以便您可以偵測何時啟動了降級。當 ELEVENLABS_API_KEY 未設定時,ElevenLabs 會自動停用。
每個聲音的 ElevenLabs 對應關係存在於 voices.elevenlabs_voice_id 資料欄中。NULL 會回退到全域預設值(ELEVENLABS_DEFAULT_VOICE,預設為 Adam)。
複製的聲音是繫結引擎的。 透過 POST /voices 複製的聲音會將其參考儲存在 vibevoice_ref_path 中,並首先由 vibevoice 引擎提供服務(每個請求的 preferred 路由在 app/engines.py 中;其他所有項目遵循 VOX_ENGINES 順序,voxcpm 優先)。如果 vibevoice 關閉,voxcpm 仍然會收到參考片段——app/voices.py:46-48 會回退到 wav_path 給任何沒有特定覆寫的引擎——所以複製的聲音會退化,不會被刪除。症狀是聽起來可辨識但略有偏差,而不是完全陌生的聲音。修正:docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice,然後在 /healthz 中確認 "name":"vibevoice","ready":true。
真正會完全取代聲音的是 ElevenLabs 降級:如果兩個 GPU 引擎都關閉且已設定 ELEVENLABS_API_KEY,vox 會以陌生人的聲音回應 200,記錄 vox: voice clone BYPASSED,並照常傳遞。檢查每個複製合成的 engine 欄位——vibevoice 或 voxcpm 是複製的聲音,elevenlabs 不是您的聲音。
參考音訊預算為 10 秒,而不是 30 秒。 兩個不同的上限會疊加,只有第二個有意義。POST /voices 會將攝入修剪為 VOX_REF_AUDIO_MAX_SECONDS = 30 秒(compose.yml:16,應用於 app/main.py:578-584,保留前 30 秒)。但 vibevoice 容器將同一個變數設定為 10(compose.engines.yml:69),且 engines/vibevoice/engine/synth.py:183,208 使用 duration=10.0 重新載入參考。其 /healthz 直接顯示:"max_ref_seconds": 10.0。因此,任何參考片段的第 10 到 30 秒會被儲存、備份,但模型永遠不會看到。請針對 8–10 個乾淨的秒數 編寫複製用的段落,並將最佳、最中性的語音放在最前面——之後的所有內容都是無效的。
詳細程序
請參閱 語音與整合工作流程 以了解相關的實作或診斷。語音複製和外部傳遞需要使用者請求這些動作。
預設值速查表
| 參數 | 預設值 | 備註 |
|---|---|---|
cfg | 2.0 | 無分類器指導;越高 = 越忠實,變化越少 |
steps | 10 | 擴散步數;4-6 以獲得速度,15-20 以獲得最大品質 |
normalize | false | 文字正規化(數字 → 單字等) |
denoise | false | 已廢棄的欄位。 在 app/main.py:98 宣告,但沒有任何地方讀取;POST /voices 根本沒有 denoise 參數。請改為在上傳前清理音訊。 |
| 快取 TTL(音訊 URL) | 3600s | VOX_AUDIO_TTL_SECONDS 環境變數;對於 Telegram 來說 1 小時很充裕 |
| 降級聲音(ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | ELEVENLABS_DEFAULT_VOICE 環境變數 |
在 RTX 3090 上,使用 VOX_OPTIMIZE=1 時,合成速度約為每秒 21 個字元——這是測量值,而非估計值:一個 60 字元的行約需 2 秒,一個 1,665 字元的行約需 35 秒。請根據長度規劃預算,而不是根據 2 秒的標題。容器重新啟動後的第一次呼叫會增加約 15 秒(JIT 編譯)。OGG/Opus 轉碼透過 ffmpeg 增加不到 100ms。
這對於任何具有超時設定的呼叫者都很重要。Hermes vox TTS 外掛程式將 httpx 超時硬編碼為 60 秒(plugins/tts/vox/__init__.py:29,316),並會忽略 tts.vox.timeout,因此超過約 2,500 個字元的單個區塊會直接失敗。請使用 tts.vox.max_text_length(在 tools/tts_tool.py:436-441 中讀取)來設定上限,它會將文字分成區塊而不是直接失敗。
引擎升級工作流程
三容器拓撲將核心協調(voxxy-core,容器 vox,僅 CPU)與 GPU 繫結的 sidecar 引擎(voxxy-engine-voxcpm、voxxy-engine-vibevoice)分離。每個引擎容器在 engines/<name>/ 下維護自己的 pyproject.toml、uv.lock 和 Dockerfile。
逐步升級程序
1. 版本發現與執行時期稽核
- 上游釋出: 檢查 PyPI 和 GitHub 釋出:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - 執行中的容器版本: 透過
importlib.metadata檢查已安裝的套件版本:(切勿使用docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__;模組未定義它並會引發AttributeError)。 - Hugging Face 上的模型權重: 檢查模型權重快照是否已更新:
套件更新(推論程式碼、串流 VAE 解碼器、裝置處理)與模型權重修訂是分開的。cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. 相依性提升與鎖定檔更新
- 提升
engines/<name>/pyproject.toml中的版本固定(例如voxcpm==2.0.3)。 - 使用 uv 重新鎖定相依性:
cd engines/voxcpm && uv lock - 檢視差異(
git diff engines/voxcpm/uv.lock)以確保 PyTorch 和 torchaudio 仍然固定在明確的pytorch-cu124索引,並且不會漂移到 PyPI CPU wheel。
3. 重建引擎容器映像檔
透過 compose 重建引擎映像檔:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# 或透過 mise 別名:
mise run build:voxcpm
Dockerfile 透過 uv 提供 Python 3.12,並執行 uv sync --frozen --no-install-project 到 /opt/venv。
4. 使用 compose profile 重新建立引擎容器
引擎容器在 compose.engines.yml 中使用 compose profiles 定義(profiles: ["voxcpm"] / profiles: ["vibevoice"])。您必須傳遞 --profile,否則 compose 會忽略該服務:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
驗證容器已選取新版本:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. 驗證與冒煙測試
- 容器啟動: 檢查日誌以確認模型載入成功:
docker logs --tail 30 voxxy-engine-voxcpm # 尋找:"Loaded VoxCPM2Model" 和 "Application startup complete." - 引擎 healthz:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # 預期:{"engine":"voxcpm","ready":true,"model_loaded":true,...} - 直接合成測試: 從
vox核心容器透過 Docker 網路發送原始合成負載:docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \ -H 'content-type: application/json' \ -d '{"text":"Testing synthesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}' - 聲音複製驗證: 使用參考音訊樣本進行測試(
/data/voices/rick.wav):docker exec vox python3 -c ' import base64, urllib.request, json with open("/data/voices/rick.wav", "rb") as f: b64 = base64.b64encode(f.read()).decode("ascii") data = json.dumps({"text": "Test clone.", "reference_audio_b64": b64}).encode("utf-8") req = urllib.request.Request("http://voxxy-engine-voxcpm:8000/v1/synthesize", data=data, headers={"Content-Type": "application/json"}) print(json.loads(urllib.request.urlopen(req).read().decode("utf-8"))) ' - 合約與 CLI 測試:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. 交付
提交引擎目錄中的 pyproject.toml 和 uv.lock:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
經驗教訓與引擎注意事項
voxcpm套件版本檢查:voxcpm不會暴露__version__。呼叫python -c "import voxcpm; print(voxcpm.__version__)"會擲回AttributeError。請務必使用importlib.metadata.version('voxcpm')檢查已安裝的中繼資料。- Compose profiles 要求: 在
compose.engines.yml中,每個引擎都有一個 profile(profiles: ["voxcpm"])。如果您執行docker compose up voxxy-engine-voxcpm而沒有加上--profile voxcpm,Docker Compose 會靜默地跳過該服務。 - 備用引擎可直接測試: 單一 GPU 卡上的本地引擎是互斥的(VoxCPM ~5 GB VRAM,VibeVoice ~7.5 GB VRAM)。即使引擎在
voxxy daemon status/.voxxy.state.json中處於standby狀態,其容器仍然在內部 Docker 網路(http://voxxy-engine-<name>:8000)上執行且健康。您可以從vox直接透過 curl 測試它,而無需切換活動引擎。 - Pytest 測試套件位置: 從 repo 根目錄執行
pytest會失敗,因為plugins/tts/vox/是一個 Hermes 外掛程式,期望agent.tts_provider包含一個活躍的 Hermes 代理上
…
[為翻譯而截斷]