Első transzkripciós hívásod
Ezen az oldalon
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 avoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3ésvoxtral-mini-tts-3-0modellek váltják fel. Főbb változások: az időbélyegek csak szegmensszinten érhetők el (awordparamé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, acontext_biasbemenetek 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
fileszó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.textmindig karakterláncként tartalmazza a teljes transzkripciót