Implementacja transkrypcji w czasie rzeczywistym w Pythonie
Na tej stronie
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 przezvoxtral-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)