Este tutorial cubre la instalación completa de Qwen3-ASR-1.7B, un sistema avanzado de reconocimiento automático de voz (ASR), en un entorno Ubuntu 22.04 con CUDA 12.1. Qwen3-ASR-1.7B representa una mejora significativa sobre versiones anteriores, ofreciendo un rendimiento superior en la transcripción de voz a texto, especialmente en escenarios complejos que involucran contenido mixto de chino e inglés, terminología especializada y oracoines largas.

Requisitos del Sistema

Hardware

• GPU: Tarjeta NVIDIA con al menos 24GB de VRAM (se recomiendan modelos como RTX 4090, A100).
• RAM: 32GB o más de memoria del sistema.
• Almacenamiento: Mínimo 50GB de espacio libre.

Software

Asegúrate de que tu sistema Ubuntu 22.04 esté actualizado:

sudo apt update && sudo apt upgrade -y

Instala los paquetes base necesarios:

sudo apt install -y python3-pip python3-venv git wget curl build-essential

Confiugración del Entorno CUDA 12.1

Instalación del Driver NVIDIA

Verifica tu driver actual:

nvidia-smi

Si es necesario, instala el driver más reciente:

sudo ubuntu-drivers autoinstall
sudo reboot

Instalación de CUDA Toolkit 12.1

Descarga e instala CUDA 12.1:

wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

Durante la instalación, selecciona:

• [X] CUDA Toolkit 12.1
• [ ] Driver (ya está instalado)
• [X] CUDA Samples (para pruebas)

Configuración de Variables de Entorno

Añade las rutas de CUDA a tu .bashrc:

echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

Verifica la instalación de CUDA:

nvcc --version

Creación de un Entorno Virtual de Python

Crea un entorno virtual dedicado:

python3 -m venv qwen-asr-env
source qwen-asr-env/bin/activate

Actualiza pip e instala las dependencias de PyTorch para CUDA 12.1:

pip install --upgrade pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Instalación de Dependencias para Qwen3-ASR-1.7B

Instala las librerías de reconocimiento de voz:

pip install transformers datasets soundfile librosa accelerate

Instala FFmpeg para el procesamiento de audio:

pip install ffmpeg-python
sudo apt install -y ffmpeg

Descarga y Despliegue del Modelo

Descarga del Modelo

Crea un directorio para el proyecto y clona el repositorio del modelo:

mkdir qwen3-asr-project && cd qwen3-asr-project
git lfs install
git clone https://huggingface.co/Qwen/Qwen3-ASR-1.7B

Verifica que los archivos del modelo (config.json, pytorch_model.bin, etc.) se hayan descargado correctamente en el directorio Qwen3-ASR-1.7B/.

Prueba Rápida de Transcripción

Script de Transcripción (transcribe.py)

import torch
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor
import soundfile as sf
import os

# Configuración del dispositivo (GPU si está disponible, de lo contrario CPU)
device = "cuda" if torch.cuda.is_available() else "cpu"
# Usar float16 para GPU si está disponible, de lo contrario float32
dtype = torch.float16 if device == "cuda" else torch.float32

# Ruta al modelo descargado
model_path = "./Qwen3-ASR-1.7B"

# Cargar el procesador y el modelo
try:
   processor = AutoProcessor.from_pretrained(model_path)
   model = AutoModelForSpeechSeq2Seq.from_pretrained(
       model_path,
       torch_dtype=dtype,
       low_cpu_mem_usage=True,
       use_safetensors=True
   ).to(device)
   print("Modelo y procesador cargados exitosamente.")
except Exception as e:
   print(f"Error al cargar el modelo o procesador: {e}")
   print("Asegúrate de que la ruta del modelo sea correcta y los archivos estén completos.")
   exit()

