FireRedTTS3 — 多语言 TTS（24 种语言，含乌克兰语）

基于 FireRedTTS3 的本地语音合成服务，提供 HTTP API 和 MCP 服务器。这是继 ukrainian-tts（StyleTTS2，:8000）和 HolosTTS（:8010）之后排第三的服务；本服务在 :8020。

模型于 2026 年 8 月 13 日发布，Apache 2.0 许可，权重公开。

与相邻服务的区别

开始之前需要了解三件事：

1. 没有预设音色。 空音色库 = 无法合成。先用任意语音录音创建音色（add_firered_voice），之后按名字使用。模型在合成时直接 zero-shot 克隆。

2. 需要参考转录文本。 模型只有音频不够——还需要音频里所说的文本。不提供的话我们会用 Whisper 识别，但自己提供的文本总是更准确。

3. 没有重音。 没有词典，没有 ByT5 回退，也没有像相邻服务那样的手动 Му+дрого。重音由模型根据上下文自己判断，在同形异义词（за́мок/замо́к）上它会混淆。这是多语言模型的固有限制——如果重音很关键，HolosTTS 仍然更适合纯乌克兰语。

Related MCP server: STT2TTS MCP

安装

cd /Users/admin/Projects/firered-tts
./setup.sh                    # venv + залежності + апстрім + патч + ваги

setup.sh 做四件事：

1. 构建 .venv（Python 3.11，torch 2.8.0，使用 MPS/CPU ）

2. 克隆上游到 vendor/FireRedTTS3，固定在 3.0 commit 00570ad

3. 为其打补适配 Apple Silicon —— 见下方

4. 下载 base+redae 权重（~14.4 ГБ）到 pretrained_models/

权重单独下载（耗时较长——建议 detached）：

nohup ./download-weights.sh base > data/download.log 2>&1 &
./download-weights.sh instruct   # +7.9 ГБ, для дизайну голосу й редагування

为什么要打补丁

上游只针对 NVIDIA 编写，在 Mac 上根本无法运行：

flash_attn 是 CUDA-only，在 Metal 上根本无法编译；sdpa 可以用于所有平台，包括 NVIDIA，所以补丁不会破坏任何东西。

补丁的第十处是另一回事：base.py:317 不是可移植性，而是性能（参考编码缓存，见下文「速度」）。

src/patch_upstream.py 是幂等的，如果替换不命中就会失败——如果上游发生变化，你立刻就知道，而不会到首次合成时才报 CUDA 错误。

启动

./run.sh                      # http://localhost:8020

不必单独启动——MCP 服务器会自行拉起后端。后端在空闲 1800 秒镜像超时（IDLE_SHUTDOWN_SECONDS）后退出并释放内存。

run.sh 会对端口加锁（data/.start-<порт>.lock）：第二次启动时如果服务已在运行，直接以退出码 0 退出。这是故意的——多个客户端同时 autostart，而 /health 在加载约 90 秒内始终不响应。

HTTP API

# 1) завести голос
curl -X POST localhost:8020/clone_voice -H 'Content-Type: application/json' -d '{
  "audio": "prompts/зразок.wav", "name": "Богдан",
  "prompt_text": "Це зразок мого голосу для клонування.",
  "language": "Ukrainian", "gender": "male"}'

# 2) озвучити
curl -X POST localhost:8020/tts -H 'Content-Type: application/json' -d '{
  "text": "Сьогодні чудова погода, ходімо гуляти в парк.",
  "voice": "Богдан", "format": "mp3"}' -o out.mp3

# Або one-shot — без реєстрації голосу: передай reference_audio замість voice,
# транскрипт зробить Whisper (перший виклик +~30с, далі кешується)
curl -X POST localhost:8020/tts -H 'Content-Type: application/json' -d '{
  "text": "Сьогодні чудова погода.", "reference_audio": "prompts/зразок.mp3",
  "format": "mp3"}' -o out.mp3

MCP

参见 mcp_server/README.md。简述：

claude mcp add firered-tts -- /Users/admin/Projects/firered-tts/.venv/bin/python \
  /Users/admin/Projects/firered-tts/mcp_server/server.py

工具：firered_backend_status、list_firered_voices、add_firered_voice、delete_firered_voice、synthesize_firered_speech、design_firered_voice、edit_firered_speech。

内存与速度

Mac mini M4，16 GB。磁盘上 base（7.9）+ redae（3.5）= 11.4 GB，但内存占用约 ~7.7 GB：LLM 骨干加载为 fp16（4.2 而不是 8.4 ——见下方优化 2），其余保留 fp32。

权重只是部分（GXP6 已测得，实际在多次合成之后）：

