Optimalizácia pre produkciu
Na tejto strane
Kurz aktualizovaný 3. novembra 2026 pre Voxtral 3 na základe príručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), zastarané 31. októbra 2026 a vyradené 30. apríla 2027, sú v príkladoch nahradené modelmivoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú len na úrovni segmentov (wordvráti chybu 400), je podporovaná diarizácia v reálnom čase, nastavenia relácie v reálnom čase sú uzamknuté po prvom zvukovom bloku a vstupycontext_biassú voľného formátu (frázy s medzerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Od prototypu k spoľahlivej službe
Už vieš prepisovať zvuk, či už asynchrónne alebo v reálnom čase. Prevádzkovanie služby, ktorá denne spracuje stovky súborov bez ľudského dohľadu, je však úplne iná disciplína. Narazíš totiž na situácie, ktoré prototyp nikdy nevidí: poškodený súbor, prekročená kvóta, výpadok siete počas nahrávania alebo nárazový nárast objemu, ktorý spustí obmedzenie rýchlosti. Táto lekcia sa zaoberá týmito prípadmi jeden po druhom – spracovanie chýb, dávkové spracovanie, príprava súborov a pozorovateľnosť.
Rozlišovanie medzi obnoviteľnými a fatálnymi chybami
Prvým pravidlom je netraktovať všetky chyby rovnako. Výpadok siete, časový limit alebo dočasná nedostupnosť si zaslúžia opakovanie pokusu; nečitateľný súbor alebo neplatný API kľúč sa nikdy neopravia samy a ich opakovanie len plytvá časom a zaplňuje tvoje logy. Nižšie uvedený obal implementuje toto rozlíšenie pomocou tuple dočasných výnimiek: čokoľvek v ERREURS_TEMPORAIRES spustí opakovanie, zatiaľ čo všetko ostatné okamžite zlyhá. V oboch prípadoch funkcia vráti slovník namiesto vyvolania výnimky, čo umožňuje pokračovať v dávkovom spracovaní so zvyšnými súbormi.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Výnimky na opakovanie
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Prepíše súbor s exponenciálnym opakovaním pokusu."""
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:
# Neobnoviteľná chyba (neplatný súbor, autentifikácia atď.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Oneskorenie medzi pokusmi sa pri každom zlyhaní zdvojnásobí – dve sekundy, potom štyri, potom osem –, aby sa predišlo zahlcovaniu API, ktoré už má problémy. Toto exponenciálne oneskorenie má však chybu, keď máš veľa klientov: ak všetci zlyhajú v rovnakom okamihu, všetci sa pokúsia o opakovanie súčasne a vlna požiadaviek zasiahne službu naraz. Opravíme to pomocou jitteru, náhodnej variácie pridanej k oneskoreniu, čo stačí na desynchronizáciu pokusov.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Dávkové spracovanie súborov bez dohľadu
Postupný prepis dvesto nahrávok je plytvanie: väčšinu času strácaš čakáním na sieť. Pool workerov zvláda viacero prepisov súčasne bez straty prehľadu o pokroku. Nižšie uvedená funkcia naskenuje priečinok, zachová známe zvukové prípony, odošle každý súbor do vyššie definovaného obalu s opakovaním pokusu a zapíše prepis hneď, ako dorazí, nie až na konci: ak proces spadne v polovici, to, čo bolo spracované, je už na disku. Správa vo formáte JSON zhrnie úspechy a zlyhania, čo ti umožní reštartovať len to, čo zlyhalo.
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
):
"""Prepíše všetky zvukové súbory v priečinku paralelne."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Nájdi všetky zvukové súbory
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}"
)
# Uloženie prepisu
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Záverečná správa
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Uloženie správy
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
# Použitie
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Nepodľahni pokušeniu zvýšiť max_workers pre rýchlejší chod. API Mistral ukladá limity na počet požiadaviek za minútu a štyria workeri ťa zvyčajne udržia pod touto hranicou. Ak sa v tvojich logoch objavia chyby 429 (Too Many Requests), riešením nie je tvrdohlavé opakovanie, ale zníženie počtu workerov alebo zavedenie oneskorenia medzi požiadavkami.
Príprava zvuku vopred
Formát súborov, ktoré odosielaš, ovplyvňuje čas nahrávania aj kvalitu výsledného textu. Ak je prioritou vernosť, drž sa formátov WAV alebo FLAC bez straty: model dostane všetky zvukové informácie. Pre bežné použitie ponúka MP3 pri 128 kbps alebo vyššie najlepší kompromis s kvalitou viac než dostatočnou na prepis a primeranou veľkosťou súboru. A keď je dominantným obmedzením šírka pásma, OGG Vorbis alebo MP3 pri 64 kbps zostávajú pre reč úplne prijateľné, čo je v tomto ohľade veľmi odlišné od hudby.
Namiesto akceptovania akýchkoľvek prichádzajúcich formátov ich pred odoslaním normalizuj. Nižšie uvedená funkcia aplikuje štyri transformácie: konverziu na mono, keďže stereo neprináša pre prepis žiadnu výhodu; prevzorkovanie na 16 kHz, čo je natívna frekvencia Voxtral; nastavenie bitovej rýchlosti na 64 kbps, čo pre hlas stačí; a loudnorm, ktorý vyrovnáva hlasitosť.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Pripraví zvukový súbor na optimálny prepis."""
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 nepomáha pri prepise)
"-ar", "16000", # 16 kHz (natívna frekvencia Voxtral)
"-b:a", "64k", # 64 kbps (stačí pre reč)
"-af", "loudnorm", # Normalizácia hlasitosti
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Zisk je dvojitý: konverzia na mono 16 kHz 64 kbps výrazne zmenšuje veľkosť súborov bez zhoršenia prepisu a loudnorm citeľne zlepšuje výsledky pri nahrávkach s nepravidelnou hlasitosťou, typicky na stretnutí, kde je jeden účastník ďaleko od mikrofónu.
Prehľad o dianí
Služba prepisu bez inštrumentácie je čiernou skrinkou: o zdvojnásobení časov spracovania sa dozvieš až od nespokojného používateľa. Pre každé volanie zaznamenaj veľkosť súboru, trvanie spracovania, počet pokusov a objem vyprodukovaného textu, potom to všetko zapíš ako JSON na jeden riadok, čo je formát priamo použiteľný agregátorom logov.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Prepíše so zberom metrík."""
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)
# Štruktúrovaný log (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Kontrolný zoznam pre produkciu
Pred otvorením služby pre prvého skutočného používateľa si prejdite týchto sedem bodov:
| Oblasť | Kontrola |
|---|---|
| Spracovanie chýb | Opakovanie s exponenciálnym oneskorením pre dočasné chyby |
| Obmedzenie rýchlosti | Rešpektovanie limitov API, implementácia tlmenia v prípade potreby |
| Monitorovanie | Štruktúrované logy, metriky výkonu, alerty pri chybách |
| Bezpečnosť | API kľúč v premennej prostredia, nikdy nie natvrdo v kóde |
| Úložisko | Trvalé ukladanie prepisov, nie len v pamäti |
| Zvukový formát | Normalizácia súborov vopred (mono, 16 kHz) |
| Testovanie | Rôznorodé súbory: jazyky, dĺžky, kvalita zvuku, počet hovoriacich |
Posledný riadok je ten, ktorý sa najčastejšie zanedbáva a stojí najviac. Tri čisté nahrávky vo francúzštine ťa nič nenaučia o skutočnom správaní tvojej služby: zostav zámerne náročnú vzorku a objavíš nastavenia, ktoré treba upraviť, kým je ešte čas.
Kľúčové poznatky
- Implementuj opakovanie s exponenciálnym oneskorením a jitterom pre dočasné chyby
- Použi pool workerov na dávkové spracovanie (4 workeri sú dobrým východiskom)
- Normalizuj svoje súbory na mono 16 kHz pomocou FFmpeg pre optimálne výsledky
- Zbieraj štruktúrované metriky pre monitorovanie produkcie
- Rešpektuj limity rýchlosti API Mistral
- Systematicky ukladaj prepisy a dávkové správy