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

Extrair Dados Estruturados de Imagens

Aula 9 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Transformar Imagens em Dados Acionáveis
  2. O Modo JSON da API
  3. Extrair uma Tabela de uma Imagem
  4. Formulários e Documentos Administrativos
  5. Extrair Dados de Rótulos de Produtos
  6. Pipeline de Extração com Validação
  7. Converter para CSV ou DataFrame
  8. Pontos-chave

Transformar Imagens em Dados Acionáveis

A lição anterior focou-se na transcrição de texto; esta vai mais longe, produzindo dados estruturados. Extrair dados estruturados significa transformar o conteúdo visual de uma imagem — uma tabela, um formulário, um cartão de visita ou um rótulo — em JSON, CSV ou qualquer outro formato que o seu código possa manipular diretamente, sem revisão manual.

As apostas são mais altas. Uma transcrição aproximada pode ainda ajudar um leitor humano, mas a ausência de uma única chave numa resposta JSON fará falhar o programa que a consome. Esta lição abrange as duas garantias que precisa de implementar: o modo JSON da API para validade sintática e a validação de esquema para conformidade com as regras de negócio.

O Modo JSON da API

A Mistral oferece um parâmetro response_format que força o modelo a devolver JSON válido. Sem ele, perderá tempo a limpar respostas envoltas em blocos Markdown ou precedidas por frases introdutórias de cortesia.

from mistralai.client import Mistral
import os
import json

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

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "Devolve sempre um objeto JSON válido com os dados extraídos da imagem."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extrai os seguintes dados deste cartão de visita como JSON: nome, cargo, empresa, email, telefone, morada."
                },
                {"type": "image_url", "image_url": data_uri_carte}
            ]
        }
    ]
)

# O resultado é diretamente analisável
donnees = json.loads(response.choices[0].message.content)
print(json.dumps(donnees, indent=2, ensure_ascii=False))

A chamada json.loads executa-se sem precauções especiais: response_format={"type": "json_object"} garante uma saída JSON sintaticamente válida. No entanto, não garante quais as chaves presentes. É por isso que deve descrever o formato esperado no próprio prompt, como mostrado nos exemplos abaixo.

Extrair uma Tabela de uma Imagem

Tabelas fotografadas ou capturas de ecrã são um caso de uso comum, e é aqui que um esquema explícito mais compensa. Sem instruções claras, o modelo inventará a sua própria estrutura, que pode diferir a cada chamada.

prompt_tableau = """Extrai o conteúdo desta tabela como JSON.
Formato esperado:
{
  "columns": ["Coluna1", "Coluna2", ...],
  "rows": [
    {"Coluna1": "valor", "Coluna2": "valor"},
    ...
  ]
}
Lê todas as linhas visíveis. Se uma célula estiver vazia, usa null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_tableau},
                {"type": "image_url", "image_url": encoder_image("captures/tableau-excel.png")}
            ]
        }
    ]
)

donnees = json.loads(response.choices[0].message.content)
print(f"Colunas: {donnees['columns']}")
print(f"Número de linhas: {len(donnees['rows'])}")

A instrução relativa às células vazias é crítica. Sem ela, o modelo pode deslocar valores para preencher lacunas, deturpando a tabela. Exibir a contagem de linhas fornece uma verificação de sanidade imediata: se a imagem mostrar doze linhas mas o script reportar oito, a extração está incompleta.

Formulários e Documentos Administrativos

Formulários preenchidos introduzem dois desafios: a escrita manual e as caixas de seleção, que não possuem valor de texto. O seu esquema deve, portanto, incluir campos dedicados para estes elementos.

prompt_formulaire = """Analisa este formulário preenchido e extrai todos os campos e os seus valores.
Formato JSON esperado:
{
  "form_type": "...",
  "fields": {
    "field_name": "entered_value",
    ...
  },
  "checked_boxes": ["field1", "field2"],
  "signature_present": true/false
}
Se um campo estiver vazio ou ilegível, usa null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "És um extrator de formulários preciso. Devolve JSON estruturado."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_formulaire},
                {"type": "image_url", "image_url": encoder_image("formulaires/cerfa-12345.jpg")}
            ]
        }
    ]
)

