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

Anotações em Lote

Aula 11 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Escalar a Operação
  2. Comece pelo Processamento Sequencial
  3. Paralelizar sem Saturar a API
  4. Quando o Volume Justifica a Inferência em Lote
  5. Monitorizar o Que Aconteceu
  6. Pontos-chave

Atualizado em 2 de novembro de 2026 — OCR. O OCR 4.0 (mistral-ocr-4-0) foi desativado em 30 de setembro de 2026. Utilize o OCR 4.1 (mistral-ocr-4-1), geralmente disponível desde 31 de agosto pelo mesmo preço, ou o alias mistral-ocr-latest, que aponta para ele desde 16 de julho. O OCR 4.1 adiciona pontuações de confiança ao nível do bloco. Adenda de 3 de novembro de 2026: Um PDF local é transmitido em base64 como {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; o tipo document_base64 de exemplos anteriores não existe nem na documentação nem no SDK mistralai, e esses exemplos teriam falhado. Fontes: OCR Processor · Document QnA. Corrigido em 3 de novembro de 2026: O código lia anteriormente page.document_annotation página por página; no SDK mistralai 3.7.0, a anotação do documento é um único campo na resposta (response.document_annotation), e a anotação de imagem é lida a partir de image.image_annotation.

Escalar a Operação

Processar um documento de cada vez funciona para prototipagem. Em produção, a realidade é diferente: um departamento de contabilidade recebe centenas de faturas diariamente, e um escritório de advocacia digitaliza milhares de documentos durante a due diligence. O código deve mudar correspondentemente — já não se trata apenas de obter uma resposta, mas de garantir que nenhum documento se perde pelo caminho e de saber exatamente quais falharam.

Comece pelo Processamento Sequencial

Mantenha a simplicidade inicialmente. O ciclo abaixo itera sobre uma pasta de PDFs, codifica cada ficheiro em base64, envia-o para o motor OCR com o esquema de anotação e acumula os resultados. A parte crítica reside no bloco try/except: uma fatura ilegível ou uma chamada à API falhada nunca deve interromper todo o lote. Regista-se o erro com o nome do ficheiro e continua-se, deixando-o com uma lista final onde cada entrada possui um status. O contador exibido em cada iteração não é apenas um extra; ao processar trezentos ficheiros, conhecer o seu progresso impede-o de reiniciar uma tarefa que já está a meio.

import os
import json
import time
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

class ExtractionFacture(BaseModel):
    fournisseur: str = Field(..., description="Supplier name")
    numero: str = Field(..., description="Invoice number")
    montant_ttc: float = Field(..., description="Total amount including tax")
    date: str = Field(..., description="Date (YYYY-MM-DD)")

def traiter_dossier_factures(dossier: str) -> list[dict]:
    """Processa todas as faturas numa pasta."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"A processar {len(fichiers)} ficheiros...")

    for i, fichier in enumerate(fichiers):
        print(f"  [{i+1}/{len(fichiers)}] {fichier.name}")

        try:
            import base64
            with open(fichier, "rb") as f:
                doc_b64 = base64.b64encode(f.read()).decode("utf-8")

            response = client.ocr.process(
                model="mistral-ocr-latest",
                document={
                    "type": "document_url",
                    "document_url": f"data:application/pdf;base64,{doc_b64}"
                },
                document_annotation_format=response_format_from_pydantic_model(
                    ExtractionFacture
                ),
                table_format="markdown"
            )

            if response.document_annotation:
                facture = ExtractionFacture.model_validate_json(
                    response.document_annotation
                )
                resultats.append({
                    "fichier": fichier.name,
                    "fournisseur": facture.fournisseur,
                    "numero": facture.numero,
                    "montant_ttc": facture.montant_ttc,
                    "date": facture.date,
                    "statut": "ok"
                })

        except Exception as e:
            resultats.append({
                "fichier": fichier.name,
                "statut": "erreur",
                "erreur": str(e)
            })

    return resultats

Paralelizar sem Saturar a API

O processamento sequencial passa a maior parte do tempo à espera da rede. As chamadas assíncronas eliminam este desperdício, desde que limite a concorrência: lançar trezentos pedidos de uma vez desencadeará erros de limite de taxa (rate-limit) e deixá-lo-á com um lote a meio. O semáforo asyncio trata exatamente disto — max_concurrent=5 significa um máximo de cinco documentos em voo a qualquer momento, independentemente de quantos ficheiros estão na fila. A função individual mantém a mesma disciplina da versão sequencial: captura exceções e devolve um dicionário de estado em vez de deixar o gather falhar.

import os
import asyncio
import base64
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

async def traiter_document(chemin_fichier: Path, schema) -> dict:
    """Processa um documento de forma assíncrona."""
    try:
        with open(chemin_fichier, "rb") as f:
            doc_b64 = base64.b64encode(f.read()).decode("utf-8")

        response = client.ocr.process(
            model="mistral-ocr-latest",
            document={
                "type": "document_url",
                "document_url": f"data:application/pdf;base64,{doc_b64}"
            },
            document_annotation_format=response_format_from_pydantic_model(
                schema
            )
        )

        annotations = []
        if response.document_annotation:
            annotations.append(response.document_annotation)

        return {
            "fichier": chemin_fichier.name,
            "annotations": annotations,
            "statut": "ok"
        }

    except Exception as e:
        return {
            "fichier": chemin_fichier.name,
            "statut": "erreur",
            "erreur": str(e)
        }


async def traiter_batch(
    dossier: str,
    schema,
    max_concurrent: int = 5
) -> list[dict]:
    """Processa uma pasta com paralelismo controlado."""
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    semaphore = asyncio.Semaphore(max_concurrent)

    async def traiter_avec_limite(fichier):
        async with semaphore:
            return await traiter_document(fichier, schema)

    taches = [traiter_avec_limite(f) for f in fichiers]
    resultats = await asyncio.gather(*taches)

    return list(resultats)

# Execução
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Quando o Volume Justifica a Inferência em Lote

Além de um certo limiar, a questão muda da velocidade para o custo. A Mistral oferece um serviço dedicado de Inferência em Lote (Batch Inference) que é mais económico do que chamadas individuais. Submete um ficheiro JSONL contendo um pedido por linha. O campo custom_id — aqui, o nome do ficheiro sem extensão — permite mapear cada resposta de volta ao seu documento original quando o lote estiver concluído.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Prepara um ficheiro JSONL para processamento em lote."""
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))
    compte = 0

    with open(sortie, "w") as f:
        for fichier in fichiers:
            with open(fichier, "rb") as pdf:
                doc_b64 = base64.b64encode(pdf.read()).decode("utf-8")

            requete = {
                "custom_id": fichier.stem,
                "model": "mistral-ocr-latest",
                "document": {
                    "type": "document_url",
                    "document_url": f"data:application/pdf;base64,{doc_b64}"
                }
            }

            f.write(json.dumps(requete) + "\n")
            compte += 1

    print(f"{compte} pedidos preparados em {sortie}")
    return compte

