Przejdź do głównej treści
Polski— Wybierz język
Menu

Implementacja transkrypcji w czasie rzeczywistym w Pythonie

Lekcja 10 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Kompletny strumień asynchroniczny w Pythonie
  2. Architektura programu strumieniowego
  3. Podstawowa implementacja
  4. Strukturyzacja przetwarzania dla środowiska produkcyjnego
  5. Przetrwanie przerw w łączności sieciowej
  6. Przygotowanie istniejącego pliku
  7. Kluczowe wnioski

Kurs zaktualizowany 3 listopada 2026 r. dla Voxtral 3, na podstawie przewodnika Mistral Migrate from Voxtral 2: modele Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603'), wycofane 31 października 2026 r. i usuwane 30 kwietnia 2027 r., zostały zastąpione w przykładach przez voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3orazvoxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasowe dotyczą tylko segmentów (wordzwraca błąd 400), diarization jest możliwa w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a dane wejściowecontext_bias` mają dowolny format (frazy ze spacjami). Źródła: Migrate from Voxtral 2 · Speech to Text.

Kompletny strumień asynchroniczny w Pythonie

Teraz napiszesz kompletny potok transkrypcji w czasie rzeczywistym, od pierwszego bajtu audio do finalnego pliku tekstowego. Wszystko opiera się na asyncio: program musi jednocześnie odczytywać audio i odbierać zdarzenia modelu, bez blokowania którejkolwiek z tych operacji. Standardowy kod synchroniczny po prostu by tu czekał, a opóźnienie, które tak starannie skonfigurowałeś, zniknęłoby w martwym czasie Twojego własnego programu.

Architektura programu strumieniowego

Niezależnie od aplikacji, struktura pozostaje taka sama i przebiega od lewej do prawej. Po stronie źródłowej mamy źródło audio: generator asynchroniczny produkujący fragmenty audio PCM. Dziś może to być plik, jutro mikrofon lub strumień sieciowy. W centrum znajduje się klient Voxtral, czyli SDK, które wysyła te fragmenty do modelu i zwraca Ci zdarzenia. Po stronie odbiorczej mamy przetwarzanie zdarzeń: Twoją logikę biznesową, która wyświetla tekst, gromadzi go, zapisuje lub przekazuje do innej usługi.

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

Taki podział ma praktyczną zaletę: źródło audio jest wymienne. Kod transkrypcji, który napiszesz poniżej, zadziała identycznie z generatorem mikrofonu z następnej lekcji, bez zmiany ani jednej linii.

Podstawowa implementacja

Dwa szczegóły w tym pierwszym programie zasługują na Twoją uwagę. Generator source_audio_fichier dzieli plik na bloki po 32 000 bajtów, co odpowiada dokładnie jednej sekundzie mono audio PCM 16-bitowego przy 16 kHz: 16 000 próbek pomnożone przez 2 bajty. Następujące po każdym yield wywołanie await asyncio.sleep symuluje czas rzeczywisty; zakomentuj tę linię i uruchom program na kilkuminutowym fragmencie, a zobaczysz, że plik zostanie zużyty w ułamku sekundy, co niczego Cię nie nauczy o zachowaniu strumieniowania. Po stronie odbiorczej zmienna texte_complet gromadzi fragmenty, dzięki czemu masz dostęp do pełnego tekstu na końcu, oprócz wyświetlania na żywo.

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):
    """Asynchroniczny generator odczytujący plik PCM fragmentami.

    taille_chunk = 32000 bajtów = 1 sekunda mono audio PCM 16-bitowego przy 16 kHz
    (16000 próbek × 2 bajty = 32000 bajtów)
    """
    with open(chemin, "rb") as f:
        while True:
            chunk = f.read(taille_chunk)
            if not chunk:
                break
            yield chunk
            # Symulacja czasu rzeczywistego (1 fragment = 1 sekunda)
            await asyncio.sleep(len(chunk) / 32000)

