Echtzeit-Transkription in Python implementieren
Auf dieser Seite
Kurs aktualisiert am 3. November 2026 für Voxtral 3, basierend auf Mistral’s Migrate from Voxtral 2-Guide: Voxtral 2-Modelle (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), am 31. Oktober 2026 veraltet und am 30. April 2027 eingestellt, werden in den Beispielen durchvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3undvoxtral-mini-tts-3-0ersetzt. Wesentliche Änderungen: Zeitstempel sind segmentbasiert (wordgibt einen 400-Fehler zurück), Sprechererkennung ist in Echtzeit möglich, Echtzeit-Sitzungseinstellungen werden nach dem ersten Audio-Chunk gesperrt, undcontext_bias-Eingaben sind frei formatiert (Phrasen mit Leerzeichen). Quellen: Migrate from Voxtral 2 · Speech to Text.
Der vollständige asynchrone Python-Stream
Sie werden nun einen vollständigen Pipeline für die Echtzeit-Transkription schreiben, vom ersten Audio-Byte bis zum fertigen Textdatei. Alles basiert auf asyncio: Das Programm muss Audio lesen und Modell-Ereignisse empfangen, ohne dass eine Operation die andere blockiert. Standard-Synchroner Code würde hier einfach warten, und die Latenz, die Sie sorgfältig konfiguriert haben, würde in der Totzeit Ihres Programms verschwinden.
Architektur des Streaming-Programms
Unabhängig von der Anwendung bleibt die Struktur gleich und wird von links nach rechts gelesen. Oben: eine Audio-Quelle: ein asynchroner Generator, der PCM-Audio-Blöcke erzeugt. Heute könnte es eine Datei sein, morgen ein Mikrofon oder ein Netzwerk-Stream. In der Mitte: der Voxtral-Client, also die SDK-Bibliothek, die diese Blöcke an das Modell sendet und Ereignisse an Sie weitergibt. Unten: Ereignisverarbeitung: Ihre Geschäftslogik, die den Text anzeigt, ihn akkumuliert, speichert oder an einen anderen Dienst weiterleitet.
Audio-Quelle → [PCM-Blöcke] → Mistral SDK → [Ereignisse] → Ihr Code
Diese Trennung hat einen praktischen Vorteil: Die Audio-Quelle ist austauschbar. Der Transkriptionscode, den Sie unten schreiben, wird identisch mit dem Mikrofon-Generator aus der nächsten Lektion funktionieren, ohne dass eine einzige Zeile geändert werden muss.
Grundlegende Implementierung
Zwei Details in diesem ersten Programm verdienen Ihre Aufmerksamkeit. Der Generator source_audio_fichier schneidet die Datei in Blöcke von 32.000 Bytes, was exakt einer Sekunde 16-Bit-Mono-PCM-Audio bei 16 kHz entspricht: 16.000 Samples multipliziert mit 2 Bytes. Das await asyncio.sleep nach jedem yield simuliert die Echtzeit; kommentieren Sie diese Zeile aus und führen Sie das Programm auf einem mehrminütigen Auszug aus, und Sie werden sehen, dass die Datei in einem Bruchteil einer Sekunde verbraucht wird, was Ihnen nichts über das Streaming-Verhalten lehrt. Auf der Empfangsseite akkumuliert texte_complet Fragmente, sodass Sie am Ende den vollständigen Text verfügbar haben, zusätzlich zur Live-Anzeige.
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):
"""Asynchroner Generator, der eine PCM-Datei in Blöcken liest.
taille_chunk = 32000 Bytes = 1 Sekunde 16-Bit-Mono-PCM-Audio bei 16kHz
(16000 Samples × 2 Bytes = 32000 Bytes)
"""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
# Simuliere Echtzeit (1 Chunk = 1 Sekunde)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transkribiert einen Audio-Stream in Echtzeit mit 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--- Transkription abgeschlossen ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Ergebnis speichern
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nText gespeichert ({len(texte)} Zeichen)")
asyncio.run(main())
Die Live-Anzeige beruht auf print(event.text, end="", flush=True). Ohne flush=True puffert Python die Ausgabe, und der Text würde in Batches erscheinen: Ihre Transkription wäre technisch in Echtzeit, aber visuell ruckelig.
Strukturierung der Verarbeitung für die Produktion
Sobald Ihre Anwendung über eine Demo hinausgeht, wird der if/elif-Schleife unhandlich: Sie möchten Fragmente zählen, Dauer messen, eine Anzeige anschließen oder eine Datenbank füttern. Das Einkapseln der Logik in eine Klasse löst das Problem endgültig. Jeder Ereignistyp erhält eine eigene dedizierte Methode, und Sie können Verhalten hinzufügen – zum Beispiel das Senden jedes Deltas an eine Web-Oberfläche –, ohne den Empfangsschleife zu berühren.
class GestionnaireTranscription:
"""Verwaltet Echtzeit-Transkriptionsereignisse."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Startet Transkription und verarbeitet Ereignisse."""
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):
"""Wird für jedes neue Textfragment aufgerufen."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Live-Anzeige
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Wird am Ende der Transkription aufgerufen."""
import time
duree = time.time() - self.debut
print(f"\n\nAbgeschlossen in {duree:.1f}s")
print(f"Empfangene Fragmente: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Gibt den vollständigen transkribierten Text zurück."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Ergebnis: {len(texte)} Zeichen")
asyncio.run(main())
Der Zähler nb_deltas ist kein Gimmick: Im Verhältnis zur Audiolaufzeit zeigt er die Emissionsrate des Modells an und warnt Sie, wenn der Stream verschlechtert.
Überleben von Netzwerkunterbrechungen
Eine Streaming-Verbindung bleibt für die gesamte Dauer der Sprache offen und ist damit weitaus exponierter als eine Offline-Anfrage von wenigen Sekunden. Ein flackerndes WLAN, ein Netzwerkschalter auf einem Mobilgerät oder ein Ausfall eines Betreibers können den Stream unterbrechen. Das Muster unten startet die Transkription bis zu dreimal neu, mit einer Verzögerung, die bei jedem Versuch zunimmt, um dem Netzwerk Zeit zur Erholung zu geben. Darüber hinaus wird die Ausnahme propagiert: Ein expliziter Fehler ist besser als eine Anwendung, die so aussieht, als würde sie nichts hören.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # Sekunden
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transkription mit automatischer Wiederverbindung."""
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[Abgeschlossen]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nNetzwerkfehler (Versuch {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nFehlgeschlagen nach {MAX_TENTATIVES} Versuchen: {e}")
raise
Vorbereitung einer bestehenden Datei
Um mit einer MP3- oder WAV-Datei zu testen, die Sie bereits vorrätig haben, können Sie die Konvertierung in PCM aus Python automatisieren, anstatt sie manuell auszuführen. Die Funktion unten delegiert die Arbeit an FFmpeg, leitet den Ausgabe-Namen aus dem Eingabename ab und gibt den resultierenden Pfad zurück, bereit, an source_audio_fichier übergeben zu werden.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Konvertiert eine Audio-Datei in 16-Bit 16kHz Mono PCM über 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
# Nutzung
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Dann source_audio_fichier(chemin_pcm) verwenden
Zwei Vorsichtsmaßnahmen bei dieser Funktion. check=True wirft eine Ausnahme, wenn FFmpeg fehlschlägt, was besser ist als die Entdeckung einer leeren PCM-Datei später im Stream; und capture_output=True verbirgt die Ausgabe des Tools, sodass eine lange Konvertierung das Programm eingefroren erscheinen lässt. Bei stundenlangen Aufnahmen planen Sie, eine Nachricht vor und nach dem Aufruf auszudrucken.
Kernaussagen
- Streaming verwendet asynchrone Generatoren (
async for,yield) - Ein 32.000-Byte-Chunk = 1 Sekunde 16-Bit-Mono-PCM-Audio bei 16 kHz
- Strukturieren Sie die Ereignisverarbeitung in einer Klasse für die Produktion
- Implementieren Sie einen Wiederherstellungsmechanismus, um Netzwerkfehler zu behandeln
- Verwenden Sie FFmpeg, um bestehende Audio-Dateien in PCM zu konvertieren
- Live-Anzeige verwendet
print(text, end="", flush=True)