添加 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 搜索。生成一份书面的依赖审计，涵盖：
- PyPI 与非 PyPI 包
- 所需的 PyInstaller 指令（
--collect-all、--copy-metadata、--hidden-import） - 必须打包的运行时数据文件
- 在冻结构建中需要环境变量覆盖的原生库路径
- 需要的猴子补丁（
torch.load、float64、MPS、HF token） - 采样率
- 模型下载方法（
from_pretrained与snapshot_download+from_local）
在继续之前，在一次性虚拟环境中测试模型加载和 CPU 上的生成。
3. 实施（阶段 1–4）
按顺序遵循指南中的阶段。需要修改的关键文件：
后端（阶段 1）：
- 创建
backend/backends/<engine>_backend.py - 在
backend/backends/__init__.py中注册（ModelConfig + TTS_ENGINES + 工厂函数） - 更新
backend/models.py中的正则表达式
前端（阶段 3）：
app/src/lib/api/types.ts— 引擎联合类型app/src/lib/constants/languages.ts— ENGINE_LANGUAGESapp/src/components/Generation/EngineModelSelector.tsx— ENGINE_OPTIONS、ENGINE_DESCRIPTIONSapp/src/lib/hooks/useGenerationForm.ts— Zod schema、模型名称映射app/src/components/ServerSettings/ModelManagement.tsx— MODEL_DESCRIPTIONS
依赖项（阶段 4）：
backend/requirements.txtjustfile（setup-python、setup-python-release 目标）.github/workflows/release.ymlDockerfile（如果适用）
4. PyInstaller 打包（阶段 5）
在 backend/build_binary.py 中注册引擎：
- 为后端模块和模型包添加
--hidden-import - 为使用
inspect.getsource、分发数据文件或原生库的包添加--collect-all - 为使用
importlib.metadata的包添加--copy-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() | “无法获取源代码” | --collect-all <package> |
| 包附带预训练模型文件 | FileNotFoundError 针对 .pth.tar、.yaml | --collect-all <package> |
| 带有硬编码系统路径的 C 库 | FileNotFoundError 针对 /usr/share/... | --collect-all + 在 server.py 中设置环境变量 |
importlib.metadata.version() | “未找到包元数据” | --copy-metadata <package> |
未指定 map_location 的 torch.load | 在 CPU 构建上 CUDA 设备不可用 | 猴子补丁 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 缓存进行测试（不要有来自开发阶段的预下载模型）。
- 不要推送或创建发布版本。将构建交给用户进行本地测试。