Salt la conținutul principal
Română— Alege o limbă
Meniu

Implementarea transcrierii în timp real în Python

Lecția 10 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Fluxul complet asincron în Python
  2. Arhitectura programului de streaming
  3. Implementarea de bază
  4. Structurarea procesării pentru producție
  5. Supraviețuirea întreruperilor de rețea
  6. Pregătirea unui fișier existent
  7. Puncte cheie

Curs actualizat la 3 noiembrie 2026 pentru Voxtral 3, pe baza ghidului Migrate from Voxtral 2 de la Mistral: modelele Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), depreciate la 31 octombrie 2026 și retrase la 30 aprilie 2027, sunt înlocuite în exemple cu voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 și voxtral-mini-tts-3-0. Modificări cheie: marcajele temporale sunt doar pe segmente (word returnează o eroare 400), diarizarea este posibilă în timp real, setările sesiunii în timp real sunt blocate după primul fragment audio, iar intrările context_bias sunt în format liber (fraze cu spații). Surse: Migrate from Voxtral 2 · Speech to Text.

Fluxul complet asincron în Python

Veți scrie acum un pipeline complet de transcriere în timp real, de la primul octet audio până la fișierul text final. Totul se bazează pe asyncio: programul trebuie să citească audio și să primească evenimente de la model simultan, fără ca nicio operațiune să o blocheze pe cealaltă. Codul sincron standard ar aștepta pur și simplu aici, iar latența pe care ați configurat-o cu grijă ar dispărea în timpul mort al propriului program.

Arhitectura programului de streaming

Indiferent de aplicație, structura rămâne aceeași și se citește de la stânga la dreapta. În amonte, o sursă audio: un generator asincron care produce fragmente de audio PCM. Astăzi poate fi un fișier, mâine un microfon sau un flux de rețea. În centru, clientul Voxtral, adică SDK-ul, care împinge aceste fragmente către model și vă returnează evenimente. În aval, procesarea evenimentelor: logica dumneavoastră de afaceri, care afișează textul, îl acumulează, îl salvează sau îl transmite către un alt serviciu.

Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code

Această separare are un avantaj practic: sursa audio este interschimbabilă. Codul de transcriere pe care îl scrieți mai jos va funcționa identic cu generatorul de microfon din lecția următoare, fără a modifica nicio linie.

Implementarea de bază

Două detalii din acest prim program merită atenția dumneavoastră. Generatorul source_audio_fichier taie fișierul în blocuri de 32.000 de octeți, ceea ce corespunde exact unei secunde de audio PCM mono pe 16 biți la 16 kHz: 16.000 de eșantioane înmulțite cu 2 octeți. Comanda await asyncio.sleep care urmează fiecărui yield simulează timpul real; comentați această linie și rulați programul pe un extras de câteva minute și veți vedea fișierul consumat într-o fracțiune de secundă, ceea ce nu vă învață nimic despre comportamentul streaming. Din partea de recepție, texte_complet acumulează fragmente astfel încât să aveți textul complet disponibil la final, pe lângă afișarea 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):
    """Generator asincron care citește un fișier PCM în fragmente.

    taille_chunk = 32000 octeți = 1 secundă de audio PCM mono pe 16 biți la 16kHz
    (16000 eșantioane × 2 octeți = 32000 octeți)
    """
    with open(chemin, "rb") as f:
        while True:
            chunk = f.read(taille_chunk)
            if not chunk:
                break
            yield chunk
            # Simulează timpul real (1 fragment = 1 secundă)
            await asyncio.sleep(len(chunk) / 32000)

