把 faster-qwen3-tts 接入 OpenWebUI:搭建 OpenAI 兼容的 TTS API 服务器

原创2026-10-12 19:08:451,929 阅读

把 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

  1. 确保 faster-qwen3-tts 的 API 服务器已在后台运行(例如 python examples/openai_server.py ... &),并记下它的地址,如 http://<服务器IP>:8000
  2. 打开 OpenWebUI,进入 Admin Panel → Settings → External Models → Add Model
  3. 类型选择 OpenAI 兼容的 TTS 接口,Base URL 填 http://<服务器IP>:8000/v1
  4. 测试连接后保存,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 切换计算设备,进一步提升响应表现。

登录后查看全文
faster-qwen3-tts