Ir al contenido principal
Español— Elegir un idioma
Menú

Optimización para producción

Lección 15 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Del prototipo al servicio fiable
  2. Gestión de errores que distingue entre recuperables y fatales
  3. Procesamiento de un lote de archivos sin supervisión
  4. Preparación previa del audio
  5. Saber qué está ocurriendo
  6. Lista de comprobación para producción
  7. Puntos clave

Curso actualizado el 3 de noviembre de 2026 para Voxtral 3, basado en la guía Migrate from Voxtral 2 de Mistral: los modelos de Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603, obsoletos desde el 31 de octubre de 2026 y retirados el 30 de abril de 2027) se sustituyen en los ejemplos por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 y voxtral-mini-tts-3-0. Cambios clave: las marcas temporales son solo por segmento (word devuelve un error 400), se admite la diarización en tiempo real, la configuración de sesión en tiempo real se bloquea tras el primer fragmento de audio y las entradas de context_bias son de texto libre (frases con espacios). Fuentes: Migrate from Voxtral 2 · Speech to Text.

Del prototipo al servicio fiable

Ya sabes cómo transcribir audio, tanto de forma asíncrona como en tiempo real. Sin embargo, poner en marcha un servicio que procese cientos de archivos diarios sin supervisión humana es un ejercicio completamente distinto, porque se enfrenta a situaciones que un prototipo nunca ve: un archivo corrupto, una cuota excedida, una caída de red a mitad de la subida o un pico de volumen que activa la limitación de tasa. Esta lección aborda estos casos uno a uno: gestión de errores, procesamiento por lotes, preparación de archivos y observabilidad.

Gestión de errores que distingue entre recuperables y fatales

La primera regla es no tratar todos los errores por igual. Una caída de red, un tiempo de espera agotado o una interrupción temporal merecen un reintento; un archivo ilegible o una clave de API inválida nunca se arreglarán solas, y reintentarlos solo hace perder tiempo y ensucia los registros. El contenedor siguiente implementa esta distinción mediante una tupla de excepciones temporales: cualquier elemento en ERREURS_TEMPORAIRES desencadena un reintento, mientras que todo lo demás falla de inmediato. En ambos casos, la función devuelve un diccionario en lugar de lanzar una excepción, lo que permite que el procesamiento por lotes continúe con los archivos restantes.

import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral

logger = logging.getLogger("voxtral")

# Excepciones para reintentar
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Transcribe un archivo con reintentos exponenciales."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
    fichier = Path(chemin_audio)

    for tentative in range(1, max_tentatives + 1):
        try:
            with open(chemin_audio, "rb") as f:
                response = client.audio.transcriptions.complete(
                    model=kwargs.get("model", "voxtral-mini-transcribe-3"),
                    file={"content": f, "file_name": fichier.name},
                    **{k: v for k, v in kwargs.items() if k != "model"}
                )

            return {
                "succes": True,
                "texte": response.text,
                "fichier": chemin_audio,
                "tentative": tentative,
            }

        except ERREURS_TEMPORAIRES as e:
            if tentative < max_tentatives:
                delai = delai_base * (2 ** (tentative - 1))
                logger.warning(
                    f"Tentative {tentative}/{max_tentatives} échouée "
                    f"pour {fichier.name} : {e}. "
                    f"Retry dans {delai:.0f}s"
                )
                time.sleep(delai)
            else:
                logger.error(
                    f"Échec définitif pour {fichier.name} "
                    f"après {max_tentatives} tentatives : {e}"
                )
                return {
                    "succes": False,
                    "erreur": str(e),
                    "fichier": chemin_audio,
                    "tentative": tentative,
                }

        except Exception as e:
            # Error no recuperable (archivo inválido, autenticación, etc.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

El retraso entre intentos se duplica con cada fallo: dos segundos, luego cuatro, luego ocho, para evitar saturar una API que ya está teniendo problemas. No obstante, este retroceso exponencial tiene un defecto cuando hay muchos clientes: si todos fallan al mismo instante, todos reintentarán al mismo instante y la oleada golpeará el servicio de golpe. Lo solucionamos con jitter, una variación aleatoria añadida al retraso, suficiente para desincronizar los intentos.

import random

delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)

Procesamiento de un lote de archivos sin supervisión

Transcribir doscientas grabaciones una tras otra es un desperdicio: la mayor parte del tiempo se pierde esperando a la red. Un grupo de trabajadores gestiona múltiples transcripciones de forma concurrente sin perder el rastro del progreso. La función siguiente examina una carpeta, conserva las extensiones de audio conocidas, envía cada archivo al contenedor de reintentos definido arriba y escribe la transcripción tan pronto como llega, en lugar de hacerlo al final: si el proceso se interrumpe a mitad de camino, lo procesado ya está en el disco. Un informe JSON resume los éxitos y fallos, lo que te permite reiniciar solo lo que falló.

import os
import json
import logging
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor, as_completed

logger = logging.getLogger("voxtral-batch")

