跳到主要内容

Qwen3-TTS 集成

在本地运行 Alibaba 的 Qwen3-TTS，获得高质量、多语言的文本转语音体验。本指南介绍如何设置 Libre WebUI 随附的 OpenAI 兼容 TTS 服务器。

概述​

Qwen3-TTS 是先进的文本转语音系统，具有：

  • 涵盖英语、中文、日语和韩语的 9 种预置声音
  • 支持 10 种语言，包括德语、法语、西班牙语、意大利语、葡萄牙语和俄语
  • 从 3 秒音频样本进行语音克隆
  • 使用自然语言描述进行声音设计
  • 用于情感和韵律的指令控制

随附服务器将 Qwen3-TTS 封装为 OpenAI 兼容 API，使 Libre WebUI 能通过标准插件系统使用它。

要求​

组件最低要求推荐配置
Python3.12+3.12（不是 3.14）
GPU 显存4GB（0.6B 模型）8GB+（1.7B 模型）
内存8GB16GB+
磁盘5GB10GB

平台支持​

平台后端说明
NVIDIA GPUCUDA性能最佳，支持 bfloat16
Apple SiliconMPS使用 0.6B 模型以提高内存效率
CPUPyTorch速度较慢，请使用 0.6B 模型
Apple Silicon 用户

在 Mac 上使用 customvoice-0.6b 模型变体，以避免内存压力。1.7B 模型可能导致配备 16GB 统一内存的机器系统不稳定。

快速开始​

1. 安装服务器​

cd examples/qwen-tts-server

# Create virtual environment (Python 3.12 required)
python3.12 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

2. 启动服务器​

# NVIDIA GPU (recommended)
python server.py --model customvoice-1.7b

# Apple Silicon
python server.py --model customvoice-0.6b

# CPU (slower)
python server.py --model customvoice-0.6b

服务器默认运行在 http://localhost:8100。

3. 配置 Libre WebUI​

插件已预先配置在 plugins/qwen-tts.json 中。在设置 → 插件 → Qwen3 TTS中启用它。

4. 测试​

curl http://localhost:8100/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-tts", "input": "Hello, welcome to Libre WebUI!", "voice": "Ryan"}' \
  --output speech.wav

可用模型​

模型大小用途
customvoice-1.7b~3.5GB支持指令控制的预置声音
customvoice-0.6b~1.5GB面向有限显存的轻量变体
voicedesign-1.7b~3.5GB根据文本描述创建声音
base-1.7b~3.5GB从 3 秒样本克隆语音
base-0.6b~1.5GB轻量语音克隆

声音​

预置声音（CustomVoice 模型）​

声音语言描述
Ryan英语男声，清晰自然
Aiden英语男声，音色温暖
Vivian中文女声，专业
Serena中文女声，友好
Uncle_Fu中文男声，成熟
Dylan中文男声，北京方言
Eric中文男声，四川方言
Ono_Anna日语女声
Sohee韩语女声

OpenAI 声音别名​

为兼容 OpenAI TTS 客户端，服务器会映射 OpenAI 声音名称：

OpenAI 声音映射到
alloyRyan
echoAiden
fableVivian
onyxUncle_Fu
novaSerena
shimmerOno_Anna

API 参考​

语音生成​

端点： POST /v1/audio/speech

{
  "model": "qwen3-tts",
  "input": "Text to convert to speech",
  "voice": "Ryan",
  "response_format": "wav",
  "instruct": "Speak with enthusiasm",
  "language": "English"
}
参数类型默认值描述
modelstringqwen3-tts模型标识符
inputstringrequired要合成的文本（最多 10,000 个字符）
voicestringryan声音名称（见上表）
response_formatstringwav音频格式（仅支持 wav）
instructstring""情感/韵律指令
languagestringauto-detect覆盖语言检测

**响应：**音频文件（audio/wav）

声音设计​

端点： POST /v1/audio/voice-design

根据自然语言描述创建自定义声音。

{
  "model": "qwen3-tts-voicedesign",
  "input": "Welcome to our service.",
  "voice_description": "A warm, friendly female voice with a slight British accent",
  "language": "English"
}
备注

需要加载 voicedesign-1.7b 模型。

语音克隆​

端点： POST /v1/audio/voice-clone

从时长 3 秒以上的音频样本克隆声音。

curl -X POST http://localhost:8100/v1/audio/voice-clone \
  -F "input=Hello, this is my cloned voice." \
  -F "reference_audio=@reference.wav" \
  -F "reference_text=This is what was said in the reference." \
  --output cloned.wav
