WhisperX con diarización

Ejecuta WhisperX para transcripción rápida de voz con marcas de tiempo a nivel de palabra y diarización de hablantes en GPUs de Clore.ai.

WhisperX amplía Whisper de OpenAI con tres mejoras críticas: marcas de tiempo a nivel de palabra mediante alineación forzada de fonemas, diarización de hablantes usando pyannote.audio, y hasta 70× de velocidad en tiempo real mediante inferencia por lotes con faster-whisper. Es la herramienta de referencia para flujos de transcripción en producción que necesitan tiempos precisos e identificación de hablantes.

GitHub: m-bain/whisperX PyPI: whisperx Licencia: BSD-4-Clause Artículo: arxiv.org/abs/2303.00747

Características clave

• Marcas de tiempo a nivel de palabra — precisión de ±50 ms mediante alineación forzada con wav2vec2 (frente a ±500 ms en Whisper estándar)

• Diarización de hablantes — identifica quién dijo qué mediante pyannote.audio 3.1

• Inferencia por lotes — hasta 70× de velocidad en tiempo real en RTX 4090

• Pre-filtrado VAD — Silero VAD elimina el silencio antes de la transcripción

• Todos los modelos Whisper — desde tiny hasta large-v3-turbo

• Múltiples formatos de salida — JSON, SRT, VTT, TXT, TSV

• Detección automática de idioma — o fuerza un idioma específico para un procesamiento más rápido

Requisitos

Componente	Mínimo	Recomendado
GPU	RTX 3060 12 GB	RTX 4090 24 GB
VRAM	4 GB (modelo pequeño)	10 GB+ (large-v3-turbo)
RAM	8 GB	16 GB+
Disco	5 GB	20 GB (caché del modelo)
Python	3.9+	3.11
CUDA	12.8+	12.8+

Se requiere token de HuggingFace para la diarización de hablantes — acepta la licencia en pyannote/speaker-diarization-3.1.

Recomendación de Clore.ai: RTX 3090 ($0.07–0.21/h) para el modelo large-v3-turbo con tamaño de lote 16. RTX 4090 ($0.14–0.42/h) para el máximo rendimiento con tamaño de lote 32.

Instalación

# Instalar WhisperX
pip install whisperx

# Verificar GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"

Si encuentras conflictos de versión de CUDA:

pip install torch==2.5.1+cu124 torchaudio==2.5.1+cu124 --index-url https://download.pytorch.org/whl/cu128
pip install whisperx

Inicio rápido

import whisperx
import json

device = "cuda"
compute_type = "float16"  # "int8" para menor VRAM
batch_size = 16            # reduce a 4-8 si la VRAM es ajustada

# 1. Cargar modelo
model = whisperx.load_model("large-v3-turbo", device, compute_type=compute_type)

# 2. Cargar y transcribir audio
audio = whisperx.load_audio("interview.mp3")
result = model.transcribe(audio, batch_size=batch_size)
print(f"Idioma: {result['language']}")

# 3. Alinear para marcas de tiempo a nivel de palabra
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(
    result["segments"], model_a, metadata, audio, device,
    return_char_alignments=False,
)

# 4. Mostrar resultados
for seg in result["segments"]:
    print(f"[{seg['start']:.2f}s → {seg['end']:.2f}s] {seg['text']}")
    for w in seg.get("words", []):
        print(f"  '{w['word']}' @ {w.get('start', 0):.2f}s")

# 5. Guardar
with open("transcript.json", "w") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)

Ejemplos de uso

Transcripción con diarización de hablantes

import whisperx
import gc
import torch

device = "cuda"
HF_TOKEN = "hf_your_token_here"  # de huggingface.co/settings/tokens

# Paso 1: Transcribir
model = whisperx.load_model("large-v3-turbo", device, compute_type="float16")
audio = whisperx.load_audio("meeting.mp3")
result = model.transcribe(audio, batch_size=16)

# Liberar memoria de la GPU antes de cargar el modelo de alineación
del model; gc.collect(); torch.cuda.empty_cache()

# Paso 2: Alinear
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(result["segments"], model_a, metadata, audio, device)
del model_a; gc.collect(); torch.cuda.empty_cache()

# Paso 3: Diarizar
diarize_model = whisperx.DiarizationPipeline(
    use_auth_token=HF_TOKEN, device=device
)
diarize_segments = diarize_model(audio, min_speakers=2, max_speakers=6)