async def transcrire_realtime(source_audio):
    """Transkrybuje strumień audio w czasie rzeczywistym za pomocą 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--- Transkrypcja zakończona ---")

    return "".join(texte_complet)

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

    # Zapisz wynik
    with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
        f.write(texte)
    print(f"\nTekst zapisany ({len(texte)} znaków)")

asyncio.run(main())

Wyświetlanie na żywo opiera się na print(event.text, end="", flush=True). Bez flush=True Python buforuje wyjście i tekst pojawiałby się partiami: Twoja transkrypcja byłaby technicznie w czasie rzeczywistym, ale wizualnie skokowa.

Strukturyzacja przetwarzania dla środowiska produkcyjnego

Gdy Twoja aplikacja wykracza poza poziom demo, pętla if/elif staje się niewygodna: chcesz liczyć fragmenty, mierzyć czas trwania, podpiąć wyświetlacz lub zasilać bazę danych. Inkapsulacja logiki w klasie rozwiązuje ten problem raz na zawsze. Każdy typ zdarzenia otrzymuje własną, dedykowaną metodę, a Ty możesz dodawać zachowania – na przykład wysyłanie każdego delta do interfejsu webowego – bez dotykania pętli odbiorczej.

class GestionnaireTranscription:
    """Obsługuje zdarzenia transkrypcji w czasie rzeczywistym."""

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

    async def traiter(self, source_audio):
        """Rozpoczyna transkrypcję i przetwarza zdarzenia."""
        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):
        """Wywoływane dla każdego nowego fragmentu tekstu."""
        self.texte_complet.append(event.text)
        self.nb_deltas += 1
        # Wyświetlanie na żywo
        print(event.text, end="", flush=True)

    def _on_done(self, event):
        """Wywoływane na końcu transkrypcji."""
        import time
        duree = time.time() - self.debut
        print(f"\n\nZakończono w {duree:.1f}s")
        print(f"Otrzymane fragmenty: {self.nb_deltas}")

    def obtenir_resultat(self) -> str:
        """Zwraca pełny przetranskrybowany tekst."""
        return "".join(self.texte_complet)

async def main():
    gestionnaire = GestionnaireTranscription()
    source = source_audio_fichier("audio.pcm")
    texte = await gestionnaire.traiter(source)
    print(f"Wynik: {len(texte)} znaków")

asyncio.run(main())

Licznik nb_deltas to nie gimmick: w odniesieniu do czasu trwania audio wskazuje on szybkość emisji modelu i ostrzega Cię, jeśli strumień ulega degradacji.

Przetrwanie przerw w łączności sieciowej

Połączenie strumieniowe pozostaje otwarte przez cały czas trwania mowy, co naraża je znacznie bardziej niż kilkusekundowe żądanie offline. Migoczące Wi-Fi, przełączanie sieci w urządzeniu mobilnym lub awaria operatora mogą przerwać strumień. Poniższy wzorzec restartuje transkrypcję do trzech razy, z opóźnieniem rosnącym przy każdej próbie, aby dać sieci czas na regenerację. Powyżej tej liczby wyjątek jest propagowany: jawna awaria jest lepsza niż aplikacja, która zdaje się niczego nie słuchać.

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

MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2  # sekundy

async def transcrire_avec_retry(source_audio, tentative=1):
    """Transkrypcja z automatycznym ponownym łączeniem."""
    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[Zakończono]")

    except ConnectionError as e:
        if tentative < MAX_TENTATIVES:
            print(f"\nBłąd sieci (próba {tentative}/{MAX_TENTATIVES})")
            await asyncio.sleep(DELAI_RECONNEXION * tentative)
            await transcrire_avec_retry(source_audio, tentative + 1)
        else:
            print(f"\nNiepowodzenie po {MAX_TENTATIVES} próbach: {e}")
            raise

Przygotowanie istniejącego pliku

Aby przetestować rozwiązanie na posiadanych już plikach MP3 lub WAV, możesz zautomatyzować konwersję do PCM bezpośrednio z Pythona, zamiast uruchamiać ją ręcznie. Poniższa funkcja deleguje pracę do FFmpeg, wywnioskowuje nazwę wyjściową z nazwy wejściowej i zwraca wynikową ścieżkę, gotową do przekazania do source_audio_fichier.

import subprocess

def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Konwertuje plik audio do mono PCM 16-bitowego 16 kHz za pomocą 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życie
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Następnie użyj source_audio_fichier(chemin_pcm)

Dwie uwagi dotyczące tej funkcji. check=True zgłasza wyjątek, jeśli FFmpeg zawiedzie, co jest lepsze niż odkrycie później w strumieniu pustego pliku PCM; capture_output=True ukrywa wyjście narzędzia, więc długa konwersja sprawi, że program będzie wydawał się zawieszony. W przypadku nagrań trwających godziny zaplanuj wypisanie komunikatu przed i po wywołaniu.

Kluczowe wnioski

  • Strumieniowanie wykorzystuje generatory asynchroniczne (async for, yield)
  • Fragment 32 000 bajtów = 1 sekunda mono audio PCM 16-bitowego przy 16 kHz
  • W środowisku produkcyjnym strukturuj przetwarzanie zdarzeń w klasie
  • Zaimplementuj mechanizm ponawiania prób, aby obsługiwać błędy sieciowe
  • Użyj FFmpeg do konwersji istniejących plików audio do PCM
  • Wyświetlanie na żywo używa print(text, end="", flush=True)