Optimisation pour la production
Na ovoj stranici
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 parvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3etvoxtral-mini-tts-3-0. Changements clés : les horodatages sont uniquement par segment (wordrenvoie 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éescontext_biassont 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 téléchargement, ou un pic de volume qui déclenche une limitation de débit. Cette leçon aborde 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 dépassement de délai 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 journaux. L’enveloppe 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 recul 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 parcourt un dossier, conserve les extensions audio connues, soumet chaque fichier à l’enveloppe de retry définie 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 journaux, 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 de téléchargement 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é largement 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 tous les formats qui arrivent, 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 microphone.
Savoir ce qu’il 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 utilisateur réel, passe en revue ces sept points :
| Domaine | Vérification |
|---|---|
| Gestion des erreurs | Réessai avec recul exponentiel pour les erreurs temporaires |
| Limitation de débit | Respecter les limites de l’API, implémenter un throttling si nécessaire |
| Surveillance | Logs 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 |
| Stockage | Sauvegarder les transcriptions durablement, pas seulement en mémoire |
| Format audio | Normaliser les fichiers en amont (mono, 16 kHz) |
| Tests | Fichiers 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.
Ključne točke
- Implémente un réessai avec recul 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 la surveillance en production
- Respecte les limites de débit de l’API Mistral
- Sauvegarde systématiquement les transcriptions et les rapports de lots