Optimizacija za proizvodno okolje
Na tej strani
Tečaj posodobljen 3. novembra 2026 za Voxtral 3, na podlagi Mistralovega vodnika Migrate from Voxtral 2: modeli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, ki so bili opuščeni 31. oktobra 2026 in umaknjeni 30. aprila 2027, so v primerih zamenjani zvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3invoxtral-mini-tts-3-0. Ključne spremembe: časovni žigi so samo po segmentih (wordvrne napako 400), podprta je diarizacija v realnem času, nastavitve seje v realnem času so zaklenjene po prvem zvočnem delčku, vnosicontext_biaspa so v prostem formatu (besedne zveze s presledki). Viri: Migrate from Voxtral 2 · Speech to Text.
Od prototipa do zanesljive storitve
Znaš transkribirati zvok, tako asinhrono kot v realnem času. Vzpostavitev storitve, ki dnevno obdela na stotine datotek brez človeškega nadzora, pa je povsem drugačna naloga, saj se sooča s težavami, ki jih prototip nikoli ne vidi: poškodovana datoteka, presežena kvota, izpad omrežja sredi nalaganja ali skok obsega prometa, ki sproži omejitev hitrosti. Ta lekcija obravnava te primere enega za drugim – obravnavo napak, paketno obdelavo, pripravo datotek in opazovanje sistema.
Obravnava napak: razlikovanje med obnovljivimi in usodnimi
Prvo pravilo je, da ne obravnavaš vseh napak enako. Izpad omrežja, časovna omejitev ali začasna nedostopnost storitve zahtevata ponovni poskus; neberljiva datoteka ali neveljaven ključ API se nikoli ne bosta popravila sama, njuno ponavljanje pa le zapravlja čas in onesnažuje dnevnike. Spodnji ovitek to razlikovanje izvaja s pomočjo nabora začasnih izjem: karkoli je v ERREURS_TEMPORAIRES, sproži ponovni poskus, vse ostalo pa takoj odpove. V obeh primerih funkcija vrne slovar namesto sprožitve izjeme, kar omogoča nadaljevanje paketne obdelave s preostalimi datotekami.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Izjeme za ponovni poskus
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Transkribira datoteko z eksponentnim ponavljanjem."""
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:
# Neobnovljiva napaka (neveljavna datoteka, avtentikacija itd.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Zamik med poskusi se z vsakim neuspehom podvoji – dve sekundi, nato štiri, nato osem – da se prepreči preobremenitev API-ja, ki že ima težave. Vendar ima to eksponentno zamikanje napako, ko imaš več odjemalcev: če vsi odpovejo hkrati, bodo vsi poskusili znova hkrati in val zahtev bo storitev znova zadavil. To popravimo z jitterjem, naključnim odmikom, dodanim zamiku, kar zadostuje za desinhronizacijo poskusov.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Paketna obdelava datotek brez nadzora
Zaporedna transkripcija dveh sto posnetkov je potratna: večino časa porabiš za čakanje na omrežje. Skupina delavcev (worker pool) hkrati obdeluje več transkripcij, ne da bi izgubila sled napredku. Spodnja funkcija pregleda mapo, obdrži znane zvočne razširitve, vsako datoteko predloži zgornjemu ovitku za ponovne poskuse in zapiše transkripcijo takoj, ko prispe, namesto šele na koncu: če se proces sredi dela sesuje, je že obdelano že na disku. Poročilo JSON povzame uspehe in napake, kar ti omogoča ponovni zagon le tistega, kar ni uspelo.
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
):
"""Vzporedno transkribira vse zvočne datoteke v mapi."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Poišči vse zvočne datoteke
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}"
)
# Shrani transkripcijo
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Končno poročilo
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Shrani poročilo
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
# Uporaba
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Ne podlegaj skušnjavi povečanja max_workers za hitrejše delo. API Mistral nalaga omejitve glede števila zahtev na minuto in štirje delavci te običajno obdržijo pod tem pragom. Če se v dnevnikih pojavijo napake 429 (Too Many Requests), odgovor ni v trdovratnejšem ponavljanju, temveč v zmanjšanju števila delavcev ali uvedbi zamika med zahtevami.
Predhodna priprava zvoka
Oblika datotek, ki jih pošiljaš, vpliva tako na čas nalaganja kot na kakovost nastalega besedila. Če je zvestoba zvoka ključna, ostani pri formatih WAV ali FLAC brez izgub: model prejme vse zvočne informacije. Za splošno uporabo MP3 pri 128 kbps ali več ponuja najboljše razmerje, s kakovostjo, ki je za transkripcijo več kot zadostna, in razumno velikostjo datoteke. Ko je pasovna širina glavna omejitev, sta OGG Vorbis ali MP3 pri 64 kbps še vedno povsem sprejemljiva za govor, ki se v tem pogledu močno razlikuje od glasbe.
Namesto da bi sprejemal poljubne formate, jih pred pošiljanjem normaliziraj. Spodnja funkcija uporabi štiri transformacije: pretvorbo v mono, saj stereo ne prispeva ničesar k transkripciji; vzorčenje na 16 kHz, kar je naravna stopnja za Voxtral; nastavitev bitne hitrosti na 64 kbps, kar zadostuje za govor; in loudnorm, ki izenači glasnost.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Pripravi zvočno datoteko za optimalno transkripcijo."""
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 ne pomaga pri transkripciji)
"-ar", "16000", # 16 kHz (naravna stopnja Voxtral)
"-b:a", "64k", # 64 kbps (dovolj za govor)
"-af", "loudnorm", # Normalizacija glasnosti
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Dobiček je dvojen: pretvorba v mono 16 kHz 64 kbps bistveno zmanjša velikost datotek brez poslabšanja transkripcije, loudnorm pa opazno izboljša rezultate pri posnetkih z neenakomerno glasnostjo, kar je tipično za sestanke, kjer je eden od udeležencev daleč od mikrofona.
Spremljanje dogajanja
Storitev transkripcije brez instrumentacije je črna škatla: ko se časi obdelave podvojijo, boš za to izvedel od nezadovoljnega uporabnika. Za vsak klic zberi velikost datoteke, trajanje obdelave, število poskusov in količino proizvedenega besedila, nato pa vse zapiši kot JSON v eni vrstici, kar je oblika, neposredno uporabna za agregator dnevnikov.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Transkribira z zbiranjem 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)
# Strukturiran dnevnik (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Kontrolni seznam za proizvodno okolje
Preden storitev odpreš prvemu stvarnemu uporabniku, preveri teh sedem točk:
| Področje | Preverjanje |
|---|---|
| Obravnava napak | Ponovni poskus z eksponentnim zamikom za začasne napake |
| Omejitev hitrosti | Upoštevanje omejitev API-ja, uvedba dušenja po potrebi |
| Spremljanje | Strukturirani dnevniki, metrike zmogljivosti, opozorila ob napakah |
| Varnost | Ključ API v okoljski spremenljivki, nikoli trdo kodiran v kodi |
| Shranjevanje | Trajno shranjevanje transkripcij, ne le v pomnilniku |
| Zvočni format | Normalizacija datotek vnaprej (mono, 16 kHz) |
| Testiranje | Raznovrstne datoteke: jeziki, trajanja, kakovost zvoka, število govorcev |
Zadnja vrstica je tista, ki jo najpogosteje zanemarimo in je hkrati najdražja. Trije čisti posnetki v francoščini te ne bodo naučili ničesar o dejanskem obnašanju tvoje storitve: sestavi namerno težaven vzorec in odkril boš nastavitve, ki jih je treba prilagoditi, dokler je še čas.
Ključne ugotovitve
- Implementiraj ponovni poskus z eksponentnim zamikom in jitterjem za začasne napake
- Uporabi skupino delavcev za paketno obdelavo (4 delavci so dobro izhodišče)
- Normaliziraj svoje datoteke v mono 16 kHz z orodjem FFmpeg za optimalne rezultate
- Zberi strukturirane metrike za spremljanje v proizvodnem okolju
- Upoštevaj omejitve hitrosti API-ja Mistral
- Sistematično shranjuj transkripcije in poročila o paketni obdelavi