Twoja pierwsza transkrypcja
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 modelamivoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3orazvoxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasowe dotyczą wyłącznie segmentów (polewordzwraca błąd 400), diarization jest możliwy w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a dane wejściowecontext_bias` mają dowolną formę (frazy ze spacjami). Źródła: Migrate from Voxtral 2 · Speech to Text.
Twoja pierwsza transkrypcja z Voxtral
Dość teorii. W tej lekcji wykonasz swoje pierwsze pełne wywołanie do interfejsu API transkrypcji offline: lokalny plik audio trafi do modelu Voxtral Mini Transcribe 3, a Ty przetworzysz zwrócony tekst. Kod mieści się w kilku liniach, ale następnie rozbudujemy go do wersji odpornej na błędy, nadającej się do pracy bez nadzoru.
Przygotowanie środowiska
SDK Mistral instaluje się jedną komendą. Krok weryfikacji, który następuje potem, uchroni Cię przed późniejszym szukaniem błędów importu.
# Instalacja SDK Mistral
pip install mistralai
# Weryfikacja instalacji
python -c "from mistralai.client import Mistral; print('SDK installed')"
Będziesz potrzebować klucza API Mistral. Utwórz go na stronie console.mistral.ai i zapisz w zmiennej środowiskowej, zamiast hardkodować go w kodzie:
export MISTRAL_API_KEY="your-api-key-here"
Transkrypcja lokalnego pliku
Oto kompletny kod do transkrypcji lokalnego pliku audio:
import os
from mistralai.client import Mistral
# Inicjalizacja klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Otwarcie i transkrypcja pliku audio
with open("mon_audio.mp3", "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "mon_audio.mp3"}
)
# Wyświetlenie wyniku
print("=== Transkrypcja ===")
print(response.text)
To wszystko. W czterech liniach aktywnego kodu otrzymujesz pełną transkrypcję swojego pliku audio.
Przeanalizujmy te cztery linie. Mistral(api_key=...) tworzy klienta z Twoim kluczem API; jest to obiekt, którego będziesz używać we wszystkich kolejnych wywołaniach. open("mon_audio.mp3", "rb") otwiera plik w trybie binarnym, co jest obowiązkowe dla plików audio – pominięcie b powoduje trudny do zinterpretowania błąd dekodowania. Parametr file={"content": f, "file_name": "..."} oczekuje słownika zawierającego obiekt pliku i jego nazwę; nazwa ta nie jest ozdobnikiem – pomaga serwerowi wykryć format. Na koniec response.text zawiera pełną transkrypcję jako ciąg znaków.
Transkrypcja z adresu URL
Jeśli Twój plik audio jest już hostowany online, użyj file_url zamiast file:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/mon_audio.mp3"
)
print(response.text)
Adres URL musi być publicznie dostępny. Serwer Mistral pobierze plik bezpośrednio, co pozwala uniknąć przesyłania audio przez Twój komputer, gdy znajduje się ono już w chmurze – to znacząca oszczędność przepustowości przy katalogu liczącym kilkaset plików.
Przejście do wersji odpornej na błędy
Minimalny skrypt sprawdza się w testach. W środowisku produkcyjnym musisz obsłużyć brakujące pliki, nieoczekiwane formaty, brakujące klucze i błędy sieciowe. Poniższy skrypt wykonuje te sprawdzenia przed wywołaniem, a następnie zapisuje wynik.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Transkrybuje plik audio za pomocą Voxtral Mini Transcribe 3."""
# Sprawdzenie, czy plik istnieje
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Sprawdzenie rozszerzenia
extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
if fichier.suffix.lower() not in extensions_valides:
raise ValueError(
f"Format non supporté : {fichier.suffix}. "
f"Formats valides : {', '.join(extensions_valides)}"
)
# Sprawdzenie rozmiaru (praktyczny limit: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Inicjalizacja klienta
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
raise EnvironmentError("Variable MISTRAL_API_KEY non définie")
client = Mistral(api_key=api_key)
# Transkrypcja
try:
with open(chemin_fichier, "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": fichier.name}
)
return response.text
except Exception as e:
raise RuntimeError(f"Erreur de transcription : {e}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage : python transcrire.py <fichier_audio>")
sys.exit(1)
chemin = sys.argv[1]
print(f"Transcription de : {chemin}")
print("-" * 50)
texte = transcrire_audio(chemin)
print(texte)
# Zapis do pliku tekstowego
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Uruchom go z terminala, przekazując ścieżkę do pliku:
python transcribe.py meeting_march15.mp3
Skrypt sprawdza plik, transkrybuje go, wyświetla wynik i automatycznie zapisuje go w pliku .txt o tej samej bazowej nazwie. Masz już szkielet do przetwarzania wsadowego: wystarczy pętla po katalogu, a Twoje archiwum audio stanie się przeszukiwalnym archiwum tekstowym.
Co zawiera odpowiedź
Obiekt response nie ogranicza się tylko do tekstu. Dostarcza również czas trwania przetworzonego audio oraz język rozpoznany przez model – dwie przydatne informacje do logowania zadań i wykrywania plików, które nie są w oczekiwanym języku.
# Pełny tekst
print(response.text)
# Czas trwania audio (w sekundach)
print(f"Durée : {response.duration:.1f}s")
# Wykryty język
print(f"Langue : {response.language}")
Najlepszym sposobem na ocenę jakości modelu jest przetestowanie go na własnym głosie. Nagraj wiadomość głosową trwającą od trzydziestu sekund do dwóch minut, uruchom powyższy skrypt i porównaj wynik słowo w słowo z tym, co powiedziałeś: od razu zobaczysz, gdzie leżą rzadkie błędy, prawie zawsze dotyczące nazw własnych. Następnie powtórz ćwiczenie z plikiem w innym języku, bez zmiany kodu, aby obserwować automatyczne wykrywanie języka w działaniu.
Kluczowe wnioski
- Minimalne wywołanie wymaga 4 linii: klient, otwarcie pliku, wywołanie API, odczyt wyniku
- Dwa tryby wysyłania: lokalny plik (
file) lub adres URL (file_url) - Nazwa pliku w słowniku
filepomaga w wykrywaniu formatu - W środowisku produkcyjnym dodaj obsługę błędów (brakujący plik, nieprawidłowy format, błąd sieci)
response.textzawsze zawiera pełną transkrypcję jako ciąg znaków