Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Optimisation pour la production

15. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Du prototype au service fiable
  2. Une gestion des erreurs qui distingue le récupérable du fatal
  3. Traiter un lot de fichiers sans supervision
  4. Préparer l’audio en amont
  5. Savoir ce qui se passe
  6. Checklist de production
  7. Főbb megállapítások

Cours mis à jour le 3 novembre 2026 pour Voxtral 3, basé sur le guide Migrate from Voxtral 2 de Mistral : les modèles Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), dépréciés le 31 octobre 2026 et retirés le 30 avril 2027, sont remplacés dans les exemples par voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 et voxtral-mini-tts-3-0. Changements clés : les horodatages sont uniquement par segment (word renvoie une erreur 400), la diarisation en temps réel est prise en charge, les paramètres de session en temps réel sont verrouillés après le premier fragment audio, et les entrées context_bias sont en texte libre (phrases avec espaces). Sources : Migrate from Voxtral 2 · Speech to Text.

Du prototype au service fiable

Tu sais maintenant transcrire de l’audio, aussi bien de manière asynchrone qu’en temps réel. Cependant, faire tourner un service qui traite des centaines de fichiers par jour sans supervision humaine est un exercice totalement différent, car il rencontre ce qu’un prototype ne voit jamais : un fichier corrompu, un quota dépassé, une coupure réseau en plein upload, ou un pic de volume qui déclenche une limitation de débit. Cette leçon traite ces cas un par un : gestion des erreurs, traitement par lots, préparation des fichiers et observabilité.

Une gestion des erreurs qui distingue le récupérable du fatal

La première règle est de ne pas traiter toutes les erreurs de la même manière. Une coupure réseau, un timeout ou une panne temporaire mérite une nouvelle tentative ; un fichier illisible ou une clé API invalide ne se réparera jamais toute seule, et les retenter ne fait que perdre du temps et polluer tes logs. Le wrapper ci-dessous implémente cette distinction avec un tuple d’exceptions temporaires : tout ce qui se trouve dans ERREURS_TEMPORAIRES déclenche une nouvelle tentative, tandis que tout le reste échoue immédiatement. Dans les deux cas, la fonction renvoie un dictionnaire au lieu de lever une exception, permettant au traitement par lots de continuer avec les fichiers restants.

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

logger = logging.getLogger("voxtral")

# Exceptions à retenter
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Transcrit un fichier avec une nouvelle tentative exponentielle."""
    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"Réessai 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:
            # Erreur non récupérable (fichier invalide, auth, etc.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Le délai entre les tentatives double à chaque échec — deux secondes, puis quatre, puis huit — pour éviter de marteler une API qui est déjà en difficulté. Cependant, ce backoff exponentiel présente un défaut lorsque tu as de nombreux clients : s’ils échouent tous au même instant, ils retenteront tous au même instant, et la vague frappera le service d’un seul coup. Nous corrigeons cela avec le jitter, une variation aléatoire ajoutée au délai, ce qui suffit à désynchroniser les tentatives.

import random

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

Traiter un lot de fichiers sans supervision

Transcrire deux cents enregistrements les uns après les autres est inefficace : la plupart du temps est passée à attendre le réseau. Un pool de workers gère plusieurs transcriptions simultanément sans perdre le fil de la progression. La fonction ci-dessous scanne un dossier, conserve les extensions audio connues, soumet chaque fichier au wrapper de retry défini plus haut, et écrit la transcription dès qu’elle arrive plutôt qu’à la fin : si le processus plante en cours de route, ce qui a été traité est déjà sur le disque. Un rapport JSON résume les succès et les échecs, te permettant de ne relancer que ce qui a échoué.

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
):
    """Transcrit tous les fichiers audio d'un dossier en parallèle."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Trouver tous les fichiers 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}"
            )

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

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

    # Sauvegarder le rapport
    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

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

