Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Optimalizácia pre produkciu

Lekcia 15 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Od prototypu k spoľahlivej službe
  2. Rozlišovanie medzi obnoviteľnými a fatálnymi chybami
  3. Dávkové spracovanie súborov bez dohľadu
  4. Príprava zvuku vopred
  5. Prehľad o dianí
  6. Kontrolný zoznam pre produkciu
  7. Kľúčové poznatky

Kurz aktualizovaný 3. novembra 2026 pre Voxtral 3 na základe príručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), zastarané 31. októbra 2026 a vyradené 30. apríla 2027, sú v príkladoch nahradené modelmi voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 a voxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú len na úrovni segmentov (word vráti chybu 400), je podporovaná diarizácia v reálnom čase, nastavenia relácie v reálnom čase sú uzamknuté po prvom zvukovom bloku a vstupy context_bias sú voľného formátu (frázy s medzerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.

Od prototypu k spoľahlivej službe

Už vieš prepisovať zvuk, či už asynchrónne alebo v reálnom čase. Prevádzkovanie služby, ktorá denne spracuje stovky súborov bez ľudského dohľadu, je však úplne iná disciplína. Narazíš totiž na situácie, ktoré prototyp nikdy nevidí: poškodený súbor, prekročená kvóta, výpadok siete počas nahrávania alebo nárazový nárast objemu, ktorý spustí obmedzenie rýchlosti. Táto lekcia sa zaoberá týmito prípadmi jeden po druhom – spracovanie chýb, dávkové spracovanie, príprava súborov a pozorovateľnosť.

Rozlišovanie medzi obnoviteľnými a fatálnymi chybami

Prvým pravidlom je netraktovať všetky chyby rovnako. Výpadok siete, časový limit alebo dočasná nedostupnosť si zaslúžia opakovanie pokusu; nečitateľný súbor alebo neplatný API kľúč sa nikdy neopravia samy a ich opakovanie len plytvá časom a zaplňuje tvoje logy. Nižšie uvedený obal implementuje toto rozlíšenie pomocou tuple dočasných výnimiek: čokoľvek v ERREURS_TEMPORAIRES spustí opakovanie, zatiaľ čo všetko ostatné okamžite zlyhá. V oboch prípadoch funkcia vráti slovník namiesto vyvolania výnimky, čo umožňuje pokračovať v dávkovom spracovaní so zvyšnými súbormi.

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

logger = logging.getLogger("voxtral")

# Výnimky na opakovanie
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Prepíše súbor s exponenciálnym opakovaním pokusu."""
    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:
            # Neobnoviteľná chyba (neplatný súbor, autentifikácia atď.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Oneskorenie medzi pokusmi sa pri každom zlyhaní zdvojnásobí – dve sekundy, potom štyri, potom osem –, aby sa predišlo zahlcovaniu API, ktoré už má problémy. Toto exponenciálne oneskorenie má však chybu, keď máš veľa klientov: ak všetci zlyhajú v rovnakom okamihu, všetci sa pokúsia o opakovanie súčasne a vlna požiadaviek zasiahne službu naraz. Opravíme to pomocou jitteru, náhodnej variácie pridanej k oneskoreniu, čo stačí na desynchronizáciu pokusov.

import random

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

Dávkové spracovanie súborov bez dohľadu

Postupný prepis dvesto nahrávok je plytvanie: väčšinu času strácaš čakáním na sieť. Pool workerov zvláda viacero prepisov súčasne bez straty prehľadu o pokroku. Nižšie uvedená funkcia naskenuje priečinok, zachová známe zvukové prípony, odošle každý súbor do vyššie definovaného obalu s opakovaním pokusu a zapíše prepis hneď, ako dorazí, nie až na konci: ak proces spadne v polovici, to, čo bolo spracované, je už na disku. Správa vo formáte JSON zhrnie úspechy a zlyhania, čo ti umožní reštartovať len to, čo zlyhalo.

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
):
    """Prepíše všetky zvukové súbory v priečinku paralelne."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Nájdi všetky zvukové súbory
    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}"
            )

            # Uloženie prepisu
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Záverečná správa
    succes = sum(1 for r in resultats if r["succes"])
    echecs = len(resultats) - succes
    logger.info(f"Terminé : {succes} succès, {echecs} échecs")

    # Uloženie správy
    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

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

