Optimering til produktion
På denne side
Kurset opdateret 3. november 2026 til Voxtral 3, baseret på Mistrals guide Migrate from Voxtral 2: Voxtral 2-modellerne (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), der blev udfaset 31. oktober 2026 og helt fjernet 30. april 2027, erstattes i eksemplerne afvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3ogvoxtral-mini-tts-3-0. Vigtige ændringer: Tidsstempler er kun tilgængelige på segmentniveau (wordgiver en 400-fejl), realtids-diarrisering understøttes, indstillinger for realtidssessioner låses efter det første lydstykke, ogcontext_bias-input er frit format (sætninger med mellemrum). Kilder: Migrate from Voxtral 2 · Speech to Text.
Fra prototype til pålidelig tjeneste
Du ved, hvordan man transskriberer lyd, både asynkront og i realtid. Men at drive en tjeneste, der behandler hundredvis af filer dagligt uden menneskelig overvågning, er en helt anden sag. Her støder du på problemer, som en prototype aldrig ser: en beskadiget fil, en overskredet kvote, et netværksafbrydelse midt i en upload, eller et volumenhop, der udløser hastighedsbegrænsning. Denne lektion gennemgår disse tilfælde én efter én – fejlhåndtering, batch-behandling, filforberedelse og observerbarhed.
Fejlhåndtering, der skelner mellem genoprettelige og fatale fejl
Den første regel er ikke at behandle alle fejl ens. Et netværksafbrydelse, en timeout eller en midlertidig nedetid fortjener et genforsøg; en ulæselig fil eller en ugyldig API-nøgle løser sig aldrig af sig selv, og at genforsøge dem spilder blot tid og forurener dine logs. Wrapperen nedenfor implementerer denne sondring med en tuple af midlertidige undtagelser: alt i ERREURS_TEMPORAIRES udløser et genforsøg, mens alt andet fejler øjeblikkeligt. I begge tilfælde returnerer funktionen en ordbog i stedet for at kaste en undtagelse, så batch-behandlingen kan fortsætte med de resterende filer.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Undtagelser der skal genforsøges
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Transskriberer en fil med eksponentielt genforsøg."""
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:
# Ikke-genoprettelig fejl (ugyldig fil, auth osv.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Forsinkelsen mellem forsøg fordobles ved hver fejl – to sekunder, derefter fire, derefter otte – for at undgå at overbelaste en API, der allerede har det svært. Denne eksponentielle backoff har dog en svaghed, når du har mange klienter: Hvis de alle fejler på samme tidspunkt, vil de alle genforsøge på samme tidspunkt, og bølgen rammer tjenesten samlet. Vi løser dette med jitter, en tilfældig variation lagt til forsinkelsen, hvilket er nok til at desynkronisere forsøgene.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Behandling af en batch filer uden overvågning
At transskribere to hundrede optagelser én efter én er spild af tid: Det meste af tiden går med at vente på netværket. En pulje af arbejdere håndterer flere transskriptioner samtidigt uden at miste overblikket over fremskridt. Funktionen nedenfor scanner en mappe, beholder kendte lydudvidelser, sender hver fil til retry-wrapperen defineret ovenfor og gemmer transskriptionen, så snart den ankommer, i stedet for til sidst: Hvis processen crascher halvvejs, er det allerede behandlede allerede på disken. En JSON-rapport opsummerer succeser og fejl, så du kun kan genstarte det, der fejlede.
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
):
"""Transskriberer alle lydfiler i en mappe parallelt."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Find alle lydfiler
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}"
)
# Gem transskriptionen
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Endelig rapport
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Gem rapporten
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
# Brug
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Lad ikke fristelsen vinde over dig til at øge max_workers for at gøre det hurtigere. Mistral API’en har begrænsninger på forespørgsler per minut, og fire arbejdere holder dig normalt under denne tærskel. Hvis 429-fejl (Too Many Requests) dukker op i dine logs, er svaret ikke at genforsøge hårdere, men at reducere antallet af arbejdere eller indføre en forsinkelse mellem forespørgslerne.
Forberedelse af lyd upstream
Formatet på de filer, du sender, påvirker både upload-tiden og kvaliteten af den resulterende tekst. Hvis troskab er altafgørende, så hold dig til WAV eller FLAC, som er tabsfri formater: Modellen modtager alle lydoplysninger. Til almindelig brug tilbyder MP3 ved 128 kbps eller højere det bedste kompromis med kvalitet, der er mere end tilstrækkelig til transskription, og en rimelig filstørrelse. Og når båndbredde er den dominerende begrænsning, er OGG Vorbis eller MP3 ved 64 kbps stadig fuldt acceptable til tale, hvilket er meget forskelligt fra musik i denne henseende.
I stedet for at acceptere hvilke som helst formater, der ankommer, bør du normalisere dem før afsendelse. Funktionen nedenfor anvender fire transformationer: konvertering til mono, da stereo ikke tilføjer noget til transskription; resampling til 16 kHz, som er Voxtrals native hastighed; bitrate sat til 64 kbps, hvilket er tilstrækkeligt til tale; og loudnorm, som udligner volumen.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Forbereder en lydfil til optimal transskription."""
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 hjælper ikke transskription)
"-ar", "16000", # 16 kHz (Voxtral native hastighed)
"-b:a", "64k", # 64 kbps (tilstrækkeligt til tale)
"-af", "loudnorm", # Volumen normalisering
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Gevinsten er dobbelt: Konvertering til mono 16 kHz 64 kbps reducerer filstørrelserne betydeligt uden at forringe transskriptionen, og loudnorm forbedrer resultaterne markant på optagelser med uregelmæssigt volumen, typisk et møde hvor en deltager sidder langt fra mikrofonen.
At vide, hvad der sker
En transskriptionstjeneste uden instrumentering er en sort boks: Den dag behandlingstiderne fordobles, vil du få det at vide fra en utilfreds bruger. Indsaml filstørrelse, behandlingsvarighed, antal forsøg og mængden af produceret tekst for hvert kald, og skriv derefter alt som JSON på en enkelt linje, et format der direkte kan bruges af en 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:
"""Transskriberer med indsamling af metrikker."""
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)
# Struktureret log (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Produktions-checkliste
Før du åbner din tjeneste for den første rigtige bruger, så gennemgå disse syv punkter:
| Domæne | Tjek |
|---|---|
| Fejlhåndtering | Genforsøg med eksponentiel backoff for midlertidige fejl |
| Hastighedsbegrænsning | Overhold API-grænser, implementer throttling om nødvendigt |
| Overvågning | Strukturerede logs, ydelsesmetrikker, alarmer ved fejl |
| Sikkerhed | API-nøgle i miljøvariabel, aldrig hardcodet i koden |
| Lagring | Gem transskriptioner holdbart, ikke kun i hukommelsen |
| Lydformat | Normaliser filer upstream (mono, 16 kHz) |
| Testning | Varierede filer: sprog, varigheder, lydkvalitet, antal talere |
Det sidste punkt er det, der oftest forsømmes, og det dyreste. Tre rene optagelser på fransk vil ikke lære dig noget om den virkelige adfærd hos din tjeneste: Byg en bevidst vanskelig prøve, så vil du opdage de indstillinger, der skal justeres, mens der stadig er tid.
Vigtige pointer
- Implementer genforsøg med eksponentiel backoff og jitter for midlertidige fejl
- Brug en worker-pulje til batch-behandling (4 arbejdere er et godt udgangspunkt)
- Normaliser dine filer til mono 16 kHz med FFmpeg for optimale resultater
- Indsaml strukturerede metrikker til produktions-overvågning
- Overhold Mistral API’s begrænsninger for forespørgsler
- Gem systematisk transskriptioner og batch-rapporter