Salt la conținutul principal
Română— Alege o limbă
Meniu

Optimizare pentru producție

Lecția 15 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De la prototip la serviciu fiabil
  2. Gestionarea erorilor: distincția dintre recuperabile și fatale
  3. Procesarea unui lot de fișiere fără supraveghere
  4. Pregătirea audio în amonte
  5. Cunoașterea a ceea ce se întâmplă
  6. Lista de verificare pentru producție
  7. Puncte cheie

Curs actualizat la 3 noiembrie 2026 pentru Voxtral 3, pe baza ghidului Migrate from Voxtral 2 de la Mistral: modelele Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), depreciate la 31 octombrie 2026 și retrase la 30 aprilie 2027, sunt înlocuite în exemple cu voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 și voxtral-mini-tts-3-0. Modificări cheie: marcajele temporale sunt doar pe segmente (word returnează o eroare 400), diarizarea în timp real este suportată, setările sesiunii în timp real sunt blocate după primul fragment audio, iar intrările context_bias sunt în format liber (fraze cu spații). Surse: Migrate from Voxtral 2 · Speech to Text.

De la prototip la serviciu fiabil

Știți deja cum să transcrieți fișiere audio, atât asincron, cât și în timp real. Totuși, operarea unui serviciu care procesează sute de fișiere zilnic, fără supraveghere umană, reprezintă un exercițiu complet diferit, deoarece se lovește de probleme pe care un prototip nu le întâlnește niciodată: un fișier corupt, o cotă depășită, o întrerupere de rețea în timpul încărcării sau un vârf de volum care declanșează limitarea ratei. Această lecție abordează aceste cazuri unul câte unul – gestionarea erorilor, procesarea în loturi, pregătirea fișierelor și observabilitatea.

Gestionarea erorilor: distincția dintre recuperabile și fatale

Prima regulă este să nu tratați toate erorile în același mod. O întrerupere de rețea, un timeout sau o pană temporară merită o reîncercare; un fișier ilizibil sau o cheie API invalidă nu se vor repara singure, iar reîncercarea lor doar pierde timpul și poluează jurnalele. Wrapper-ul de mai jos implementează această distincție printr-un tuplu de excepții temporare: orice eroare din ERREURS_TEMPORAIRES declanșează o reîncercare, în timp ce orice altceva eșuează imediat. În ambele cazuri, funcția returnează un dicționar în loc să arunce o excepție, permițând procesării în loturi să continue cu fișierele rămase.

import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral

logger = logging.getLogger("voxtral")

# Excepții de reîncercat
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Transcrie un fișier cu reîncercare exponențială."""
    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:
            # Eroare nerecuperabilă (fișier invalid, auth, etc.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Întârzierea dintre încercări se dublează la fiecare eșec – două secunde, apoi patru, apoi opt – pentru a evita suprasolicitarea unui API care deja întâmpină dificultăți. Totuși, această strategie de „backoff“ exponențial are un defect atunci când aveți mulți clienți: dacă toți eșuează în același instant, se vor reîncerca toți simultan, iar valul de cereri va lovi serviciul dintr-o dată. Rezolvăm acest lucru prin jitter, o variație aleatorie adăugată întârzierii, suficientă pentru a desincroniza încercările.

import random

delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)

Procesarea unui lot de fișiere fără supraveghere

Transcrierea a două sute de înregistrări una după alta este ineficientă: cea mai mare parte a timpului se pierde așteptând rețeaua. Un pool de lucrători gestionează mai multe transcrieri concurent, fără a pierde șirul progresului. Funcția de mai jos scanează un dosar, păstrează extensiile audio cunoscute, trimite fiecare fișier către wrapper-ul de reîncercare definit anterior și scrie transcrierea imediat ce aceasta sosește, nu la final: dacă procesul se blochează la jumătate, ceea ce a fost procesat este deja pe disc. Un raport JSON rezumă succesele și eșecurile, permițându-vă să reporniți doar ce a eșuat.

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
):
    """Transcrie toate fișierele audio dintr-un dosar în paralel."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Găsește toate fișierele audio
    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}"
            )

            # Salvează transcrierea
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Raport final
    succes = sum(1 for r in resultats if r["succes"])
    echecs = len(resultats) - succes
    logger.info(f"Terminé : {succes} succès, {echecs} échecs")

    # Salvează raportul
    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