phys_footprint:      13 ГБ
phys_footprint_peak: 14 ГБ

7.7 与 13 的差距来自 MPS 分配器缓存、KV cache 和生成时的激活值。在 16 GB 上，即使仅仅一个进程也非常局促；ps/RSS 在这里会骗人（只显示零点几 GB，MPS 缓冲区在 unified memory 中不计入 RSS）。用 footprint 测，别用 ps。

这种设计带来的实际后果：

• 内存中只有一个模型在驻留，base 或 instruct；切换 = 完全重载（耗时几分钟，会记录日志）；

• 合成操作被全局锁串行化——两个并发请求在 16 GB 上只会 OOM，不会加速；

• run.sh 对端口加锁，否则多个 autostart 的客户端会各自拉起一份后端（真实案例：16 GB 上跑了七个进程）。

  上述都通过 run.sh 的端口锁来保证。

• 空闲 1800 秒自动退出（比邻居长，因为重启要支付约 40 秒的 shader 编译成本，保持进程存活更划算）；

• 自动转录用的 Whisper 在 CPU 上以 int8 运行，使用后立即卸载。

速度与四项优化

Primapsing compilers the naive upstream run on M4 之外，最初是 ~189× 实时——3 秒乌克兰语要算 9.5 分钟。三处修复把它降到 ×4.0，即 48 倍提速；第四处优化再到 ×2.7。问题所在（通过 tools/profile_steps.py 和插桩测量）：

1. 每个 AR 步骤上的 Autocast——最大的问题。 上游用装饰器 @torch.autocast 挂在 _backbone_one_step 上，因此 autocast 区域在每个自回归步骤都会打开/关闭。torch 的权重重转缓存长度只在区域内部存活，因此 1.7B 个 fp32 参数每个步骤都要重新转成 half。骨干一步从 19000 ms → 2710 ms。现在 autocast 默认关闭，转换只在骨干边界显式进行。

2. 骨干权存 fp32。 权重本来就是 float32 保存（3.0B 参数 = 11.4 GB），在 16 GB 上意味着 swap。只把 LLM 骨干换成 half（8.4 GB 变成 4.2 GB），而 redae 和 flow 解码器仍保留 fp32——上游在那里有意保持全精度，half 会使 MPS-matmul 出错。步时进一步 2710 → 1387 ms。

3. Metal 着色器编译。 “慢”的最大因素其实是一次性的：Metal 在第一次执行时编译 kernel。骨干步骤逐步测量：9873, 2104, 120, 93, 96, 97… ms。因此服务在启动时预热（FIRERED_WARMUP=1），并有很长的空闲超时——重启需要约 40 秒编译。

4. 参考编码缓存。 generate() 每次句子都会调用，每次调用都重新对参考音频执行一次 redae 编码器——无论文本时长都是 5.58 秒。缓存键是音频内容而非 tensor id，因此无法用另一个音色替换缓存。在 6.6 分钟音频（14 个 chunk）的生成中，30 次命中对 2 次 miss ≈ 150 秒，即约 ~11% 的时间。

在 M4 上合成 1 分钟音频大约需要 2.7 分钟 实时（Mac mini M4/16GB，模型已预热，参考缓存已热；以 5 轮 3 秒乌克兰语中的最佳成绩计算，中位数为 ×2.9）。不是实时，但已经是可用工具，不是那种“放一夜跑”的离线脚本了。

一次性预热后的计算 profile：flow 解码器 57%，骨干 18%，redae 11%。

n_timesteps 是 flow 解码器中最贵部分的 ODE 步数。该参数在 /tts、MCP 及 FIRERED_N_TIMESTEPS 中可用，但默认值是 10，与上游一致——上游没有文档，也没有推荐改变。低于 4 时质量明显变粗。用同样的测评：10 → ×2.7，6 → ×1.9，4 → ×1.3，2 → ×1.0。只有在特定任务下并且用听感校验后才建议降低。

Text normalization

内置 TN（wetext）只支持中文和 English，因此对五种语言没有用，我们不部署它。19:30、250 грн、2026 р. 之类，模型只能靠猜。

两种出路：

1. 直接写完整的文本；

2. 启用 LLM-TN——在 .env 里配 FIRERED_TN_API_URL / _API_KEY / _MODEL。任何 OpenAI 兼容的端点都可，包括本地（llama.cpp / vLLM / Ollama）——这样所有内容保持离线。

许可

代码和权重是 Apache 2.0。上游 README 单独声明 zero-shot 克隆 “solely for academic research purposes” —— 这与 Apache 2.0 并不矛盾，但商用克隆声音时请谨慎。家里用没有问题。