Przejdź do głównej treści
Polski— Wybierz język
Menu

Optymalizacja pod środowisko produkcyjne

Lekcja 15 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Od prototypu do niezawodnej usługi
  2. Obsługa błędów rozróżniająca te odwracalne od krytycznych
  3. Przetwarzanie wsadowe plików bez nadzoru
  4. Wstępne przygotowanie audio
  5. Wiedza o tym, co się dzieje
  6. Lista kontrolna produkcyjna
  7. Kluczowe wnioski

Kurs zaktualizowany 3 listopada 2026 r. dla Voxtral 3, na podstawie przewodnika Mistral Migrate from Voxtral 2: modele Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603, wycofane 31 października 2026 r. i usunięte 30 kwietnia 2027 r.) zostały zastąpione w przykładach przez voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 oraz voxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasu dotyczą tylko segmentów (word zwraca błąd 400), obsługiwana jest diarizacja w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a dane wejściowe context_bias mają dowolny format (frazy ze spacjami). Źródła: Migrate from Voxtral 2 · Speech to Text.

Od prototypu do niezawodnej usługi

Wiesz już, jak transkrybować audio, zarówno asynchronicznie, jak i w czasie rzeczywistym. Uruchomienie usługi przetwarzającej setki plików dziennie bez nadzoru człowieka to zupełnie inne wyzwanie, ponieważ napotyka ona problemy, z którymi prototyp nigdy się nie styka: uszkodzony plik, przekroczony limit quota, przerwa w sieci w trakcie przesyłania czy nagły skok obciążenia uruchamiający ograniczenie liczby żądań (rate limiting). Ta lekcja omawia te przypadki po kolei: obsługę błędów, przetwarzanie wsadowe, przygotowanie plików i obserwowalność.

Obsługa błędów rozróżniająca te odwracalne od krytycznych

Pierwsza zasada brzmi: nie traktuj wszystkich błędów tak samo. Przerwa w sieci, przekroczenie czasu oczekiwania (timeout) czy tymczasowa awaria zasługują na ponowną próbę; nieczytelny plik lub nieprawidłowy klucz API nigdy same się nie naprawią, a ich ponawianie tylko marnuje czas i zaśmieca logi. Poniższy wrapper implementuje to rozróżnienie za pomocą krotki wyjątków tymczasowych: wszystko, co znajduje się w ERREURS_TEMPORAIRES, uruchamia ponowną próbę, podczas gdy wszystko inne kończy się natychmiastowym niepowodzeniem. W obu przypadkach funkcja zwraca słownik zamiast zgłaszać wyjątek, co pozwala kontynuować przetwarzanie wsadowe dla pozostałych plików.

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

logger = logging.getLogger("voxtral")

# Wyjątki wymagające ponownej próby
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Transkrybuje plik z wykładniczą liczbą ponownych prób."""
    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:
            # Błąd nieodwracalny (nieprawidłowy plik, auth itp.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Opóźnienie między próbami podwaja się przy każdej nieudanej próbie – dwie sekundy, potem cztery, potem osiem – aby nie „dobijać“ API, które już ma problemy. Jednak to wykładnicze opóźnienie (exponential backoff) ma wadę, gdy masz wielu klientów: jeśli wszyscy zawiodą w tej samej chwili, wszyscy ponowią próbę również w tej samej chwili, a fala żądań uderzy w usługę jednocześnie. Rozwiązaniem jest jitter, czyli losowa zmienność dodawana do opóźnienia, która wystarczy, aby desynchronizować próby.

import random

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

Przetwarzanie wsadowe plików bez nadzoru

Transkrybowanie dwustu nagrań jedno po drugim jest marnotrawstwem: większość czasu spędza się na oczekiwaniu na sieć. Pulka workerów obsługuje wiele transkrypcji równocześnie, nie tracąc przy tym kontroli nad postępem. Poniższa funkcja skanuje folder, wybiera znane rozszerzenia audio, przesyła każdy plik do wrapperu z ponownymi próbami zdefiniowanego powyżej i zapisuje transkrypcję natychmiast po jej otrzymaniu, a nie na samym końcu: jeśli proces ulegnie awarii w połowie, to, co już przetworzono, znajduje się na dysku. Raport JSON podsumowuje sukcesy i porażki, pozwalając uruchomić ponownie tylko to, co się nie powiodło.

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
):
    """Transkrybuje wszystkie pliki audio w folderze równolegle."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Znajdź wszystkie pliki 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}"
            )

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

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

    # Zapisz raport
    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życie
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