# Utilizare
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

Nu cedați tentației de a mări max_workers pentru a merge mai repede. API-ul Mistral impune limite de cereri pe minut, iar patru lucrători vă mențin de obicei sub acest prag. Dacă erorile 429 (Too Many Requests) apar în jurnalele dumneavoastră, soluția nu este să reîncercați mai agresiv, ci să reduceți numărul de lucrători sau să introduceți o întârziere între cereri.

Pregătirea audio în amonte

Formatul fișierelor pe care le trimiteți influențează atât timpul de încărcare, cât și calitatea textului rezultat. Dacă fidelitatea este primordială, rămâneți la WAV sau FLAC, formate fără pierderi: modelul primește toate informațiile audio. Pentru uz curent, MP3 la 128 kbps sau mai mult oferă cel mai bun compromis, cu o calitate mai mult decât suficientă pentru transcriere și o dimensiune rezonabilă a fișierului. Iar când lățimea de bandă este constrângerea dominantă, OGG Vorbis sau MP3 la 64 kbps rămân perfect acceptabile pentru vorbire, care este foarte diferită de muzică sub acest aspect.

În loc să acceptați orice format care sosește, normalizați-le înainte de trimitere. Funcția de mai jos aplică patru transformări: conversia la mono, deoarece stereo nu adaugă nimic transcrierii; resampling la 16 kHz, rata nativă Voxtral; bitrate setat la 64 kbps, suficient pentru voce; și loudnorm, care egalizează volumul.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Pregătește un fișier audio pentru o transcriere optimă."""
    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 nu ajută transcrierea)
        "-ar", "16000",       # 16 kHz (rata nativă Voxtral)
        "-b:a", "64k",        # 64 kbps (suficient pentru vorbire)
        "-af", "loudnorm",    # Normalizare volum
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Câștigul este dublu: conversia la mono 16 kHz 64 kbps reduce semnificativ dimensiunile fișierelor fără a degrada transcrierea, iar loudnorm îmbunătățește vizibil rezultatele pe înregistrările cu volum neregulat, tipic o întâlnire unde un participant este departe de microfon.

Cunoașterea a ceea ce se întâmplă

Un serviciu de transcriere fără instrumentare este o cutie neagră: în ziua în care timpii de procesare se dublează, veți afla de la un utilizator nemulțumit. Colectați dimensiunea fișierului, durata procesării, numărul de încercări și volumul de text produs pentru fiecare apel, apoi scrieți totul ca JSON pe o singură linie, un format direct utilizabil de un agregator de jurnale.

import time
import logging
import json
from datetime import datetime

logger = logging.getLogger("voxtral-prod")

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Transcrie cu colectare de metrici."""
    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)

    # Jurnal structurat (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Lista de verificare pentru producție

Înainte de a deschide serviciul dumneavoastră primului utilizator real, revizuiți aceste șapte puncte:

DomeniuVerificare
Gestionarea erorilorReîncercare cu backoff exponențial pentru erorile temporare
Limitarea rateiRespectați limitele API, implementați throttling dacă este necesar
MonitorizareJurnale structurate, metrici de performanță, alerte la erori
SecuritateCheie API în variabilă de mediu, niciodată hardcoded în cod
StocareSalvați transcrierile durabil, nu doar în memorie
Format audioNormalizați fișierele în amonte (mono, 16 kHz)
TestareFișiere variate: limbi, durate, calitate audio, număr de vorbitori

Ultima linie este cea mai adesea neglijată și cea mai costisitoare. Trei înregistrări curate în franceză nu vă vor învăța nimic despre comportamentul real al serviciului dumneavoastră: construiți un eșantion deliberat dificil și veți descoperi setările de ajustat cât mai este timp.

Puncte cheie

  • Implementați reîncercarea cu backoff exponențial și jitter pentru erorile temporare
  • Utilizați un pool de lucrători pentru procesarea în loturi (4 lucrători este un punct de plecare bun)
  • Normalizați fișierele la mono 16 kHz cu FFmpeg pentru rezultate optime
  • Colectați metrici structurate pentru monitorizarea în producție
  • Respectați limitele de rată ale API-ului Mistral
  • Salvați sistematic transcrierile și rapoartele de loturi