Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Otimização para Produção

Aula 15 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Do Protótipo ao Serviço Fiável
  2. Tratamento de Erros que Distingue Recuperáveis de Fatais
  3. Processamento de um Lote de Ficheiros Sem Supervisão
  4. Preparação do Áudio a Montante
  5. Saber o Que Está a Acontecer
  6. Lista de Verificação para Produção
  7. Pontos-chave

Curso atualizado a 3 de novembro de 2026 para o Voxtral 3, com base no guia Migrate from Voxtral 2 da Mistral: os modelos Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), descontinuados a 31 de outubro de 2026 e retirados a 30 de abril de 2027, são substituídos nos exemplos por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Principais alterações: as marcas temporais são apenas por segmento (word devolve um erro 400), a identificação de locutores em tempo real é suportada, as definições de sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradas context_bias são de formato livre (frases com espaços). Fontes: Migrate from Voxtral 2 · Speech to Text.

Do Protótipo ao Serviço Fiável

Já sabe como transcrever áudio, tanto de forma assíncrona como em tempo real. No entanto, operar um serviço que processa centenas de ficheiros diariamente sem supervisão humana é um exercício completamente diferente, pois enfrenta situações que um protótipo nunca vê: um ficheiro corrompido, uma quota excedida, uma queda de rede a meio do carregamento ou um pico de volume que ativa a limitação de taxa. Esta lição aborda estes casos um a um: tratamento de erros, processamento em lote, preparação de ficheiros e observabilidade.

Tratamento de Erros que Distingue Recuperáveis de Fatais

A primeira regra é não tratar todos os erros da mesma forma. Uma queda de rede, um tempo limite esgotado ou uma indisponibilidade temporária merecem uma nova tentativa; um ficheiro ilegível ou uma chave de API inválida nunca se corrigirão sozinhos, e tentar novamente apenas desperdiça tempo e polui os seus registos. O wrapper abaixo implementa esta distinção com um tuplo de exceções temporárias: qualquer coisa em ERREURS_TEMPORAIRES aciona uma nova tentativa, enquanto todo o resto falha imediatamente. Em ambos os casos, a função devolve um dicionário em vez de lançar uma exceção, permitindo que o processamento em lote continue com os ficheiros restantes.

import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral

logger = logging.getLogger("voxtral")

# Exceções para tentar novamente
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Transcreve um ficheiro com nova tentativa exponencial."""
    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:
            # Erro não recuperável (ficheiro inválido, autenticação, etc.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

O atraso entre as tentativas duplica a cada falha — dois segundos, depois quatro, depois oito — para evitar sobrecarregar uma API que já está com dificuldades. No entanto, este recuo exponencial tem uma falha quando se têm muitos clientes: se todos falharem no mesmo instante, todos tentarão novamente no mesmo instante, e a onda atingirá o serviço de uma só vez. Corrigimos isto com jitter, uma variação aleatória adicionada ao atraso, o que é suficiente para dessincronizar as tentativas.

import random

delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)

Processamento de um Lote de Ficheiros Sem Supervisão

Transcrever duzentas gravações uma após a outra é um desperdício: a maior parte do tempo é gasta à espera da rede. Um pool de trabalhadores gere várias transcrições simultaneamente sem perder o controlo do progresso. A função abaixo varre uma pasta, mantém as extensões de áudio conhecidas, submete cada ficheiro ao wrapper de nova tentativa definido acima e escreve a transcrição assim que esta chega, em vez de o fazer no final: se o processo falhar a meio, o que já foi processado já está no disco. Um relatório JSON resume os sucessos e falhas, permitindo reiniciar apenas o que falhou.

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
):
    """Transcreve todos os ficheiros de áudio numa pasta em paralelo."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # Encontrar todos os ficheiros de áudio
    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}"
            )

            # Guardar a transcrição
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Relatório final
    succes = sum(1 for r in resultats if r["succes"])
    echecs = len(resultats) - succes
    logger.info(f"Terminé : {succes} succès, {echecs} échecs")

    # Guardar o relatório
    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

# Utilização
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

