Ottimizzazzjoni għall-Produzzjoni
F'din il-paġna
Kors aġġornat fit-3 ta’ Novembru 2026 għal Voxtral 3, ibbażat fuq il-gwida Migrate from Voxtral 2 ta’ Mistral: Il-mudelli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, iddeprekati fil-31 ta’ Ottubru 2026 u rtirati fit-30 ta’ April 2027, huma mibdula fl-eżempji b’voxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3, uvoxtral-mini-tts-3-0. Bidliet ewlenin: it-timestamps huma biss għas-segmenti (wordjirritorna żball 400), id-dijarizzazzjoni f’ħin reali hija appoġġjata, is-settings tas-sessjoni f’ħin reali jingħalqu wara l-ewwel biċċa awdjo, u l-inputs ta’context_biashuma f’forma libera (frażijiet b’ispazji). Sorsi: Migrate from Voxtral 2 · Speech to Text.
Mill-Prototip għal Servizz Affidabbli
Int taf kif tittrascri vi awdjo, kemm b’mod asinkronu kif ukoll f’ħin reali. Iżda t-tħaddim ta’ servizz li jipproċessa mijiet ta’ fajls kuljum mingħajr superviżjoni umana huwa eżerċizzju kompletament differenti, għax jiltaqa’ ma’ dak li prototip qatt ma jara: fajl ikkorrott, kwota maqbura, waqgħa fin-netwerk nofs it-tlugħ, jew qawwa tal-volum li tikkawża limitazzjoni tar-rata. Din il-lezzjoni tittratta dawn il-każijiet wieħed wieħed—ġestjoni tal-iżbalji, ipproċessar bil-batch, tħejjija tal-fajls, u osservabbiltà.
Ġestjoni tal-Iżbalji li Tiddistingwi bejn Dak li Jista’ Jiġi Rkuprat u Dak Fatali
L-ewwel regola hija li ma tittrattax l-iżbalji kollha bl-istess mod. Waqgħa fin-netwerk, timeout, jew ħsara temporanja meritaw tentattiv mill-ġdid; fajl li ma jinqarax jew API key invalida qatt mhux se jissolvu waħedhom, u li tipprova mill-ġdid biss iħassar il-ħin u jniġġes il-logs tiegħek. Il-wrapper hawn taħt jimplimenta din id-distinzjoni b’tuple ta’ eċċezzjonijiet temporanji: kull ma jkun f’ERREURS_TEMPORAIRES jikkawża tentattiv mill-ġdid, filwaqt li kull ħaġa oħra tfalli immedjatament. Fiż-żewġ każijiet, il-funzjoni tirritorna dizzjunarju minflok ma tħalli eċċezzjoni, u b’hekk l-ipproċessar bil-batch ikompli bil-fajls li jifdal.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Eċċezzjonijiet biex tipprova mill-ġdid
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Tittrascri fajl b'tentattivi mill-ġdid esponenzjali."""
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:
# Żball mhux rkuprabbli (fajl invalidu, awtentikazzjoni, eċċ.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Id-dewmien bejn it-tentattivi jirdoppja ma’ kull falliment—żewġ sekondi, imbagħad erbgħa, imbagħad tmienja—biex tevita li tgħaffeġ API li diġà qed issib diffikultà. Madankollu, dan il-”backoff” esponenzjali għandu difett meta jkollok ħafna klijenti: jekk ifallu kollha fl-istess mument, kollha se jippruvaw mill-ġdid fl-istess mument, u l-mewġa tolqot is-servizz kollu f’daqqa. Nissolvu dan bil-jitter, varjazzjoni każwali miżjuda mad-dewmien, li hija biżżejjed biex tiddesinkronizza t-tentattivi.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Ipproċessar ta’ Batch ta’ Fajls Mingħajr Superviżjoni
It-traskrizzjoni ta’ mitejn rekording wieħed wara l-ieħor hija ħela: il-biċċa l-kbira tal-ħin tintilef tistenna n-netwerk. Pool ta’ ħaddiema jittratta traskrizzjonijiet multipli b’mod konkorrenti mingħajr ma jitlif il-pass tal-progress. Il-funzjoni hawn taħt tiskannja folder, iżżomm estensjonijiet tal-awdjo magħrufa, tibgħat kull fajl lill-wrapper tat-tentattiv mill-ġdid definit hawn fuq, u tikteb it-traskrizzjoni hekk kif tasal minflok ma tistenna t-tmiem: jekk il-proċess jaqa’ nofs it-triq, dak li ġie pproċessat diġà jkun fuq id-diska. Rapport JSON jagħmel sommarju tas-suċċessi u l-fallimenti, u jippermettilek terġa’ tibda biss dak li falla.
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
):
"""Tittrascri l-fajls tal-awdjo kollha f'folder b'mod parallel."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Sib il-fajls tal-awdjo kollha
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}"
)
# Ikteb it-traskrizzjoni
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Rapport finali
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Ikteb ir-rapport
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
# Użu
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Tċedix għat-tentazzjoni li żżid max_workers biex tmur aktar malajr. L-API ta’ Mistral timponi limiti fuq it-talbiet kull minuta, u erba’ ħaddiema ġeneralment iżommuk taħt dik il-limitu. Jekk jiġu żbalji 429 (Too Many Requests) fil-logs tiegħek, it-tweġiba mhix li tipprova aktar iebes iżda li tnaqqas in-numru ta’ ħaddiema jew tintroduċi dewmien bejn it-talbiet.
Tħejjija tal-Awdjo Minn Qabel
Il-format tal-fajls li tibgħat jinfluwenza kemm il-ħin tat-tlugħ kif ukoll il-kwalità tat-test li jirriżulta. Jekk il-fidelità hija l-aktar importanti, ibqa’ ma’ WAV jew FLAC, formats mingħajr telf: il-mudell jirċievi l-informazzjoni sħiħa tal-awdjo. Għal użu komuni, MP3 f’128 kbps jew ogħla joffri l-aħjar kompromess, b’kwalità aktar minn biżżejjed għat-traskrizzjoni u daqs tal-fajl raġonevoli. U meta l-bandwidth huwa l-kostrenza dominanti, OGG Vorbis jew MP3 f’64 kbps jibqgħu aċċettabbli ħafna għad-diskors, li huwa differenti ħafna mill-mużika f’dan ir-rigward.
Minflok ma taċċetta kwalunkwe format li jaslek, normalizzahom qabel ma tibgħathom. Il-funzjoni hawn taħt tapplika erba’ trasformazzjonijiet: konverżjoni għal mono, peress li stereo ma jżid xejn mat-traskrizzjoni; resampling għal 16 kHz, ir-rata nattiva ta’ Voxtral; bitrate stabbilit għal 64 kbps, biżżejjed għall-vuċi; u loudnorm, li jwettaq l-ekwalizzazzjoni tal-volum.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Iħejji fajl tal-awdjo għal traskrizzjoni ottimali."""
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 ma jgħinx fit-traskrizzjoni)
"-ar", "16000", # 16 kHz (Rata nattiva ta' Voxtral)
"-b:a", "64k", # 64 kbps (Biżżejjed għad-diskors)
"-af", "loudnorm", # Normalizzazzjoni tal-volum
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Il-gwadann huwa doppju: il-konverżjoni għal mono 16 kHz 64 kbps tonqos b’mod sinifikanti d-daqs tal-fajls mingħajr ma tiddeterjora t-traskrizzjoni, u loudnorm itejjeb b’mod notevoli r-riżultati fuq rekording b’volum irregolari, tipikament laqgħa fejn parteċipant wieħed ikun ‘il bogħod mill-mikrofonu.
Li Tkun Taf X’Qed Jiġri
Servizz ta’ traskrizzjoni mingħajr strumentazzjoni huwa kaxxa sewda: il-jum li l-ħinijiet tal-ipproċessar jirdoppjaw, se titgħallem bih minn utent mhux kuntent. Iġbor id-daqs tal-fajl, it-tul tal-ipproċessar, in-numru ta’ tentattivi, u l-volum tat-test prodott għal kull sejħa, imbagħed ikteb kollox bħala JSON fuq linja waħda, format użabbli direttament minn aggregatur tal-logs.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Tittrascri bil-ġbir tal-metriċi."""
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)
# Log strutturat (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Lista ta’ Verifika għall-Produzzjoni
Qabel ma tiftaħ is-servizz tiegħek għall-ewwel utent reali, irrevedi dawn is-seba’ punti:
| Dominju | Verifika |
|---|---|
| Ġestjoni tal-iżbalji | Erġa’ pprova b’backoff esponenzjali għal żbalji temporanji |
| Limitazzjoni tar-rata | Irrispetta l-limiti tal-API, implimenta throttling jekk meħtieġ |
| Monitoraġġ | Logs strutturat, metriċi tal-prestazzjoni, allerti fuq l-iżbalji |
| Sigurtà | API key f’varjabbli tal-ambjent, qatt mhux imwaħħla fil-kodiċi |
| Ħażna | Ikteb it-traskrizzjonijiet b’mod durabbli, mhux biss fil-memorja |
| Format tal-awdjo | Normalizza l-fajls minn qabel (mono, 16 kHz) |
| Ittestjar | Fajls varjati: lingwi, tul, kwalità tal-awdjo, numru ta’ kelliema |
L-aħħar linja hija dik l-aktar traskurata spiss u l-aktar għalja. Tliet rekording nodfa bil-Franċiż ma jgħallmuk xejn dwar l-imġiba reali tas-servizz tiegħek: ibni kampjun deliberatament diffiċli, u se tiskopri s-settings li għandek taġġusta waqt li għad hemm ħin.
Punti Ewlenin
- Implimenta tentattiv mill-ġdid b’backoff esponenzjali u jitter għal żbalji temporanji
- Uża pool ta’ ħaddiema għall-ipproċessar bil-batch (4 ħaddiema huwa punt tat-tluq tajjeb)
- Normalizza l-fajls tiegħek għal mono 16 kHz b’FFmpeg għal riżultati ottimali
- Iġbor metriċi strutturat għall-monitoraġġ tal-produzzjoni
- Irrispetta l-limiti tar-rata tal-API ta’ Mistral
- Ikteb sistematikament it-traskrizzjonijiet u r-rapporti tal-batch