Ne cède pas à la tentation d’augmenter max_workers pour aller plus vite. L’API Mistral impose des limites de requêtes par minute, et quatre workers te maintiennent généralement en dessous de ce seuil. Si des erreurs 429 (Too Many Requests) apparaissent dans tes logs, la réponse n’est pas de retenter plus fort, mais de réduire le nombre de workers ou d’introduire un délai entre les requêtes.

Préparer l’audio en amont

Le format des fichiers que tu envoies influence à la fois le temps d’upload et la qualité du texte résultant. Si la fidélité est primordiale, reste sur le WAV ou le FLAC, des formats sans perte : le modèle reçoit toute l’information audio. Pour un usage courant, le MP3 à 128 kbps ou plus offre le meilleur compromis, avec une qualité plus que suffisante pour la transcription et une taille de fichier raisonnable. Et lorsque la bande passante est la contrainte dominante, l’OGG Vorbis ou le MP3 à 64 kbps restent parfaitement acceptables pour la parole, ce qui est très différent de la musique à cet égard.

Plutôt que d’accepter n’importe quel format arrivant, normalise-les avant l’envoi. La fonction ci-dessous applique quatre transformations : conversion en mono, car la stéréo n’ajoute rien à la transcription ; rééchantillonnage à 16 kHz, la fréquence native de Voxtral ; débit binaire fixé à 64 kbps, suffisant pour la voix ; et loudnorm, qui égalise le volume.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Prépare un fichier audio pour une transcription optimale."""
    if chemin_sortie is None:
        chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"

    subprocess.run([
        "ffmpeg", "-y",
        "-i", chemin_entree,
        "-ac", "1",          # Mono (la stéréo n'aide pas la transcription)
        "-ar", "16000",       # 16 kHz (fréquence native Voxtral)
        "-b:a", "64k",        # 64 kbps (suffisant pour la parole)
        "-af", "loudnorm",    # Normalisation du volume
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Le gain est double : la conversion en mono 16 kHz 64 kbps réduit considérablement la taille des fichiers sans dégrader la transcription, et loudnorm améliore nettement les résultats sur les enregistrements au volume irrégulier, typiquement une réunion où un participant est loin du micro.

Savoir ce qui se passe

Un service de transcription sans instrumentation est une boîte noire : le jour où les temps de traitement doubleront, tu l’apprendras par un utilisateur mécontent. Collecte la taille du fichier, la durée de traitement, le nombre de tentatives et le volume de texte produit pour chaque appel, puis écris le tout en JSON sur une seule ligne, un format directement utilisable par un agrégateur de logs.

import time
import logging
import json
from datetime import datetime

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

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Transcrit avec collecte de métriques."""
    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)

    # Log structuré (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Checklist de production

Avant d’ouvrir ton service au premier vrai utilisateur, passe en revue ces sept points :

DomaineVérification
Gestion des erreursRetry avec backoff exponentiel pour les erreurs temporaires
Limitation de débitRespecter les limites de l’API, implémenter un throttling si nécessaire
MonitoringLogs structurés, métriques de performance, alertes sur les erreurs
SécuritéClé API dans une variable d’environnement, jamais en dur dans le code
StockageSauvegarder les transcriptions durablement, pas seulement en mémoire
Format audioNormaliser les fichiers en amont (mono, 16 kHz)
TestsFichiers variés : langues, durées, qualité audio, nombre de locuteurs

La dernière ligne est celle le plus souvent négligée et la plus coûteuse. Trois enregistrements propres en français ne t’apprendront rien sur le comportement réel de ton service : construis un échantillon délibérément difficile, et tu découvriras les réglages à ajuster tant qu’il est encore temps.

Főbb megállapítások

  • Implémente un retry avec backoff exponentiel et jitter pour les erreurs temporaires
  • Utilise un pool de workers pour le traitement par lots (4 workers est un bon point de départ)
  • Normalise tes fichiers en mono 16 kHz avec FFmpeg pour des résultats optimaux
  • Collecte des métriques structurées pour le monitoring en production
  • Respecte les limites de débit de l’API Mistral
  • Sauvegarde systématiquement les transcriptions et les rapports de lots