Implimenta t-Traskrizzjoni f'Ħin Reali f'Python
F'din il-paġna
Kors aġġornat fit-3 ta’ Novembru 2026 għal Voxtral 3, ibbażat fuq il-gwida Migrate from Voxtral 2 ta’ Mistral: Il-mudelli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, skaduti fil-31 ta’ Ottubru 2026 u rtirati fit-30 ta’ April 2027) ġew sostitwiti fl-eżempji b’voxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3, uvoxtral-mini-tts-3-0. Bidliet ewlenin: it-timstamps huma biss għas-segmenti (wordjirritorna żball 400), id-djarizzazzjoni hija possibbli f’ħin reali, is-settings tas-sessjoni f’ħin reali jissakkaw wara l-ewwel biċċa awdjo, u l-inputs ta’context_biashuma f’forma libera (frażijiet b’ispazji). Sorsi: Migrate from Voxtral 2 · Speech to Text.
L-Istream Sħiħ Asinkronu f’Python
Issa se tikteb pipeline sħiħa ta’ traskrizzjoni f’ħin reali, mill-ewwel byte tal-awdjo sal-fajl finali tat-test. Kollox jiddependi fuq asyncio: il-programm irid jaqra l-awdjo u jirċievi l-avvenimenti tal-mudell fl-istess ħin, mingħajr ma waħda minn dawn l-operazzjonijiet timblokka l-oħra. Kodiċi sinkronu standard sempliċiment jistenna hawnhekk, u l-latenza li kkonfigurajt bir-reqqa tisparixxi fiż-żmien mejjet tal-programm tiegħek stess.
Arkitettura tal-Programma ta’ Streaming
Irregolament l-applikazzjoni, l-istruttura tibqa’ l-istess u taqra mix-xellug għal-lemin. ‘Il fuq mill-fluss, sors tal-awdjo: ġeneratur asinkronu li jipproduċi biċċiet PCM tal-awdjo. Illum jista’ jkun fajl, għada jista’ jkun mikrofonu jew stream tan-network. Fiċ-ċentru, il-klijent Voxtral, jiġifieri l-SDK, li jimbotta dawn il-biċċiet lejn il-mudell u jagħtik l-avvenimenti. ‘L isfel mill-fluss, ipproċessar tal-avvenimenti: il-loġika tan-negozju tiegħek, li turi t-test, takkumulah, isalvah, jew jgħaddih lil servizz ieħor.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Din is-separazzjoni għandha benefiċċju prattiku: is-sors tal-awdjo huwa interkambjabbli. Il-kodiċi tat-traskrizzjoni li tikteb hawn taħt se jaħdem bl-istess mod mal-ġeneratur tal-mikrofonu mil-lezzjoni li jmiss, mingħajr ma tbiddel linja waħda.
Implimentazzjoni Bażika
Żewġ dettalji f’dan l-ewwel programm jistħoqqilhom attenzjoni. Il-ġeneratur source_audio_fichier jaqsam il-fajl f’blokki ta’ 32,000 byte, li jikkorrispondu eżattament għal sekonda waħda ta’ awdjo PCM mono ta’ 16-bit f’16 kHz: 16,000 kampjun immultiplikat b’2 bytes. L-await asyncio.sleep wara kull yield jissimula l-ħin reali; ikkummenta din il-linja u ġġib il-programm fuq estratt ta’ ftit minuti, u se tara l-fajl jiġi kkunsmat f’frazzjoni ta’ sekonda, li ma jgħallmek xejn dwar l-imġiba tal-istream. Fuq in-naħa tar-riċeviment, texte_complet jakkumula l-frammenti sabiex ikollok it-test sħiħ disponibbli fl-aħħar, minbarra l-wiri live.
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):
"""Ġeneratur asinkronu li jaqra fajl PCM f'biċċiet.
taille_chunk = 32000 bytes = sekonda waħda ta' awdjo PCM mono ta' 16-bit f'16kHz
(16000 kampjun × 2 bytes = 32000 bytes)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simula l-ħin reali (biċċa waħda = sekonda waħda)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Jittraskrivi stream tal-awdjo f'ħin reali b'Voxtral."""
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--- Traskrizzjoni lestuta ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Isalva r-riżultat
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTest maħżun ({len(texte)} karattru)")
asyncio.run(main())
Il-wiri live jiddependi fuq print(event.text, end="", flush=True). Mingħajr flush=True, Python jibbufferja l-output u t-test jidher f’lotti: it-traskrizzjoni tiegħek tkun teknikament f’ħin reali, iżda viżwalment imqatta’.
Strutturar l-Ipproċessar għall-Produzzjoni
Ladarba l-applikazzjoni tiegħek tmur lil hinn minn demo, iċ-ċiklu if/elif isir skomdu: trid tgħodd il-frammenti, tkejjel id-durata, tħabbat display, jew titma’ database. L-inkapsular tal-loġika f’klassi jsolvi l-problema għal kollox. Kull tip ta’ avveniment jikseb il-metodu dedikat tiegħu stess, u tista’ żżid imġiba—pereżempju, tibgħat kull delta lil interfaċċja web—mingħajr ma tmiss iċ-ċiklu tar-riċeviment.
class GestionnaireTranscription:
"""Jimmaniġġja l-avvenimenti tat-traskrizzjoni f'ħin reali."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Jibda t-traskrizzjoni u jipproċessa l-avvenimenti."""
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):
"""Imsejjaħ għal kull framment ġdid tat-test."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Wirja live
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Imsejjaħ fit-tmiem tat-traskrizzjoni."""
import time
duree = time.time() - self.debut
print(f"\n\nLest f'{duree:.1f}s")
print(f"Frammenti rċevuti: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Jirritorna t-test sħiħ ittraskritt."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Riżultat: {len(texte)} karattru")
asyncio.run(main())
Il-kontatur nb_deltas mhuwiex gimmick: relattivament għad-durata tal-awdjo, jindika r-rata ta’ emissjoni tal-mudell u jwissek jekk l-istream jiddeterjorax.
Is-Sopravivenza ta’ Interruzzjonijiet fin-Network
Konnessjoni ta’ streaming tibqa’ miftuħa matul id-durata kollha tad-diskors, u tesponiha ħafna aktar minn talba offline ta’ ftit sekondi. Wi-Fi li jixgħel u jitfi, switch tan-network fuq apparat mobbli, jew tfixkil fl-operatur jistgħu jinterrompu l-istream. Il-mudell hawn taħt jerġa’ jibda t-traskrizzjoni sa tliet darbiet, b’dewmien li jiżdied ma’ kull tentattiv biex jagħti ż-żmien lin-network jirkupra. Lil hinn minn hekk, l-eċċezzjoni tiġi propagata: falliment espliċitu huwa aħjar minn applikazzjoni li tidher li qed tisma’ xejn.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # sekondi
async def transcrire_avec_retry(source_audio, tentative=1):
"""Traskrizzjoni b'konnessjoni mill-ġdid awtomatika."""
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[Lestuta]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nŻball fin-network (tentattiv {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nFalliment wara {MAX_TENTATIVES} tentattivi: {e}")
raise
Tħejjija ta’ Fajl Eżistenti
Biex tittestja b’fajl MP3 jew WAV li diġà għandek fuq idejk, tista’ tawtomatizza l-konverżjoni għal PCM minn Python minflok ma tħaddimha manwalment. Il-funzjoni hawn taħt tiddelega x-xogħol lil FFmpeg, tiddeduċi l-isem tal-output mill-isem tal-input, u tirritorna l-mogħdija riżultanti, lesta biex tgħaddiha lil source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Jikkonverti fajl tal-awdjo għal PCM mono ta' 16-bit 16kHz permezz ta' FFmpeg."""
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
# Użu
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Imbagħad uża source_audio_fichier(chemin_pcm)
Żewġ prekawzjonijiet ma’ din il-funzjoni. check=True iqajjem eċċezzjoni jekk FFmpeg ifalli, li huwa aħjar milli tiskopri fajl PCM vojt aktar tard fl-istream; u capture_output=True jaħbi l-output tal-għodda, sabiex konverżjoni twila ma tagħmilx il-programm jidher iffriżat. Għal reġistrazzjonijiet ta’ siegħa, ippjana li tistampa messaġġ qabel u wara s-sejħa.
Punti Ewlenin
- L-istream juża ġeneraturi asinkroni (
async for,yield) - Biċċa ta’ 32,000 byte = sekonda waħda ta’ awdjo PCM mono ta’ 16-bit f’16 kHz
- Ipproċessa l-avvenimenti f’klassi għall-produzzjoni
- Implimenta mekkaniżmu ta’ retry biex tittratta żbalji fin-network
- Uża FFmpeg biex tikkonverti fajls tal-awdjo eżistenti għal PCM
- Il-wiri live juża
print(text, end="", flush=True)