TTS Hub · 统一语音合成调度服务

从 NarrifyAudio 拆出的统一 TTS 调度服务：一套 API、音色库、任务队列和显存分批，调度多个引擎（目前两个），通过 HTTP API（以及 MCP）供 agent 自主调用制作配音：

• 音色库：8 个内置音色 + 9 个 Qwen3 预置音色；可用参考音频克隆，或用一句文字描述「设计」新音色并固化，保证同一角色每句音色一致。克隆/设计出的音色两个引擎通用

• 单段合成 /v1/tts：长文本自动按句切分、批量合成、拼接

• 多角色配音 /v1/dub：一份剧本 → 合并音频 + 逐行音频 + SRT 字幕 + 时间轴

• 批量条目 /v1/batch：上千条互相独立的台词一次提交，每条一个文件 + manifest.json

• 按显存自动分批：实测拟合的显存模型算出每批最多放几行，OOM 自动拆批（见「批处理与显存上限」）

• 语气控制：每句可带 instruction（情绪/语速/音量），文本内可插 [笑] [叹气] 等声音事件

• 单 GPU 任务队列：并发请求排队不报错；同步等待或异步轮询

• OpenAI 兼容 /v1/audio/speech；MCP 服务器 mcp_server.py

安装

需要 Windows + NVIDIA GPU（≥12 GB 显存）、git、Python 启动器 py。

powershell -ExecutionPolicy Bypass -File .\install.ps1

脚本会：创建 .venv（Python 3.14，uv）→ 装依赖 → 装 CUDA 版 torch 2.11 → 检出固定版本的上游推理代码到 vendor\breeze-tts → 校验 GPU。Qwen3-TTS 的推理代码是 pip 包 qwen-tts，已在依赖里。

模型权重（自动下载）

不需要手动下载：服务用到哪个模型，就先查 HuggingFace 缓存（默认 %USERPROFILE%\.cache\huggingface\hub）， 没有才自动下载，之后一直复用。

下载期间 /health 停在 loading（启动时）或请求一直等待（Qwen3 首次用到时），日志里有「权重未缓存，正在从 HuggingFace 下载」。分词器在各自仓库里，不会再拉别的仓库。

国内网络 / 镜像：设置 HF_ENDPOINT 后，服务的自动下载就走镜像。写进 .env（start.ps1 启动时读取）：

HF_ENDPOINT=https://hf-mirror.com

或只对当前终端生效：$env:HF_ENDPOINT = "https://hf-mirror.com"; .\start.ps1。 其他常用变量：HF_HOME（换缓存位置，例如放到大容量盘）、HF_TOKEN（需要登录时）。

提前 / 手动下载（想在启动前下好、机器离线，或遇到下面的符号链接问题）：用虚拟环境自带的 hf 命令下载到 普通目录，再把对应变量指向该目录（写进 .env 即可）：

$env:HF_ENDPOINT = "https://hf-mirror.com"   # 可选：走镜像
.\.venv\Scripts\hf.exe download BreezeBlue/breeze-tts-2 --local-dir D:\models\breeze-tts-2
.\.venv\Scripts\hf.exe download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir D:\models\Qwen3-TTS-CustomVoice
.\.venv\Scripts\hf.exe download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir D:\models\Qwen3-TTS-Base
.\.venv\Scripts\hf.exe download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir D:\models\Qwen3-TTS-VoiceDesign

BREEZE_MODEL=D:\models\breeze-tts-2
QWEN_CUSTOM_MODEL=D:\models\Qwen3-TTS-CustomVoice
QWEN_BASE_MODEL=D:\models\Qwen3-TTS-Base
QWEN_DESIGN_MODEL=D:\models\Qwen3-TTS-VoiceDesign

只用 breeze 时下第一个就够；Qwen3 按需要的功能下对应的仓库。去掉 --local-dir 则下载到 HuggingFace 缓存， 服务会自动找到，不用设变量。

Windows 符号链接：HuggingFace 缓存要创建符号链接，没开「开发者模式」也不是管理员时，自动下载会报 WinError 1314（日志有中文提示）。开启「设置 → 系统 → 开发者选项 → 开发者模式」即可；或者按上面用 --local-dir 下载到普通目录（不需要符号链接），再用变量指过去。

