Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ottimizzazione per la produzione

Lezione 15 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Dal prototipo al servizio affidabile
  2. Gestione degli errori: distinguere tra recuperabili e fatali
  3. Elaborare un batch di file senza supervisione
  4. Preparare l’audio a monte
  5. Sapere cosa sta succedendo
  6. Checklist per la produzione
  7. Punti chiave

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 da voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Cambiamenti chiave: i timestamp sono solo per segmento (word restituisce 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 input context_bias sono 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:

DominioControllo
Gestione erroriRetry con backoff esponenziale per errori temporanei
Rate limitingRispetta i limiti API, implementa throttling se necessario
MonitoraggioLog strutturati, metriche di performance, alert sugli errori
SicurezzaChiave API in variabile d’ambiente, mai hardcoded nel codice
ArchiviazioneSalva le trascrizioni in modo durevole, non solo in memoria
Formato audioNormalizza i file a monte (mono, 16 kHz)
TestingFile 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