Integração com o Qwen3-TTS

Execute localmente o Qwen3-TTS da Alibaba para conversão multilíngue de texto em fala com alta qualidade. Este guia explica como configurar o servidor TTS compatível com OpenAI incluído no Libre WebUI.

Visão geral

O Qwen3-TTS é um sistema avançado de conversão de texto em fala que oferece:

• 9 vozes prontas em inglês, chinês, japonês e coreano
• Suporte a 10 idiomas, incluindo alemão, francês, espanhol, italiano, português e russo
• Clonagem de voz a partir de amostras de áudio de 3 segundos
• Criação de vozes usando descrições em linguagem natural
• Controle por instruções para emoção e prosódia

O servidor incluído envolve o Qwen3-TTS em uma API compatível com OpenAI, permitindo que o Libre WebUI o use pelo sistema padrão de plugins.

Requisitos

Componente	Mínimo	Recomendado
Python	3.12+	3.12 (não 3.14)
VRAM da GPU	4GB (modelos 0.6B)	8GB+ (modelos 1.7B)
RAM	8GB	16GB+
Disco	5GB	10GB

Suporte a plataformas

Plataforma	Backend	Observações
GPU NVIDIA	CUDA	Melhor desempenho, suporte a bfloat16
Apple Silicon	MPS	Use modelos 0.6B para economizar memória
CPU	PyTorch	Mais lento; use modelos 0.6B

Para usuários do Apple Silicon

Use a variante de modelo customvoice-0.6b no Mac para evitar pressão sobre a memória. Os modelos 1.7B podem causar instabilidade do sistema em máquinas com 16GB de memória unificada.

Início rápido

1. Instale o servidor

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. Inicie o servidor

# 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

Por padrão, o servidor é executado em http://localhost:8100.

3. Configure o Libre WebUI

O plugin vem pré-configurado em plugins/qwen-tts.json. Ative-o em Configurações → Plugins → Qwen3 TTS.

4. Teste

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

Modelos disponíveis

Modelo	Tamanho	Caso de uso
customvoice-1.7b	~3.5GB	Vozes prontas com controle por instruções
customvoice-0.6b	~1.5GB	Variante leve para VRAM limitada
voicedesign-1.7b	~3.5GB	Criar vozes a partir de descrições textuais
base-1.7b	~3.5GB	Clonagem de voz com amostras de 3 segundos
base-0.6b	~1.5GB	Clonagem de voz leve

Vozes

Vozes prontas (modelos CustomVoice)

Voz	Idioma	Descrição
Ryan	Inglês	Masculina, clara e natural
Aiden	Inglês	Masculina, tom acolhedor
Vivian	Chinês	Feminina, profissional
Serena	Chinês	Feminina, amigável
Uncle_Fu	Chinês	Masculina, madura
Dylan	Chinês	Masculina, dialeto de Pequim
Eric	Chinês	Masculina, dialeto de Sichuan
Ono_Anna	Japonês	Feminina
Sohee	Coreano	Feminina

Aliases de vozes da OpenAI

Para oferecer compatibilidade com clientes TTS da OpenAI, o servidor mapeia os nomes de voz da OpenAI:

Voz da OpenAI	Mapeada para
alloy	Ryan
echo	Aiden
fable	Vivian
onyx	Uncle_Fu
nova	Serena
shimmer	Ono_Anna

Referência da API

Geração de fala

Endpoint: POST /v1/audio/speech

{
  "model": "qwen3-tts",
  "input": "Text to convert to speech",
  "voice": "Ryan",
  "response_format": "wav",
  "instruct": "Speak with enthusiasm",
  "language": "English"
}

Parâmetro	Tipo	Padrão	Descrição
model	string	qwen3-tts	Identificador do modelo
input	string	required	Texto a sintetizar (máx. 10.000 caracteres)
voice	string	ryan	Nome da voz (consulte a tabela acima)
response_format	string	wav	Formato do áudio (somente wav é compatível)
instruct	string	""	Instrução de emoção/prosódia
language	string	auto-detect	Substituir a detecção de idioma

Resposta: arquivo de áudio (audio/wav)

Criação de voz

Endpoint: POST /v1/audio/voice-design

Crie vozes personalizadas a partir de descrições em linguagem natural.

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

observação

Exige que o modelo voicedesign-1.7b esteja carregado.

Clonagem de voz

Endpoint: POST /v1/audio/voice-clone

Clone uma voz a partir de uma amostra de áudio de 3 segundos ou mais.

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

Parâmetro	Tipo	Descrição
input	string	Texto a sintetizar
reference_audio	file	Amostra de áudio de 3 segundos ou mais
reference_text	string	Transcrição do áudio de referência

observação

Exige que o modelo base-1.7b ou base-0.6b esteja carregado.

Listar vozes

Endpoint: GET /v1/voices

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

Verificação de integridade

Endpoint: GET /health

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

Configuração do servidor

python server.py [OPTIONS]

Opção	Padrão	Descrição
--host	0.0.0.0	Host ao qual vincular
--port	8100	Porta à qual vincular
--model	customvoice-1.7b	Variante do modelo a carregar

Acesso pela rede

Para acessar o servidor de outras máquinas da sua rede:

# 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 ...

Atualize o endpoint do plugin em 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"
    }
  }
}

Recursos de produção

Sanitização de texto

O servidor sanitiza automaticamente o texto de entrada para evitar travamentos do modelo:

• Remove emojis e símbolos
• Remove a formatação Markdown (*bold*, _italic_ etc.)
• Reduz caracteres repetidos (FUUUUU → FUU)
• Remove indicações de cena (*(action)*, (whispers))
• Normaliza os espaços em branco

Divisão do texto

Textos longos são divididos automaticamente nos limites das frases:

• Máximo de 500 caracteres por trecho
• Tempo limite de 30 segundos por trecho
• Trechos com falha são ignorados; os restantes continuam
• Os trechos são concatenados em uma única resposta de áudio

Isso evita tempos limite em respostas longas de IA e mantém o fluxo natural da fala.

Configuração com várias GPUs

Em sistemas com várias GPUs, o servidor força a execução em uma única GPU para evitar incompatibilidades entre dispositivos dos tensores:

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

Para usar uma GPU específica:

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

Solução de problemas

Falha no download do modelo

O modelo é baixado do Hugging Face na primeira execução. Se isso falhar:

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

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

Falta de memória (Apple Silicon)

RuntimeError: MPS backend out of memory

Use a variante menor do modelo:

python server.py --model customvoice-0.6b

Falta de memória CUDA

torch.cuda.OutOfMemoryError: CUDA out of memory

1. Feche outros aplicativos que usam a GPU
2. Use a variante de modelo 0.6B
3. Reduza o tamanho dos trechos em server.py (max_chunk_size=300)

O servidor excede o tempo limite

Se a geração exceder o tempo limite com textos longos:

1. O servidor divide o texto automaticamente e continua com os trechos restantes
2. Verifique nos logs do servidor quais trechos excederam o tempo limite
3. Considere encurtar o texto de entrada

O áudio parece incorreto

• Sílabas repetidas: geralmente causadas por emojis ou caracteres especiais. O sanitizador deve tratar isso automaticamente.
• Idioma incorreto: defina explicitamente o parâmetro language na solicitação.
• Pausas pouco naturais: o texto pode estar sendo dividido nos pontos errados. Verifique se há pontuação incomum.

Configuração do plugin

O plugin incluído (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"
}

Recursos

• GitHub do Qwen3-TTS - Repositório oficial
• Demonstração do Qwen3-TTS - Experimente online
• Documentação de TTS do Alibaba Cloud - Documentação da API em nuvem