Nepodľahni pokušeniu zvýšiť max_workers pre rýchlejší chod. API Mistral ukladá limity na počet požiadaviek za minútu a štyria workeri ťa zvyčajne udržia pod touto hranicou. Ak sa v tvojich logoch objavia chyby 429 (Too Many Requests), riešením nie je tvrdohlavé opakovanie, ale zníženie počtu workerov alebo zavedenie oneskorenia medzi požiadavkami.

Príprava zvuku vopred

Formát súborov, ktoré odosielaš, ovplyvňuje čas nahrávania aj kvalitu výsledného textu. Ak je prioritou vernosť, drž sa formátov WAV alebo FLAC bez straty: model dostane všetky zvukové informácie. Pre bežné použitie ponúka MP3 pri 128 kbps alebo vyššie najlepší kompromis s kvalitou viac než dostatočnou na prepis a primeranou veľkosťou súboru. A keď je dominantným obmedzením šírka pásma, OGG Vorbis alebo MP3 pri 64 kbps zostávajú pre reč úplne prijateľné, čo je v tomto ohľade veľmi odlišné od hudby.

Namiesto akceptovania akýchkoľvek prichádzajúcich formátov ich pred odoslaním normalizuj. Nižšie uvedená funkcia aplikuje štyri transformácie: konverziu na mono, keďže stereo neprináša pre prepis žiadnu výhodu; prevzorkovanie na 16 kHz, čo je natívna frekvencia Voxtral; nastavenie bitovej rýchlosti na 64 kbps, čo pre hlas stačí; a loudnorm, ktorý vyrovnáva hlasitosť.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Pripraví zvukový súbor na optimálny prepis."""
    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 nepomáha pri prepise)
        "-ar", "16000",       # 16 kHz (natívna frekvencia Voxtral)
        "-b:a", "64k",        # 64 kbps (stačí pre reč)
        "-af", "loudnorm",    # Normalizácia hlasitosti
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Zisk je dvojitý: konverzia na mono 16 kHz 64 kbps výrazne zmenšuje veľkosť súborov bez zhoršenia prepisu a loudnorm citeľne zlepšuje výsledky pri nahrávkach s nepravidelnou hlasitosťou, typicky na stretnutí, kde je jeden účastník ďaleko od mikrofónu.

Prehľad o dianí

Služba prepisu bez inštrumentácie je čiernou skrinkou: o zdvojnásobení časov spracovania sa dozvieš až od nespokojného používateľa. Pre každé volanie zaznamenaj veľkosť súboru, trvanie spracovania, počet pokusov a objem vyprodukovaného textu, potom to všetko zapíš ako JSON na jeden riadok, čo je formát priamo použiteľný agregátorom logov.

import time
import logging
import json
from datetime import datetime

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

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Prepíše so zberom metrík."""
    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)

    # Štruktúrovaný log (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Kontrolný zoznam pre produkciu

Pred otvorením služby pre prvého skutočného používateľa si prejdite týchto sedem bodov:

OblasťKontrola
Spracovanie chýbOpakovanie s exponenciálnym oneskorením pre dočasné chyby
Obmedzenie rýchlostiRešpektovanie limitov API, implementácia tlmenia v prípade potreby
MonitorovanieŠtruktúrované logy, metriky výkonu, alerty pri chybách
BezpečnosťAPI kľúč v premennej prostredia, nikdy nie natvrdo v kóde
ÚložiskoTrvalé ukladanie prepisov, nie len v pamäti
Zvukový formátNormalizácia súborov vopred (mono, 16 kHz)
TestovanieRôznorodé súbory: jazyky, dĺžky, kvalita zvuku, počet hovoriacich

Posledný riadok je ten, ktorý sa najčastejšie zanedbáva a stojí najviac. Tri čisté nahrávky vo francúzštine ťa nič nenaučia o skutočnom správaní tvojej služby: zostav zámerne náročnú vzorku a objavíš nastavenia, ktoré treba upraviť, kým je ešte čas.

Kľúčové poznatky

  • Implementuj opakovanie s exponenciálnym oneskorením a jitterom pre dočasné chyby
  • Použi pool workerov na dávkové spracovanie (4 workeri sú dobrým východiskom)
  • Normalizuj svoje súbory na mono 16 kHz pomocou FFmpeg pre optimálne výsledky
  • Zbieraj štruktúrované metriky pre monitorovanie produkcie
  • Rešpektuj limity rýchlosti API Mistral
  • Systematicky ukladaj prepisy a dávkové správy