把 faster-qwen3-tts 接入 OpenWebUI:搭建 OpenAI 兼容的 TTS API 服务器
把 faster-qwen3-tts 接入 OpenWebUI:搭建 OpenAI 兼容的 TTS API 服务器
faster-qwen3-tts 是一个实时文本转语音(TTS)推理项目,它让 Qwen3-TTS 模型借助 CUDA Graphs 实现数倍于实时的合成速度。项目自带的 examples/openai_server.py 可以一键暴露 OpenAI 标准的 /v1/audio/speech 端点,让你轻松把本地 GPU 变成一台 TTS API 服务器,并无缝接入 OpenWebUI、llama-swap 等任何 OpenAI 兼容客户端。本文将带你从零完成 faster-qwen3-tts 的部署、TTS API 服务器搭建,以及 OpenWebUI 语音合成的完整配置。
为什么选择 faster-qwen3-tts 做 TTS 后端 🚀
普通的开源 TTS 推理代码往往"能跑但不快":生成 1 秒音频可能要等 5 秒以上。faster-qwen3-tts 的核心突破是用 StaticCache + torch.cuda.CUDAGraph 消除了 Python 层的 kernel 调度开销,实测性能(详见 README.md 的基准测试):
| 硬件 | 0.6B 模型 RTF | 首包延迟 TTFA |
|---|---|---|
| RTX 4090 | 4.78 | 156ms |
| H100 80GB | 3.88 | 228ms |
| Jetson AGX Orin | 1.31 | 597ms |
RTF > 1 表示比实时还快;TTFA 是"听到第一声"的等待时间。这意味着你在 OpenWebUI 里点下朗读按钮,几乎不用等就能出声。
技术原理的完整解析可参考项目博客 BLOG.md。
环境准备:安装 faster-qwen3-tts 的完整步骤
系统要求:
- Python 3.10+、PyTorch 2.5.1+(低于 2.5.1 的 CUDA Graph 捕获可能失败)
- Torch 后端需要 NVIDIA CUDA 显卡;GGML 后端还支持 Apple Silicon Metal(见 docs/ggml-backend.md)
安装命令(一条搞定):
pip install "faster-qwen3-tts[demo]"
<a href="https://link.gitcode.com/i/514cbad0fa588ba0da26d7a41af70e54" target="_blank">demo] 附加依赖会自动装好 FastAPI 和 uvicorn,这正是 TTS API 服务器需要的 Web 框架,依赖定义见 [pyproject.toml。
也可以从源码克隆运行:
git clone https://gitcode.com/gh_mirrors/fa/faster-qwen3-tts
cd faster-qwen3-tts
pip install "faster-qwen3-tts[demo]"
⚠️ 驱动版本注意: 如果 nvidia-smi 右上角显示的 CUDA 版本较旧(如 12.4 的 T4/A10G 主机),默认 PyTorch wheel 可能报 The NVIDIA driver on this system is too old。此时改装对应 CUDA 版本的 wheel 即可,详见 README.md 的 "Driver / CUDA mismatch" 说明。
启动 OpenAI 兼容的 TTS API 服务器
准备好一段参考音频(WAV 格式)及其文字转录,然后运行服务器脚本:
python examples/openai_server.py \
--ref-audio ref_audio.wav \
--ref-text "参考音频对应的文字内容" \
--language English \
--port 8000
几个关键参数:
| 参数 | 作用 |
|---|---|
--model |
模型 ID,默认 Qwen/Qwen3-TTS-12Hz-1.7B-Base,可用环境变量 QWEN_TTS_MODEL 覆盖 |
--ref-audio / --ref-text |
单音色模式:参考音频 + 转录文本 |
--voices |
多音色模式:指向一个 JSON 配置文件 |
--port |
监听端口,默认 8000 |
服务启动后会暴露两个端点(定义于 examples/openai_server.py):
POST /v1/audio/speech:OpenAI TTS 标准接口GET /health:健康检查,返回模型加载状态
WAV 和 PCM 格式的响应是流式输出的——音频块一边生成一边发送,进一步降低收听延迟。
用 curl 快速验证 TTS 端点
curl http://localhost:8000/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{"model": "tts-1", "input": "你好,语音合成测试。", "voice": "alloy", "response_format": "wav"}' \
--output speech.wav
能播放 speech.wav,说明你的 TTS API 服务器已经就绪 ✅
在 OpenWebUI 中接入 TTS API
- 确保 faster-qwen3-tts 的 API 服务器已在后台运行(例如
python examples/openai_server.py ... &),并记下它的地址,如http://<服务器IP>:8000 - 打开 OpenWebUI,进入 Admin Panel → Settings → External Models → Add Model
- 类型选择 OpenAI 兼容的 TTS 接口,Base URL 填
http://<服务器IP>:8000/v1 - 测试连接后保存,OpenWebUI 会拉取音色列表;在聊天界面即可选择该 TTS 模型朗读回复
请求到达服务器后,voice 字段会被路由到对应音色配置(音色解析逻辑见 examples/openai_server.py),未配置的音色会自动回落到默认音色。
多音色配置:让 OpenWebUI 拥有更多声音 🎙
单音色模式下所有请求都用同一个参考音频。想暴露多个音色(比如"新闻播报音""温柔女声"),准备一个 JSON 文件 voices.json:
{
"alloy": {"ref_audio": "voice.wav", "ref_text": "这段是 voice.wav 的转录", "language": "English"},
"echo": {"ref_audio": "voice2.wav", "ref_text": "这是 voice2.wav 的转录", "language": "English"}
}
然后启动时改用 --voices 参数:
python examples/openai_server.py --voices voices.json
在 OpenWebUI 的请求中填 voice: "alloy" 或 "echo",即会被路由到对应参考音频,无需重启服务。
输出格式小贴士: response_format 支持 wav、pcm、mp3 三种。WAV/PCM 走流式路径;MP3 需要额外安装 pydub(pip install pydub),且为整段非流式返回。
常见问题排查 ⚠️
| 现象 | 原因与解决 |
|---|---|
返回 503 Model not loaded |
模型还在加载中或加载失败,查看服务器日志确认 |
返回 400 Voice ... is not configured |
请求的音色名不在 voices.json 中,用错误信息里列出的可用名称 |
torch.cuda.is_available() 为 False |
NVIDIA 驱动与 PyTorch wheel 的 CUDA 版本不匹配,按 README.md 安装对应 cu12x 版本的 wheel |
| 想换更小的模型 | 0.6B 模型显存占用更低:--model Qwen/Qwen3-TTS-12Hz-0.6B-Base |
并发请求由内置的模型锁串行执行 GPU 推理,这是为保证数值正确性做的取舍,单流场景下不影响"边生成边播放"的体验。
小结
通过本文的四步流程——安装 faster-qwen3-tts → 启动 OpenAI 兼容 TTS API 服务器 → curl 验证 → OpenWebUI 接入——你就在本地搭建了一个实时、可多音色的语音合成服务。RTX 4090 上 4.7 倍实时率 + 156ms 首包延迟的组合,让 OpenWebUI 的朗读体验接近"即点即听"。后续还可以用 model.warmup() 预热模型、用 --device 切换计算设备,进一步提升响应表现。