Optimalisatie voor productie
Op deze pagina
Cursus bijgewerkt op 3 november 2026 voor Voxtral 3, gebaseerd op de gids Migrate from Voxtral 2 van Mistral: Voxtral 2-modellen (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), verouderd op 31 oktober 2026 en buiten gebruik gesteld op 30 april 2027, worden in de voorbeelden vervangen doorvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3envoxtral-mini-tts-3-0. Belangrijkste wijzigingen: tijdstempels zijn alleen per segment (wordgeeft een 400-fout), real-time sprekerherkenning wordt ondersteund, real-time sessie-instellingen zijn vergrendeld na het eerste audioblok, encontext_bias-invoer is vrij (zinnen met spaties). Bronnen: Migrate from Voxtral 2 · Speech to Text.
Van prototype naar betrouwbare service
U weet hoe u audio moet transcriberen, zowel asynchroon als in real time. Het beheren van een service die dagelijks honderden bestanden verwerkt zonder menselijk toezicht, is echter een heel andere oefening. Een dergelijke service krijgt namelijk te maken met situaties die een prototype nooit ziet: een beschadigd bestand, een overschreden quotum, een netwerkonderbreking tijdens het uploaden, of een volumepiek die rate limiting activeert. Deze les behandelt deze gevallen één voor één: foutafhandeling, batchverwerking, bestandsvoorbereiding en observeerbaarheid.
Foutafhandeling die herstelbare van fatale fouten onderscheidt
De eerste regel is om niet alle fouten op dezelfde manier te behandelen. Een netwerkonderbreking, een time-out of een tijdelijke storing verdient een nieuwe poging; een onleesbaar bestand of een ongeldige API-sleutel lost zichzelf nooit op, en opnieuw proberen verspilt alleen maar tijd en vervuilt uw logs. De onderstaande wrapper maakt dit onderscheid met een tuple van tijdelijke uitzonderingen: alles in ERREURS_TEMPORAIRES activeert een retry, terwijl al het andere direct faalt. In beide gevallen retourneert de functie een dictionary in plaats van een uitzondering te genereren, zodat de batchverwerking met de resterende bestanden kan doorgaan.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Exceptions to retry
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Transcribes a file with exponential retry."""
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:
# Non-recoverable error (invalid file, auth, etc.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
De vertraging tussen pogingen verdubbelt bij elke mislukking—twee seconden, dan vier, dan acht—om te voorkomen dat u een API bestookt die het al moeilijk heeft. Deze exponentiële backoff heeft echter een zwak punt wanneer u veel clients heeft: als ze allemaal op hetzelfde moment falen, zullen ze ook allemaal op hetzelfde moment opnieuw proberen, en zal de golf de service tegelijkertijd treffen. We lossen dit op met jitter, een willekeurige variatie die aan de vertraging wordt toegevoegd, wat volstaat om de pogingen te desynchroniseren.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Een batch bestanden verwerken zonder toezicht
Tweehonderd opnames één voor één transcriberen is inefficiënt: het grootste deel van de tijd wordt besteed aan wachten op het netwerk. Een pool van workers verwerkt meerdere transcripties gelijktijdig zonder het overzicht over de voortgang te verliezen. De onderstaande functie scant een map, behoudt bekende audio-extensies, dient elk bestand in bij de eerder gedefinieerde retry-wrapper en schrijft de transcriptie direct weg zodra deze binnenkomt, in plaats van aan het einde: als het proces halverwege crasht, is het reeds verwerkte werk al op schijf opgeslagen. Een JSON-rapport vat successen en mislukkingen samen, zodat u alleen datgene opnieuw kunt starten dat is mislukt.
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
):
"""Transcribes all audio files in a folder in parallel."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Find all audio files
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}"
)
# Save the transcription
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Final report
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Save the report
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
# Usage
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Geef niet toe aan de verleiding om max_workers te verhogen om sneller te gaan. De Mistral API stelt limieten aan het aantal verzoeken per minuut, en vier workers houden u doorgaans onder die drempel. Als er 429-fouten (Too Many Requests) in uw logs verschijnen, is het antwoord niet om harder te retryen, maar om het aantal workers te verminderen of een vertraging tussen de verzoeken in te bouwen.
Audio vooraf voorbereiden
Het formaat van de bestanden die u verzendt, beïnvloedt zowel de uploadtijd als de kwaliteit van de resulterende tekst. Als trouwheid voorop staat, kies dan voor WAV of FLAC, verliesvrije formaten: het model ontvangt dan de volledige audio-informatie. Voor algemeen gebruik biedt MP3 op 128 kbps of hoger het beste compromis, met een kwaliteit die meer dan voldoende is voor transcriptie en een redelijke bestandsgrootte. En wanneer bandbreedte de dominante beperking is, blijven OGG Vorbis of MP3 op 64 kbps perfect acceptabel voor spraak, wat in dit opzicht zeer verschilt van muziek.
Accepteer niet zomaar elk formaat dat binnenkomt, maar normaliseer ze voordat u ze verzendt. De onderstaande functie past vier transformaties toe: conversie naar mono, aangezien stereo niets toevoegt aan transcriptie; resampling naar 16 kHz, de native snelheid van Voxtral; bitrate ingesteld op 64 kbps, voldoende voor spraak; en loudnorm, dat het volume egaliseert.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Prepares an audio file for optimal transcription."""
if chemin_sortie is None:
chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"
subprocess.run([
"ffmpeg", "-y",
"-i", chemin_entree,
"-ac", "1", # Mono (stereo does not help transcription)
"-ar", "16000", # 16 kHz (Voxtral native rate)
"-b:a", "64k", # 64 kbps (sufficient for speech)
"-af", "loudnorm", # Volume normalization
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Het voordeel is tweeledig: converteren naar mono 16 kHz 64 kbps verkleint de bestandsgroottes aanzienlijk zonder de transcriptie te verslechteren, en loudnorm verbetert de resultaten merkbaar bij opnames met een onregelmatig volume, typisch een vergadering waarbij één deelnemer ver van de microfoon zit.
Weten wat er gebeurt
Een transcriptieservice zonder instrumentatie is een black box: op de dag dat de verwerkingstijden verdubbelen, hoort u het pas van een ontevreden gebruiker. Verzamel voor elke call de bestandsgrootte, verwerkingsduur, aantal pogingen en de hoeveelheid gegenereerde tekst, en schrijf dit alles als JSON op één regel, een formaat dat direct bruikbaar is voor een log-aggregator.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Transcribes with metrics collection."""
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)
# Structured log (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Productiechecklist
Voordat u uw service opent voor de eerste echte gebruiker, controleert u deze zeven punten:
| Domein | Controle |
|---|---|
| Foutafhandeling | Retry met exponentiële backoff voor tijdelijke fouten |
| Rate limiting | Respecteer API-limieten, implementeer throttling indien nodig |
| Monitoring | Gestructureerde logs, prestatiemetrieken, alerts bij fouten |
| Beveiliging | API-sleutel in omgevingsvariabele, nooit hardcoded in code |
| Opslag | Sla transcripties duurzaam op, niet alleen in het geheugen |
| Audioformaat | Normaliseer bestanden vooraf (mono, 16 kHz) |
| Testen | Gevarieerde bestanden: talen, duur, audiokwaliteit, aantal sprekers |
De laatste regel is degene die het vaakst wordt verwaarloosd en het duurst uitpakt. Drie schone opnames in het Frans leren u niets over het echte gedrag van uw service: bouw een bewust moeilijke steekproef, en u ontdekt de instellingen die moeten worden aangepast terwijl er nog tijd is.
Belangrijkste punten
- Implementeer retry met exponentiële backoff en jitter voor tijdelijke fouten
- Gebruik een worker-pool voor batchverwerking (4 workers is een goed startpunt)
- Normaliseer uw bestanden naar mono 16 kHz met FFmpeg voor optimale resultaten
- Verzamel gestructureerde metrieken voor productiemonitoring
- Respecteer de rate limiting-limieten van de Mistral API
- Sla transcripties en batchrapporten systematisch op