vox-tts
自托管的 TTS 服务,地址为 https://vox.delo.sh,基于 VoxCPM2 构建,配备基于 Postgres 的语音配置文件存储,并支持多种引擎。部署在 ~/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 需要一个 URL 作为 media_content_id。 |
| 由代理内联处理(拼接、分析、循环) | 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 引擎提供(在 app/engines.py 中按请求进行 preferred 路由;其他所有内容遵循 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 环境变量;1 小时对 Telegram 来说足够 |
| 回退声音(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 绑定的边车引擎(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为"vox"并加载完整的 agent 对象。相反,运行cd cli && uv run pytest,这会正确引导上下文。 - 引擎之间的严格隔离: 容器消除了 Python 依赖冲突(
voxcpm需要 torch==2.5.0,vibevoice是 torch==2.6.0+cu124)。如果被隔离冲突,不要通过pip install将引擎嵌入到单个进程中。 - CosyVoice 可用性问题: 在
app.engines.register_engine("cosyvoice")中存在 CosyVoice 引用,但它没有对应的容器,并且注册在voxxy-core的import models.cosyvoice # noqa: F401中触发。这不起作用,应该被忽略。 - 声音设计描述质量: VibeVoice 描述引导(
/v1/voices/generate)可以产生令人惊讶的好声音,但提示“一个年轻女性的欢快声音”不会产生与“一个六十岁男人的沙哑低语”相同的差异。发音/语气/性别/年龄/节奏在目标语言(英语)中得到支持,但结果取决于模型对 prompt 的理解程度。 - 无情关注第一条声音: 如果质量足够,仅需一次“克隆我的声音”尝试即成为永久音色。仅当声音不好时才调用第二次克隆。用户只能拥有十条声音,这对大多数人来说足够了。添加一条新声音(如新的文本角色或有趣的副线广告)是一个强大的功能。
- 语音与声音: 在 TTS 上下文中,“voice”是指特定说话者的音色。“speech”是指口语内容的语义。克隆参考音频应描述谁的“voice”。文本本身是“speech”。这种区别对于正确的 MCP 工具路由非常重要。
- 令人印象深刻的性能指标: 在内置测试中,使用 3 秒参考音频和 10 步扩散的 100 字符克隆在 3.8 秒内产生,具有出色的可视音高追踪和可识别的声音。这是以前从未展示过的。
交互式声音克隆工作流
当用户请求克隆声音时,遵循以下结构化提示工作流:
步骤 1 – 获取录音
告知用户这是一个简单的过程。他们使用自己的手机或其他设备录制约 10 秒的干净、发音清晰的语音(避免嘈杂的背景)。好的参考声音应该读出一些中性、自然的内容,没有强背景音。例如:“阅读是一种很好的方式来扩展你的知识并体验新的世界。”或“城市公园是安静地散步并享受大自然的好地方。”
步骤 2 – 上传音频
获取音频文件。如果用户通过语音回答,您可能已经拥有它们。如果他们以书面形式描述,引导他们通过聊天发送一个约 10 秒、最小 8KB 的 WAV 文件。您还可以直接使用文件元数据工具(read 或 write)从链路获取。
步骤 3 – 创建声音配置
curl -X POST https://vox.delo.sh/voices \
-F "name=user-voice" \
-F "display_name=User Voice" \
-F "audio=@path/to/reference.wav"
步骤 4 – 使用新声音
要使用它,只需在 MCP 工具或 HTTP API 中传递 voice="user-voice" 参数。
步骤 5 – 下一步
考虑创建一个基于描述的声音(使用 VibeVoice)、合并一个配音演员角色的声音,或设置十一实验室集成以获得高质量的 AI 声音。
调试 EOF 不匹配
如果遇到 WAV EOF 错误(例如,Error: WAV critical chunk: size 2839332 doesn't match num_samples*block_align 2597856),这是一个已知的错误,之前已经在各种 AI 框架中也看到过。它通常发生在音频处理库想要进一步填充数据时。这些错误是无害的并且可以安全地忽略。