参数类型描述
inputstring要合成的文本
reference_audiofile时长 3 秒以上的音频样本
reference_textstring参考音频的转录文本
备注

需要加载 base-1.7b 或 base-0.6b 模型。

列出声音​

端点： GET /v1/voices

{
  "voices": [
    {"id": "ryan", "name": "Ryan", "language": "English"},
    {"id": "aiden", "name": "Aiden", "language": "English"},
    ...
  ]
}

健康检查​

端点： GET /health

{ "status": "healthy", "model_loaded": true }

服务器配置​

python server.py [OPTIONS]
选项默认值描述
--host0.0.0.0要绑定的主机
--port8100要绑定的端口
--modelcustomvoice-1.7b要加载的模型变体

网络访问​

从网络上的其他机器访问服务器：

# Start server on all interfaces
python server.py --host 0.0.0.0 --port 8100

# Access from another machine
curl http://192.168.1.100:8100/v1/audio/speech ...

更新 plugins/qwen-tts.json 中的插件端点：

{
  "endpoint": "http://192.168.1.100:8100/v1/audio/speech",
  "capabilities": {
    "tts": {
      "endpoint": "http://192.168.1.100:8100/v1/audio/speech"
    }
  }
}

生产功能​

文本清理​

服务器会自动清理输入文本，防止模型卡住：

  • 移除表情符号和特殊符号
  • 去除 markdown 格式（*bold*、_italic_ 等）
  • 合并重复字符（FUUUUU → FUU）
  • 移除舞台指示（*(action)*、(whispers)）
  • 规范化空白字符

文本分块​

长文本会在句子边界自动拆分：

  • 每块最多 500 个字符
  • 每块超时时间为 30 秒
  • 失败的块会跳过，其余块继续处理
  • 各块拼接成单个音频响应

这能防止较长 AI 回复超时，同时保持自然的语流。

多 GPU 设置​

对于配有多个 GPU 的系统，服务器会强制使用单 GPU 执行，以避免张量设备不匹配：

device_map = {"": "cuda:0"}  # Uses first GPU only

使用特定 GPU：

CUDA_VISIBLE_DEVICES=1 python server.py --model customvoice-1.7b

故障排查​

模型下载失败​

首次运行时，模型会从 Hugging Face 下载。如果失败：

# Set Hugging Face token for gated models
export HF_TOKEN=hf_...

# Or download manually
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice

内存不足（Apple Silicon）​

RuntimeError: MPS backend out of memory

使用较小的模型变体：

python server.py --model customvoice-0.6b

CUDA 显存不足​

torch.cuda.OutOfMemoryError: CUDA out of memory
  1. 关闭其他 GPU 应用
  2. 使用 0.6B 模型变体
  3. 减小 server.py 中的块大小（max_chunk_size=300）

服务器超时​

如果生成长文本时超时：

  1. 服务器会自动拆分文本并继续处理剩余块
  2. 检查服务器日志，确认哪些块超时
  3. 考虑缩短输入文本

音频听起来不对​

  • **音节重复：**通常由表情符号或特殊字符引起。清理程序应会自动处理。
  • **语言错误：**在请求中明确设置 language 参数。
  • **停顿不自然：**文本可能在错误的边界拆分。请检查异常标点。

插件配置​

随附插件（plugins/qwen-tts.json）：

{
  "id": "qwen-tts",
  "name": "Qwen3 TTS",
  "type": "tts",
  "endpoint": "http://localhost:8100/v1/audio/speech",
  "auth": {
    "header": "",
    "key_env": ""
  },
  "model_map": [
    "qwen3-tts",
    "qwen3-tts-customvoice",
    "qwen3-tts-voicedesign",
    "qwen3-tts-clone"
  ],
  "capabilities": {
    "tts": {
      "endpoint": "http://localhost:8100/v1/audio/speech",
      "model_map": [
        "qwen3-tts",
        "qwen3-tts-customvoice",
        "qwen3-tts-voicedesign",
        "qwen3-tts-clone"
      ],
      "config": {
        "voices": [
          "Ryan",
          "Aiden",
          "Vivian",
          "Serena",
          "Uncle_Fu",
          "Dylan",
          "Eric",
          "Ono_Anna",
          "Sohee"
        ],
        "default_voice": "Ryan",
        "formats": ["wav"],
        "default_format": "wav",
        "max_characters": 10000,
        "supports_streaming": false,
        "no_auth_required": true
      }
    }
  },
  "description": "Qwen3-TTS local TTS server (NVIDIA CUDA, Apple MPS, or CPU)",
  "documentation_url": "https://github.com/QwenLM/Qwen3-TTS"
}

资源​