def traiter_batch(
    dossier_audio: str,
    dossier_sortie: str,
    max_workers: int = 4,
    **kwargs_transcription
):
    """Transcribe todos los archivos de audio de una carpeta en paralelo."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Buscar todos los archivos de audio
    extensions = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
    fichiers = [
        f for f in dossier.iterdir()
        if f.suffix.lower() in extensions
    ]

    if not fichiers:
        logger.warning(f"Aucun fichier audio dans {dossier_audio}")
        return []

    logger.info(f"Traitement de {len(fichiers)} fichiers avec {max_workers} workers")

    resultats = []

    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {
            pool.submit(
                transcrire_avec_retry,
                str(f),
                **kwargs_transcription
            ): f
            for f in fichiers
        }

        for i, future in enumerate(as_completed(futures), 1):
            fichier = futures[future]
            resultat = future.result()
            resultats.append(resultat)

            status = "OK" if resultat["succes"] else "ERREUR"
            logger.info(
                f"[{i}/{len(fichiers)}] {status} — {fichier.name}"
            )

            # Guardar la transcripción
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Informe final
    succes = sum(1 for r in resultats if r["succes"])
    echecs = len(resultats) - succes
    logger.info(f"Terminé : {succes} succès, {echecs} échecs")

    # Guardar el informe
    rapport_path = sortie / "rapport_batch.json"
    with open(rapport_path, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    return resultats

# Uso
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

No cedas a la tentación de aumentar max_workers para ir más rápido. La API de Mistral impone límites de solicitudes por minuto, y cuatro trabajadores suelen mantenerte por debajo de ese umbral. Si aparecen errores 429 (Too Many Requests) en tus registros, la respuesta no es reintentar con más fuerza, sino reducir el número de trabajadores o introducir un retraso entre solicitudes.

Preparación previa del audio

El formato de los archivos que envías influye tanto en el tiempo de subida como en la calidad del texto resultante. Si la fidelidad es primordial, quédate con WAV o FLAC, formatos sin pérdida: el modelo recibe toda la información de audio. Para un uso común, MP3 a 128 kbps o superior ofrece el mejor compromiso, con calidad más que suficiente para transcripción y un tamaño de archivo razonable. Y cuando el ancho de banda es la restricción dominante, OGG Vorbis o MP3 a 64 kbps siguen siendo perfectamente aceptables para la voz, que en este aspecto es muy distinta de la música.

En lugar de aceptar cualquier formato que llegue, normalízalos antes de enviarlos. La función siguiente aplica cuatro transformaciones: conversión a mono, ya que el estéreo no aporta nada a la transcripción; remuestreo a 16 kHz, la tasa nativa de Voxtral; tasa de bits fijada en 64 kbps, suficiente para la voz; y loudnorm, que ecualiza el volumen.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Prepara un archivo de audio para una transcripción óptima."""
    if chemin_sortie is None:
        chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"

    subprocess.run([
        "ffmpeg", "-y",
        "-i", chemin_entree,
        "-ac", "1",          # Mono (el estéreo no ayuda a la transcripción)
        "-ar", "16000",       # 16 kHz (tasa nativa de Voxtral)
        "-b:a", "64k",        # 64 kbps (suficiente para la voz)
        "-af", "loudnorm",    # Normalización de volumen
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

La ganancia es doble: convertir a mono 16 kHz 64 kbps reduce significativamente el tamaño de los archivos sin degradar la transcripción, y loudnorm mejora notablemente los resultados en grabaciones con volumen irregular, típicamente una reunión donde un participante está lejos del micrófono.

Saber qué está ocurriendo

Un servicio de transcripción sin instrumentación es una caja negra: el día que los tiempos de procesamiento se dupliquen, te enterarás por un usuario enfadado. Recoge el tamaño del archivo, la duración del procesamiento, el número de intentos y el volumen de texto producido para cada llamada, y escríbelo todo como JSON en una sola línea, un formato directamente utilizable por un agregador de registros.

import time
import logging
import json
from datetime import datetime

logger = logging.getLogger("voxtral-prod")

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Transcribe con recogida de métricas."""
    debut = time.time()
    taille_fichier = Path(chemin_audio).stat().st_size

    resultat = transcrire_avec_retry(chemin_audio, **kwargs)

    duree_traitement = time.time() - debut

    metriques = {
        "timestamp": datetime.now().isoformat(),
        "fichier": chemin_audio,
        "taille_octets": taille_fichier,
        "duree_traitement_s": round(duree_traitement, 2),
        "succes": resultat["succes"],
        "tentatives": resultat["tentative"],
    }

    if resultat["succes"]:
        metriques["nb_caracteres"] = len(resultat["texte"])
        metriques["nb_mots"] = len(resultat["texte"].split())
        ratio = taille_fichier / duree_traitement / 1024
        metriques["debit_ko_par_s"] = round(ratio, 1)

    # Registro estructurado (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Lista de comprobación para producción

Antes de abrir tu servicio al primer usuario real, revisa estos siete puntos:

DominioComprobación
Gestión de erroresReintento con retroceso exponencial para errores temporales
Limitación de tasaRespetar los límites de la API, implementar throttling si es necesario
MonitorizaciónRegistros estructurados, métricas de rendimiento, alertas ante errores
SeguridadClave de API en variable de entorno, nunca hardcodeada en el código
AlmacenamientoGuardar transcripciones de forma duradera, no solo en memoria
Formato de audioNormalizar archivos previamente (mono, 16 kHz)
PruebasArchivos variados: idiomas, duraciones, calidad de audio, número de hablantes

La última línea es la que más se suele descuidar y la más costosa. Tres grabaciones limpias en francés no te enseñarán nada sobre el comportamiento real de tu servicio: construye una muestra deliberadamente difícil y descubrirás los ajustes que debes hacer mientras aún hay tiempo.

Puntos clave

  • Implementa reintentos con retroceso exponencial y jitter para errores temporales
  • Usa un grupo de trabajadores para el procesamiento por lotes (4 trabajadores es un buen punto de partida)
  • Normaliza tus archivos a mono 16 kHz con FFmpeg para obtener resultados óptimos
  • Recoge métricas estructuradas para la monitorización en producción
  • Respeta los límites de tasa de la API de Mistral
  • Guarda sistemáticamente las transcripciones y los informes de lotes