Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Estrarre dati strutturati dalle immagini

Lezione 9 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Trasforma le immagini in dati utilizzabili
  2. La modalità JSON dell’API
  3. Estrarre una tabella da un’immagine
  4. Moduli e documenti amministrativi
  5. Estrarre dati dalle etichette dei prodotti
  6. Pipeline di estrazione con validazione
  7. Convertire in CSV o DataFrame
  8. Punti chiave

Trasforma le immagini in dati utilizzabili

La lezione precedente si concentrava sulla trascrizione del testo; questa va oltre producendo dati strutturati. Estrarre dati strutturati significa trasformare il contenuto visivo di un’immagine—una tabella, un modulo, un biglietto da visita o un’etichetta—in JSON, CSV o qualsiasi altro formato che il tuo codice possa manipolare direttamente, senza revisione manuale.

La posta in gioco è più alta. Una trascrizione approssimativa potrebbe ancora aiutare un lettore umano, ma la mancanza di una singola chiave in una risposta JSON farà crashare il programma che la consuma. Questa lezione copre le due garanzie che devi implementare: la modalità JSON dell’API per la validità sintattica e la validazione dello schema per la conformità aziendale.

La modalità JSON dell’API

Mistral offre un parametro response_format che forza il modello a restituire JSON valido. Senza di esso, perderai tempo a pulire risposte racchiuse in blocchi Markdown o precedute da frasi introduttive di 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": "Restituisci sempre un oggetto JSON valido con i dati estratti dall'immagine."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Estrai i seguenti dati da questo biglietto da visita come JSON: name, title, company, email, phone, address."
                },
                {"type": "image_url", "image_url": data_uri_carte}
            ]
        }
    ]
)

# Il risultato è direttamente analizzabile
donnees = json.loads(response.choices[0].message.content)
print(json.dumps(donnees, indent=2, ensure_ascii=False))

La chiamata json.loads viene eseguita senza precauzioni speciali: response_format={"type": "json_object"} garantisce un output JSON sintatticamente valido. Tuttavia, non garantisce quali chiavi siano presenti. Ecco perché devi descrivere il formato atteso nel prompt stesso, come mostrato negli esempi seguenti.

Estrarre una tabella da un’immagine

Le tabelle fotografate o gli screenshot sono un caso d’uso comune, ed è qui che uno schema esplicito ripaga di più. Senza istruzioni chiare, il modello inventerà la propria struttura, che potrebbe differire a ogni chiamata.

prompt_tableau = """Estrai il contenuto di questa tabella come JSON.
Formato atteso:
{
  "columns": ["Column1", "Column2", ...],
  "rows": [
    {"Column1": "value", "Column2": "value"},
    ...
  ]
}
Leggi tutte le righe visibili. Se una cella è vuota, 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"Colonne: {donnees['columns']}")
print(f"Numero di righe: {len(donnees['rows'])}")

L’istruzione riguardante le celle vuote è fondamentale. Senza di essa, il modello potrebbe spostare i valori per colmare le lacune, distorcendo la tabella. Visualizzare il conteggio delle righe fornisce un controllo di sanità immediato: se l’immagine mostra dodici righe ma lo script ne riporta otto, l’estrazione è incompleta.

Moduli e documenti amministrativi

I moduli compilati introducono due sfide: la calligrafia e le caselle di spunta, che non hanno un valore testuale. Il tuo schema deve quindi includere campi dedicati per questi elementi.

prompt_formulaire = """Analizza questo modulo compilato ed estrai tutti i campi e i loro valori.
Formato JSON atteso:
{
  "form_type": "...",
  "fields": {
    "field_name": "entered_value",
    ...
  },
  "checked_boxes": ["field1", "field2"],
  "signature_present": true/false
}
Se un campo è vuoto o illeggibile, usa null."""

response = client.chat.complete(
    model="mistral-large-latest",
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": "Sei un estrattore di moduli preciso. Restituisci JSON strutturato."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt_formulaire},
                {"type": "image_url", "image_url": encoder_image("formulaires/cerfa-12345.jpg")}
            ]
        }
    ]
)

Estrarre dati dalle etichette dei prodotti

Le etichette alimentari seguono una struttura standard: una tabella nutrizionale per 100 g, un elenco degli ingredienti e gli allergeni. Puoi definire lo schema fino al nome dell’unità di misura, evitando successivamente congetture sul fatto che “12” si riferisse a grammi o chilocalorie.

prompt_etiquette = """Estrai le informazioni nutrizionali da questa etichetta.
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 di estrazione con validazione

In produzione, le garanzie sintattiche non sono sufficienti. Il modello potrebbe restituire un JSON perfettamente valido in cui manca email, o dove phone contiene un intero invece di una stringa. Pydantic trasforma questi casi in eccezioni esplicite durante la fase di estrazione, anziché tre passaggi più avanti nella tua 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):
    """Estrae e valida i dati del biglietto da visita."""
    response = client.chat.complete(
        model="mistral-large-latest",
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": "Estrai i dati da questo biglietto da visita. Campi: last_name, first_name, title, company, email, phone, address, website. Restituisci JSON."
            },
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Estrai le informazioni da questo biglietto da visita."},
                    {"type": "image_url", "image_url": encoder_image(image_path)}
                ]
            }
        ]
    )

    # Analizza e valida con Pydantic
    raw_data = json.loads(response.choices[0].message.content)
    card = BusinessCard(**raw_data)
    return card

# Utilizzo
card = extract_business_card("cartes/contact-dupont.jpg")
print(f"Contatto: {card.first_name} {card.last_name} - {card.email}")

Nota la distinzione tra last_name: str e title: Optional[str] = None. Un biglietto senza nome è un’estrazione fallita; un biglietto senza titolo lavorativo è un caso normale. Sei tu a tracciare quella linea, e Pydantic la fa rispettare.

Convertire in CSV o DataFrame

Il passaggio finale consiste nell’alimentare la tua pipeline di elaborazione dati. Il JSON prodotto sopra si converte direttamente:

import pandas as pd

# Da una tabella estratta
donnees = json.loads(response.choices[0].message.content)

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

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

L’argomento encoding="utf-8" durante l’esportazione è obbligatorio ogni volta che i tuoi dati contengono caratteri accentati o simboli di valuta.

Punti chiave

  • Il parametro response_format={"type": "json_object"} garantisce un output JSON valido
  • Fornisci sempre uno schema JSON atteso nel tuo prompt per guidare l’estrazione
  • Usa Pydantic per validare i dati estratti in produzione
  • Tabelle, moduli, etichette e biglietti da visita sono target ideali
  • Combina l’estrazione con pandas per un’integrazione diretta nei tuoi flussi di lavoro dati