Extrair Metadados Estruturados
Nesta página
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 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: Processador OCR · QnA de Documentos. Corrigido a 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.
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_promptcom o esquema para máximo contexto