Optimierung für die Produktion
Auf dieser Seite
Kurs aktualisiert am 3. November 2026 für Voxtral 3, basierend auf Mistrals Migrate from Voxtral 2-Guide: Voxtral 2-Modelle (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), am 31. Oktober 2026 veraltet und am 30. April 2027 eingestellt, werden in den Beispielen durchvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3undvoxtral-mini-tts-3-0ersetzt. Wesentliche Änderungen: Zeitstempel sind segmentbasiert (wordgibt einen 400-Fehler zurück), Echtzeit-Diarisierung wird unterstützt, Echtzeit-Sitzungseinstellungen werden nach dem ersten Audio-Chunk gesperrt, undcontext_bias-Eingaben sind frei formatiert (Phrasen mit Leerzeichen). Quellen: Migrate from Voxtral 2 · Speech to Text.
Vom Prototypen zum zuverlässigen Service
Sie wissen, wie man Audio transkribiert, sowohl asynchron als auch in Echtzeit. Der Betrieb eines Services, der täglich Hunderte von Dateien verarbeitet, ohne menschliche Aufsicht, ist eine völlig andere Übung, da er auf Probleme stößt, die ein Prototyp nie sieht: eine beschädigte Datei, ein überschrittenes Kontingent, ein Netzwerkausfall mitten im Upload oder ein Volumenspitze, die die Rate-Limitierung auslöst. Diese Lektion behandelt diese Fälle einzeln – Fehlerbehandlung, Batch-Verarbeitung, Dateivorbereitung und Observability.
Fehlerbehandlung, die zwischen wiederherstellbaren und fatalen Fehlern unterscheidet
Die erste Regel ist, nicht alle Fehler gleich zu behandeln. Ein Netzwerkausfall, ein Timeout oder eine vorübergehende Ausfallzeit verdienen einen Neustart; eine unlesbare Datei oder ein ungültiger API-Schlüssel werden sich nie von selbst beheben, und ein erneuter Versuch verschwendet nur Zeit und verschmutzt Ihre Protokolle. Die untenstehende Implementierung unterscheidet dies mit einem Tupel vorübergehender Ausnahmen: Alles in ERREURS_TEMPORAIRES löst einen Neustart aus, während alles andere sofort fehlschlägt. In beiden Fällen gibt die Funktion ein Wörterbuch zurück, anstatt eine Ausnahme zu werfen, sodass die Batch-Verarbeitung mit den verbleibenden Dateien fortgesetzt werden kann.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Ausnahmen zum Neustart
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Transkribiert eine Datei mit exponentiellem Neustart."""
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:
# Nicht wiederherstellbarer Fehler (ungültige Datei, Authentifizierung usw.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Die Verzögerung zwischen den Versuchen verdoppelt sich bei jedem Misserfolg – zwei Sekunden, dann vier, dann acht –, um zu vermeiden, eine API zu überlasten, die ohnehin unter Druck steht. Allerdings hat dieses exponentielle Backoff einen Nachteil, wenn Sie viele Clients haben: Wenn sie alle gleichzeitig fehlschlagen, werden sie alle gleichzeitig neu starten, und die Welle trifft den Service auf einmal. Wir beheben dies mit Jitter, einer zufälligen Variation, die zur Verzögerung hinzugefügt wird, was ausreicht, um die Versuche zu desynchronisieren.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Verarbeitung einer Batch-Datei ohne Aufsicht
Die nacheinander Transkribierung von zweihundert Aufnahmen ist verschwenderisch: die meiste Zeit wird mit dem Warten auf das Netzwerk verbracht. Ein Pool von Arbeitern behandelt mehrere Transkriptionen gleichzeitig, ohne den Fortschritt zu verlieren. Die Funktion unten durchsucht einen Ordner, behält bekannte Audio-Endungen bei, reicht jede Datei an den oben definierten Neustart-Wrapper ein und schreibt die Transkription sofort auf, sobald sie eingeht, nicht erst am Ende: Wenn der Prozess mitten durch abbricht, liegt das, was bereits verarbeitet wurde, bereits auf der Festplatte. Ein JSON-Bericht fasst Erfolge und Misserfolge zusammen und ermöglicht es Ihnen, nur das neu zu starten, was fehlgeschlagen ist.
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
):
"""Transkribiert alle Audio-Dateien in einem Ordner parallel."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Finde alle Audio-Dateien
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}"
)
# Speichere die Transkription
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Endbericht
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Speichere den Bericht
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"]
)
Geben Sie nicht nach der Versuchung nach, max_workers zu erhöhen, um schneller zu gehen. Die Mistral-API setzt Grenzen für Anfragen pro Minute, und vier Arbeiter halten Sie in der Regel unter diesem Schwellenwert. Wenn 429-Fehler (Too Many Requests) in Ihren Protokollen erscheinen, ist die Antwort nicht härter neu zu starten, sondern die Anzahl der Arbeiter zu reduzieren oder eine Verzögerung zwischen den Anfragen einzuführen.
Vorbereitung des Audios upstream
Das Format der gesendeten Dateien beeinflusst sowohl die Uploadzeit als auch die Qualität des resultierenden Textes. Wenn die Treue von größter Bedeutung ist, bleiben Sie bei WAV oder FLAC, verlustfreien Formaten: das Modell erhält die vollständige Audio-Information. Für den allgemeinen Gebrauch bietet MP3 mit 128 kbps oder höher den besten Kompromiss, wobei die Qualität für die Transkription mehr als ausreichend ist und eine vernünftige Dateigröße aufweist. Und wenn die Bandbreite die dominierende Einschränkung ist, bleiben OGG Vorbis oder MP3 mit 64 kbps für Sprache perfekt akzeptabel, was sich in dieser Hinsicht sehr von Musik unterscheidet.
Statt alles zu akzeptieren, was ankommt, normalisieren Sie sie vor dem Senden. Die Funktion unten wendet vier Transformationen an: Umwandlung in Mono, da Stereo der Transkription nichts hinzufügt; Abtastung auf 16 kHz, die native Rate von Voxtral; Bitrate auf 64 kbps eingestellt, ausreichend für Sprache; und loudnorm, das die Lautstärke ausgleicht.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Vorbereitet eine Audio-Datei für eine optimale Transkription."""
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 hilft der Transkription nicht)
"-ar", "16000", # 16 kHz (native Voxtral-Rate)
"-b:a", "64k", # 64 kbps (ausreichend für Sprache)
"-af", "loudnorm", # Lautstärke-Normalisierung
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Der Gewinn ist zweifach: Die Umwandlung in Mono 16 kHz 64 kbps reduziert die Dateigrößen signifikant, ohne die Transkription zu verschlechtern, und loudnorm verbessert die Ergebnisse bei Aufnahmen mit unregelmäßiger Lautstärke merklich, typischerweise ein Meeting, bei dem ein Teilnehmer weit vom Mikrofon entfernt ist.
Wissen, was passiert
Ein Transkriptionsservice ohne Instrumentierung ist eine Black Box: Wenn die Verarbeitungszeiten am Tag verdoppeln, werden Sie es von einem unglücklichen Benutzer erfahren. Sammeln Sie die Dateigröße, die Verarbeitungszeit, die Anzahl der Versuche und das Volumen des erzeugten Textes für jeden Aufruf und schreiben Sie alles als JSON auf einer einzigen Zeile, ein Format, das direkt von einem Protokoll-Aggregator verwendet werden kann.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Transkribiert mit Metrik-Sammlung."""
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)
# Strukturiertes Protokoll (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Produktions-Checkliste
Bevor Sie Ihren Service dem ersten echten Benutzer öffnen, überprüfen Sie diese sieben Punkte:
| Bereich | Prüfung |
|---|---|
| Fehlerbehandlung | Neustart mit exponentiellem Backoff für vorübergehende Fehler |
| Rate-Limitierung | API-Grenzen respektieren, bei Bedarf Throttling implementieren |
| Überwachung | Strukturierte Protokolle, Leistungsmetriken, Warnungen bei Fehlern |
| Sicherheit | API-Schlüssel in Umgebungsvariable, niemals hartcodiert im Code |
| Speicherung | Transkriptionen dauerhaft speichern, nicht nur im Speicher |
| Audio-Format | Dateien upstream normalisieren (Mono, 16 kHz) |
| Testen | Verschiedene Dateien: Sprachen, Längen, Audioqualität, Anzahl der Sprecher |
Die letzte Zeile ist die, die am häufigsten vernachlässigt und die teuerste ist. Drei saubere Aufnahmen auf Französisch werden Ihnen nichts über das tatsächliche Verhalten Ihres Services lehren: Erstellen Sie eine absichtlich schwierige Probe, und Sie werden die Einstellungen entdecken, die angepasst werden müssen, solange noch Zeit bleibt.
Kernaussagen
- Implementieren Sie Neustart mit exponentiellem Backoff und Jitter für vorübergehende Fehler
- Verwenden Sie einen Worker-Pool für die Batch-Verarbeitung (4 Arbeiter sind ein guter Ausgangspunkt)
- Normalisieren Sie Ihre Dateien auf Mono 16 kHz mit FFmpeg für optimale Ergebnisse
- Sammeln Sie strukturierte Metriken für die Produktionsüberwachung
- Respektieren Sie die Mistral-API-Rate-Limitierungsgrenzen
- Speichern Sie Transkriptionen und Batch-Berichte systematisch