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

Tvoja prvá transkripčná požiadavka

Lekcia 5 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Tvoja prvá transkripcia s Voxtral
  2. Príprava prostredia
  3. Transkripcia lokálneho súboru
  4. Transkripcia z URL adresy
  5. Prechod na robustnú verziu
  6. Čo obsahuje odpoveď
  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"), ktoré boli zastarané 31. októbra 2026 a odstránené 30. apríla 2027, sú v príkladoch nahradené modelmi voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú len na úrovni segmentov (wordvráti chybu 400), diarizácia je možná v reálnom čase, nastavenia relácie v reálnom čase sú uzamknuté po prvom zvukovom bloku a vstupycontext_bias` sú voľného formátu (frázy s medzerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.

Tvoja prvá transkripcia s Voxtral

Dosť teórie. V tejto lekcii vykonáš svoju prvú kompletnú požiadavku na API pre offline transkripciu: lokálny zvukový súbor odošleš do Voxtral Mini Transcribe 3 a spracuješ vrátený text. Kód sa zmestí do niekoľkých riadkov, no následne ho rozšírime na robustnú verziu vhodnú na automatickú prevádzku.

Príprava prostredia

SDK od Mistral nainštaluješ jediným príkazom. Overovací krok, ktorý nasleduje, ťa ušetrí od neskoršieho hľadania chyby pri importe.

# Inštalácia Mistral SDK
pip install mistralai

# Overenie inštalácie
python -c "from mistralai.client import Mistral; print('SDK installed')"

Budeš potrebovať kľúč API od Mistral. Vytvor si ho na console.mistral.ai a ulož ho do premennej prostredia namiesto toho, aby si ho hardcodedoval priamo do kódu:

export MISTRAL_API_KEY="your-api-key-here"

Transkripcia lokálneho súboru

Tu je kompletný kód na transkripciu lokálneho zvukového súboru:

import os
from mistralai.client import Mistral

# Inicializácia klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Otvorenie a transkripcia zvukového súboru
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"}
    )

# Zobrazenie výsledku
print("=== Transkripcia ===")
print(response.text)

To je všetko. Štyrmi riadkami aktívneho kódu získaš úplnú transkripciu svojho zvukového súboru.

Prejdime si tieto štyri riadky. Mistral(api_key=...) vytvorí klienta s tvojím API kľúčom; toto je objekt, ktorý budeš znovu používať pri všetkých nasledujúcich volaniach. open("mon_audio.mp3", "rb") otvorí súbor v binárnom režime, čo je pre zvuk povinné – vynechanie b spôsobí chybu dekódovania, ktorú sa ťažko interpretuje. Parameter file={"content": f, "file_name": "..."} očakáva slovník obsahujúci objekt súboru a jeho názov; tento názov nie je len ozdobný, pomáha serveru detegovať formát. Nakoniec, response.text obsahuje celú transkripciu ako reťazec.

Transkripcia z URL adresy

Ak je tvoj zvukový súbor už hostovaný online, použij file_url namiesto 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)

URL adresa musí byť verejne dostupná. Server Mistral si súbor stiahne priamo, čím sa vyhneš smerovaniu zvuku cez tvoj stroj, keď už je v cloude – čo predstavuje významnú úsporu šírky pásma pri katalógu niekoľkých stoviek súborov.

Prechod na robustnú verziu

Minimálny skript funguje na testovanie. V produkčnom prostredí potrebuješ ošetriť chýbajúce súbory, neočakávané formáty, chýbajúce kľúče a chyby siete. Nasledujúci skript vykoná tieto kontroly pred volaním a následne uloží výsledok.

import os
import sys
from pathlib import Path
from mistralai.client import Mistral

def transcrire_audio(chemin_fichier: str) -> str:
    """Transkripcia zvukového súboru pomocou Voxtral Mini Transcribe 3."""

    # Kontrola existencie súboru
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Kontrola prípony
    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)}"
        )

    # Kontrola veľkosti (praktický limit: ~200 MB)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # Inicializácia 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)

    # Transkripcia
    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)

    # Uloženie do textového súboru
    sortie = Path(chemin).stem + "_transcription.txt"
    Path(sortie).write_text(texte, encoding="utf-8")
    print(f"\nTranscription sauvegardée dans : {sortie}")

Spusti ho z terminálu s cestou k súboru ako argumentom:

python transcribe.py meeting_march15.mp3

Skript skontroluje súbor, transkribuje ho, zobrazí výsledok a automaticky ho uloží do súboru .txt s rovnakým základným názvom. Teraz máš kostru pre dávkové spracovanie: prejdeme adresár a tvoj zvukový archív sa stane vyhľadávateľným textovým archívom.

Čo obsahuje odpoveď

Objekt response nie je obmedzený len na text. Poskytuje aj dĺžku spracovaného zvuku a jazyk rozpoznaný modelom – dve užitočné informácie pre logovanie tvojich úloh a detekciu súborov, ktoré nie sú v očakávanom jazyku.

# Celý text
print(response.text)

# Dĺžka zvuku (v sekundách)
print(f"Durée : {response.duration:.1f}s")

# Rozpoznaný jazyk
print(f"Langue : {response.language}")

Najlepší spôsob, ako odhadnúť kvalitu modelu, je otestovať ho na vlastnom hlase. Nahraj hlasovú správu trvajúcu tridsať sekúnd až dve minúty, spusti vyššie uvedený skript a porovnaj výsledok slovo od slova s tým, čo si povedal: okamžite uvidíš, kde sa nachádzajú zriedkavé chyby, takmer vždy pri vlastných menách. Potom zopakuj cvičenie so súborom v inom jazyku bez zmeny kódu, aby si pozoroval automatickú detekciu jazyka v akcii.

Kľúčové poznatky

  • Minimálne volanie vyžaduje 4 riadky: klient, otvorenie súboru, volanie API, prečítanie výsledku
  • Dva režimy odoslania: lokálny súbor (file) alebo URL (file_url)
  • Názov súboru v slovníku file pomáha pri detekcii formátu
  • V produkčnom prostredí pridaj ošetrenie chýb (chýbajúci súbor, neplatný formát, chyba siete)
  • response.text vždy obsahuje celú transkripciu ako reťazec