Optimalizace pro produkci
Na této stránce
Kurz aktualizován 3. listopadu 2026 pro Voxtral 3 na základě příručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), které byly zastaralé k 31. říjnu 2026 a vyřazené k 30. dubnu 2027, jsou v příkladech nahrazeny modelyvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Klíčové změny: časové značky jsou pouze na úrovni segmentů (wordvrací chybu 400), je podporována diarizace v reálném čase, nastavení relace v reálném čase jsou uzamčena po prvním zvukovém úseku a vstupycontext_biasjsou volného formátu (fráze s mezerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Od prototypu ke spolehlivé službě
Umíš přepisovat zvuk, ať už asynchronně, nebo v reálném čase. Provozování služby, která denně zpracovává stovky souborů bez lidského dohledu, je však zcela jiná disciplína. Setkáš se totiž s problémy, které prototyp nikdy nevidí: poškozený soubor, překročená kvóta, výpadek sítě uprostřed nahrávání nebo prudký nárůst objemu, který spustí omezování rychlosti (rate limiting). Tato lekce se věnuje těmto případům jeden po druhém – zpracování chyb, dávkové zpracování, příprava souborů a pozorovatelnost.
Rozlišování mezi obnovitelnými a fatálními chybami
Prvním pravidlem je netreatovat všechny chyby stejně. Výpadek sítě, časový limit nebo dočasná nedostupnost si zaslouží opakovaný pokus; nečitelný soubor nebo neplatný API klíč se nikdy sám neopraví a jejich opakované zkoušení jen plýtvá časem a znečišťuje logy. Následující obálka toto rozlišení implementuje pomocí tuple dočasných výjimek: cokoli v ERREURS_TEMPORAIRES spustí retry, zatímco vše ostatní okamžitě selže. V obou případech funkce vrátí slovník místo vyvolání výjimky, což umožňuje pokračovat v dávkovém zpracování zbývajících souborů.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Výjimky k opakování
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Přepíše soubor s exponenciálním opakováním."""
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:
# Neobnovitelná chyba (neplatný soubor, auth atd.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Prodleva mezi pokusy se s každým selháním zdvojnásobí – dvě sekundy, pak čtyři, pak osm – aby nedocházelo k zahlcování API, které již má potíže. Toto exponenciální čekání má však při velkém počtu klientů jednu vadu: pokud všichni selžou ve stejný okamžik, všichni se pokusí o retry také ve stejný okamžik a vlna požadavků udeří na službu najednou. Vyřešíme to pomocí jitteru, náhodné variace přidané k prodlevě, což stačí k desynchronizaci pokusů.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Dávkové zpracování souborů bez dohledu
Postupný přepis dvou set nahrávek je plýtváním: většinu času strávíš čekáním na síť. Pool workerů zvládne více přepisů současně, aniž by ztratil přehled o postupu. Následující funkce prohledá složku, vyfiltruje známé zvukové přípony, odešle každý soubor do výše definované obálky s retry a zapíše přepis hned, jak dorazí, nikoli až na konci: pokud proces v polovině spadne, již zpracovaná data jsou na disku. Zpráva ve formátu JSON shrne úspěchy a neúspěchy, takže můžeš restartovat pouze to, co selhalo.
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
):
"""Přepíše všechny zvukové soubory ve složce paralelně."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Najít všechny zvukové soubory
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žit přepis
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Závěrečná zprá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žit zprávu
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žití
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Nepodlehněš pokušení zvýšit max_workers pro rychlejší běh. API Mistral ukládá limity na počet požadavků za minutu a čtyři workeři tě obvykle udrží pod touto hranicí. Pokud se v logech objeví chyby 429 (Too Many Requests), řešením není tvrdší retry, ale snížení počtu workerů nebo zavedení prodlevy mezi požadavky.
Příprava zvuku předem
Formát souborů, které odešleš, ovlivňuje jak dobu nahrávání, tak kvalitu výsledného textu. Pokud je prioritou věrnost, drž se formátů WAV nebo FLAC bez ztráty dat: model obdrží všechny zvukové informace. Pro běžné použití nabízí MP3 při 128 kbps nebo vyšší nejlepší kompromis s kvalitou více než dostatečnou pro přepis a přiměřenou velikostí souboru. A když je dominantním omezením šířka pásma, OGG Vorbis nebo MP3 při 64 kbps zůstávají pro řeč zcela přijatelné, což se výrazně liší od hudby.
Místo přijímání libovolných formátů je před odesláním normalizuj. Následující funkce aplikuje čtyři transformace: převod na mono, protože stereo nic nepřidává k přepisu; převzorkování na 16 kHz, což je nativní frekvence Voxtral; nastavení bitové rychlosti na 64 kbps, což pro řeč stačí; a loudnorm, který vyrovnává hlasitost.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Připraví zvukový soubor pro optimální přepis."""
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áhá přepisu)
"-ar", "16000", # 16 kHz (nativní frekvence Voxtral)
"-b:a", "64k", # 64 kbps (pro řeč dostatečné)
"-af", "loudnorm", # Normalizace hlasitosti
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Zisk je dvojnásobný: převod na mono 16 kHz 64 kbps výrazně zmenšuje velikost souborů bez degradace přepisu a loudnorm znatelně zlepšuje výsledky u nahrávek s nepravidelnou hlasitostí, typicky u schůzek, kde je jeden účastník daleko od mikrofonu.
Přehled o dění
Služba pro přepis bez instrumentace je černá skříň: až se doby zpracování zdvojnásobí, dozvíš se to od nespokojeného uživatele. Pro každý požadavek sbírej velikost souboru, dobu zpracování, počet pokusů a objem vyprodukovaného textu, poté vše zapiš jako JSON na jeden řádek, což je formát přímo použitelný pro agregátor logů.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Přepíše se sběrem metrik."""
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)
# Strukturovaný log (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Kontrolní seznam pro produkci
Než svou službu otevřeš prvnímu skutečnému uživateli, zkontroluj těchto sedm bodů:
| Oblast | Kontrola |
|---|---|
| Zpracování chyb | Retry s exponenciálním čekáním pro dočasné chyby |
| Omezování rychlosti | Respektování limitů API, implementace throttlingu v případě potřeby |
| Monitorování | Strukturované logy, metriky výkonu, alerty na chyby |
| Bezpečnost | API klíč v proměnné prostředí, nikdy natvrdo v kódu |
| Úložiště | Trvalé ukládání přepisů, ne jen v paměti |
| Zvukový formát | Normalizace souborů předem (mono, 16 kHz) |
| Testování | Různorodé soubory: jazyky, délky, kvalita zvuku, počet mluvčích |
Poslední řádek je ten, který se nejčastěji zanedbává a stojí nejvíce peněz. Tři čisté nahrávky ve francouzštině tě nic nenaučí o skutečném chování tvé služby: vytvoř záměrně obtížný vzorek a objevíš nastavení, která je třeba upravit, dokud je ještě čas.
Klíčové poznatky
- Implementuj retry s exponenciálním čekáním a jitterem pro dočasné chyby
- Pro dávkové zpracování použij pool workerů (4 workeři jsou dobrým startem)
- Pro optimální výsledky normalizuj soubory pomocí FFmpeg na mono 16 kHz
- Sbírej strukturované metriky pro produkční monitorování
- Respektuj limity rychlosti API Mistral
- Systematicky ukládej přepisy a dávkové zprávy