Related MCP server: leanvox-mcp

启动

.\start.ps1                                    # 仅本机：http://127.0.0.1:7861
.\start.ps1 -BindHost 0.0.0.0 -ApiKey 换成你的密钥  # 局域网可访问，需 Bearer 认证
.\start.ps1 -Engine qwen3                      # 默认引擎改为 Qwen3（请求不指定 engine 时使用）

约 30–60 秒后 GET /health 返回 "status": "ready"（加载默认引擎 → 首次生成内置音色 → 预热）。另一个引擎在第一次 被请求时才加载。/health 的 engines 字段列出每个引擎是否已加载。

显存

Qwen3 的三个模型各自按需加载，只用预置音色时只占一个。显存不足 24 GB 时建议只用一个引擎（-Engine 选默认， 请求里不要混用）；空闲卸载会把两个引擎一起释放。 配置项见 .env.example（复制为 .env 生效）：端口、权重路径、API key、批大小、空闲策略等。 服务级变量统一为 TTS_*（旧名 BREEZE_* 仍兼容，两者都设时以 TTS_* 为准）；引擎专属变量带引擎前缀： BREEZE_MODEL、BREEZE_CODE_DIR、BREEZE_FAST_CLONE、QWEN_*_MODEL。也可直接 python -m tts_hub --help 用命令行参数。

空闲自动卸载 / 关闭

设为 0 关闭对应阶段（例如 .\start.ps1 -IdleUnloadMinutes 0 -IdleShutdownMinutes 0 常驻）。只有 API 请求计入活动， /health 轮询不会让服务保持加载。也可手动 POST /v1/unload、POST /v1/shutdown。

调用

完整接口说明见 AGENT_GUIDE.md（服务运行时也可 GET /v1/guide 取到，/docs 为交互式文档）。

curl -X POST http://127.0.0.1:7861/v1/tts -H "Content-Type: application/json" -d "{\"text\":\"你好，欢迎收听。\",\"voice\":\"zh_male_narrator\",\"format\":\"mp3\"}"

import httpx
r = httpx.post("http://127.0.0.1:7861/v1/dub", timeout=900, json={
    "name": "ep01", "format": "mp3", "srt_speaker": True,
    "lines": [
        {"voice": "zh_male_narrator", "text": "夜色渐深，古堡里传来一阵奇怪的声响。"},
        {"voice": "zh_young_female", "speaker": "小雨", "text": "你听到了吗？", "instruction": "紧张地小声说"},
    ]}).json()
print(r["result"]["path"], r["result"]["srt"]["path"])

选引擎：请求或某一行加 "engine": "qwen3"；用 qwen_* 预置音色时自动走 qwen3。同一份剧本可以混用两个引擎。

curl -X POST http://127.0.0.1:7861/v1/tts -H "Content-Type: application/json" -d "{\"text\":\"你怎么能这样！\",\"voice\":\"qwen_uncle_fu\",\"instruction\":\"非常愤怒\"}"

给 agent 接入 MCP

服务先启动，再把 MCP 服务器注册给 agent（以 Claude Code 为例）：

claude mcp add tts-hub -- "<项目目录>\.venv\Scripts\python.exe" "<项目目录>\mcp_server.py"

其他支持 MCP 的客户端照此配置 stdio 命令即可。环境变量 TTS_URL、TTS_API_KEY 指向远程服务（旧名 BREEZE_URL、BREEZE_API_KEY 仍兼容）。 工具：tts_health、tts_list_voices、tts_design_voice、tts_clone_voice、tts_delete_voice、 tts_speak、tts_dub、tts_batch、tts_job。tts_speak/tts_dub/tts_batch 可传 output_path/output_dir 把结果存到 agent 指定位置。

不支持 MCP 的 agent 直接调 HTTP：让它先读 GET /v1/guide。

配音流程与判断经验另有用户级 skill tts-dubbing（~/.claude/skills/tts-dubbing/）：服务启动检查、 选角与 casting.json 跨集复用、剧本整理、按语速自检（scripts/check_timeline.py）并重做坏行、交付清单。 提到「配音」「有声书」等会自动加载，也可用 /tts-dubbing 显式调用。

