Integrazione Qwen3-TTS

Esegui Qwen3-TTS di Alibaba localmente per una sintesi vocale multilingue di alta qualità. Questa guida descrive la configurazione del server TTS compatibile con OpenAI incluso in Libre WebUI.

Panoramica

Qwen3-TTS è un sistema avanzato di sintesi vocale che offre:

• 9 voci predefinite in inglese, cinese, giapponese e coreano
• Supporto di 10 lingue, tra cui tedesco, francese, spagnolo, italiano, portoghese e russo
• Clonazione vocale da campioni audio di 3 secondi
• Progettazione della voce mediante descrizioni in linguaggio naturale
• Controllo tramite istruzioni di emozione e prosodia

Il server incluso racchiude Qwen3-TTS in un'API compatibile con OpenAI, consentendo a Libre WebUI di usarlo attraverso il sistema di plugin standard.

Requisiti

Componente	Minimo	Consigliato
Python	3.12+	3.12 (non 3.14)
VRAM GPU	4GB (modelli 0.6B)	8GB+ (modelli 1.7B)
RAM	8GB	16GB+
Disco	5GB	10GB

Piattaforme supportate

Piattaforma	Backend	Note
GPU NVIDIA	CUDA	Prestazioni migliori, supporto bfloat16
Apple Silicon	MPS	Usa modelli 0.6B per ridurre l'uso di memoria
CPU	PyTorch	Più lento, usa modelli 0.6B

Utenti Apple Silicon

Su Mac usa la variante del modello customvoice-0.6b per evitare un'eccessiva pressione sulla memoria. I modelli 1.7B possono rendere instabile il sistema sulle macchine con 16GB di memoria unificata.

Avvio rapido

1. Installare il server

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. Avviare il server

# 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

Per impostazione predefinita, il server viene eseguito all'indirizzo http://localhost:8100.

3. Configurare Libre WebUI

Il plugin è preconfigurato in plugins/qwen-tts.json. Abilitalo in Impostazioni → Plugin → Qwen3 TTS.

4. Verificarne il funzionamento

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

Modelli disponibili

Modello	Dimensione	Caso d'uso
customvoice-1.7b	~3.5GB	Voci predefinite con controllo tramite istruzioni
customvoice-0.6b	~1.5GB	Variante leggera per VRAM limitata
voicedesign-1.7b	~3.5GB	Creazione di voci da descrizioni testuali
base-1.7b	~3.5GB	Clonazione vocale da campioni di 3 secondi
base-0.6b	~1.5GB	Clonazione vocale leggera

Voci

Voci predefinite (modelli CustomVoice)

Voce	Lingua	Descrizione
Ryan	Inglese	Maschile, chiara e naturale
Aiden	Inglese	Maschile, tono caldo
Vivian	Cinese	Femminile, professionale
Serena	Cinese	Femminile, amichevole
Uncle_Fu	Cinese	Maschile, matura
Dylan	Cinese	Maschile, dialetto di Pechino
Eric	Cinese	Maschile, dialetto del Sichuan
Ono_Anna	Giapponese	Femminile
Sohee	Coreano	Femminile

Alias delle voci OpenAI

Per la compatibilità con i client TTS OpenAI, il server associa i nomi delle voci OpenAI:

Voce OpenAI	Associata a
alloy	Ryan
echo	Aiden
fable	Vivian
onyx	Uncle_Fu
nova	Serena
shimmer	Ono_Anna

Riferimento API

Generazione vocale

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"
}

Parametro	Tipo	Valore predefinito	Descrizione
model	string	qwen3-tts	Identificatore del modello
input	string	obbligatorio	Testo da sintetizzare (max 10.000 caratteri)
voice	string	ryan	Nome della voce (vedi tabella precedente)
response_format	string	wav	Formato audio (è supportato solo wav)
instruct	string	""	Istruzione per emozione/prosodia
language	string	rilevamento automatico	Sostituisce il rilevamento della lingua

Risposta: file audio (audio/wav)

Progettazione della voce

Endpoint: POST /v1/audio/voice-design

Crea voci personalizzate da descrizioni in linguaggio naturale.

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

nota

Richiede che sia caricato il modello voicedesign-1.7b.

Clonazione vocale

Endpoint: POST /v1/audio/voice-clone

Clona una voce da un campione audio di almeno 3 secondi.

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

Parametro	Tipo	Descrizione
input	string	Testo da sintetizzare
reference_audio	file	Campione audio di almeno 3 secondi
reference_text	string	Trascrizione dell'audio di riferimento

nota

Richiede che sia caricato il modello base-1.7b o base-0.6b.

Elencare le voci

Endpoint: GET /v1/voices

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

Controllo dello stato

Endpoint: GET /health

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

Configurazione del server

python server.py [OPTIONS]

Opzione	Valore predefinito	Descrizione
--host	0.0.0.0	Host a cui effettuare il binding
--port	8100	Porta a cui effettuare il binding
--model	customvoice-1.7b	Variante del modello da caricare

Accesso di rete

Per accedere al server da altre macchine della rete:

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

Aggiorna l'endpoint del plugin in 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"
    }
  }
}

Funzionalità per la produzione

Sanificazione del testo

Il server sanifica automaticamente il testo di input per evitare blocchi del modello:

• Rimuove emoji e simboli
• Elimina la formattazione Markdown (*bold*, _italic_ e così via)
• Riduce i caratteri ripetuti (FUUUUU → FUU)
• Rimuove le indicazioni sceniche (*(action)*, (whispers))
• Normalizza gli spazi

Suddivisione del testo

Il testo lungo viene suddiviso automaticamente ai confini delle frasi:

• Massimo 500 caratteri per segmento
• Timeout di 30 secondi per segmento
• I segmenti non riusciti vengono saltati e i restanti continuano
• I segmenti vengono concatenati in un'unica risposta audio

Ciò evita timeout nelle risposte AI lunghe, mantenendo naturale il flusso del parlato.

Configurazione con più GPU

Nei sistemi con più GPU, il server forza l'esecuzione su una sola GPU per evitare incompatibilità dei dispositivi dei tensori:

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

Per usare una GPU specifica:

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

Risoluzione dei problemi

Download del modello non riuscito

Il modello viene scaricato da Hugging Face al primo avvio. Se il download non riesce:

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

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

Memoria esaurita (Apple Silicon)

RuntimeError: MPS backend out of memory

Usa la variante più piccola del modello:

python server.py --model customvoice-0.6b

Memoria CUDA esaurita

torch.cuda.OutOfMemoryError: CUDA out of memory

1. Chiudi le altre applicazioni che usano la GPU
2. Usa la variante 0.6B del modello
3. Riduci la dimensione dei segmenti in server.py (max_chunk_size=300)

Timeout del server

Se la generazione va in timeout con un testo lungo:

1. Il server suddivide automaticamente il testo e continua con i segmenti restanti
2. Controlla nei log del server quali segmenti sono andati in timeout
3. Valuta la possibilità di accorciare il testo di input

Audio non corretto

• Sillabe ripetute: in genere sono causate da emoji o caratteri speciali. Il sistema di sanificazione dovrebbe gestirli automaticamente.
• Lingua errata: imposta esplicitamente il parametro language nella richiesta.
• Pause innaturali: il testo potrebbe essere suddiviso nei punti sbagliati. Controlla la presenza di punteggiatura insolita.

Configurazione del plugin

Il plugin incluso (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"
}

Risorse

• GitHub di Qwen3-TTS - Repository ufficiale
• Demo di Qwen3-TTS - Provalo online
• Documentazione TTS di Alibaba Cloud - Documentazione dell'API cloud