Não ceda à tentação de aumentar max_workers para ir mais depressa. A API da Mistral impõe limites de pedidos por minuto, e quatro trabalhadores geralmente mantêm-no abaixo desse limiar. Se os erros 429 (Too Many Requests) aparecerem nos seus registos, a resposta não é tentar novamente com mais força, mas reduzir o número de trabalhadores ou introduzir um atraso entre os pedidos.

Preparação do Áudio a Montante

O formato dos ficheiros que envia influencia tanto o tempo de carregamento como a qualidade do texto resultante. Se a fidelidade for primordial, mantenha-se no WAV ou FLAC, formatos sem perdas: o modelo recebe toda a informação de áudio. Para uso comum, o MP3 a 128 kbps ou superior oferece o melhor compromisso, com qualidade mais do que suficiente para transcrição e um tamanho de ficheiro razoável. E quando a largura de banda é a restrição dominante, o OGG Vorbis ou o MP3 a 64 kbps permanecem perfeitamente aceitáveis para a fala, que é muito diferente da música neste aspeto.

Em vez de aceitar quaisquer formatos que cheguem, normalize-os antes de enviar. A função abaixo aplica quatro transformações: conversão para mono, já que o estéreo não acrescenta nada à transcrição; reamostragem para 16 kHz, a taxa nativa do Voxtral; taxa de bits definida para 64 kbps, suficiente para voz; e loudnorm, que equaliza o volume.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Prepara um ficheiro de áudio para uma transcrição ótima."""
    if chemin_sortie is None:
        chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"

    subprocess.run([
        "ffmpeg", "-y",
        "-i", chemin_entree,
        "-ac", "1",          # Mono (o estéreo não ajuda na transcrição)
        "-ar", "16000",       # 16 kHz (taxa nativa do Voxtral)
        "-b:a", "64k",        # 64 kbps (suficiente para fala)
        "-af", "loudnorm",    # Normalização de volume
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

O ganho é duplo: converter para mono 16 kHz 64 kbps reduz significativamente os tamanhos dos ficheiros sem degradar a transcrição, e o loudnorm melhora notavelmente os resultados em gravações com volume irregular, tipicamente numa reunião onde um participante está longe do microfone.

Saber o Que Está a Acontecer

Um serviço de transcrição sem instrumentação é uma caixa negra: no dia em que os tempos de processamento duplicarem, saberá disso através de um utilizador infeliz. Recolha o tamanho do ficheiro, a duração do processamento, o número de tentativas e o volume de texto produzido para cada chamada e escreva tudo como JSON numa única linha, um formato diretamente utilizável por um agregador de registos.

import time
import logging
import json
from datetime import datetime

logger = logging.getLogger("voxtral-prod")

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Transcreve com recolha de métricas."""
    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)

    # Registo estruturado (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Lista de Verificação para Produção

Antes de abrir o seu serviço ao primeiro utilizador real, reveja estes sete pontos:

DomínioVerificação
Tratamento de errosNova tentativa com recuo exponencial para erros temporários
Limitação de taxaRespeitar os limites da API, implementar estrangulamento se necessário
MonitorizaçãoRegistos estruturados, métricas de desempenho, alertas sobre erros
SegurançaChave da API em variável de ambiente, nunca codificada no código
ArmazenamentoGuardar transcrições de forma duradoura, não apenas na memória
Formato de áudioNormalizar ficheiros a montante (mono, 16 kHz)
TestesFicheiros variados: idiomas, durações, qualidade de áudio, número de locutores

A última linha é a mais frequentemente negligenciada e a mais dispendiosa. Três gravações limpas em francês não lhe ensinarão nada sobre o comportamento real do seu serviço: construa uma amostra deliberadamente difícil e descobrirá as definições a ajustar enquanto ainda há tempo.

Pontos-chave

  • Implemente nova tentativa com recuo exponencial e jitter para erros temporários
  • Utilize um pool de trabalhadores para processamento em lote (4 trabalhadores é um bom ponto de partida)
  • Normalize os seus ficheiros para mono 16 kHz com o FFmpeg para resultados ótimos
  • Recolha métricas estruturadas para monitorização de produção
  • Respeite os limites de taxa da API da Mistral
  • Guarde sistematicamente as transcrições e os relatórios de lote