开发者模型管理：各引擎的模型下载、加载与状态跟踪机制详解
Voicebox 管理两类模型：
TTS 模型 —— 涵盖 8 种引擎，支持零样本声音克隆、预设音色及音色设计。每个引擎可能拥有一个或多个尺寸变体。
ASR 模型 —— 用于转录的 Whisper。包含 5 种尺寸，且在 Apple Silicon 上配合 MLX-Whisper 可实现约 8 倍速的转录。
每个模型都由 `backend/backends/__init__.py` 中的一个 ModelConfig 条目描述。模型在首次使用时从 HuggingFace Hub 下载，并缓存在平台标准的 HF 缓存目录中。
可用 TTS 模型
| 模型 | 引擎 | HuggingFace 仓库 | 大小 | 显存需求 | 语言 |
|---|
| Qwen TTS 1.7B | qwen | Qwen/Qwen3-TTS-12Hz-1.7B-Base | 3.5 GB | ~6 GB | 10 |
| Qwen TTS 0.6B | qwen | Qwen/Qwen3-TTS-12Hz-0.6B-Base | 1.2 GB | ~2 GB | 10 |
| Qwen CustomVoice 1.7B | qwen_custom_voice | Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice | 3.5 GB | ~6 GB | 10 |
| Qwen CustomVoice 0.6B | qwen_custom_voice | Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice | 1.2 GB | ~2 GB | 10 |
| Qwen VoiceDesign 1.7B | qwen_voice_design | Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign | 3.5 GB | ~6 GB | 10 |
| LuxTTS | luxtts | YatharthS/LuxTTS | 300 MB | ~1 GB | 英语 |
| Chatterbox Multilingual | chatterbox | ResembleAI/chatterbox | 3.2 GB | ~3 GB | 23 |
| Chatterbox Turbo | chatterbox_turbo | ResembleAI/chatterbox-turbo | 1.5 GB | ~1.5 GB | 英语 |
| TADA 1B | tada | HumeAI/tada-1b | 4 GB | ~4 GB | 英语 |
| TADA 3B Multilingual | tada | HumeAI/tada-3b-ml | 8 GB | ~8 GB | 10 |
| Kokoro 82M | kokoro | hexgrad/Kokoro-82M | 350 MB | ~150 MB | 8 |
在 Apple Silicon 上，Qwen TTS 会优先使用 `mlx-community` 提供的 MLX 优化仓库，而非 PyTorch 仓库。后端通过 `get_backend_type()` 自动选择相应实现。CustomVoice 和 VoiceDesign 仅支持 PyTorch，因为上游并未发布 MLX 转换版本。
Qwen VoiceDesign 仅提供 1.7B 检查点，没有 0.6B 变体。它是唯一消费 `voice_type: "designed"` 配置的引擎，其中声音身份由配置中的 `design_prompt` 定义，而非参考音频或预设 ID。
可用 Whisper 模型
| 模型 | HuggingFace 仓库 | 大小 |
|---|
| Whisper Base | openai/whisper-base | ~300 MB |
| Whisper Small | openai/whisper-small | ~500 MB |
| Whisper Medium | openai/whisper-medium | ~1.5 GB |
| Whisper Large | openai/whisper-large-v3 | ~3 GB |
| Whisper Turbo | openai/whisper-large-v3-turbo | ~1.5 GB |
在 Apple Silicon 上，系统会自动优先使用 MLX-Whisper —— 详见“转录”章节。
模型存储位置
模型保存在平台默认的 HuggingFace 缓存目录中：
| 平台 | 路径 |
|---|
| macOS | ~/.cache/huggingface/hub |
| Linux | ~/.cache/huggingface/hub/ |
| Windows | %USERPROFILE%\.cache\huggingface\hub\ |
| Docker | /home/voicebox/.cache/huggingface/hub（通过卷挂载） |
可通过设置环境变量 `VOICEBOX_MODELS_DIR` 覆盖此路径。
进度跟踪
下载进度通过服务器发送事件（Server-Sent Events, SSE）实时推送到前端。进度管道包含三个部分：
- ProgressManager (`backend/utils/progress.py`) —— 内存映射，记录 `model_name` 对应 `{current, total, filename, status}` 的状态。
- HFProgressTracker —— 上下文管理器，拦截 HuggingFace Hub 下载以发送字节级进度更新。由于 `huggingface_hub` 在 PyInstaller 冻结构建中会静默禁用 tqdm，因此需要此机制。
- SSE 端点 —— `GET /models/progress/{model_name}` 持续推送更新，直到状态变为 complete 或 error。
# 前端示例
```javascript
const eventSource = new EventSource(`/models/progress/${modelName}`);
eventSource.onmessage = (event) => {
const { current, total, status } = JSON.parse(event.data);
updateProgressBar(current / total);
if (status === "complete") eventSource.close();
};
```
模型状态
`GET /models/status` 返回所有已注册模型的当前状态：
```json
{
"models": [
{
"model_name": "qwen-tts-1.7B",
"display_name": "Qwen TTS 1.7B",
"engine": "qwen",
"downloaded": true,
"size_mb": 3500,
"loaded": true
},
...
]
}
```
处理器遍历 `get_all_model_configs()`，并对每个条目调用 `check_model_loaded(config)`，因此新引擎只要在 ModelConfig 中注册即可自动出现。
手动模型操作
| 方法 | 端点 | 描述 |
|---|
| GET | /models/status | 获取所有已注册模型的状态 |
| POST | /models/load | 将 TTS 模型加载到内存 |
| POST | /models/unload | 从内存卸载 TTS 模型 |
| POST | /models/download | 触发后台下载 |
| GET | /models/progress/{name} | 流式推送下载进度 (SSE) |
| DELETE | /models/{name} | 从缓存中删除已下载的模型 |
加载模型
POST /models/load
```json
{
"model_name": "qwen-tts-1.7B"
}
```
该路由查询配置，调度至 `get_model_load_func(config)`，并在模型就绪后返回。`model_name` 可以是 `GET /models/status` 中的任何 ID —— TTS、Whisper 和 LLM 条目均通过同一注册表解析。
若省略 `model_name`，则回退至默认 Qwen TTS 后端，并通过可选的 `model_size` 参数（如 `POST /models/load?model_size=0.6B`）进行选择。这是早期基于模型名称的形式，至今仍有效。
卸载模型
POST /models/unload
```json
{
"model_name": "chatterbox-tts"
}
```
调用 `unload_model_by_config(config)`，路由至对应后端的 `unload_model()` 以释放 GPU 内存。`POST /models/{name}/unload` 具有相同效果。若省略 `model_name`，则卸载默认的 Qwen TTS 模型。
下载模型
POST /models/download
```json
{
"model_name": "kokoro"
}
```
启动异步下载任务。进度可通过 SSE 端点获取。由于首次生成时会自动触发下载，此接口仅用于预热。
预设音色初始化
对于使用预设音色的引擎（Kokoro、Qwen CustomVoice），模型下载完成后，后端会自动为每个预设音色创建一个声音配置文件。此过程由 `backend/services/profiles.py` 中的 `seed_preset_profiles(engine)` 驱动，并在模型路由中于下载完成时调用。
预设配置文件包含：
- `voice_type = "preset"`
- `preset_engine = 引擎名称 ("kokoro", "qwen_custom_voice")`
- `preset_voice_id = 引擎特定的音色 ID ("am_adam", "f000001" 等)`
- 无 `profile_samples` 行 —— 无需存储音频
详见“声音配置文件”章节以了解数据结构。
添加新模型
若要为现有引擎添加新的尺寸变体，只需新增一个 ModelConfig：
```python
ModelConfig(
model_name="qwen-tts-3B",
display_name="Qwen TTS 3B",
engine="qwen",
hf_repo_id="Qwen/Qwen3-TTS-12Hz-3B-Base",
model_size="3B",
size_mb=7000,
languages=["zh", "en", ...],
),
```
前端通过 `/models/status` 自动识别新模型，下载和加载流程无需额外修改即可正常工作。
添加全新引擎工作量较大 —— 完整的分阶段工作流程请参见“TTS 引擎”章节。
错误处理
| 错误 | 原因 | 解决方案 |
|---|
| 下载失败 | 网络问题 / HF 速率限制 | 重试 |
| 加载时 OOM | 显存不足 | 使用更小变体，或卸载其他引擎 |
| 未找到模型 | 缓存损坏 | 通过 /models/download 重新下载 |
| 冻结构建中进度条卡住 | huggingface_hub 的 tqdm 被静默禁用 | HFProgressTracker 强制启用内部计数器 |
| 不支持的 GPU 架构 | PyTorch 轮子未针对你的 GPU 编译 | 参见“GPU 加速”章节 |
后续步骤
- TTS 生成：生成流程如何通过注册表流转
- TTS 引擎：端到端添加新引擎
- 转录：Whisper 与 MLX-Whisper 集成
- 在 GitHub 上编辑
- 音频通道：Voicebox 中的音频输出路由机制
