Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Első transzkripciós hívásod

5. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Első transzkripciód a Voxtrallal
  2. A környezet előkészítése
  3. Helyi fájl transzkripciója
  4. Transzkripció URL-címről
  5. Áttérés egy robusztus verzióra
  6. Mit tartalmaz a válasz?
  7. Főbb megállapítások

A tanfolyam frissítve: 2026. november 3., Voxtral 3 verzió, a Mistral Migrate from Voxtral 2 útmutatója alapján: a 2026. október 31-én elavult és 2027. április 30-án eltávolított Voxtral 2 modelleket (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603) a példákban a voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 és voxtral-mini-tts-3-0 modellek váltják fel. Főbb változások: az időbélyegek csak szegmensszinten érhetők el (a word paraméter 400-as hibát eredményez), a beszélőazonosítás valós időben is lehetséges, a valós idejű munkamenet beállításai az első hangcsomag után rögzülnek, a context_bias bemenetek pedig szabad formátumúak (szóközöket tartalmazó kifejezések). Források: Migrate from Voxtral 2 · Speech to Text.

Első transzkripciód a Voxtrallal

Elég az elméletből. Ebben a leckében végrehajtod az első teljes hívást az offline transzkripciós API felé: egy helyi hangfájlt küldesz a Voxtral Mini Transcribe 3 modellnek, majd feldolgozod a visszaadott szöveget. A kód néhány sorból áll, de később ezt kibővítjük egy olyan robusztus verzióvá, amely felügyelet nélküli működésre is alkalmas.

A környezet előkészítése

A Mistral SDK egyetlen paranccsal telepíthető. Az ezt követő ellenőrző lépés megkímél attól, hogy később importálási hibák után kelljen kutatnod.

# A Mistral SDK telepítése
pip install mistralai

# A telepítés ellenőrzése
python -c "from mistralai.client import Mistral; print('SDK installed')"

Szükséged lesz egy Mistral API-kulcsra. Hozz létre egyet a console.mistral.ai oldalon, és tárold környezeti változóban, ne pedig keményen kódold be:

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

Helyi fájl transzkripciója

Íme a teljes kód egy helyi hangfájl transzkripciójához:

import os
from mistralai.client import Mistral

# A kliens inicializálása
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# A hangfájl megnyitása és transzkripciója
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"}
    )

# Az eredmény megjelenítése
print("=== Transzkripció ===")
print(response.text)

Ennyi az egész. Négy sor aktív kóddal megkapod a hangfájlod teljes transzkripcióját.

Nézzük végig ezt a négy sort. A Mistral(api_key=...) létrehozza a klienst az API-kulcsoddal; ez az objektum, amelyet minden további híváshoz újra felhasználsz. Az open("mon_audio.mp3", "rb") bináris módban nyitja meg a fájlt, ami hanganyagok esetén kötelező – a b elhagyása olyan dekódolási hibát okoz, amelyet nehéz értelmezni. A file={"content": f, "file_name": "..."} paraméter egy szótárat vár, amely tartalmazza a fájl objektumát és a nevét; ez a név nem csupán díszítés, segít a szervernek a formátum felismerésében. Végül a response.text a teljes transzkripciót tartalmazza karakterláncként.

Transzkripció URL-címről

Ha a hangfájlod már online elérhető, a file helyett a file_url paramétert használd:

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)

Az URL-címnek nyilvánosan elérhetőnek kell lennie. A Mistral szerver közvetlenül letölti a fájlt, ami megkíméli attól, hogy a gépeden keresztül irányítsd az audiót, amikor az már a felhőben van – ez jelentős sávszélesség-megtakarítást jelent több száz fájlból álló katalógus esetén.

Áttérés egy robusztus verzióra

A minimális szkript tesztelésre megfelel. Éles környezetben azonban kezelned kell a hiányzó fájlokat, váratlan formátumokat, hiányzó kulcsokat és hálózati hibákat. Az alábbi szkript ezeket az ellenőrzéseket végzi el a hívás előtt, majd elmenti az eredményt.

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

def transcrire_audio(chemin_fichier: str) -> str:
    """Transzkribál egy hangfájlt a Voxtral Mini Transcribe 3 segítségével."""

    # Ellenőrizze, hogy a fájl létezik-e
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Ellenőrizze a kiterjesztést
    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)}"
        )

    # Ellenőrizze a méretet (gyakorlati korlát: ~200 MB)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # A kliens inicializálása
    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)

    # Transzkripció
    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)

    # Mentés szöveges fájlba
    sortie = Path(chemin).stem + "_transcription.txt"
    Path(sortie).write_text(texte, encoding="utf-8")
    print(f"\nTranscription sauvegardée dans : {sortie}")

Futtasd a terminálból a fájl elérési útjának megadásával:

python transcribe.py meeting_march15.mp3

A szkript ellenőrzi a fájlt, transzkribálja azt, megjeleníti az eredményt, és automatikusan elmenti egy .txt fájlba, amelynek alapneve megegyezik az eredetivel. Most már rendelkezel a kötegelt feldolgozás vázával: iterálj végig egy könyvtáron, és a hangarchívumod kereshető szöveges archívummá válik.

Mit tartalmaz a válasz?

A response objektum nem csak szöveget tartalmaz. Megadja a feldolgozott hanganyag időtartamát és a modell által felismert nyelvet is – ez két hasznos információ a feladatok naplózásához és a nem várt nyelvű fájlok észleléséhez.

# Teljes szöveg
print(response.text)

# Hang időtartama (másodpercben)
print(f"Durée : {response.duration:.1f}s")

# Észlelt nyelv
print(f"Langue : {response.language}")

A modell minőségének legjobb felmérésére az szolgál, ha a saját hangodon teszteled. Rögzíts egy harminc másodperctől két percig tartó hangüzenetet, futtasd le a fenti szkriptet, és hasonlítsd össze szóról szóra az eredményt azzal, amit mondtál: azonnal látni fogod, hol vannak a ritka hibák, amelyek szinte mindig a tulajdonneveknél fordulnak elő. Ezután ismételd meg a gyakorlatot egy másik nyelvű fájllal, a kód módosítása nélkül, hogy megfigyeld az automatikus nyelvfelismerést működés közben.

Főbb megállapítások

  • A minimális hívás 4 sort igényel: kliens, fájlmegnyitás, API-hívás, eredmény beolvasása
  • Két küldési mód: helyi fájl (file) vagy URL-cím (file_url)
  • A file szótárban szereplő fájlnév segít a formátum felismerésében
  • Éles környezetben adj hozzá hibakezelést (hiányzó fájl, érvénytelen formátum, hálózati hiba)
  • A response.text mindig karakterláncként tartalmazza a teljes transzkripciót