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

Casos de Utilização de Anotações

Aula 12 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Anotações para Cada Função
  2. Classificar Antes de Processar
  3. Ler um Contrato Como um Advogado
  4. Verificar a Conformidade Automaticamente
  5. Não Perder Nada Antes da Indexação
  6. Pontos-chave

Atualização de 2 de novembro de 2026 — OCR. O OCR 4.0 (mistral-ocr-4-0) foi descontinuado a 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: Processador OCR · QnA de Documentos. Corrigido a 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.

Anotações para Cada Função

As anotações de IA de documentos transformam documentos não estruturados em dados acionáveis. O mecanismo é sempre o mesmo — um esquema, um prompt, uma chamada — mas o que extrai muda radicalmente dependendo da função. Esta lição percorre quatro implementações concretas: classificação a montante num pipeline, análise de cláusulas contratuais, verificações de conformidade regulamentar e enriquecimento de um índice RAG.

Classificar Antes de Processar

Num fluxo de trabalho real, os documentos chegam misturados: uma fatura, uma ordem de compra, um cartão de identificação, uma carta. Antes de aplicar o esquema de extração adequado, precisa de saber com o que está a lidar. A anotação serve como a primeira etapa de triagem. O enumerado TypeDocument fixa as categorias admissíveis, a pontuação de confiança permite encaminhar tudo o que esteja abaixo de um limiar para revisão humana, e o resumo de uma frase dá aos operadores contexto suficiente para tomar uma decisão sem abrir o ficheiro.

import os
from enum import Enum
from pydantic import BaseModel, Field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

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

class TypeDocument(str, Enum):
    INVOICE = "facture"
    PURCHASE_ORDER = "bon_commande"
    CONTRACT = "contrat"
    REPORT = "rapport"
    LETTER = "courrier"
    FORM = "formulaire"
    ID_DOCUMENT = "piece_identite"
    OTHER = "autre"

class Classification(BaseModel):
    document_type: TypeDocument = Field(
        ..., description="Identified document type"
    )
    confidence: float = Field(
        ..., description="Confidence score between 0 and 1"
    )
    language: str = Field(
        ..., description="Primary language (ISO 639-1 code)"
    )
    summary: str = Field(
        ..., description="One-sentence summary of the content"
    )

def classify_document(document_base64: str) -> Classification:
    """Classifica automaticamente um documento."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            Classification
        ),
        document_annotation_prompt=(
            "Identify the type of this document and provide "
            "a summary of its content."
        )
    )

    if response.document_annotation:
        return Classification.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Ler um Contrato Como um Advogado

A análise contratual é um caso de utilização importante nas áreas jurídica e financeira, e é onde os esquemas aninhados realmente se destacam. Cada Clause carrega o seu título, um resumo do conteúdo, a sua categoria — confidencialidade, rescisão, não concorrência, responsabilidade, pagamento — e uma avaliação de risco em três níveis. O próprio contrato agrega estas cláusulas juntamente com as partes, data de assinatura, duração, montante e jurisdição aplicável. Num portefólio de duzentos contratos de fornecedores, obtém em poucas horas um mapeamento que ninguém teria tempo de produzir manualmente.

O campo risk merece um aviso: é uma avaliação produzida por um modelo, útil para priorizar a revisão de um advogado, nunca para a substituir.

from pydantic import BaseModel, Field
from typing import Optional

class Clause(BaseModel):
    title: str = Field(..., description="Title or number of the clause")
    content: str = Field(..., description="Summary of the clause content")
    clause_type: str = Field(
        ..., description="Type: confidentiality, termination, "
        "non-compete, liability, payment, other"
    )
    risk: str = Field(
        ..., description="Risk level: low, medium, high"
    )

class ContractAnalysis(BaseModel):
    parts: list[str] = Field(
        ..., description="Names of the contracting parts"
    )
    signature_date: Optional[str] = Field(
        None, description="Signature date (YYYY-MM-DD)"
    )
    duration: Optional[str] = Field(
        None, description="Contract duration"
    )
    key_clauses: list[Clause] = Field(
        ..., description="Identified main clauses"
    )
    amount: Optional[float] = Field(
        None, description="Total amount if mentioned"
    )
    jurisdiction: Optional[str] = Field(
        None, description="Applicable jurisdiction"
    )

def analyze_contract(document_base64: str) -> ContractAnalysis:
    """Analisa um contrato e extrai as cláusulas principais."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ContractAnalysis
        ),
        document_annotation_prompt=(
            "Analyze this commercial contract. Identify the parts, "
            "the main clauses, and evaluate the risk level "
            "of each clause."
        )
    )

    if response.document_annotation:
        return ContractAnalysis.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Verificar a Conformidade Automaticamente

