Implementer realtids-transskription i Python
På denne side
Kurset opdateret 3. november 2026 til Voxtral 3, baseret på Mistrals guide Migrate from Voxtral 2: Voxtral 2-modellerne (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), der blev udfaset 31. oktober 2026 og trukket tilbage 30. april 2027, erstattes i eksemplerne afvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3ogvoxtral-mini-tts-3-0. Vigtige ændringer: Tidsstempler er kun tilgængelige på segmentniveau (wordreturnerer en 400-fejl), diarisering er mulig i realtid, indstillinger for realtidssessioner låses efter den første lydbid, ogcontext_bias-input er frit formaterede (sætninger med mellemrum). Kilder: Migrate from Voxtral 2 · Speech to Text.
Den komplette Python-async-strøm
Nu skal du skrive en komplet pipeline til realtids-transskription, fra den første lydbyte til den endelige tekstfil. Alt hviler på asyncio: programmet skal læse lyd og modtage modelbegivenheder samtidigt, uden at nogen af operationerne blokerer hinanden. Almindelig synkron kode ville blot vente her, og den latens, du omhyggeligt har konfigureret, ville forsvinde ind i dit programs døde tid.
Arkitektur for streaming-programmer
Uanset applikationen forbliver strukturen den samme og læses fra venstre mod højre. Opstrøms har du en lydkilde: en asynkron generator, der producerer PCM-lydbider. I dag kan det være en fil, i morgen en mikrofon eller en netværksstrøm. I midten finder du Voxtral-klienten, altså SDK’et, som skubber disse bidder til modellen og returnerer begivenheder til dig. Nedstrøms har du begivenhedsbehandling: din forretningslogik, der viser teksten, akkumulerer den, gemmer den eller videresender den til en anden tjeneste.
Lydkilde → [PCM-bider] → Mistral SDK → [begivenheder] → Din kode
Denne opdeling har en praktisk fordel: lydkilden er udskiftelig. Den transskriptionskode, du skriver nedenfor, vil fungere identisk med mikrofon-generatoren fra næste lektion uden at ændre en eneste linje.
Grundlæggende implementering
To detaljer i dette første program fortjener din opmærksomhed. Generatoren source_audio_fichier opdeler filen i blokke på 32.000 bytes, hvilket svarer præcis til ét sekund 16-bit mono PCM-lyd ved 16 kHz: 16.000 samples ganget med 2 bytes. await asyncio.sleep efter hvert yield simulerer realtid; kommentér denne linje ud og kør programmet på et uddrag på få minutter, så vil du se, at filen bliver brugt op på en brøkdel af et sekund, hvilket ikke lærer dig noget om streaming-adfærd. På modtagersiden akkumulerer texte_complet fragmenter, så du har hele teksten tilgængelig til sidst, udover live-visningen.
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):
"""Asynkron generator der læser en PCM-fil i bidder.
taille_chunk = 32000 bytes = 1 sekund 16-bit mono PCM-lyd ved 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
# Simuler realtid (1 bid = 1 sekund)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transskriberer en lydstrøm i realtid med 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--- Transskription afsluttet ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Gem resultatet
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nTekst gemt ({len(texte)} tegn)")
asyncio.run(main())
Live-visningen afhænger af print(event.text, end="", flush=True). Uden flush=True bufferer Python outputtet, og teksten ville vises i portioner: din transskription ville være teknisk set i realtid, men visuelt hakket.
Strukturering af behandling til produktion
Når din applikation bevæger sig ud over en demo, bliver if/elif-løkken besværlig: du vil tælle fragmenter, måle varighed, tilslutte et display eller mate en database. Ved at kapsle logikken i en klasse løser du problemet én gang for alle. Hver begivenhedstype får sin egen dedikerede metode, og du kan tilføje adfærd – for eksempel at sende hver delta til et webinterface – uden at røre ved modtagelsesløkken.
class GestionnaireTranscription:
"""Håndterer begivenheder fra realtids-transskription."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Starter transskription og behandler begivenheder."""
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):
"""Kaldes for hvert nyt tekstfragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Live-visning
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Kaldes ved afslutning af transskription."""
import time
duree = time.time() - self.debut
print(f"\n\nAfsluttet på {duree:.1f}s")
print(f"Modtagne fragmenter: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Returnerer den fulde transskriberede tekst."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Resultat: {len(texte)} tegn")
asyncio.run(main())
Tælleren nb_deltas er ikke bare pynt: i forhold til lydens varighed indikerer den modellens udsendelseshastighed og advarer dig, hvis strømmen forringes.
Overlevelse af netværksafbrydelser
En streaming-forbindelse holdes åben i hele talevarigheden, hvilket udsætter den langt mere end en offline-anmodning på få sekunder. Et ustabil Wi-Fi, et netværksskift på en mobilenhed eller et operatørudfald kan afbryde strømmen. Mønsteret nedenfor genstarter transskriptionen op til tre gange med en forsinkelse, der øges for hvert forsøg for at give netværket tid til at komme sig. Derefter propageres undtagelsen: en eksplicit fejl er bedre end en applikation, der ser ud til at lytte til ingenting.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # sekunder
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transskription med automatisk genforbindelse."""
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[Afsluttet]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nNetværksfejl (forsøg {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nMislykkedes efter {MAX_TENTATIVES} forsøg: {e}")
raise
Forberedelse af en eksisterende fil
For at teste med en MP3- eller WAV-fil, du allerede har ved hånden, kan du automatisere konverteringen til PCM fra Python i stedet for at køre den manuelt. Funktionen nedenfor delegerer arbejdet til FFmpeg, udleder output-navnet fra input-navnet og returnerer den resulterende sti, klar til at blive sendt til source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Konverterer en lydfil til 16-bit 16kHz mono PCM via 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
# Brug
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Brug derefter source_audio_fichier(chemin_pcm)
To forholdsregler med denne funktion. check=True udløser en undtagelse, hvis FFmpeg fejler, hvilket er bedre end senere i strømmen at opdage en tom PCM-fil; og capture_output=True skjuler værktøjets output, så en lang konvertering ikke får programmet til at se ud, som om det er frosset. For optagelser på timevis bør du planlægge at udskrive en besked før og efter kaldet.
Vigtige pointer
- Streaming bruger asynkrone generatorer (
async for,yield) - En bid på 32.000 bytes = 1 sekund 16-bit mono PCM-lyd ved 16 kHz
- Strukturér begivenhedsbehandling i en klasse til produktion
- Implementér en genforsøgsmekanisme til håndtering af netværksfejl
- Brug FFmpeg til at konvertere eksisterende lydfiler til PCM
- Live-visning bruger
print(text, end="", flush=True)