Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Ottimizzazzjoni għall-Produzzjoni

Lezzjoni 15 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Mill-Prototip għal Servizz Affidabbli
  2. Ġestjoni tal-Iżbalji li Tiddistingwi bejn Dak li Jista’ Jiġi Rkuprat u Dak Fatali
  3. Ipproċessar ta’ Batch ta’ Fajls Mingħajr Superviżjoni
  4. Tħejjija tal-Awdjo Minn Qabel
  5. Li Tkun Taf X’Qed Jiġri
  6. Lista ta’ Verifika għall-Produzzjoni
  7. Punti Ewlenin

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, u voxtral-mini-tts-3-0. Bidliet ewlenin: it-timestamps huma biss għas-segmenti (word jirritorna ż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_bias huma 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:

DominjuVerifika
Ġestjoni tal-iżbaljiErġa’ pprova b’backoff esponenzjali għal żbalji temporanji
Limitazzjoni tar-rataIrrispetta 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żnaIkteb it-traskrizzjonijiet b’mod durabbli, mhux biss fil-memorja
Format tal-awdjoNormalizza l-fajls minn qabel (mono, 16 kHz)
IttestjarFajls 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