Introduzione alla trascrizione in tempo reale
In questa pagina
Corso aggiornato il 3 novembre 2026 per Voxtral 3, basato sulla guida Migrate from Voxtral 2 di Mistral: i modelli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, deprecati il 31 ottobre 2026 e ritirati il 30 aprile 2027) sono sostituiti negli esempi davoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Cambiamenti chiave: i timestamp sono solo per segmento (wordrestituisce un errore 400), la diarizzazione è disponibile in tempo reale, le impostazioni della sessione in tempo reale sono bloccate dopo il primo chunk audio e gli inputcontext_biassono in formato libero (frasi con spazi). Fonti: Migrate from Voxtral 2 · Speech to Text.
Un nuovo paradigma: lo streaming audio
Finora hai lavorato in modalità offline: invii un file audio completo, attendi che il modello lo elabori e poi utilizzi il risultato. Questo flusso di lavoro è adatto alle registrazioni esistenti, come riunioni archiviate, podcast o interviste. Fallisce invece quando l’audio arriva in modo continuo: nessuno aspetterà la fine di una conferenza di due ore per vedere i primi sottotitoli, e un assistente vocale che comprende una domanda solo dopo un lungo silenzio sembra rotto.
Voxtral Realtime risponde a questa esigenza con un’architettura streaming. L’audio viene trascritto al volo, parola per parola, e il ritardo tra suono e testo diventa un’impostazione che puoi controllare, scendendo fino a 200 millisecondi. Il cambiamento è tanto mentale quanto tecnico: non pensi più in termini di richieste isolate ma di flussi, e il tuo programma deve essere pronto a ricevere testo in qualsiasi momento.
Cosa offre il modello Realtime
Il modello viene invocato con l’identificativo voxtral-mini-transcribe-realtime-3 e differisce fondamentalmente dalla sua controparte offline. Riceve chunk audio ed emette frammenti di testo in modo continuo, senza mai attendere la fine della registrazione. La sua latenza è controllata dal parametro target_streaming_delay_ms, che esplorerai in dettaglio più avanti in questo corso. Copre 45 lingue e dialetti, e la lingua può essere fissata o rilevata automaticamente. Il suo predecessore di Generazione 2, voxtral-mini-transcribe-realtime-2602 (4 miliardi di parametri), è pubblicato come open weights sotto licenza Apache 2.0 su Hugging Face Hub per un’installazione completamente sovrana sui tuoi server.
Con Voxtral 3, le prestazioni in tempo reale hanno colmato in gran parte il divario con la modalità offline. La diarizzazione è disponibile, sebbene non nella stessa sessione del rilevamento della fine del turno, così come il context biasing e il rilevamento della fine del turno. Restano due differenze: i segmenti portano l’etichetta dell’oratore ma non l’orario di inizio o fine, e tutte le impostazioni della sessione (lingua, vocabolario, diarizzazione, ritardo) devono essere inviate prima del primo chunk audio, dopodiché sono bloccate. Se il tuo caso d’uso richiede timestamp precisi, hai bisogno della modalità offline, eventualmente come complemento al tempo reale.
Installazione
L’SDK di Mistral non carica le dipendenze per lo streaming per impostazione predefinita. Devi richiedere esplicitamente l’extra realtime, che aggiunge il supporto per le connessioni WebSocket e l’elaborazione asincrona dell’audio:
pip install "mistralai[realtime]"
Il formato audio richiesto
A differenza della modalità offline, che accetta un’ampia gamma di container, Voxtral Realtime si aspetta uno stream grezzo in un unico formato non negoziabile:
- Codifica: PCM signed a 16 bit little-endian (
pcm_s16le) - Frequenza di campionamento: 16.000 Hz (16 kHz)
- Canali: Mono (1 canale)
Questo vincolo non è un ostacolo: questo formato è il più standard disponibile e tutti gli strumenti di acquisizione lo producono nativamente, che si tratti di PyAudio, FFmpeg o PulseAudio. Lo dichiari una volta al client, che lo utilizza per interpretare i byte che trasmetti.
from mistralai.client.models import AudioFormat
# Definisci il formato audio
audio_format = AudioFormat(
encoding="pcm_s16le",
sample_rate=16000
)
I due eventi dello stream
Quando iteri sulla trascrizione, l’SDK restituisce due tipi di oggetti. TranscriptionStreamTextDelta viene emesso per ogni nuovo frammento trascritto e contiene il testo parziale che puoi visualizzare immediatamente; è ciò che alimenta lo schermo dell’utente. TranscriptionStreamDone arriva esattamente una volta, quando lo stream audio termina, sia alla fine di un file che alla chiusura del microfono; segnala che non arriverà nient’altro e che puoi consolidare il risultato. Tutta la tua logica rientra quindi in un ciclo asincrono che distingue questi due casi:
from mistralai.client.models import (
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
async for event in flux_transcription:
if isinstance(event, TranscriptionStreamTextDelta):
# Nuovo testo disponibile
print(event.text, end="", flush=True)
elif isinstance(event, TranscriptionStreamDone):
# Trascrizione terminata
print("\n[Finished]")
Primo esempio completo
Per prendere confidenza con il meccanismo senza affidarti a un microfono, l’approccio più semplice è simulare uno stream a partire da un file già convertito in PCM. La funzione lire_fichier_pcm è un generatore asincrono: legge il file a blocchi e li restituisce uno per uno, esattamente come farebbe una scheda audio. Il resto del programma è ciò che riutilizzerai in seguito senza modifiche.
import asyncio
import os
from mistralai.client import Mistral
from mistralai.client.models import (
AudioFormat,
TranscriptionStreamTextDelta,
TranscriptionStreamDone
)
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
audio_format = AudioFormat(encoding="pcm_s16le", sample_rate=16000)
async def lire_fichier_pcm(chemin: str, taille_chunk: int = 32000):
"""Legge un file PCM a chunk per simulare uno stream."""
with open(chemin, "rb") as f:
while True:
chunk = f.read(taille_chunk)
if not chunk:
break
yield chunk
async def main():
flux_audio = lire_fichier_pcm("audio.pcm")
async for event in client.audio.realtime.transcribe_stream(
audio_stream=flux_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\nTrascrizione terminata.")
asyncio.run(main())
Se il tuo file sorgente è un MP3, non può essere inviato così com’è: convertilo prima con FFmpeg, imponendo le tre caratteristiche richieste dal modello.
ffmpeg -i audio.mp3 -f s16le -acodec pcm_s16le -ar 16000 -ac 1 audio.pcm
Quando passare al tempo reale
Il criterio di selezione è semplice: il tempo reale è giustificato quando qualcuno attende il testo mentre il suono viene prodotto. Questo vale per i sottotitoli in diretta per una conferenza, un webinar o un corso online, dove il pubblico legge mentre ascolta; per un assistente vocale, che deve comprendere l’utente mentre parla per rispondere senza pause imbarazzanti; per la dettatura, dove il discorso diventa testo sotto gli occhi di chi parla; e infine per la trascrizione di conferenze, quando il testo deve apparire mentre viene pronunciato. Ovunque altrove, la modalità offline rimane più ricca e semplice da implementare.
Le prossime lezioni ti mostreranno come acquisire il microfono, ottimizzare la latenza e costruire questi casi d’uso dall’inizio alla fine.
Punti chiave
- Voxtral Mini Transcribe Realtime 3 trascrive l’audio in modalità streaming con un ritardo regolabile da 80 ms a 1,2 s (o 2,4 s)
- Formato audio richiesto: PCM a 16 bit, 16 kHz, mono
- Due tipi di eventi:
TextDelta(testo parziale) eDone(fine) - Installa con
pip install "mistralai[realtime]" - Programmazione asincrona richiesta (
async/await) - Diarizzazione (escluso il rilevamento della fine del turno) e context biasing disponibili in tempo reale, senza timestamp di segmento; impostazioni bloccate dopo il primo chunk audio
- La Generazione 2 del modello realtime è open weights Apache 2.0, per un deployment sovrano