Optymalizacja pod środowisko produkcyjne
Na tej stronie
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 przezvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3orazvoxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasu dotyczą tylko segmentów (wordzwraca błąd 400), obsługiwana jest diarizacja w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a dane wejściowecontext_biasmają 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:
| Obszar | Sprawdzenie |
|---|---|
| Obsługa błędów | Ponowne próby z wykładniczym opóźnieniem dla błędów tymczasowych |
| Ograniczanie przepustowości | Przestrzeganie limitów API, wdrożenie throttlingu w razie potrzeby |
| Monitorowanie | Ustrukturyzowane logi, metryki wydajności, alerty na błędy |
| Bezpieczeństwo | Klucz API w zmiennej środowiskowej, nigdy na sztywno w kodzie |
| Przechowywanie | Trwałe zapisywanie transkrypcji, nie tylko w pamięci |
| Format audio | Normalizacja plików z wyprzedzeniem (mono, 16 kHz) |
| Testowanie | Róż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