Ottimizzazione per la produzione
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 in tempo reale è supportata, le impostazioni di 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.
Dal prototipo al servizio affidabile
Sai come trascrivere audio, sia in modo asincrono che in tempo reale. Gestire un servizio che elabora centinaia di file al giorno senza supervisione umana è un esercizio completamente diverso, perché si scontra con ciò che un prototipo non vede mai: un file corrotto, una quota superata, una caduta di rete a metà upload o un picco di volume che attiva il rate limiting. Questa lezione affronta questi casi uno per uno: gestione degli errori, elaborazione in batch, preparazione dei file e osservabilità.
Gestione degli errori: distinguere tra recuperabili e fatali
La prima regola è non trattare tutti gli errori allo stesso modo. Una caduta di rete, un timeout o un’interruzione temporanea meritano un retry; un file illeggibile o una chiave API invalida non si risolveranno mai da sole, e ritentarle spreca solo tempo e inquina i log. Il wrapper sottostante implementa questa distinzione con una tupla di eccezioni temporanee: qualsiasi cosa in ERREURS_TEMPORAIRES attiva un retry, mentre tutto il resto fallisce immediatamente. In entrambi i casi, la funzione restituisce un dizionario invece di sollevare un’eccezione, permettendo all’elaborazione in batch di continuare con i file rimanenti.
import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral
logger = logging.getLogger("voxtral")
# Eccezioni da ritentare
ERREURS_TEMPORAIRES = (
ConnectionError,
TimeoutError,
OSError,
)
def transcrire_avec_retry(
chemin_audio: str,
max_tentatives: int = 3,
delai_base: float = 2.0,
**kwargs
) -> dict:
"""Trascrive un file con retry esponenziale."""
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
fichier = Path(chemin_audio)
for tentative in range(1, max_tentatives + 1):
try:
with open(chemin_audio, "rb") as f:
response = client.audio.transcriptions.complete(
model=kwargs.get("model", "voxtral-mini-transcribe-3"),
file={"content": f, "file_name": fichier.name},
**{k: v for k, v in kwargs.items() if k != "model"}
)
return {
"succes": True,
"texte": response.text,
"fichier": chemin_audio,
"tentative": tentative,
}
except ERREURS_TEMPORAIRES as e:
if tentative < max_tentatives:
delai = delai_base * (2 ** (tentative - 1))
logger.warning(
f"Tentative {tentative}/{max_tentatives} échouée "
f"pour {fichier.name} : {e}. "
f"Retry dans {delai:.0f}s"
)
time.sleep(delai)
else:
logger.error(
f"Échec définitif pour {fichier.name} "
f"après {max_tentatives} tentatives : {e}"
)
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
except Exception as e:
# Errore non recuperabile (file invalido, auth, ecc.)
logger.error(f"Erreur fatale pour {fichier.name} : {e}")
return {
"succes": False,
"erreur": str(e),
"fichier": chemin_audio,
"tentative": tentative,
}
Il ritardo tra i tentativi raddoppia ad ogni fallimento—due secondi, poi quattro, poi otto—per evitare di martellare un’API che sta già faticando. Tuttavia, questo backoff esponenziale ha un difetto quando hai molti client: se falliscono tutti nello stesso istante, ritenteranno tutti nello stesso istante, e l’ondata colpirà il servizio tutta insieme. Risolviamo questo problema con il jitter, una variazione casuale aggiunta al ritardo, sufficiente a desincronizzare i tentativi.
import random
delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)
Elaborare un batch di file senza supervisione
Trascrivere duecento registrazioni una dopo l’altra è uno spreco: la maggior parte del tempo viene spesa ad aspettare la rete. Un pool di worker gestisce più trascrizioni contemporaneamente senza perdere traccia dei progressi. La funzione sottostante scansiona una cartella, mantiene le estensioni audio note, invia ogni file al wrapper di retry definito sopra e scrive la trascrizione non appena arriva, invece che alla fine: se il processo crasha a metà strada, ciò che è stato elaborato è già su disco. Un report JSON riassume successi e fallimenti, permettendoti di riavviare solo ciò che è fallito.
import os
import json
import logging
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor, as_completed
logger = logging.getLogger("voxtral-batch")
def traiter_batch(
dossier_audio: str,
dossier_sortie: str,
max_workers: int = 4,
**kwargs_transcription
):
"""Trascrive tutti i file audio in una cartella in parallelo."""
dossier = Path(dossier_audio)
sortie = Path(dossier_sortie)
sortie.mkdir(parents=True, exist_ok=True)
# Trova tutti i file audio
extensions = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
fichiers = [
f for f in dossier.iterdir()
if f.suffix.lower() in extensions
]
if not fichiers:
logger.warning(f"Aucun fichier audio dans {dossier_audio}")
return []
logger.info(f"Traitement de {len(fichiers)} fichiers avec {max_workers} workers")
resultats = []
with ThreadPoolExecutor(max_workers=max_workers) as pool:
futures = {
pool.submit(
transcrire_avec_retry,
str(f),
**kwargs_transcription
): f
for f in fichiers
}
for i, future in enumerate(as_completed(futures), 1):
fichier = futures[future]
resultat = future.result()
resultats.append(resultat)
status = "OK" if resultat["succes"] else "ERREUR"
logger.info(
f"[{i}/{len(fichiers)}] {status} — {fichier.name}"
)
# Salva la trascrizione
if resultat["succes"]:
nom_sortie = fichier.stem + ".txt"
(sortie / nom_sortie).write_text(
resultat["texte"], encoding="utf-8"
)
# Report finale
succes = sum(1 for r in resultats if r["succes"])
echecs = len(resultats) - succes
logger.info(f"Terminé : {succes} succès, {echecs} échecs")
# Salva il report
rapport_path = sortie / "rapport_batch.json"
with open(rapport_path, "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
return resultats
# Utilizzo
resultats = traiter_batch(
dossier_audio="enregistrements/",
dossier_sortie="transcriptions/",
max_workers=4,
diarize=True,
timestamp_granularities=["segment"]
)
Non cedere alla tentazione di aumentare max_workers per andare più veloce. Le API di Mistral impongono limiti alle richieste al minuto e quattro worker di solito ti mantengono sotto quella soglia. Se negli log compaiono errori 429 (Too Many Requests), la risposta non è ritentare più duramente, ma ridurre il numero di worker o introdurre un ritardo tra le richieste.
Preparare l’audio a monte
Il formato dei file che invii influenza sia il tempo di upload che la qualità del testo risultante. Se la fedeltà è fondamentale, attieniti a WAV o FLAC, formati lossless: il modello riceve tutte le informazioni audio. Per l’uso comune, MP3 a 128 kbps o superiore offre il miglior compromesso, con una qualità più che sufficiente per la trascrizione e una dimensione del file ragionevole. E quando la banda è il vincolo dominante, OGG Vorbis o MP3 a 64 kbps rimangono perfettamente accettabili per la voce, che è molto diversa dalla musica in questo senso.
Invece di accettare qualsiasi formato arrivi, normalizzali prima dell’invio. La funzione sottostante applica quattro trasformazioni: conversione in mono, poiché lo stereo non aggiunge nulla alla trascrizione; ricampionamento a 16 kHz, la frequenza nativa di Voxtral; bitrate impostato a 64 kbps, sufficiente per la voce; e loudnorm, che equalizza il volume.
import subprocess
def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
"""Prepara un file audio per una trascrizione ottimale."""
if chemin_sortie is None:
chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"
subprocess.run([
"ffmpeg", "-y",
"-i", chemin_entree,
"-ac", "1", # Mono (lo stereo non aiuta la trascrizione)
"-ar", "16000", # 16 kHz (frequenza nativa Voxtral)
"-b:a", "64k", # 64 kbps (sufficiente per la voce)
"-af", "loudnorm", # Normalizzazione del volume
chemin_sortie
], check=True, capture_output=True)
return chemin_sortie
Il guadagno è duplice: convertire in mono 16 kHz 64 kbps riduce significativamente le dimensioni dei file senza degradare la trascrizione, e loudnorm migliora nettamente i risultati su registrazioni con volume irregolare, tipicamente una riunione dove un partecipante è lontano dal microfono.
Sapere cosa sta succedendo
Un servizio di trascrizione senza strumentazione è una scatola nera: il giorno in cui i tempi di elaborazione raddoppiano, lo scoprirai da un utente infelice. Raccogli la dimensione del file, la durata dell’elaborazione, il numero di tentativi e il volume di testo prodotto per ogni chiamata, poi scrivi tutto come JSON su una singola riga, un formato direttamente utilizzabile da un aggregatore di log.
import time
import logging
import json
from datetime import datetime
logger = logging.getLogger("voxtral-prod")
def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
"""Trascrive con raccolta di metriche."""
debut = time.time()
taille_fichier = Path(chemin_audio).stat().st_size
resultat = transcrire_avec_retry(chemin_audio, **kwargs)
duree_traitement = time.time() - debut
metriques = {
"timestamp": datetime.now().isoformat(),
"fichier": chemin_audio,
"taille_octets": taille_fichier,
"duree_traitement_s": round(duree_traitement, 2),
"succes": resultat["succes"],
"tentatives": resultat["tentative"],
}
if resultat["succes"]:
metriques["nb_caracteres"] = len(resultat["texte"])
metriques["nb_mots"] = len(resultat["texte"].split())
ratio = taille_fichier / duree_traitement / 1024
metriques["debit_ko_par_s"] = round(ratio, 1)
# Log strutturato (JSON)
logger.info(json.dumps(metriques, ensure_ascii=False))
return resultat
Checklist per la produzione
Prima di aprire il tuo servizio al primo utente reale, rivedi questi sette punti:
| Dominio | Controllo |
|---|---|
| Gestione errori | Retry con backoff esponenziale per errori temporanei |
| Rate limiting | Rispetta i limiti API, implementa throttling se necessario |
| Monitoraggio | Log strutturati, metriche di performance, alert sugli errori |
| Sicurezza | Chiave API in variabile d’ambiente, mai hardcoded nel codice |
| Archiviazione | Salva le trascrizioni in modo durevole, non solo in memoria |
| Formato audio | Normalizza i file a monte (mono, 16 kHz) |
| Testing | File vari: lingue, durate, qualità audio, numero di speaker |
L’ultima riga è quella più spesso trascurata e la più costosa. Tre registrazioni pulite in francese non ti insegneranno nulla sul comportamento reale del tuo servizio: costruisci un campione deliberatamente difficile e scoprirai le impostazioni da aggiustare mentre c’è ancora tempo.
Punti chiave
- Implementa retry con backoff esponenziale e jitter per errori temporanei
- Usa un pool di worker per l’elaborazione in batch (4 worker sono un buon punto di partenza)
- Normalizza i tuoi file in mono 16 kHz con FFmpeg per risultati ottimali
- Raccogli metriche strutturate per il monitoraggio in produzione
- Rispetta i limiti di rate limiting delle API Mistral
- Salva sistematicamente le trascrizioni e i report dei batch