async def transcrire_realtime(source_audio):
    """Transcrie un flux audio în timp real cu 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--- Transcriere terminată ---")

    return "".join(texte_complet)

async def main():
    source = source_audio_fichier("audio.pcm")
    texte = await transcrire_realtime(source)

    # Salvează rezultatul
    with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
        f.write(texte)
    print(f"\nText salvat ({len(texte)} caractere)")

asyncio.run(main())

Afișarea live se bazează pe print(event.text, end="", flush=True). Fără flush=True, Python buffer-ează ieșirea, iar textul ar apărea în loturi: transcrierea dumneavoastră ar fi tehnic în timp real, dar vizual sacadată.

Structurarea procesării pentru producție

Odată ce aplicația dumneavoastră depășește stadiul de demo, bucla if/elif devine greoaie: doriți să numărați fragmente, să măsurați durata, să conectați un afișaj sau să alimentați o bază de date. Încapsularea logicii într-o clasă rezolvă problema o dată pentru totdeauna. Fiecare tip de eveniment primește propria metodă dedicată, iar dumneavoastră puteți adăuga comportamente – de exemplu, trimiterea fiecărui delta către o interfață web – fără a atinge bucla de recepție.

class GestionnaireTranscription:
    """Gestionează evenimentele de transcriere în timp real."""

    def __init__(self):
        self.texte_complet = []
        self.nb_deltas = 0
        self.debut = None

    async def traiter(self, source_audio):
        """Pornește transcrierea și procesează evenimentele."""
        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):
        """Apelată pentru fiecare fragment nou de text."""
        self.texte_complet.append(event.text)
        self.nb_deltas += 1
        # Afișare live
        print(event.text, end="", flush=True)

    def _on_done(self, event):
        """Apelată la sfârșitul transcrierii."""
        import time
        duree = time.time() - self.debut
        print(f"\n\nTerminat în {duree:.1f}s")
        print(f"Fragmente primite: {self.nb_deltas}")

    def obtenir_resultat(self) -> str:
        """Returnează textul complet transcris."""
        return "".join(self.texte_complet)

async def main():
    gestionnaire = GestionnaireTranscription()
    source = source_audio_fichier("audio.pcm")
    texte = await gestionnaire.traiter(source)
    print(f"Rezultat: {len(texte)} caractere")

asyncio.run(main())

Contorul nb_deltas nu este un moft: raportat la durata audio, acesta indică rata de emisie a modelului și vă alertează dacă fluxul se degradează.

Supraviețuirea întreruperilor de rețea

O conexiune de streaming rămâne deschisă pe toată durata vorbirii, expunând-o mult mai mult decât o cerere offline de câteva secunde. Un Wi-Fi instabil, o comutare de rețea pe un dispozitiv mobil sau o pană a operatorului pot întrerupe fluxul. Modelul de mai jos repornește transcrierea de până la trei ori, cu o întârziere care crește la fiecare încercare pentru a permite rețelei timp să își revină. Dincolo de acest punct, excepția este propagată: o eroare explicită este mai bună decât o aplicație care pare să nu asculte nimic.

import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
    AudioFormat,
    TranscriptionStreamTextDelta,
    TranscriptionStreamDone
)

MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2  # secunde

async def transcrire_avec_retry(source_audio, tentative=1):
    """Transcriere cu reconectare automată."""
    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[Terminat]")

    except ConnectionError as e:
        if tentative < MAX_TENTATIVES:
            print(f"\nEroare de rețea (încercarea {tentative}/{MAX_TENTATIVES})")
            await asyncio.sleep(DELAI_RECONNEXION * tentative)
            await transcrire_avec_retry(source_audio, tentative + 1)
        else:
            print(f"\nEșuat după {MAX_TENTATIVES} încercări: {e}")
            raise

Pregătirea unui fișier existent

Pentru a testa cu un fișier MP3 sau WAV pe care îl aveți deja la îndemână, puteți automatiza conversia în PCM din Python, în loc să o rulați manual. Funcția de mai jos deleagă munca către FFmpeg, deduce numele de ieșire din numele de intrare și returnează calea rezultată, gata de a fi transmisă lui source_audio_fichier.

import subprocess

def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Convertește un fișier audio în PCM mono 16kHz pe 16 biți prin 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

# Utilizare
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Apoi folosiți source_audio_fichier(chemin_pcm)

Două precauții cu această funcție. check=True aruncă o excepție dacă FFmpeg eșuează, ceea ce este mai bine decât să descoperiți mai târziu, în flux, un fișier PCM gol; iar capture_output=True ascunde ieșirea instrumentului, astfel încât o conversie lungă va face programul să pară blocat. Pentru înregistrări de o oră, planificați tipărirea unui mesaj înainte și după apel.

Puncte cheie

  • Streaming-ul utilizează generatoare asincrone (async for, yield)
  • Un fragment de 32.000 de octeți = 1 secundă de audio PCM mono pe 16 biți la 16 kHz
  • Structurați procesarea evenimentelor într-o clasă pentru producție
  • Implementați un mecanism de reîncercare pentru a gestiona erorile de rețea
  • Utilizați FFmpeg pentru a converti fișierele audio existente în PCM
  • Afișarea live folosește print(text, end="", flush=True)