Pipeline de Produção
Nesta página
Atualização de 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), disponível geralmente 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 uma imagem é lida a partir deimage.image_annotation.
Da Prova de Conceito à Produção
Aprendeu a utilizar o OCR, as anotações e o Document AI QnA. Resta uma lacuna dispendiosa: a distância entre um script que funciona no seu portátil e um serviço do qual os seus colegas dependem todas as manhãs. Esta última lição reúne os blocos de construção anteriores num pipeline robusto, completo com recuperação de erros, monitorização e controlo de custos.
Os Seis Componentes de um Pipeline Completo
- Fila de Ingestão: Recebe e prioriza documentos.
- Pré-processamento: Valida, converte formatos e melhora imagens.
- OCR + Anotações: Extrai texto e dados estruturados.
- Pós-processamento: Valida, limpa e enriquece dados.
- Armazenamento: Bases de dados, repositórios vetoriais e arquivamento.
- Interface de Consulta: API QnA, painéis de controlo e integrações.
O código nesta lição cobre o núcleo da cadeia — passos 3 e 4 — porque é aí que se concentram as dificuldades operacionais.
Uma Classe que Encapsula o Processamento
A classe PipelineDocumentAI define uma configuração de uma vez por todas — o esquema de anotação, o formato da tabela e o número de novas tentativas — aplicando-a depois a cada documento. Três mecanismos merecem a sua atenção. Em primeiro lugar, a nova tentativa com espera exponencial (time.sleep(2 ** tentative)) espaça as tentativas em um, depois dois, depois quatro segundos. Isto dá tempo para resolver a saturação transitória da API em vez de a agravar. Em segundo lugar, o registo (logging) rastreia cada sucesso com a sua contagem de páginas e duração, e cada falha com o seu número de tentativa; sem estas linhas, só descobrirá incidentes quando o departamento de contabilidade ligar. Por fim, o dicionário stats alimenta o relatório de fim de lote.
Note que o método devolve sempre um ResultatTraitement, mesmo após esgotar as novas tentativas: o chamador nunca tem de tratar uma exceção, basta ler o campo erreur.
import os
import time
import base64
import logging
from pathlib import Path
from dataclasses import dataclass, field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
from typing import Optional
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("document_ai_pipeline")
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
@dataclass
class ResultatTraitement:
fichier: str
pages: int = 0
texte: str = ""
annotations: Optional[dict] = None
duree_secondes: float = 0.0
erreur: Optional[str] = None
class PipelineDocumentAI:
def __init__(
self,
schema_annotation=None,
table_format: str = "markdown",
max_retries: int = 3,
):
self.schema_annotation = schema_annotation
self.table_format = table_format
self.max_retries = max_retries
self.stats = {"total": 0, "succes": 0, "erreurs": 0}
def traiter_document(self, chemin: str) -> ResultatTraitement:
"""Processes a document with retry and monitoring."""
debut = time.time()
self.stats["total"] += 1
for tentative in range(self.max_retries):
try:
# Read and encode
with open(chemin, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
# Call parameters
params = {
"model": "mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
"table_format": self.table_format,
}
if self.schema_annotation:
params["document_annotation_format"] = (
response_format_from_pydantic_model(
self.schema_annotation
)
)
# OCR Call
response = client.ocr.process(**params)
# Extract text
texte = "\n\n".join(
p.markdown for p in response.pages
)
# Extract annotations
annotations = None
if self.schema_annotation:
if response.document_annotation:
annotations = response.document_annotation
duree = time.time() - debut
self.stats["succes"] += 1
logger.info(
f"OK: {chemin} ({len(response.pages)} pages, "
f"{duree:.1f}s)"
)
return ResultatTraitement(
fichier=chemin,
pages=len(response.pages),
texte=texte,
annotations=annotations,
duree_secondes=duree,
)
except Exception as e:
logger.warning(
f"Tentative {tentative + 1}/{self.max_retries} "
f"échouée pour {chemin}: {e}"
)
if tentative < self.max_retries - 1:
time.sleep(2 ** tentative) # Exponential backoff
# All attempts failed
self.stats["erreurs"] += 1
return ResultatTraitement(
fichier=chemin,
duree_secondes=time.time() - debut,
erreur="Échec après toutes les tentatives",
)
def traiter_dossier(self, dossier: str) -> list[ResultatTraitement]:
"""Processes all PDFs in a folder."""
chemin = Path(dossier)
fichiers = sorted(chemin.glob("*.pdf"))
resultats = []
for fichier in fichiers:
resultat = self.traiter_document(str(fichier))
resultats.append(resultat)
return resultats
def rapport(self) -> str:
"""Generates a processing report."""
return (
f"Documents traités : {self.stats['total']}\n"
f"Succès : {self.stats['succes']}\n"
f"Erreurs : {self.stats['erreurs']}\n"
f"Taux de succès : "
f"{self.stats['succes']/max(self.stats['total'],1)*100:.1f}%"
)
Na prática, a mesma classe cobre ambas as necessidades: instanciada sem um esquema, extrai simplesmente texto; instanciada com um modelo Pydantic, produz também dados estruturados.
# Simple pipeline (OCR only)
pipeline = PipelineDocumentAI(table_format="markdown")
resultats = pipeline.traiter_dossier("./factures/")
print(pipeline.rapport())
# Pipeline with annotations
from pydantic import BaseModel, Field
class ExtractionFacture(BaseModel):
fournisseur: str = Field(..., description="Nom du fournisseur")
montant_ttc: float = Field(..., description="Montant TTC")
date: str = Field(..., description="Date (YYYY-MM-DD)")
pipeline_annote = PipelineDocumentAI(
schema_annotation=ExtractionFacture,
table_format="markdown"
)
resultats = pipeline_annote.traiter_dossier("./factures/")
Antecipar a Fatura
O controlo de custos é essencial em produção e começa por compreender pelo que é cobrado.
| Item | Base de Faturação |
|---|---|
| OCR | Por página processada |
| Anotações | Incluídas na chamada OCR (sem custo extra) |
| QnA | Tokens de entrada/saída com base no modelo de chat |
| Embeddings | Tokens de entrada |
O facto de as anotações não implicarem custos adicionais altera o desenho: extraia metadados durante a passagem do OCR em vez de executar uma chamada LLM separada posteriormente. A função de estimativa abaixo permite-lhe precificar um projeto antes de o lançar; as suas taxas são valores de ordem de grandeza a ajustar, permanecendo a tabela de referência publicada pela Mistral como autoridade.
def estimer_cout(
nombre_pages: int,
avec_qna: bool = False,
modele_qna: str = "mistral-small-latest"
) -> dict:
"""Estimates processing cost."""
# Approximate rates (check current rates)
cout_ocr_par_page = 0.001 # Adjust based on tier
cout_qna_par_1k_tokens = {
"mistral-small-latest": 0.001,
"mistral-large-latest": 0.008,
}
cout_ocr = nombre_pages * cout_ocr_par_page
cout_qna = 0.0
if avec_qna:
# Estimate: ~500 tokens per page on average
tokens_estimes = nombre_pages * 500
cout_qna = (
tokens_estimes / 1000
* cout_qna_par_1k_tokens.get(modele_qna, 0.001)
)
return {
"cout_ocr": round(cout_ocr, 4),
"cout_qna": round(cout_qna, 4),
"cout_total": round(cout_ocr + cout_qna, 4),
}
Monitorizar a Saúde do Serviço
Um pipeline degrada-se lenta e silenciosamente: um novo fornecedor envia digitalizações de má qualidade, a taxa de erro sobe de 2% para 15% e ninguém nota até ao fecho mensal. Quatro métricas são suficientes para detetar desvios — volume processado, duração média, taxa de erro e custo estimado — desde que as emita sistematicamente e as envie para a sua ferramenta habitual, seja Datadog, Prometheus ou outra.
import json
from datetime import datetime
def log_metrique(nom: str, valeur: float, tags: dict = None) -> None:
"""Records a monitoring metric."""
metrique = {
"timestamp": datetime.utcnow().isoformat(),
"nom": nom,
"valeur": valeur,
"tags": tags or {}
}
# In production: send to Datadog, Prometheus, etc.
logger.info(f"METRIQUE: {json.dumps(metrique)}")
# Example metrics to track
log_metrique("ocr.pages_traitees", 150, {"batch": "factures_mars"})
log_metrique("ocr.duree_moyenne_secondes", 2.3)
log_metrique("ocr.taux_erreur", 0.02)
log_metrique("ocr.cout_estime_usd", 0.15)
Para Onde Seguir
Dispõe agora dos fundamentos para construir um sistema completo de Document AI, e abrem-se várias extensões dependendo das suas restrições. Volumes muito elevados justificam uma implementação no local (on-premise) do modelo OCR numa GPU dedicada; documentos altamente específicos do seu negócio podem motivar um ajuste fino (fine-tuning), um tópico a abordar diretamente com a Mistral. No lado da integração, o desafio consiste em ligar o pipeline aos seus sistemas existentes — ERP, CRM — e construir um painel de controlo para que as suas equipas possam consultar documentos elas próprias, sem passar por si. O passo final é remover o acionamento manual: o pipeline executa-se automaticamente quando chegam novos documentos.
Resumo do Curso
Estas dezasseis lições levaram-no através de todo o ciclo. Começou com os fundamentos — o que é o Document AI, o modelo OCR 4 e casos de uso — antes de avançar para o OCR avançado com a API, extração de tabelas, cabeçalhos/rodapés e otimização. As anotações deram-lhe depois extração estruturada, processamento em lote e controlo de conformidade, seguidas pelo Document QnA, que abriu a consulta em linguagem natural, desde documentos isolados até corpora indexados em RAG. Dispõe agora dos blocos de construção necessários para equipar a gestão documental da sua organização com o Mistral Document AI.
Pontos-chave
- Um pipeline de produção inclui novas tentativas, registo (logging), monitorização e gestão de custos.
- A espera exponencial protege contra erros transitórios da API.
- Estime os seus custos antes de escalar (OCR por página, QnA por token).
- A monitorização contínua permite detetar degradação de desempenho.
- O Document AI cobre todo o ciclo de vida do documento, desde a ingestão até à operação.
Teste os Seus Conhecimentos
OCR, anotações, QnA: valide a cadeia documental completa.
1. O que produz a API OCR da Mistral a partir de um documento?
Resposta: O conteúdo estruturado do documento — texto, tabelas, layout — pronto para uso programático: o OCR 4 lê o documento como uma fonte de dados, não como uma imagem.
2. Qual é o objetivo da API de Anotações?
Resposta: Extrair metadados estruturados de acordo com o seu esquema (campos de fatura, cláusulas de contrato) — individualmente ou em lote para grandes volumes.
3. O que permite o Document QnA?
Resposta: Fazer perguntas em linguagem natural sobre um ou mais documentos e obter respostas baseadas no seu conteúdo — a camada conversacional sobre a extração.
4. Como otimizar a precisão do OCR?
Resposta: Através da qualidade da entrada (resolução, nitidez, orientação) e do tratamento de áreas difíceis — cabeçalhos, rodapés, paginação — que o curso ensina a gerir explicitamente.
5. Por que combinar OCR e RAG?
Resposta: O OCR transforma documentos digitalizados em texto indexável, enquanto o RAG os torna consultáveis em escala: juntos, permitem a pesquisa semântica em arquivos inteiros.
Extração, anotação, pergunta-e-resposta, indexação: o pipeline de produção acima encadeia todos os quatro — a sua papelada torna-se uma base de dados.