# Paso 4: Asignar hablantes a las palabras
result = whisperx.assign_word_speakers(diarize_segments, result)

for seg in result["segments"]:
    speaker = seg.get("speaker", "UNKNOWN")
    print(f"[{speaker}] [{seg['start']:.1f}s → {seg['end']:.1f}s] {seg['text']}")

Uso desde la línea de comandos

# Transcripción básica
whisperx audio.mp3 --model large-v3-turbo --device cuda

# Forzar idioma (más rápido, omite la detección)
whisperx audio.mp3 --model large-v3-turbo --language en --device cuda

# Con diarización de hablantes
whisperx audio.mp3 --model large-v3-turbo --diarize --hf_token hf_your_token

# Salida de subtítulos SRT
whisperx audio.mp3 --model large-v3-turbo --output_format srt --output_dir ./subs/

# Modo de baja VRAM
whisperx audio.mp3 --model medium --compute_type int8 --batch_size 4 --device cuda

# Procesar por lotes un directorio
for f in /data/audio/*.mp3; do
  whisperx "$f" --model large-v3-turbo --output_dir /data/transcripts/
done

Script de generación de SRT

import whisperx

def transcribe_to_srt(audio_path, output_path, model_name="large-v3-turbo"):
    device = "cuda"
    model = whisperx.load_model(model_name, device, compute_type="float16")
    audio = whisperx.load_audio(audio_path)
    result = model.transcribe(audio, batch_size=16)

    model_a, metadata = whisperx.load_align_model(
        language_code=result["language"], device=device
    )
    result = whisperx.align(result["segments"], model_a, metadata, audio, device)

    with open(output_path, "w") as f:
        for i, seg in enumerate(result["segments"], 1):
            start = format_ts(seg["start"])
            end = format_ts(seg["end"])
            f.write(f"{i}\n{start} --> {end}\n{seg['text'].strip()}\n\n")

    print(f"SRT guardado en {output_path}")

def format_ts(seconds):
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    s = int(seconds % 60)
    ms = int((seconds % 1) * 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

transcribe_to_srt("podcast.mp3", "podcast.srt")

Puntos de referencia de rendimiento

Método	Modelo	1 h de audio	GPU	Velocidad aprox.
Whisper estándar	large-v3	~60 min	RTX 3090	1×
faster-whisper	large-v3	~5 min	RTX 3090	~12×
WhisperX	large-v3-turbo	~1 min	RTX 3090	~60×
WhisperX	large-v3-turbo	~50 s	RTX 4090	~70×

Tamaño de lote	Velocidad (RTX 4090)	VRAM
4	~30× en tiempo real	6 GB
8	~45× en tiempo real	8 GB
16	~60× en tiempo real	10 GB
32	~70× en tiempo real	14 GB

Consejos para usuarios de Clore.ai

• Liberar VRAM entre pasos — elimina los modelos y llama a torch.cuda.empty_cache() entre la transcripción, la alineación y la diarización

• token de HuggingFace — debes aceptar la licencia del modelo de pyannote antes de que la diarización funcione; establece HF_TOKEN como variable de entorno

• Ajuste del tamaño de lote — empieza con batch_size=16, reduce a 4–8 en tarjetas de 12 GB, aumenta a 32 en tarjetas de 24 GB

• int8 compute — usa compute_type="int8" para reducir a la mitad el uso de VRAM con una pérdida mínima de calidad

• Imagen Docker — pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime

• Caché persistente del modelo — monta /root/.cache/huggingface para evitar volver a descargar los modelos en cada reinicio del contenedor

Solución de problemas

Problema	Solución
CUDA sin memoria	Reduce batch_size, usa compute_type="int8", o usa un modelo más pequeño (medium, small)
La diarización devuelve UNKNOWN	Asegúrate de que el token de HuggingFace sea válido y de haber aceptado la licencia de pyannote
No module named 'whisperx'	pip install whisperx — asegúrate de que no haya un error tipográfico (es whisperx, no whisper-x)
Malas marcas de tiempo de palabras	Comprueba que whisperx.align() se llame después de transcribe() — la salida sin procesar de Whisper no tiene precisión a nivel de palabra
Detección de idioma incorrecta	Fuerza el idioma con --language en o language="en" en la API de Python
Procesamiento lento	Aumenta batch_size, usa large-v3-turbo en lugar de large-v3, asegúrate de que la GPU no esté compartida