def perform_transcription(audio_filepath):
   """
   Realiza la transcripción de un archivo de audio dado.
   :param audio_filepath: Ruta al archivo de audio.
   :return: Cadena de texto transcrita.
   """
   if not os.path.exists(audio_filepath):
       print(f"Error: El archivo de audio '{audio_filepath}' no se encontró.")
       return None

   try:
       # Leer el archivo de audio
       audio_data, sample_rate = sf.read(audio_filepath)

       # Procesar la entrada de audio
       # Asegurarse de que la tasa de muestreo sea la esperada por el modelo (generalmente 16kHz para ASR)
       if sample_rate != 16000:
           print(f"Advertencia: La tasa de muestreo del audio ({sample_rate}Hz) no es 16kHz. El procesamiento puede ser subóptimo.")
           # Aquí podrías añadir lógica para re-muestrear si fuera necesario, pero transformers a menudo lo maneja internamente.

       input_features = processor(
           audio_data,
           sampling_rate=sample_rate,
           return_tensors="pt",
           padding=True
       ).input_features

       # Mover las características de entrada al dispositivo correcto
       input_features = input_features.to(device=device, dtype=dtype)

       # Generar la transcripción
       print("Generando transcripción...")
       with torch.no_grad():
           predicted_ids = model.generate(input_features, max_new_tokens=512) # Ajusta max_new_tokens según sea necesario

       # Decodificar los IDs predichos a texto
       transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True)[0]
       return transcription

   except Exception as e:
       print(f"Ocurrió un error durante la transcripción de {audio_filepath}: {e}")
       return None

# Bloque principal para ejecutar la prueba
if __name__ == "__main__":
   # Reemplaza 'test_audio.wav' con la ruta a tu archivo de audio de prueba
   test_audio_file = "test_audio.wav"

   # Crear un archivo de audio de prueba si no existe
   if not os.path.exists(test_audio_file):
       print(f"El archivo de audio de prueba '{test_audio_file}' no se encontró.")
       print("Por favor, crea un archivo de audio (ej. WAV, MP3) o usa el siguiente código para generar uno de ejemplo.")
       # Ejemplo de generación de audio con gTTS (requiere instalación: pip install gtts)
       try:
           from gtts import gTTS
           print("Generando un archivo de audio de ejemplo 'test_audio.wav'...")
           text_to_speak = "Hola mundo. Este es un ejemplo de transcripción de audio usando Qwen3 ASR."
           tts = gTTS(text=text_to_speak, lang='es')
           tts.save(test_audio_file)
           print(f"Archivo de audio '{test_audio_file}' generado.")
       except ImportError:
           print("Para generar un archivo de audio de ejemplo, instala gTTS: pip install gtts")
       except Exception as e:
           print(f"Error al generar el archivo de audio de ejemplo: {e}")

   # Realizar la transcripción si el archivo de audio existe
   if os.path.exists(test_audio_file):
       result = perform_transcription(test_audio_file)
       if result:
           print("\n--- Resultado de la Transcripción ---")
           print(result)
           print("-----------------------------------")
   else:
       print("\nNo se pudo proceder con la transcripción porque el archivo de audio de prueba no existe ni se pudo generar.")

Ejecución

Ejecuta el script de prueba:

python transcribe.py

Si la configuración es corecta, verás la transcripción del audio en la salida.

Solución de Problemas Comunes

Error de Memoria CUDA Insuficiente

Si encuentras errores relacionados con la memoria de la GPU, considera:

• Reducir el tamaño del lote (batch size) si procesas múltiples audios a la vez.
• Usar precisión mixta (float16) como se configura en el script.
• Asegurarte de que no haya otros procesos consumiendo VRAM de la GPU.

Problemas con Formatos de Audio

El modelo espera ciertos formatos y tasas de muestreo (usualmente 16kHz). Usa FFmpeg para convertir archivos si es necesario:

ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav

Uso Avanzado

Procesamiento por Lotes

Adapta el script de prueba para procesar múltiples archivos de audio en un directorio. Puedes iterar sobre los archivos, llamar a la función de transcripción para cada uno y guardar los resultados.

Este tutorial te ha guiado a través de la instalación y una prueba básica de Qwen3-ASR-1.7B. Puedes empezar a integrar esta potente herramienta en tus proyectos.