Nie ulegaj pokusie zwiększania max_workers, aby przyspieszyć działanie. API Mistral narzuca limity liczby żądań na minutę, a czterech workerów zazwyczaj utrzymuje Cię poniżej tego progu. Jeśli w logach pojawią się błędy 429 (Too Many Requests), odpowiedzią nie jest intensywniejsze ponawianie prób, lecz zmniejszenie liczby workerów lub wprowadzenie opóźnienia między żądaniami.

Wstępne przygotowanie audio

Format przesyłanych plików wpływa zarówno na czas przesyłania, jak i na jakość wynikowego tekstu. Jeśli wierność oryginału jest paramountowa, trzymaj się formatów bezstratnych, takich jak WAV lub FLAC: model otrzymuje pełną informację audio. Do powszechnego użytku MP3 z bitrate 128 kbps lub wyższym oferuje najlepszy kompromis, z jakością więcej niż wystarczającą do transkrypcji i rozsądnym rozmiarem pliku. A gdy głównym ograniczeniem jest przepustowość, OGG Vorbis lub MP3 z bitrate 64 kbps pozostają całkowicie akceptowalne dla mowy, która pod tym względem bardzo różni się od muzyki.

Zamiast akceptować dowolne formaty, które nadejdą, znormalizuj je przed wysłaniem. Poniższa funkcja stosuje cztery transformacje: konwersję do mono, ponieważ stereo nic nie wnosi do transkrypcji; zmianę częstotliwości próbkowania na 16 kHz, natywną dla Voxtral; ustawienie bitrate na 64 kbps, wystarczające dla głosu; oraz loudnorm, który wyrównuje głośność.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Przygotowuje plik audio do optymalnej transkrypcji."""
    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 nie pomaga w transkrypcji)
        "-ar", "16000",       # 16 kHz (natywna częstotliwość Voxtral)
        "-b:a", "64k",        # 64 kbps (wystarczające dla mowy)
        "-af", "loudnorm",    # Normalizacja głośności
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Korzyści są podwójne: konwersja do mono 16 kHz 64 kbps znacząco zmniejsza rozmiary plików bez degradacji transkrypcji, a loudnorm wyraźnie poprawia wyniki w przypadku nagrań o nieregularnej głośności, typowo spotykanych na spotkaniach, gdzie jeden z uczestników znajduje się daleko od mikrofonu.

Wiedza o tym, co się dzieje

Usługa transkrypcji bez instrumentacji jest czarną skrzynką: o dniu, w którym czasy przetwarzania się podwoją, dowiesz się od niezadowolonego użytkownika. Zbieraj rozmiar pliku, czas przetwarzania, liczbę prób i objętość wygenerowanego tekstu dla każdego wywołania, a następnie zapisz wszystko jako JSON w jednej linii – format ten jest bezpośrednio użyteczny dla agregatora logów.

import time
import logging
import json
from datetime import datetime

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

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Transkrybuje z kolekcjonowaniem metryk."""
    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)

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

    return resultat

Lista kontrolna produkcyjna

Zanim udostępnisz swoją usługę pierwszemu rzeczywistemu użytkownikowi, przejrzyj te siedem punktów:

ObszarSprawdzenie
Obsługa błędówPonowne próby z wykładniczym opóźnieniem dla błędów tymczasowych
Ograniczanie przepustowościPrzestrzeganie limitów API, wdrożenie throttlingu w razie potrzeby
MonitorowanieUstrukturyzowane logi, metryki wydajności, alerty na błędy
BezpieczeństwoKlucz API w zmiennej środowiskowej, nigdy na sztywno w kodzie
PrzechowywanieTrwałe zapisywanie transkrypcji, nie tylko w pamięci
Format audioNormalizacja plików z wyprzedzeniem (mono, 16 kHz)
TestowanieRóżnorodne pliki: języki, czasy trwania, jakość audio, liczba mówców

Ostatni wiersz jest najczęściej pomijany i najbardziej kosztowny. Trzy czyste nagrania po francusku niczego Cię nie nauczą o rzeczywistym zachowaniu Twojej usługi: stwórz celnie trudną próbę, a odkryjesz ustawienia do dostosowania, dopóki jest jeszcze czas.

Kluczowe wnioski

  • Wdróż ponowne próby z wykładniczym opóźnieniem i jitterem dla błędów tymczasowych
  • Użyj puli workerów do przetwarzania wsadowego (4 workerów to dobry punkt startowy)
  • Znormalizuj pliki do mono 16 kHz za pomocą FFmpeg dla optymalnych wyników
  • Zbieraj ustrukturyzowane metryki do monitorowania produkcyjnego
  • Przestrzegaj limitów przepustowości API Mistral
  • Systematycznie zapisuj transkrypcje i raporty wsadowe