Este tutorial detalla cómo implementar el modelo de síntesis de voz Qwen3-TTS-1.7B-Base utilizando contenedores Docker. El modelo permite generar audio de alta calidad a partir de texto, clonar voces y soporta múltiples idiomas, lo que facilita su integración en aplicaciones de contenido multimedia.

1. Verificación del entorno e instalación de Docker

Antes de iniciar, asegúrese de que su sistema cumple con los requisitos necesarios para alojar el modelo.

1.1 Requisitos del sistema

• SO recomendado: Linux (Ubuntu 20.04/22.04) o macOS. Windows puede usar WSL2 para entornos Linux.
• Memoria RAM: Mínimo 8 GB para un rendimiento óptimo.
• Almacenamiento: Al mennos 10 GB de espacio libre para la imagen y archivos del modelo.
• Conexión a red: Estable para descargar la imagen Docker.

1.2 Instalación de Docker y Docker Compose

Para sistemas basados en Debian/Ubuntu, ejecute los siguientes comandos en la terminal:

# Actualizar repositorios
sudo apt-get update

# Instalar dependencias
sudo apt-get install -y ca-certificates curl gnupg

# Configurar el repositorio oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Verificar la instalación
docker --version
docker compose version

Para macOS, descargue e instale Docker Desktop desde el sitio oficial. En Windows, use Docker Desktop con WL2 habilitado.

Opcionalmente, añada su usuario al grupo docker para evitar usar sudo:

sudo usermod -aG docker $USER

Reinicie la sesión para aplicar los cambios.

2. Obtención y ejecución de la imagen Docker

Descargue e inicie el contenedor con el modelo preconfigurado.

2.1 Comando de despliegue

Ejecute el siguiente comando en la terminal:

docker run -d --nombre tts-qwen -p 8080:7860 --gpus all csdns/qwen3-tts-12hz-1.7b-base:latest

Desglose de parámetros:

• docker run: Crea y arranca un nuevo contenedor.
• -d: Ejecuta el contenedor en segundo plano.
• --nombre tts-qwen: Asigna un nombre descriptivo al contenedor para facilitar su gestión.
• -p 8080:7860: Mapea el puerto 7860 del contenedor al puerto 8080 local, permitiendo el acceso vía navegador.
• --gpus all: Habilita el uso de GPUs NVIDIA para acelerar la inferencia. Sin GPU, el modelo usará CPU pero será más lento.
• csdns/qwen3-tts-12hz-1.7b-base:latest: Especifica la imagen y versión a descargar.

La primera ejecución descargará varios gigabytes de datos; espere a que finalice.

2.2 Comprobación del estado del contenedor

Verifique que el contenedor está en ejecución:

docker ps

Si el contenedor no aparece, revise todos los contenedores con:

docker ps -a

Para diagnosticar problemas, examine los registros:

docker logs tts-qwen

Errores comunes incluyen conflictos de puertos o problemas con los controladores de GPU.

3. Acceso a la interfaz web y uso inicial

Una vez el contenedor esté activo, acceda a la aplicación web.

3.1 Interfaz de usuario

Abra su navegador y navegue a http://localhost:8080 (ajuste el puerto si lo modificó). La carga inicial puede tomar hasta un minuto mientras el modelo se inicializa.

3.2 Generación de voz desde texto

1. Localice el campo de entrada de teexto en la interfaz.
2. Escriba el contenido deseado, por ejemplo: "Hola, esto es una prueba de síntesis de voz."
3. Seleccione el idioma, voz predefinida y ajuste parámetros como velocidad.
4. Pulse el botón de generación y espere a que se produzca el audio.
5. Reproduzca el archivo de audio resultante usando el reproductor integrado.

3.3 Clonación de voces

Para replicar una voz específica:

1. Prepare un archivo de audio de referencia (10-60 segundos, formato WAV o MP3) con voz clara y sin ruido.

2. Suba el archivo mediante la sección de clonación en la interfaz.

3. Introduzca el texto que desee sintetizar con la voz clonada.

4. Genere el audio y compare el resultado con la muestra original.

5. Configuración avanzada y solución de problemas

4.1 Personalización del mapeo de puertos

El formato del mapeo es -p <puerto_local>:<puerto_contenedor>. Cambie el puerto local para evitar conflictos o ejecutar múltiples servicios. Por ejemplo, use -p 9090:7860 y acceda vía http://localhost:9090. Para modificar un contenedor existente, deténgalo, elimínelo y vuelva a ejecutarlo con el nuevo puerto.

4.2 Persistencia de datos con volúmenes

Para conservar archivos generados o subidos, monte un directorio local en el contenedor:

docker run -d --nombre tts-qwen \
  -p 8080:7860 \
  --gpus all \
  -v $(pwd)/datos_tts:/app/data \
  csdns/qwen3-tts-12hz-1.7b-base:latest

Esto asegura que los datos persistan incluso si el contenedor se elimina.

4.3 Problemas frecuentes y soluciones

• Acceso denegado al puerto: Verifique que el puerto local no esté en uso por otra aplicación. Cambie el mapeo si es necesario.
• GPU no detectada: Ejecute nvidia-smi para confirmar que los controladores están instalados. Asegúrese de incluir --gpus all en el comando.
• Clonación de voz de baja calidad: Use muestras de audio limpias, con pronunciación clara y duración adecuada (10-30 segundos).
• Gestión de contenedores: Use comandos como docker stop tts-qwen, docker start tts-qwen o docker rm tts-qwen para controlar el ciclo de vida.

Con estos pasos, Qwen3-TTS-1.7B-Base estará operativo en su entorno, listo para aplicaciones de síntesis de voz multilingüe y clonación de voces.