Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Implimenta t-Traskrizzjoni f'Ħin Reali f'Python

Lezzjoni 10 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-Istream Sħiħ Asinkronu f’Python
  2. Arkitettura tal-Programma ta’ Streaming
  3. Implimentazzjoni Bażika
  4. Strutturar l-Ipproċessar għall-Produzzjoni
  5. Is-Sopravivenza ta’ Interruzzjonijiet fin-Network
  6. Tħejjija ta’ Fajl Eżistenti
  7. Punti Ewlenin

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, u voxtral-mini-tts-3-0. Bidliet ewlenin: it-timstamps huma biss għas-segmenti (word jirritorna ż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_bias huma 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)