Extrair Dados Estruturados de Imagens
Nesta página
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