Υλοποίηση Απομαγνητοφώνησης σε Πραγματικό Χρόνο με Python
Σε αυτήν τη σελίδα
Το μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 για το Voxtral 3, βάσει του οδηγού Migrate from Voxtral 2 της Mistral: Τα μοντέλα Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), που αποσύρθηκαν στις 31 Οκτωβρίου 2026 και θα απενεργοποιηθούν οριστικά στις 30 Απριλίου 2027, αντικαθίστανται στα παραδείγματα από ταvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3καιvoxtral-mini-tts-3-0. Βασικές αλλαγές: οι χρονοσημάνσεις αφορούν μόνο τμήματα (wordεπιστρέφει σφάλμα 400), η διάκριση ομιλητών (diarization) είναι δυνατή σε πραγματικό χρόνο, οι ρυθμίσεις συνεδρίας πραγματικού χρόνου κλειδώνουν μετά το πρώτο κομμάτι ήχου και οι είσοδοιcontext_biasείναι ελεύθερης μορφής (φράσεις με κενά). Πηγές: Migrate from Voxtral 2 · Speech to Text.
Η Πλήρης Ροή Async σε Python
Πρόκειται να γράψετε έναν πλήρη αγωγό απομαγνητοφώνησης σε πραγματικό χρόνο, από το πρώτο byte ήχου έως το τελικό αρχείο κειμένου. Όλα βασίζονται στο asyncio: το πρόγραμμα πρέπει να διαβάζει ήχο και να λαμβάνει συμβάντα από το μοντέλο ταυτόχρονα, χωρίς η μία λειτουργία να μπλοκάρει την άλλη. Ο τυπικός συγχρονικός κώδικας θα περίμενε απλώς εδώ, και η καθυστέρηση που διαμορφώσατε με προσοχή θα εξαφανιζόταν στον νεκρό χρόνο του ίδιου του προγράμματός σας.
Αρχιτεκτονική Προγράμματος Streaming
Ανεξάρτητα από την εφαρμογή, η δομή παραμένει η ίδια και διαβάζεται από αριστερά προς τα δεξιά. Ανηφορικά, μια πηγή ήχου: ένας ασύγχρονος γεννήτορας που παράγει κομμάτια ήχου PCM. Σήμερα μπορεί να είναι ένα αρχείο, αύριο ένα μικρόφωνο ή μια ροή δικτύου. Στο κέντρο, ο πελάτης Voxtral, δηλαδή το SDK, το οποίο ωθεί αυτά τα κομμάτια στο μοντέλο και σας παραδίδει συμβάντα. Κατηφορικά, επεξεργασία συμβάντων: η επιχειρηματική σας λογική, η οποία εμφανίζει το κείμενο, το συσσωρεύει, το αποθηκεύει ή το προωθεί σε άλλη υπηρεσία.
Audio Source → [PCM chunks] → Mistral SDK → [events] → Your Code
Αυτός ο διαχωρισμός έχει ένα πρακτικό όφελος: η πηγή ήχου είναι εναλλάξιμη. Ο κώδικας απομαγνητοφώνησης που γράφετε παρακάτω θα λειτουργήσει πανομοιότυπα με τον γεννήτορα μικροφώνου του επόμενου μαθήματος, χωρίς να αλλάξετε ούτε μία γραμμή.
Βασική Υλοποίηση
Δύο λεπτομέρειες σε αυτό το πρώτο πρόγραμμα αξίζουν την προσοχή σας. Ο γεννήτορας source_audio_fichier τεμαχίζει το αρχείο σε μπλοκ των 32.000 byte, κάτι που αντιστοιχεί ακριβώς σε ένα δευτερόλεπτο μονοφωνικού ήχου PCM 16-bit στα 16 kHz: 16.000 δείγματα πολλαπλασιασμένα επί 2 byte. Το await asyncio.sleep που ακολουθεί κάθε yield προσομοιώνει τον πραγματικό χρόνο· σχολιάστε αυτή τη γραμμή και εκτελέστε το πρόγραμμα σε ένα απόσπασμα λίγων λεπτών, και θα δείτε το αρχείο να καταναλώνεται σε κλάσμα του δευτερολέπτου, χωρίς να σας διδάσκει τίποτα για τη συμπεριφορά του streaming. Στην πλευρά λήψης, το texte_complet συσσωρεύει θραύσματα ώστε να έχετε διαθέσιμο το πλήρες κείμενο στο τέλος, επιπλέον της ζωντανής εμφάνισης.
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):
"""Asynchronous generator that reads a PCM file in chunks.
taille_chunk = 32000 bytes = 1 second of 16-bit mono PCM audio at 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
# Simulate real time (1 chunk = 1 second)
await asyncio.sleep(len(chunk) / 32000)
async def transcrire_realtime(source_audio):
"""Transcribes an audio stream in real time with 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--- Transcription finished ---")
return "".join(texte_complet)
async def main():
source = source_audio_fichier("audio.pcm")
texte = await transcrire_realtime(source)
# Save the result
with open("transcription_realtime.txt", "w", encoding="utf-8") as f:
f.write(texte)
print(f"\nText saved ({len(texte)} characters)")
asyncio.run(main())
Η ζωντανή εμφάνιση βασίζεται στο print(event.text, end="", flush=True). Χωρίς το flush=True, η Pythonbuffererώνει την έξοδο και το κείμενο θα εμφανιζόταν κατά παρτίδες: η απομαγνητοφώνησή σας θα ήταν τεχνικά σε πραγματικό χρόνο, αλλά οπτικά θα έτρεμε.
Δομή Επεξεργασίας για Παραγωγή
Μόλις η εφαρμογή σας ξεπεράσει το στάδιο της επίδειξης, ο βρόχος if/elif γίνεται δυσκίνητος: θέλετε να μετρήσετε θραύσματα, να μετρήσετε τη διάρκεια, να συνδέσετε μια οθόνη ή να τροφοδοτήσετε μια βάση δεδομένων. Η ενθυλάκωση της λογικής σε μια κλάση λύνει το πρόβλημα οριστικά. Κάθε τύπος συμβάντος αποκτά τη δική του αφιερωμένη μέθοδο και μπορείτε να προσθέσετε συμπεριφορά—για παράδειγμα, αποστολή κάθε delta σε μια διαδικτυακή διεπαφή—χωρίς να αγγίξετε τον βρόχο λήψης.
class GestionnaireTranscription:
"""Handles real-time transcription events."""
def __init__(self):
self.texte_complet = []
self.nb_deltas = 0
self.debut = None
async def traiter(self, source_audio):
"""Starts transcription and processes events."""
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):
"""Called for each new text fragment."""
self.texte_complet.append(event.text)
self.nb_deltas += 1
# Live display
print(event.text, end="", flush=True)
def _on_done(self, event):
"""Called at the end of transcription."""
import time
duree = time.time() - self.debut
print(f"\n\nFinished in {duree:.1f}s")
print(f"Fragments received: {self.nb_deltas}")
def obtenir_resultat(self) -> str:
"""Returns the full transcribed text."""
return "".join(self.texte_complet)
async def main():
gestionnaire = GestionnaireTranscription()
source = source_audio_fichier("audio.pcm")
texte = await gestionnaire.traiter(source)
print(f"Result: {len(texte)} characters")
asyncio.run(main())
Ο μετρητής nb_deltas δεν είναι φιγούρα: σε σχέση με τη διάρκεια του ήχου, υποδεικνύει τον ρυθμό εκπομπής του μοντέλου και σας ειδοποιεί εάν η ροή υποβαθμίζεται.
Αντιμετώπιση Διακοπών Δικτύου
Μια σύνδεση streaming παραμένει ανοιχτή για όλη τη διάρκεια της ομιλίας, εκθέτοντάς την πολύ περισσότερο από ένα αίτημα offline λίγων δευτερολέπτων. Ένα ασταθές Wi-Fi, μια εναλλαγή δικτύου σε μια κινητή συσκευή ή μια διακοπή παρόχου μπορούν να διακόψουν τη ροή. Το παρακάτω μοτίβο επανεκκινεί την απομαγνητοφώνηση έως και τρεις φορές, με καθυστέρηση που αυξάνεται σε κάθε προσπάθεια για να δοθεί χρόνος στο δίκτυο να ανακάμψει. Πέρα από αυτό, η εξαίρεση προωθείται: μια ρητή αποτυχία είναι προτιμότερη από μια εφαρμογή που φαίνεται να μην ακούει τίποτα.
import asyncio
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
MAX_TENTATIVES = 3
DELAI_RECONNEXION = 2 # seconds
async def transcrire_avec_retry(source_audio, tentative=1):
"""Transcription with automatic reconnection."""
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[Finished]")
except ConnectionError as e:
if tentative < MAX_TENTATIVES:
print(f"\nNetwork error (attempt {tentative}/{MAX_TENTATIVES})")
await asyncio.sleep(DELAI_RECONNEXION * tentative)
await transcrire_avec_retry(source_audio, tentative + 1)
else:
print(f"\nFailed after {MAX_TENTATIVES} attempts: {e}")
raise
Προετοιμασία Υπάρχοντος Αρχείου
Για να κάνετε δοκιμές με ένα αρχείο MP3 ή WAV που έχετε ήδη στη διάθεσή σας, μπορείτε να αυτοματοποιήσετε τη μετατροπή σε PCM από την Python αντί να την εκτελείτε χειροκίνητα. Η παρακάτω συνάρτηση αναθέτει την εργασία στο FFmpeg, εξάγει το όνομα εξόδου από το όνομα εισόδου και επιστρέφει την προκύπτουσα διαδρομή, έτοιμη να περαστεί στο source_audio_fichier.
import subprocess
def convertir_en_pcm(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Converts an audio file to 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
# Usage
chemin_pcm = convertir_en_pcm("reunion.mp3")
# Then use source_audio_fichier(chemin_pcm)
Δύο προφυλάξεις με αυτή τη συνάρτηση. Το check=True εγείρει εξαίρεση εάν το FFmpeg αποτύχει, κάτι που είναι προτιμότερο από το να ανακαλύψετε αργότερα στη ροή ένα κενό αρχείο PCM· και το capture_output=True κρύβει την έξοδο του εργαλείου, ώστε μια μακρά μετατροπή να μην κάνει το πρόγραμμα να φαίνεται παγωμένο. Για ηχογραφήσεις διάρκειας ωρών, προβλέψτε την εκτύπωση ενός μηνύματος πριν και μετά την κλήση.
Βασικά σημεία
- Το streaming χρησιμοποιεί ασύγχρονους γεννήτορες (
async for,yield) - Ένα κομμάτι 32.000 byte = 1 δευτερόλεπτο μονοφωνικού ήχου PCM 16-bit στα 16 kHz
- Δομήστε την επεξεργασία συμβάντων σε μια κλάση για παραγωγή
- Υλοποιήστε έναν μηχανισμό επαναπροσπάθειας για τη διαχείριση σφαλμάτων δικτύου
- Χρησιμοποιήστε το FFmpeg για τη μετατροπή υπαρχόντων αρχείων ήχου σε PCM
- Η ζωντανή εμφάνιση χρησιμοποιεί το
print(text, end="", flush=True)