Valós idejű átírás megvalósítása Pythonban
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 kivezetett 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 (diarization) 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 kötötlen formátumúak (szóközöket tartalmazó kifejezések). Források: Migrate from Voxtral 2 · Speech to Text.
A teljes Python aszinkron adatfolyam
Most megírod a teljes valós idejű átírási folyamatot, az első hangbájttól a végső szövegfájlig. Minden az asyncio-ra épül: a programnak egyszerre kell olvasnia a hangot és fogadnia a modell eseményeit anélkül, hogy bármelyik művelet blokkolná a másikat. A hagyományos szinkron kód itt egyszerűen várakozna, és a gondosan beállított késleltetés a saját programod holtidejében semmisülne meg.
Az adatfolyam-alapú program architektúrája
Bármilyen alkalmazásról is legyen szó, a felépítés ugyanaz marad, és balról jobbra olvasható. Felső szinten egy hangforrás: egy aszinkron generátor, amely PCM hangcsomagokat állít elő. Ma ez egy fájl lehet, holnap egy mikrofon vagy egy hálózati adatfolyam. Középen a Voxtral kliens, azaz az SDK, amely továbbítja ezeket a csomagokat a modellnek, és eseményeket szolgáltat neked. Alsó szinten az eseményfeldolgozás: az üzleti logikád, amely megjeleníti a szöveget, felhalmozza, elmenti vagy továbbítja egy másik szolgáltatás felé.
Hangforrás → [PCM csomagok] → Mistral SDK → [események] → A kódod
Ennek a szétválasztásnak gyakorlati előnye van: a hangforrás cserélhető. Az alább megírt átírási kód változatlanul működik a következő leckében szereplő mikrofon-generátorral is, egyetlen sor módosítása nélkül.
Alapvető megvalósítás
Ebben az első programban két részletre érdemes figyelned. A source_audio_fichier generátor 32 000 bájtos blokkokra vágja a fájlt, ami pontosan egy másodpercnyi 16 kHz-es, 16 bites mono PCM hangnak felel meg: 16 000 minta szorozva 2 bájttal. Az egyes yield utáni await asyncio.sleep szimulálja a valós időt; kommentezd ki ezt a sort, és futtasd a programot néhány perces részleten: látni fogod, hogy a fájl töredékmásodperc alatt elfogy, ami semmit nem tanít az adatfolyam-viselkedésről. A fogadó oldalon a texte_complet felhalmozza a töredékeket, így a végén a teljes szöveg rendelkezésedre áll a élő megjelenítés mellett.
import asyncio
import os
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
async def source_audio_fichier(chemin: str, taille_chunk: int = 32000):
"""Aszinkron generátor, amely chunkokban olvas be egy PCM fájlt.
taille_chunk = 32000 bájt = 1 másodpercnyi 16 bites mono PCM hang 16 kHz-en
(16000 minta × 2 bájt = 32000 bájt)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Valós idő szimulálása (1 csomag = 1 másodperc)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Hangadatfolyam valós idejű átírása Voxtrallal."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(
encoding="pcm_s16le",
sample_rate=16000
)
texte_complet = []
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
texte_complet.append(event.text)
elif isinstance(event, TranscriptionStreamDone):
print("\n\n--- Az átírás befejeződött ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Eredmény mentése
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nSzöveg elmentve ({len(texte)} karakter)")
asyncio.run(main())
Az élő megjelenítés a print(event.text, end="", flush=True) hívásra épül. A flush=True nélkül a Python puffereli a kimenetet, és a szöveg kötegekben jelenne meg: az átírás technikailag valós idejű lenne, de vizuálisan akadozna.
A feldolgozás strukturálása éles környezethez
Ha az alkalmazásod kilép a demó szintjéről, az if/elif ciklus kezelhetetlenné válik: szeretnéd megszámolni a töredékeket, mérni az időtartamot, kijelzőt csatlakoztatni vagy adatbázist táplálni. A logika osztályba zárása egyszer és mindenkorra megoldja a problémát. Minden eseménytípus saját dedikált metódust kap, és új viselkedést adhatsz hozzá – például minden delta elküldése egy webes felületre – anélkül, hogy hozzá kellene nyúlnod a fogadó ciklushoz.
class GestionnaireTranscription:
"""Kezeli a valós idejű átírási eseményeket."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Elindítja az átírást és feldolgozza az eseményeket."""
import time
self.debut = time.time()
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
self._on_text_delta(event)
elif isinstance(event, TranscriptionStreamDone):
self._on_done(event)
return self.obtenir_resultat()
def _on_text_delta(self, event):
"""Minden új szövegtöredéknél meghívódik."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Élő megjelenítés
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Az átírás végén meghívódik."""
import time
duree = time.time() - self.debut
print(f"\n\nBefejezve {duree:.1f}s alatt")
print(f"Fogadott töredékek: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Visszaadja a teljes átírt szöveget."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Eredmény: {len(texte)} karakter")
asyncio.run(main())
A nb_deltas számláló nem díszítés: a hang időtartamához viszonyítva jelzi a modell kibocsátási rátáját, és figyelmeztet, ha az adatfolyam romlani kezd.
Hálózati megszakítások kezelése
Egy adatfolyam-kapcsolat a beszéd teljes időtartama alatt nyitva marad, így sokkal inkább ki van téve a hibáknak, mint egy néhány másodperces offline kérés. Egy ingadozó Wi-Fi, egy hálózati váltás mobil eszközön vagy egy szolgáltatói kimaradás megszakíthatja az adatfolyamot. Az alábbi minta legfeljebb háromszor újraindítja az átírást, olyan késleltetéssel, amely kísérletenként nő, hogy időt adjon a hálózatnak a helyreállásra. Ezen túl a kivétel továbbítódik: egy explicit hiba jobb, mint egy olyan alkalmazás, amely úgy tűnik, mintha semmit sem hallana.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # másodperc
async def transcrire_avec_retry(source_audio, tentative=1):
"""Átírás automatikus újracsatlakozással."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
try:
async for event in client.audio.realtime.transcribe_stream(
audio_stream=source_audio,
model="voxtral-mini-transcribe-realtime-3",
audio_format=audio_format,
):
if isinstance(event, TranscriptionStreamTextDelta):
print(event.text, end="", flush=True)
elif isinstance(event, TranscriptionStreamDone):
print("\n[Befejezve]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nHálózati hiba ({tentative}/{MAX_TENTATIVES}. kísérlet)")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nSikertelen {MAX_TENTATIVES} kísérlet után: {e}")
raise
Meglévő fájl előkészítése
Ha egy már meglévő MP3- vagy WAV-fájllal szeretnél tesztelni, automatizálhatod a PCM-re való konverziót Pythonból, ahelyett, hogy manuálisan futtatnád. Az alábbi függvény az FFmpeg-re bízza a munkát, a bemeneti névből következteti ki a kimeneti nevet, és visszaadja az eredményül kapott elérési utat, készen arra, hogy átadd a source_audio_fichier függvénynek.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Hangfájl konvertálása 16 bites, 16 kHz-es mono PCM formátumba FFmpeg segítségével."""
if chemin_sortie is None:
chemin_sortie = chemin_entree.rsplit(".", 1)[0] + ".pcm"
subprocess.run([
"ffmpeg", "-y",
"-i", chemin_entree,
"-f", "s16le",
"-acodec", "pcm_s16le",
"-ar", "16000",
"-ac", "1",
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
# Használat
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Ezután használd: source_audio_fichier(chemin_pcm)
Két óvintézkedés ezzel a függvénnyel kapcsolatban. A check=True kivételt dob, ha az FFmpeg meghibásodik, ami jobb, mint ha csak később, az adatfolyamban vennéd észre, hogy üres a PCM fájl; a capture_output=True pedig elrejti az eszköz kimenetét, így egy hosszú konverzió alatt a program befagyottnak tűnhet. Órányi felvételeknél érdemes üzenetet kiírni a hívás előtt és után is.
Főbb megállapítások
- Az adatfolyam-aszinkron generátorokat használ (
async for,yield) - Egy 32 000 bájtos csomag = 1 másodpercnyi 16 bites mono PCM hang 16 kHz-en
- Éles környezetben strukturáld osztályba az eseményfeldolgozást
- Implementálj újrapróbálkozási mechanizmust a hálózati hibák kezelésére
- Használd az FFmpeg-et a meglévő hangfájlok PCM-re konvertálásához
- Az élő megjelenítéshez a
print(szöveg, end="", flush=True)használandó