Anotações em Lote
Nesta página
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 aliasmistral-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 tipodocument_base64de exemplos anteriores não existe nem na documentação nem no SDKmistralai, e esses exemplos teriam falhado. Fontes: OCR Processor · Document QnA. Corrigido em 3 de novembro de 2026: O código lia anteriormentepage.document_annotationpágina por página; no SDKmistralai3.7.0, a anotação do documento é um único campo na resposta (response.document_annotation), e a anotação de imagem é lida a partir deimage.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
asyncioe 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