Integración de Qwen3-TTS

Ejecuta Qwen3-TTS de Alibaba localmente para obtener síntesis de voz multilingüe de alta calidad. Esta guía explica cómo configurar el servidor TTS compatible con OpenAI incluido en Libre WebUI.

Descripción general

Qwen3-TTS es un sistema avanzado que ofrece:

9 voces predefinidas en inglés, chino, japonés y coreano
Compatibilidad con 10 idiomas, incluidos alemán, francés, español, italiano, portugués y ruso
Clonación de voz a partir de muestras de 3 segundos
Diseño de voces mediante descripciones en lenguaje natural
Control por instrucciones de la emoción y la prosodia

El servidor incluido envuelve Qwen3-TTS en una API compatible con OpenAI para que Libre WebUI lo use mediante el sistema estándar de plugins.

Requisitos

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

Plataformas compatibles

Plataforma	Backend	Notas
GPU NVIDIA	CUDA	Mejor rendimiento, compatible con bfloat16
Apple Silicon	MPS	Usa modelos 0.6B para ahorrar memoria
CPU	PyTorch	Más lento; usa modelos 0.6B

Usuarios de Apple Silicon

Usa la variante customvoice-0.6b en Mac para evitar presión de memoria. Los modelos 1.7B pueden causar inestabilidad en equipos con 16GB de memoria unificada.

Inicio rápido

1. Instalar el 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. Iniciar el 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

El servidor se ejecuta en http://localhost:8100 de forma predeterminada.

3. Configurar Libre WebUI

El plugin está preconfigurado en plugins/qwen-tts.json. Actívalo en Ajustes → Plugins → Qwen3 TTS.

4. Probarlo

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 disponibles

Modelo	Tamaño	Uso
`customvoice-1.7b`	~3.5GB	Voces predefinidas con control por instrucciones
`customvoice-0.6b`	~1.5GB	Variante ligera para VRAM limitada
`voicedesign-1.7b`	~3.5GB	Crear voces desde descripciones
`base-1.7b`	~3.5GB	Clonar voces desde muestras de 3 segundos
`base-0.6b`	~1.5GB	Clonación ligera

Voces

Voces predefinidas (modelos CustomVoice)

Voz	Idioma	Descripción
Ryan	Inglés	Masculina, clara y natural
Aiden	Inglés	Masculina, tono cálido
Vivian	Chino	Femenina, profesional
Serena	Chino	Femenina, amable
Uncle_Fu	Chino	Masculina, madura
Dylan	Chino	Masculina, dialecto de Pekín
Eric	Chino	Masculina, dialecto de Sichuan
Ono_Anna	Japonés	Femenina
Sohee	Coreano	Femenina

Alias de voces de OpenAI

Para ser compatible con clientes TTS de OpenAI, el servidor asigna estos nombres:

Voz OpenAI	Se asigna a
`alloy`	Ryan
`echo`	Aiden
`fable`	Vivian
`onyx`	Uncle_Fu
`nova`	Serena
`shimmer`	Ono_Anna

Referencia de la API

Generación de voz

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	Predeterminado	Descripción
`model`	string	`qwen3-tts`	Identificador del modelo
`input`	string	obligatorio	Texto que sintetizar (máx. 10,000 caracteres)
`voice`	string	`ryan`	Nombre de voz
`response_format`	string	`wav`	Formato (solo se admite `wav`)
`instruct`	string	`""`	Instrucción de emoción o prosodia
`language`	string	detección automática	Sustituye la detección del idioma

Respuesta: archivo de audio (audio/wav)

Diseño de voces

Endpoint: POST /v1/audio/voice-design

Crea voces personalizadas desde descripciones en lenguaje natural.

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

nota

Requiere cargar el modelo voicedesign-1.7b.

Clonación de voz

Endpoint: POST /v1/audio/voice-clone

Clona una voz desde una muestra de al menos 3 segundos.

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	Descripción
`input`	string	Texto que sintetizar
`reference_audio`	file	Muestra de al menos 3 segundos
`reference_text`	string	Transcripción del audio de referencia

nota

Requiere cargar base-1.7b o base-0.6b.

Listar voces

Endpoint: GET /v1/voices

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

Comprobación de salud

Endpoint: GET /health

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

Configuración del servidor

python server.py [OPTIONS]

Opción	Predeterminado	Descripción
`--host`	`0.0.0.0`	Host al que vincularse
`--port`	`8100`	Puerto al que vincularse
`--model`	`customvoice-1.7b`	Variante que cargar

Acceso de red

Para acceder desde otras máquinas:

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

Actualiza el endpoint en 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"
    }
  }
}

Funciones de producción

Saneamiento del texto

El servidor sanea automáticamente la entrada para evitar bloqueos:

Elimina emojis y símbolos
Quita formato markdown (*bold*, _italic_, etc.)
Reduce caracteres repetidos (FUUUUU → FUU)
Elimina acotaciones (*(action)*, (whispers))
Normaliza espacios

División del texto

Los textos largos se dividen automáticamente en límites de oración:

Máximo de 500 caracteres por fragmento
Tiempo de espera de 30 segundos por fragmento
Los fragmentos fallidos se omiten y los demás continúan
Los fragmentos se concatenan en una sola respuesta

Así se evitan tiempos de espera en respuestas largas manteniendo una voz natural.

Configuración multi-GPU

En sistemas con varias GPU, el servidor fuerza una sola GPU para evitar incompatibilidades de dispositivo entre tensores:

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

Para usar una GPU concreta:

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

Solución de problemas

Falla la descarga del modelo

El modelo se descarga de Hugging Face en la primera ejecución. Si falla:

# 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 insuficiente (Apple Silicon)

RuntimeError: MPS backend out of memory

Usa la variante pequeña:

python server.py --model customvoice-0.6b

Memoria CUDA insuficiente

torch.cuda.OutOfMemoryError: CUDA out of memory

Cierra otras aplicaciones de GPU
Usa la variante 0.6B
Reduce el tamaño en server.py (max_chunk_size=300)

El servidor agota el tiempo

Si la generación de un texto largo agota el tiempo:

El servidor divide automáticamente el texto y continúa
Consulta los registros para saber qué fragmentos fallaron
Considera acortar la entrada

El audio suena mal

Sílabas repetidas: suelen deberse a emojis o caracteres especiales; el saneador debe eliminarlos.
Idioma incorrecto: define explícitamente language.
Pausas poco naturales: revisa la puntuación inusual.

Configuración del plugin

El plugin incluido (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

Qwen3-TTS en GitHub - Repositorio oficial
Demostración de Qwen3-TTS - Pruébalo en línea
Documentación TTS de Alibaba Cloud - Documentación de la API en la nube

Descripción general​

Requisitos​

Plataformas compatibles​

Inicio rápido​

1. Instalar el servidor​

2. Iniciar el servidor​

3. Configurar Libre WebUI​

4. Probarlo​

Modelos disponibles​

Voces​

Voces predefinidas (modelos CustomVoice)​

Alias de voces de OpenAI​

Referencia de la API​

Generación de voz​

Diseño de voces​

Clonación de voz​

Listar voces​

Comprobación de salud​

Configuración del servidor​

Acceso de red​

Funciones de producción​

Saneamiento del texto​

División del texto​

Configuración multi-GPU​

Solución de problemas​

Falla la descarga del modelo​

Memoria insuficiente (Apple Silicon)​

Memoria CUDA insuficiente​

El servidor agota el tiempo​

El audio suena mal​

Configuración del plugin​

Recursos​