O controlo regulamentar é particularmente adequado para anotação porque os critérios estão escritos preto no branco na lei. Para uma fatura francesa, o prompt lista as obrigações a verificar — menções obrigatórias (SIRET, IVA intracomunitário, condições de pagamento, penalidades por atraso), formatação do montante, data de emissão — e o esquema impõe, para cada critério, um veredito booleano acompanhado da sua justificação. Recupera uma pontuação global e recomendações de melhoria, o que é suficiente para bloquear uma fatura não conforme antes de entrar no circuito de pagamentos.

from pydantic import BaseModel, Field

class CompliancePoint(BaseModel):
    criterion: str = Field(..., description="Compliance criterion checked")
    compliant: bool = Field(..., description="True if compliant, False otherwise")
    justification: str = Field(
        ..., description="Explanation of compliance or non-compliance"
    )

class ComplianceAudit(BaseModel):
    document_type: str = Field(..., description="Type of document audited")
    compliance_points: list[CompliancePoint] = Field(
        ..., description="Compliance points checked"
    )
    global_score: float = Field(
        ..., description="Global compliance score (0-100)"
    )
    recommendations: list[str] = Field(
        ..., description="Improvement recommendations"
    )

def audit_invoice_compliance(document_base64: str) -> ComplianceAudit:
    """Verifica a conformidade da fatura segundo as regras francesas."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ComplianceAudit
        ),
        document_annotation_prompt=(
            "Verify the compliance of this invoice according to "
            "French legal obligations: mandatory mentions "
            "(SIRET, intra-community VAT, payment terms, "
            "late payment penalties), amount formatting, issue date."
        )
    )

    if response.document_annotation:
        return ComplianceAudit.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Não Perder Nada Antes da Indexação

Um último caso de utilização, mais discreto mas decisivo: preparar conteúdo para um índice RAG. Um índice construído apenas em Markdown perde tudo o que era visual, e as suas pesquisas nunca encontrarão o gráfico que continha o dado chave. A função abaixo recompõe, página a página, o texto e a descrição de cada imagem, adicionando depois os metadados extraídos do documento, num único bloco pronto para ser dividido em fragmentos.

def enrich_for_rag(ocr_response) -> str:
    """Enriquece o conteúdo OCR com anotações para RAG."""
    parts = []

    for page in ocr_response.pages:
        # Text content
        parts.append(page.markdown)

        # Image annotations (replace images with their description)
        for image in page.images:
            if image.image_annotation:
                parts.append(
                    f"[Description of {image.id}]: {image.image_annotation}"
                )

    # Document annotation: a single one, carried by the response
    if ocr_response.document_annotation:
        parts.append(
            f"[Extracted Metadata]: {ocr_response.document_annotation}"
        )

    return "\n\n".join(parts)

Ao adicionar descrições de imagens e metadados extraídos ao conteúdo indexado, não perde nenhuma informação do documento original. Notará que estes quatro cenários partilham a mesma espinha dorsal: o que os distingue é o esquema e o prompt, não o código de chamada.

Pontos-chave

  • A classificação automática encaminha documentos para o pipeline de processamento correto
  • A extração de cláusulas contratuais identifica riscos e pontos chave
  • A verificação de conformidade automatiza auditorias regulamentares
  • O enriquecimento por anotação melhora a qualidade da indexação RAG
  • Cada caso de utilização resume-se a um esquema Pydantic bem desenhado e um prompt adaptado