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

Extrair Metadados Estruturados

Aula 10 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Extraia exatamente o que precisa
  2. Estrutura em vez de achatamento
  3. Dados repetidos
  4. Caixas de seleção e formulários
  5. Implementação de ponta a ponta
  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.

Extraia exatamente o que precisa

A anotação de documentos não se resume a recuperar texto bruto. Produz dados estruturados, tipados e validados, prontos para uso imediato nos seus sistemas: uma linha inserida numa base de dados, um campo comparado com uma referência ou um montante verificado antes do pagamento. O desafio desloca-se inteiramente para o desenho do esquema, que é o foco desta lição.

Estrutura em vez de achatamento

Um esquema de extração deve refletir a realidade do documento. Uma fatura provém de uma entidade legal com um nome de empresa, um número SIRET (identificador empresarial francês) e um endereço. Em vez de alinhar oito campos como emetteur_rue, emetteur_ville, emetteur_siret, defina um modelo Adresse e, em seguida, um modelo LegalEntity que o contenha. Reutilize estes blocos de construção tanto para o emissor como para o destinatário. A enumeração TypeDocument desempenha um papel semelhante: impede que o modelo invente uma categoria e garante um valor que pode utilizar numa instrução if ou para encaminhamento. Os campos Optional indicam explicitamente o que pode estar ausente, enquanto os valores padrão — como default="France" para o país — poupam o modelo de adivinhar o óbvio.

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum

class DocumentType(str, Enum):
    INVOICE = "facture"
    CONTRACT = "contrat"
    REPORT = "rapport"
    FORM = "formulaire"
    OTHER = "autre"

class Address(BaseModel):
    street: Optional[str] = Field(None, description="Número e rua")
    postal_code: Optional[str] = Field(None, description="Código postal")
    city: Optional[str] = Field(None, description="Cidade")
    country: str = Field(default="France", description="País")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Razão social")
    siret: Optional[str] = Field(None, description="Número SIRET")
    address: Optional[Address] = Field(None, description="Morada postal")
    email: Optional[str] = Field(None, description="Endereço de e-mail")

class DocumentExtraction(BaseModel):
    document_type: DocumentType = Field(
        ..., description="Tipo de documento"
    )
    date: Optional[str] = Field(
        None, description="Data principal (AAAA-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entidade que emite o documento"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Entidade destinatária"
    )
    resume: str = Field(
        ..., description="Resumo em 2-3 frases do conteúdo"
    )
    langue: str = Field(
        ..., description="Idioma do documento (código ISO 639-1)"
    )

Dados repetidos

Muitos documentos contêm séries: linhas de faturação, cláusulas ou itens de despesas. Modele-os como uma list[...] de um submodelo dedicado. O modelo analisa então a tabela do documento e produz tantos objetos LigneFacture quantas as linhas que encontrar, incluindo a descrição, quantidade, preço unitário e total para cada uma. Isto fornece-lhe dados suficientes para recalcular o subtotal e verificar a consistência do documento antes de o aceitar.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Descrição do produto/serviço")
    quantity: float = Field(..., description="Quantidade")
    unit_price: float = Field(..., description="Preço unitário sem IVA")
    amount: float = Field(..., description="Montante total sem IVA da linha")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Nome do fornecedor")
    number: str = Field(..., description="Número da fatura")
    date: str = Field(..., description="Data (AAAA-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Linhas da fatura"
    )
    subtotal_excl_tax: float = Field(..., description="Subtotal sem IVA")
    vat: float = Field(..., description="Montante de IVA")
    total_incl_tax: float = Field(..., description="Total com IVA")
    payment_terms: str = Field(
        ..., description="Condições de pagamento mencionadas"
    )

Caixas de seleção e formulários

Os formulários em papel digitalizados são onde o modelo se destaca. Um campo bool emparelhado com o rótulo da pergunta é suficiente: o modelo reconhece se uma caixa está assinalada, extrai a pergunta correspondente e — crucialmente para uso médico ou administrativo — infere que um campo está em falta em vez de inventar um valor, como demonstrou a equipa da Mistral. A nota “null if not provided” na descrição do número de telefone não é decorativa; autoriza explicitamente um valor vazio.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Enunciado da pergunta")
    answer: bool = Field(..., description="True se assinalado, False caso contrário")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Nome completo do paciente")
    age: Optional[int] = Field(None, description="Idade do paciente")
    sex: Optional[str] = Field(None, description="Sexo (M/F)")
    patient_id: Optional[str] = Field(None, description="ID do paciente")
    phone: Optional[str] = Field(
        None, description="Número de telefone (null se não fornecido)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Respostas às perguntas do formulário"
    )

Implementação de ponta a ponta

Pegue no exemplo da fatura detalhada e ligue-o a um documento codificado em base64. O prompt de anotação complementa o esquema especificando o tipo de ficheiro e enfatizando a atenção às linhas de faturação; a validação Pydantic no retorno converte a cadeia JSON num objeto que pode percorrer com segurança.

import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

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

ocr_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(
        DetailedInvoice
    ),
    document_annotation_prompt=(
        "Este documento é uma fatura. Extraia todas as linhas "
        "de faturação com os respetivos montantes."
    )
)

# Extração e validação
if ocr_response.document_annotation:
    invoice = DetailedInvoice.model_validate_json(
        ocr_response.document_annotation
    )

    print(f"Fatura {invoice.numero} - {invoice.fornecedor}")
    print(f"Data : {invoice.data}")
    print(f"\nLinhas :")
    for line in invoice.lines:
        print(f"  - {line.descricao}: {line.quantidade} x "
              f"{line.preco_unitario}€ = {line.montante}€")
    print(f"\nTotal com IVA : {invoice.total_com_iva}€")

Resultados de extração deficientes devem-se quase sempre ao esquema, raramente ao modelo. Reveja as suas descrições uma a uma: devem ser precisas e inequívocas, pois o modelo depende apenas delas para compreender as suas expectativas. Escreva-as no idioma dos seus documentos — o francês funciona perfeitamente para faturas francesas — e reserve enums para campos com valores limitados e submodelos para estruturas que reutilizará entre esquemas.

Pontos-chave

  • Os esquemas Pydantic permitem a extração de dados tipados e validados
  • Utilize tipos complexos (listas, enums, modelos aninhados) para extrações precisas
  • O modelo gere campos opcionais e caixas de seleção de forma fiável
  • As descrições dos campos orientam a extração: seja preciso e explícito
  • Combine document_annotation_prompt com o esquema para máximo contexto