Extrair Dados de Rótulos de Produtos

Os rótulos alimentares seguem uma estrutura padrão: uma tabela de informação nutricional por 100 g, uma lista de ingredientes e alérgenos. Pode definir o esquema até ao nome da unidade, evitando suposições posteriores sobre se “12” se referia a gramas ou quilocalorias.

prompt_etiquette = """Extrai a informação nutricional deste rótulo.
Formato JSON:
{
  "product_name": "...",
  "net_weight": "...",
  "nutrition_per_100g": {
    "energy_kcal": ...,
    "fat_g": ...,
    "saturated_fat_g": ...,
    "carbohydrates_g": ...,
    "sugars_g": ...,
    "protein_g": ...,
    "salt_g": ...
  },
  "ingredients": "...",
  "allergens": ["..."]
}"""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_etiquette},
                {"type": "image_url", "image_url": encoder_image("produits/etiquette.jpg")}
            ]
        }
    ]
)

produit = json.loads(response.choices[0].message.content)

Pipeline de Extração com Validação

Em produção, as garantias sintáticas não são suficientes. O modelo pode devolver um JSON perfeitamente válido onde falta o email, ou onde o phone contém um inteiro em vez de uma cadeia de caracteres. O Pydantic transforma estes casos em exceções explícitas na fase de extração, em vez de três etapas a jusante no seu pipeline.

from pydantic import BaseModel, Field
from typing import Optional
import json

class BusinessCard(BaseModel):
    last_name: str
    first_name: str
    title: Optional[str] = None
    company: Optional[str] = None
    email: Optional[str] = None
    phone: Optional[str] = None
    address: Optional[str] = None
    website: Optional[str] = None

def extract_business_card(image_path):
    """Extrai e valida dados de cartão de visita."""
    response = client.chat.complete(
        model="mistral-large-latest",
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": "Extrai dados deste cartão de visita. Campos: last_name, first_name, title, company, email, phone, address, website. Devolve JSON."
            },
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Extrai informação deste cartão de visita."},
                    {"type": "image_url", "image_url": encoder_image(image_path)}
                ]
            }
        ]
    )

    # Analisar e validar com Pydantic
    raw_data = json.loads(response.choices[0].message.content)
    card = BusinessCard(**raw_data)
    return card

# Utilização
card = extract_business_card("cartes/contact-dupont.jpg")
print(f"Contacto: {card.first_name} {card.last_name} - {card.email}")

Note a distinção entre last_name: str e title: Optional[str] = None. Um cartão sem nome é uma extração falhada; um cartão sem cargo é um caso normal. Você traça essa linha, e o Pydantic impõe-na.

Converter para CSV ou DataFrame

O passo final é alimentar o seu pipeline de processamento de dados. O JSON produzido acima converte-se diretamente:

import pandas as pd

# De uma tabela extraída
donnees = json.loads(response.choices[0].message.content)

# Criar um DataFrame pandas
df = pd.DataFrame(donnees["rows"])
print(df.to_string())

# Exportar para CSV
df.to_csv("export/tableau_extrait.csv", index=False, encoding="utf-8")

O argumento encoding="utf-8" durante a exportação é obrigatório sempre que os seus dados contêm caracteres acentuados ou símbolos de moeda.

Pontos-chave

  • O parâmetro response_format={"type": "json_object"} garante uma saída JSON válida
  • Forneça sempre um esquema JSON esperado no seu prompt para orientar a extração
  • Utilize o Pydantic para validar os dados extraídos em produção
  • Tabelas, formulários, rótulos e cartões de visita são alvos ideais
  • Combine a extração com o pandas para uma integração direta nos seus fluxos de trabalho de dados