Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Optimalizace pro produkci

Lekce 15 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Od prototypu ke spolehlivé službě
  2. Rozlišování mezi obnovitelnými a fatálními chybami
  3. Dávkové zpracování souborů bez dohledu
  4. Příprava zvuku předem
  5. Přehled o dění
  6. Kontrolní seznam pro produkci
  7. Klíčové poznatky

Kurz aktualizován 3. listopadu 2026 pro Voxtral 3 na základě příručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), které byly zastaralé k 31. říjnu 2026 a vyřazené k 30. dubnu 2027, jsou v příkladech nahrazeny modely voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 a voxtral-mini-tts-3-0. Klíčové změny: časové značky jsou pouze na úrovni segmentů (word vrací chybu 400), je podporována diarizace v reálném čase, nastavení relace v reálném čase jsou uzamčena po prvním zvukovém úseku a vstupy context_bias jsou volného formátu (fráze s mezerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.

Od prototypu ke spolehlivé službě

Umíš přepisovat zvuk, ať už asynchronně, nebo v reálném čase. Provozování služby, která denně zpracovává stovky souborů bez lidského dohledu, je však zcela jiná disciplína. Setkáš se totiž s problémy, které prototyp nikdy nevidí: poškozený soubor, překročená kvóta, výpadek sítě uprostřed nahrávání nebo prudký nárůst objemu, který spustí omezování rychlosti (rate limiting). Tato lekce se věnuje těmto případům jeden po druhém – zpracování chyb, dávkové zpracování, příprava souborů a pozorovatelnost.

Rozlišování mezi obnovitelnými a fatálními chybami

Prvním pravidlem je netreatovat všechny chyby stejně. Výpadek sítě, časový limit nebo dočasná nedostupnost si zaslouží opakovaný pokus; nečitelný soubor nebo neplatný API klíč se nikdy sám neopraví a jejich opakované zkoušení jen plýtvá časem a znečišťuje logy. Následující obálka toto rozlišení implementuje pomocí tuple dočasných výjimek: cokoli v ERREURS_TEMPORAIRES spustí retry, zatímco vše ostatní okamžitě selže. V obou případech funkce vrátí slovník místo vyvolání výjimky, což umožňuje pokračovat v dávkovém zpracování zbývajících souborů.

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

logger = logging.getLogger("voxtral")

# Výjimky k opakování
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Přepíše soubor s exponenciálním opakováním."""
    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:
            # Neobnovitelná chyba (neplatný soubor, auth atd.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Prodleva mezi pokusy se s každým selháním zdvojnásobí – dvě sekundy, pak čtyři, pak osm – aby nedocházelo k zahlcování API, které již má potíže. Toto exponenciální čekání má však při velkém počtu klientů jednu vadu: pokud všichni selžou ve stejný okamžik, všichni se pokusí o retry také ve stejný okamžik a vlna požadavků udeří na službu najednou. Vyřešíme to pomocí jitteru, náhodné variace přidané k prodlevě, což stačí k desynchronizaci pokusů.

import random

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

Dávkové zpracování souborů bez dohledu

Postupný přepis dvou set nahrávek je plýtváním: většinu času strávíš čekáním na síť. Pool workerů zvládne více přepisů současně, aniž by ztratil přehled o postupu. Následující funkce prohledá složku, vyfiltruje známé zvukové přípony, odešle každý soubor do výše definované obálky s retry a zapíše přepis hned, jak dorazí, nikoli až na konci: pokud proces v polovině spadne, již zpracovaná data jsou na disku. Zpráva ve formátu JSON shrne úspěchy a neúspěchy, takže můžeš restartovat pouze to, co selhalo.

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
):
    """Přepíše všechny zvukové soubory ve složce paralelně."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Najít všechny zvukové soubory
    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žit přepis
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Závěrečná zprá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žit zprávu
    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žití
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

Nepodlehněš pokušení zvýšit max_workers pro rychlejší běh. API Mistral ukládá limity na počet požadavků za minutu a čtyři workeři tě obvykle udrží pod touto hranicí. Pokud se v logech objeví chyby 429 (Too Many Requests), řešením není tvrdší retry, ale snížení počtu workerů nebo zavedení prodlevy mezi požadavky.

Příprava zvuku předem

Formát souborů, které odešleš, ovlivňuje jak dobu nahrávání, tak kvalitu výsledného textu. Pokud je prioritou věrnost, drž se formátů WAV nebo FLAC bez ztráty dat: model obdrží všechny zvukové informace. Pro běžné použití nabízí MP3 při 128 kbps nebo vyšší nejlepší kompromis s kvalitou více než dostatečnou pro přepis a přiměřenou velikostí souboru. A když je dominantním omezením šířka pásma, OGG Vorbis nebo MP3 při 64 kbps zůstávají pro řeč zcela přijatelné, což se výrazně liší od hudby.

Místo přijímání libovolných formátů je před odesláním normalizuj. Následující funkce aplikuje čtyři transformace: převod na mono, protože stereo nic nepřidává k přepisu; převzorkování na 16 kHz, což je nativní frekvence Voxtral; nastavení bitové rychlosti na 64 kbps, což pro řeč stačí; a loudnorm, který vyrovnává hlasitost.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Připraví zvukový soubor pro optimální přepis."""
    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áhá přepisu)
        "-ar", "16000",       # 16 kHz (nativní frekvence Voxtral)
        "-b:a", "64k",        # 64 kbps (pro řeč dostatečné)
        "-af", "loudnorm",    # Normalizace hlasitosti
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Zisk je dvojnásobný: převod na mono 16 kHz 64 kbps výrazně zmenšuje velikost souborů bez degradace přepisu a loudnorm znatelně zlepšuje výsledky u nahrávek s nepravidelnou hlasitostí, typicky u schůzek, kde je jeden účastník daleko od mikrofonu.

Přehled o dění

Služba pro přepis bez instrumentace je černá skříň: až se doby zpracování zdvojnásobí, dozvíš se to od nespokojeného uživatele. Pro každý požadavek sbírej velikost souboru, dobu zpracování, počet pokusů a objem vyprodukovaného textu, poté vše zapiš jako JSON na jeden řádek, což je formát přímo použitelný pro agregátor logů.

import time
import logging
import json
from datetime import datetime

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

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Přepíše se sběrem 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)

    # Strukturovaný log (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Kontrolní seznam pro produkci

Než svou službu otevřeš prvnímu skutečnému uživateli, zkontroluj těchto sedm bodů:

OblastKontrola
Zpracování chybRetry s exponenciálním čekáním pro dočasné chyby
Omezování rychlostiRespektování limitů API, implementace throttlingu v případě potřeby
MonitorováníStrukturované logy, metriky výkonu, alerty na chyby
BezpečnostAPI klíč v proměnné prostředí, nikdy natvrdo v kódu
ÚložištěTrvalé ukládání přepisů, ne jen v paměti
Zvukový formátNormalizace souborů předem (mono, 16 kHz)
TestováníRůznorodé soubory: jazyky, délky, kvalita zvuku, počet mluvčích

Poslední řádek je ten, který se nejčastěji zanedbává a stojí nejvíce peněz. Tři čisté nahrávky ve francouzštině tě nic nenaučí o skutečném chování tvé služby: vytvoř záměrně obtížný vzorek a objevíš nastavení, která je třeba upravit, dokud je ještě čas.

Klíčové poznatky

  • Implementuj retry s exponenciálním čekáním a jitterem pro dočasné chyby
  • Pro dávkové zpracování použij pool workerů (4 workeři jsou dobrým startem)
  • Pro optimální výsledky normalizuj soubory pomocí FFmpeg na mono 16 kHz
  • Sbírej strukturované metriky pro produkční monitorování
  • Respektuj limity rychlosti API Mistral
  • Systematicky ukládej přepisy a dávkové zprávy