Monitorizar o Que Aconteceu

O processamento em massa sem métricas é uma caixa negra. A pequena classe de dados abaixo conta sucessos e erros, calcula o tempo decorrido e deriva uma velocidade em documentos por segundo. Esta velocidade indica-lhe se a sua definição max_concurrent é ótima, enquanto a lista de ficheiros falhados alimenta o seu processo de recuperação de incidentes.

import time
from dataclasses import dataclass, field

@dataclass
class StatsBatch:
    total: int = 0
    succes: int = 0
    erreurs: int = 0
    temps_debut: float = field(default_factory=time.time)
    fichiers_erreur: list = field(default_factory=list)

    @property
    def duree(self) -> float:
        return time.time() - self.temps_debut

    @property
    def vitesse(self) -> float:
        if self.duree > 0:
            return self.succes / self.duree
        return 0.0

    def rapport(self) -> str:
        return (
            f"Processamento concluído em {self.duree:.1f}s\n"
            f"  Sucessos: {self.succes}/{self.total}\n"
            f"  Erros: {self.erreurs}\n"
            f"  Velocidade: {self.vitesse:.2f} docs/s\n"
            f"  Ficheiros falhados: {self.fichiers_erreur}"
        )

Finalmente, exporte os resultados do script. O CSV vai para a folha de cálculo do departamento de contabilidade, o JSON para a sua aplicação; em ambos os casos, garanta a codificação UTF-8 e ensure_ascii=False, caso contrário, os seus caracteres acentuados aparecerão como sequências ilegíveis para o destinatário.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Exporta resultados para CSV."""
    if not resultats:
        return

    cles = resultats[0].keys()

    with open(chemin, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=cles)
        writer.writeheader()
        writer.writerows(resultats)

    print(f"Exportação CSV: {chemin}")


def exporter_json(resultats: list[dict], chemin: str) -> None:
    """Exporta resultados para JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    print(f"Exportação JSON: {chemin}")

Pontos-chave

  • O processamento sequencial adequa-se a pequenos volumes com tratamento robusto de erros
  • O processamento paralelo com asyncio e semáforos acelera grandes volumes
  • O serviço de Inferência em Lote da Mistral é a solução mais económica para volumes muito grandes
  • Adicione monitorização e relatórios para acompanhar o progresso e identificar erros
  • Exporte os resultados para CSV ou JSON para integração com os seus sistemas