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

Pipeline de Produção

Aula 16 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Da Prova de Conceito à Produção
  2. Os Seis Componentes de um Pipeline Completo
  3. Uma Classe que Encapsula o Processamento
  4. Antecipar a Fatura
  5. Monitorizar a Saúde do Serviço
  6. Para Onde Seguir
  7. Resumo do Curso
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

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 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 uma imagem é lida a partir de image.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

  1. Fila de Ingestão: Recebe e prioriza documentos.
  2. Pré-processamento: Valida, converte formatos e melhora imagens.
  3. OCR + Anotações: Extrai texto e dados estruturados.
  4. Pós-processamento: Valida, limpa e enriquece dados.
  5. Armazenamento: Bases de dados, repositórios vetoriais e arquivamento.
  6. 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.

ItemBase de Faturação
OCRPor página processada
AnotaçõesIncluídas na chamada OCR (sem custo extra)
QnATokens de entrada/saída com base no modelo de chat
EmbeddingsTokens 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.