性能（RTX 5090 实测）

同一请求内的多行会批量合成，所以剧本一次提交比逐句调用快得多。大批量实测见下节。

批处理与显存上限

/v1/dub、/v1/batch、长文本 /v1/tts 的所有行先按「引擎 + 生成模板 + 种子」分组，组内从短到长排序，再由 tts_hub/batch_limits.py 的显存模型决定每批放多少行：

批峰值 ≈ base + base_per_frame × F + 行数 × multiplier × (row_fixed + per_frame × F)
F      = 参考音频帧 + 文本字数 + 解码上限（批内最长一行）
预算   = 空闲 + 已缓存 − 已占用（规划前实时读取，另一个已加载的引擎自动扣除）
每批行数 = 0.9 × 预算能容纳的行数，向下取偶数，上限 TTS_MAX_BATCH（默认 128）

• Qwen3：常数来自 NarrifyAudio 的拟合（RTX 5090，每行强制解到上限，残差 <0.4%），并装上同款 talker hidden-state 裁剪（数值等价，每帧省 ~116 KiB/行）。单元测试核对了与 Narrify 相同的批大小。

• Breeze：本机用 scripts/calibrate_vram.py 实测 30 个批次（1–96 行 × 12/48/110 字 × 纯克隆/CFG）拟合； CFG（设计音色、带 instruction）每行要跑 cond+uncond 两行，multiplier=2。模型对所有样本都不低估。

• OOM 兜底：仍然 OOM 时把较短的 90% 立即重跑、最长的推到下一批，之后的批次预算再乘 0.9（/health 里的 oom_scale）。

• 换显卡：停服务后运行 .venv\Scripts\python.exe scripts\calibrate_vram.py，写出 data/vram_fit.json，启动时自动覆盖内置常数。

• 实际分批：/health → engines.<名>.last_batches。压测：服务运行时执行 scripts\batch_stress_test.py --items 300。

大批量实测（RTX 5090，batch_stress_test.py --items 300：300 条 / 6980 字，句长 3–80 字，4 个音色）：

¹ 两个引擎同时驻留，含 PyTorch 缓存池。两者都触到 TTS_MAX_BATCH=128 的上限，显存模型给出的容量更大； 冷启动第一次（含 CUDA Graph 捕获）Breeze 约 15× 实时。逐句调用只有 1–2× 实时。

相比上游：纯克隆（无 instruction）在上游每帧调用一次 HF generate，约 0.4 倍实时；这里复用了深度解码器的 CUDA Graph（cond=uncond、scale=1，数学上与无引导等价），提速约 3 倍。BREEZE_FAST_CLONE=0 可回退上游路径。

目录

tts_hub/          服务代码：api（HTTP）、jobs（GPU 队列）、engine（Breeze 推理）、qwen_engine（Qwen3 推理）、
                  batch_limits（显存分批模型）、voices（音色库）、audio、text
mcp_server.py     MCP 桥接
scripts/smoke_test.py         Breeze 真机端到端测试（服务运行时执行）
scripts/qwen3_smoke_test.py   Qwen3 真机端到端测试
scripts/batch_stress_test.py  大批量压测：自动批大小、GPU 峰值、吞吐
scripts/calibrate_vram.py     在本机 GPU 上拟合 Breeze 显存模型（停服务后执行）
tests/            单元测试（假引擎，无需 GPU）：.venv\Scripts\python.exe -m pytest tests
vendor/breeze-tts 上游推理代码（install.ps1 检出）
data/             运行数据：voices/ 音色库、outputs/<任务id>/ 产物、jobs/ 任务记录

许可

服务代码与上游推理代码为 Apache 2.0。

• Breeze TTS 2：权重与自托管生成的音频仅限研究与非商业用途（BreezeBlue Research and Non-Commercial License）。

• Qwen3-TTS：权重为 Apache-2.0，可商用。商用作品请整份用 engine: "qwen3"，并注意内置的 zh_*/en_* 音色是用 Breeze 设计生成的参考音频——商用时改用 qwen_* 预置音色，或用 engine: "qwen3" 重新设计/克隆的音色。

克隆他人声音须取得授权。