Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Optimizacija za proizvodno okolje

Lekcija 15 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Od prototipa do zanesljive storitve
  2. Obravnava napak: razlikovanje med obnovljivimi in usodnimi
  3. Paketna obdelava datotek brez nadzora
  4. Predhodna priprava zvoka
  5. Spremljanje dogajanja
  6. Kontrolni seznam za proizvodno okolje
  7. Ključne ugotovitve

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 z voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 in voxtral-mini-tts-3-0. Ključne spremembe: časovni žigi so samo po segmentih (word vrne napako 400), podprta je diarizacija v realnem času, nastavitve seje v realnem času so zaklenjene po prvem zvočnem delčku, vnosi context_bias pa 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čjePreverjanje
Obravnava napakPonovni poskus z eksponentnim zamikom za začasne napake
Omejitev hitrostiUpoštevanje omejitev API-ja, uvedba dušenja po potrebi
SpremljanjeStrukturirani dnevniki, metrike zmogljivosti, opozorila ob napakah
VarnostKljuč API v okoljski spremenljivki, nikoli trdo kodiran v kodi
ShranjevanjeTrajno shranjevanje transkripcij, ne le v pomnilniku
Zvočni formatNormalizacija datotek vnaprej (mono, 16 kHz)
TestiranjeRaznovrstne 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