Introduzione alla classificazione ed estrazione di dati strutturati da testo, Immagini, e documenti con LLM multimodali come Google Gemini.
Questo articolo descrive come utilizzare l’API di Google Gemini per generare output di dati strutturati. Si concentra principalmente sulla produzione di testo in formato JSON, un formato ideale per l’elaborazione automatica.
La guida spiega come specificare uno schema JSON, sia direttamente nel prompt che tramite la configurazione del modello, per guidare il modello LLM nella generazione di risposte prevedibili e conformi a una struttura definita. Viene inoltre illustrato l’uso delle enumerazioni per limitare l’output del modello a una serie di opzioni predefinite. Infine, fornisce dettagli sulla sintassi per la definizione degli schemi JSON e sull’importanza dell’ordine delle proprietà per ottenere risultati ottimali dall’API Gemini.
L’obiettivo principale è fornire ad analisti gli strumenti per ottenere output di dati strutturati affidabili e utilizzabili dalle applicazioni nelle proprie applicazioni di analisi, sfruttando la potenza degli LLM multimodali come Gemini per analizzare immagini e documentii.
L’importanza dei dati strutturati per l’analisi strategica
Nel contesto dinamico e complesso dei modelli di analisi aziendale odierno, la capacità di analizzare e comprendere grandi volumi di informazioni in modo rapido ed efficiente è fondamentale per effettuare analisi robuste e concrete. Gli analisti aziendali si affidano sempre più ai dati per guidare i loro modelli, e la qualità e la fruibilità di questi dati giocano un ruolo cruciale.
L’AI Generativa sta riferendo i paradigmi per la creazione di contenuti e la gestione delle informazioni. Tuttavia, nel contesto aziendale, dove automazione, efficienza dei processi e integrazioni software richiedono dati precisi e interpretabili da sistemi automatizzati, emerge un’esigenza cruciale: strutturare l’output dell’AI.
Estrazione, processamento e archiviazione di dati in formati definiti (tramite schemi o liste di valori) diventano quindi fondamentali per:
- Consentire l’elaborazione automatica e la creazione di database affidabili.
- Ottenere informazioni standardizzate, pronte per l’integrazione nei sistemi esistenti.
- Garantire l’usabilità e l’affidabilità dei risultati dell’AI Generativa nei workflow aziendali e nell’analisi dei dati.
I dati strutturati, generati o precisasti da un LLM organizzati in formati ben definiti, offrono vantaggi significativi rispetto ai dati non strutturati, specialmente quando si tratta di elaborazione automatica e analisi approfondita, integrazione i sviluppo di applicazioni.
Inoltre l’adozione di schemi definiti dall’utente per esigenze specifiche offre un ulteriore vantaggio: risposte più deterministische e conformi a strutture predefinite. Questo permette di controllare la forma dei dati, inclusi tipi e valori ammissibili, garantendo una precisione superiore rispetto alle interazioni di chat generiche.
La generazione di output di dati strutturati attraverso LLM apre nuove frontiere per l’analisi strategica. Invece di dover interpretare e organizzare manualmente grandi quantità di testo non strutturato generato da modelli linguistici, gli analisti possono utilizzare l’API dei modelli più avanzati come Gemini per ottenere direttamente informazioni in formati come JSON (JavaScript Object Notation) . JSON, con la sua struttura basata su coppie chiave-valore e array, è un formato standard del settore delle analisi, poiché facilita l’integrazione e l’interoperabilità dei dati con un’ampia gamma di strumenti e piattaforme software.

Perché scegliere JSON per l’output strutturato

JSON è diventato un formato di scambio dati onnipresente nel mondo dello sviluppo software e dell’analisi dati grazie alla sua semplicità, flessibilità e leggibilità sia per gli umani che per le macchine. Alcuni dei principali vantaggi di utilizzare JSON per l’output strutturato dall’API Gemini includono:
- Semplicità e leggibilità: La sintassi di JSON è minimalista e intuitiva. I dati sono rappresentati come una raccolta di oggetti (coppie chiave-valore) o array di valori3 . Questa semplicità rende facile comprendere la struttura dei dati e mapparli a modelli di dati interni.
- Ampio supporto da linguaggi di programmazione: JSON è supportato nativamente dalla maggior parte dei linguaggi di programmazione moderni e dalle piattaforme di database3 . Questo facilita l’integrazione dell’output dell’API Gemini in flussi di lavoro di analisi esistenti senza la necessità di complesse operazioni di parsing o conversione.
- Flessibilità: JSON può rappresentare una vasta gamma di strutture di dati, da semplici elenchi di valori a oggetti complessi con annidamento di array e altri oggetti5 . Questa flessibilità consente di definire schemi JSON che si adattano perfettamente alle esigenze specifiche di diversi compiti di analisi.
- Efficienza per l’elaborazione automatica: La natura strutturata di JSON lo rende ideale per l’elaborazione automatica da parte di software e algoritmi di machine learning1 . Le librerie di parsing JSON consentono di accedere e manipolare facilmente i dati contenuti negli oggetti e negli array.
- Standard de facto: JSON è ampiamente adottato come standard per lo scambio di dati sul web e nelle API3 . Utilizzare JSON per l’output strutturato dall’API Gemini garantisce la compatibilità con un ecosistema di strumenti e servizi consolidato.
In estrema sintesi il formato JSON
Fonti per approfondire:
| Definizione del formato | https://json-schema.org/learn |
| Documentazione sullo schema JSON | https://json-schema.org/learn |
| Codificatore e decodificatore JSON – Python | https://docs.python.org/it/3.13/library/json.html |
Estrarre informazioni da un immagine in formato strutturato
L’API Gemini offre due modi principali estrarre informazioni da da un testo a da una immagine:
- Chiedere di estrarre / trasformare in formato strutturato di tipo JSON includendo (opzionalmente) lo schema come testo nel Prompt: Questo approccio prevede di descrivere la struttura JSON desiderata direttamente all’interno del prompt fornito al modello .
- Fornire uno Schema strutturato tramite la configurazione del Modello: Questo metodo utilizza parametri di configurazione specifici dell’API per definire formalmente lo schema JSON atteso.
Di seguito si riportano due esempi su come estrarre le Informazioni da un immagine
Estrarre le coordinate degli oggetti da un’immagine
Nell’esempio si illustra come estrarre le coordinate dei complementi di arredo di un un progetto di design d’interni di una Piantana 3D.
Immagine di input:
Prompt:
Rileva le coordinate di tutti i componenti di arredo del progetto di design illustrato nella piantina 3D allegata, compresi gli accessori. Scrivi le etichette in italiano. Riporta l'output in formato JSON compatto.Applicazione in: Google AI Studio
Modello: Gemini 2.0 Flash
Output:
[
{"label": "quadri", "box_3d": [271, 141, 438, 291]},
{"label": "pianta", "box_3d": [234, 187, 421, 250]},
{"label": "tavolo da pranzo", "box_3d": [302, 141, 438, 197]},
{"label": "servizio di piatti", "box_3d": [260, 190, 262, 195]},
{"label": "pianta", "box_3d": [314, 251, 403, 291]},
{"label": "wc", "box_3d": [302, 414, 452, 483]},
{"label": "lavabo", "box_3d": [234, 455, 327, 504]},
{"label": "sgabelli da bar", "box_3d": [507, 519, 600, 570]},
{"label": "lavandino da cucina", "box_3d": [317, 522, 462, 650]},
{"label": "isola da cucina", "box_3d": [336, 493, 564, 683]},
{"label": "tavolo da pranzo", "box_3d": [260, 340, 348, 387]},
{"label": "mobiletto da cucina", "box_3d": [114, 616, 244, 784]},
{"label": "armadi da cucina", "box_3d": [107, 520, 345, 784]},
{"label": "fornello", "box_3d": [255, 594, 289, 667]},
{"label": "scrivania", "box_3d": [341, 837, 464, 909]},
{"label": "computer", "box_3d": [315, 863, 359, 899]},
{"label": "tavolino", "box_3d": [687, 418, 823, 503]},
{"label": "divano", "box_3d": [618, 232, 844, 438]},
{"label": "lampada da terra", "box_3d": [382, 511, 528, 559]},
{"label": "lampada da terra", "box_3d": [516, 376, 740, 472]},
{"label": "quadri", "box_3d": [236, 185, 421, 250]},
{"label": "piante", "box_3d": [401, 511, 588, 566]},
{"label": "wc", "box_3d": [302, 414, 452, 483]},
{"label": "pianta", "box_3d": [234, 455, 327, 504]},
{"label": "tavolo", "box_3d": [577, 700, 721, 809]}
]Estrarre informazioni sugli oggetti di un’immagine
In questo esempio si illustra come analizzare ed estrarre informazioni in modo strutturato da un’immagine. Partendo dall’input dell’esempio precedente si cerca di estrarre in modo strutturato la tipologia dei complementi di arredo, il numero, l’ubicazione, inferire il materiale, lo stile il colore e altre informazioni utili.
Input:

Prompt:
#---------------------------
# PROMPT DI SISTEMA
#---------------------------
# Per testare le richieste nel palyground copiare e incollare solamnete il testo
SYSTEM_PROMPT = """
# ISTRUZIONI PER IL MODELLO
Sei un esperto di architettura d'interni e riconoscimento di oggetti. Hai davanti un'immagine 3D dettagliata di un appartamento moderno. Il tuo compito è quello di:
1. Analizzare l’ambiente rappresentato.
2. Identificare ogni elemento di arredamento (es. divani, tavoli, sedie, lampade, piante, elettrodomestici, decorazioni, mobili da cucina, ecc.).
3. Restituire ogni oggetto in un formato JSON strutturato e coerente con i campi richiesti.
4. Quando necessario, inferisci lo stile, il materiale, il colore e la quantità degli oggetti sulla base del contesto visivo e architettonico.
5. Ogni elemento deve essere descritto con precisione e con termini coerenti al linguaggio dell’interior design.
6. Ignora elementi strutturali come muri o porte, a meno che non siano parte dell’arredo o abbiano valenza estetica.
7. SOLO se richiesto ESPLCITAMNETE riepiloga tutto in una tabella markdown.
"""
#---------------------------
# PROMPT UTENTE
#---------------------------
USER_PROMPT_1 = """
# QUERY
## Hai davanti un'immagine 3D dettagliata di un ambiente domestico. Il tuo compito è:
1. Analizzare attentamente la scena raffigurata.
2. Riconoscere ogni elemento di arredamento o decorazione presente (es. mobili, complementi, lampade, elettrodomestici, oggetti funzionali e decorativi).
3. Restituire ogni oggetto in formato JSON strutturato seguendo lo schema fornito.
4. Per ogni oggetto, inferisci il più possibile:
- Nome descrittivo
- Tipologia (categoria)
- Quantità
- Ubicazione (nome ambiente o zona funzionale)
- Stile di design
- Colore dominante
- Materiale principale
- Note aggiuntive (funzione, disposizione, dettagli visivi o tecnici)
- NON RSTITUIRE SPIEGAZIONI, descrizioni testuali o altri output oltre al JSON.
"""
USER_PROMPT_2 = """
# QUERY
Riepiloga tutto in una tabella
"""
Applicazione in Google AI Studio:
Modello: Gemini 2.0 Flash
Output: JSON
L’output JSON può adesso esser utilizzato per diverse analisi tra cui creazione di tabelle, applicazioni di filtri e formule, trasformazioni aggregazioni e applicazioni software.
Prima estrazione …

Cliccare per visualizzare l’intero output JSON in dettaglio
[
{
"nome": "Divano lineare imbottito",
"tipologia": "Divano",
"quantità": 1,
"ubicazione": "Soggiorno",
"stile": "Moderno",
"colore": "Beige chiaro",
"materiale": "Tessuto",
"note": "Con cuscino decorativo"
},
{
"nome": "Tavolino da caffè rettangolare",
"tipologia": "Tavolino",
"quantità": 1,
"ubicazione": "Soggiorno",
"stile": "Moderno",
"colore": "Marrone scuro",
"materiale": "Legno",
"note": "Con ripiano inferiore"
},
{
"nome": "Lampada da terra con paralume cilindrico",
"tipologia": "Lampada",
"quantità": 1,
"ubicazione": "Soggiorno",
"stile": "Moderno",
"colore": "Bianco e nero",
"materiale": "Metallo e tessuto",
"note": "Con paralume in tessuto"
},
{
"nome": "Tappeto rettangolare",
"tipologia": "Tappeto",
"quantità": 2,
"ubicazione": "Soggiorno",
"stile": "Moderno",
"colore": "Grigio",
"materiale": "Tessuto",
"note": "Sotto il divano e sotto il tavolo da pranzo"
},
{
"nome": "Pianta ornamentale in vaso",
"tipologia": "Pianta",
"quantità": 3,
"ubicazione": "Soggiorno, Sala da pranzo, Studio",
"stile": "Naturale",
"colore": "Verde",
"materiale": "Vaso in ceramica",
"note": "Elemento decorativo"
},
{
"nome": "Set di tre quadri con cornice",
"tipologia": "Decorazione murale",
"quantità": 3,
"ubicazione": "Sala da pranzo",
"stile": "Moderno",
"colore": "Bianco e nero",
"materiale": "Carta e legno",
"note": "Disposti orizzontalmente"
},
{
"nome": "Tavolo da pranzo rettangolare",
"tipologia": "Tavolo",
"quantità": 1,
"ubicazione": "Sala da pranzo",
"stile": "Moderno",
"colore": "Nero",
"materiale": "Legno",
"note": "Con piano in vetro"
},
{
"nome": "Sedia da pranzo imbottita",
"tipologia": "Sedia",
"quantità": 6,
"ubicazione": "Sala da pranzo",
"stile": "Moderno",
"colore": "Grigio",
"materiale": "Tessuto e metallo",
"note": "Con gambe in metallo"
},
{
"nome": "Stoviglie e bicchieri",
"tipologia": "Servizio da tavola",
"quantità": 6,
"ubicazione": "Sala da pranzo",
"stile": "Moderno",
"colore": "Bianco e trasparente",
"materiale": "Ceramica e vetro",
"note": "Disposti sul tavolo da pranzo"
},
{
"nome": "Mobile cucina con isola",
"tipologia": "Mobile cucina",
"quantità": 1,
"ubicazione": "Cucina",
"stile": "Moderno",
"colore": "Bianco e nero",
"materiale": "Legno e laminato",
"note": "Con lavello integrato"
},
{
"nome": "Sgabello da bar",
"tipologia": "Sgabello",
"quantità": 3,
"ubicazione": "Cucina",
"stile": "Moderno",
"colore": "Beige",
"materiale": "Tessuto e metallo",
"note": "Con seduta imbottita"
},
{
"nome": "Piano cottura a induzione",
"tipologia": "Elettrodomestico",
"quantità": 1,
"ubicazione": "Cucina",
"stile": "Moderno",
"colore": "Nero",
"materiale": "Vetroceramica",
"note": "Integrato nel piano di lavoro"
},
{
"nome": "Lavello da cucina",
"tipologia": "Sanitario",
"quantità": 2,
"ubicazione": "Cucina",
"stile": "Moderno",
"colore": "Nero",
"materiale": "Acciaio",
"note": "Integrato nel piano di lavoro"
},
{
"nome": "Tavolo rotondo",
"tipologia": "Tavolo",
"quantità": 1,
"ubicazione": "Zona living",
"stile": "Moderno",
"colore": "Bianco",
"materiale": "Legno e metallo",
"note": "Con gambe in metallo"
},
{
"nome": "Sedia da tavolo",
"tipologia": "Sedia",
"quantità": 3,
"ubicazione": "Zona living",
"stile": "Moderno",
"colore": "Beige",
"materiale": "Tessuto e metallo",
"note": "Con gambe in metallo"
},
{
"nome": "Scrivania",
"tipologia": "Scrivania",
"quantità": 1,
"ubicazione": "Studio",
"stile": "Moderno",
"colore": "Legno chiaro",
"materiale": "Legno",
"note": "Con ripiani laterali"
},
{
"nome": "Sedia da ufficio",
"tipologia": "Sedia",
"quantità": 1,
"ubicazione": "Studio",
"stile": "Moderno",
"colore": "Nero",
"materiale": "Tessuto e plastica",
"note": "Con rotelle"
},
{
"nome": "Computer desktop",
"tipologia": "Elettronica",
"quantità": 1,
"ubicazione": "Studio",
"stile": "Moderno",
"colore": "Nero",
"materiale": "Plastica e metallo",
"note": "Con monitor, tastiera e mouse"
},
{
"nome": "Mobile bagno sospeso",
"tipologia": "Mobile bagno",
"quantità": 2,
"ubicazione": "Bagno",
"stile": "Moderno",
"colore": "Bianco",
"materiale": "Legno e laminato",
"note": "Con lavabo integrato"
},
{
"nome": "WC sospeso",
"tipologia": "Sanitario",
"quantità": 2,
"ubicazione": "Bagno",
"stile": "Moderno",
"colore": "Bianco",
"materiale": "Ceramica",
"note": "Con scarico a parete"
}
]I video seguente illustra come visualizzare un file JSON, ispezionare i dati in forma di tabella ed esportare il CSV per poi elaborare la tabella in Microsoft Excel.
Tools utilizzato: JSONGRID
Attraverso il secondo prompt dell’esempio è possibile guidare LLM a generare una tabella di riepilogo utile alla visualizzazione, tuttavia risulta molto più efficiente importare i dati in excel per qualsiasi tipo di elaborazione, importando il CSV del della tabella o direttamente il file JSON.
Risultato dell’importazione in Excel

Estrarre informazioni specificando uno schema nella richiesta del modello
Per costruire schemi JSON da inviare a modelli di linguaggio di grandi dimensioni (LLM), Pydantic si rivela uno strumento estremamente utile per garantire la validazione e la correttezza dei dati. Pydantic consente di definire modelli di dati utilizzando le annotazioni di tipo di Python, il che rende l’intero processo sia intuitivo che potente. Di seguito vengono riportati degli esempi avanzati per la creazione di schemi JSON orientati.
Pydantic è una libreria Python utilizzata per la validazione dei dati e la gestione dei modelli di dati tramite l’uso di annotazioni di tipo. Essa consente di definire schemi dati in modo chiaro e strutturato, rendendo il processo di sviluppo molto più semplice e intuitivo.
- Validazione dei dati: Pydantic offre un sistema di validazione dei dati automatico che assicura che i dati soddisfino determinati criteri definiti nel modello. Questo riduce il rischio di errori dovuti a dati non conformi.
- Definizione intuitiva: Attraverso l’uso delle annotazioni di tipo, gli sviluppatori possono creare modelli di dati in modo naturale e leggibile. Questo rende Pydantic molto accessibile anche per chi è agli inizi con Python.
- Serializzazione e deserializzazione: Pydantic permette di convertire facilmente oggetti Python in formato JSON e viceversa. Questo è particolarmente utile quando si lavora con API e modelli di linguaggio di grandi dimensioni (LLM), dove i dati sono spesso scambiati in formato JSON.
- Supporto per tipi complessi: La libreria consente di definire modelli dati complessi, inclusi quelli costituiti da liste, dizionari e oggetti annidati. Questa flessibilità è fondamentale quando si progettano schemi dettagliati per LLM.
- Facilità d’uso con LLM: Quando si interagisce con modelli di linguaggio come quelli offerti da Google Gemini, avere un modo efficace per strutturare le richieste e gestire le risposte è fondamentale. Pydantic consente di definire chiaramente le aspettative sui dati, garantendo che interazioni con LLM siano coerenti e affidabili.
- Documentazione automatica: Grazie alla sua capacità di generare schemi JSON automaticamente, Pydantic facilita la documentazione dei modelli. Questo consente agli sviluppatori di mantenere la comunicazione chiara riguardo ai formati dei dati attesi e delle risposte.
Iniziamo con l’installare Pydantic, se non lo abbiamo già fatto
pip install pydanticUse Case 1: Classificare e analizzare il sentiment di una richiesta di assistenza.
In questa sezione, presenteremo un esempio avanzato di come creare uno schema Pydantic per classificare e inferire informazioni da una richiesta di assistenza, comprendente diverse informazioni chiave come la classificazione della richiesta, un titolo di massimo cinque parole, il sentimento (positivo, negativo o neutro), la presenza di rabbia, il prodotto a cui si riferisce la richiesta, le caratteristiche positive o negative e informazioni utili per la classificazione. Inclusi anche i gradi di confidenza della rabbia e del sentimento su una scala da 1 a 5.
Ecco come definire uno schema Pydantic per gestire la richiesta di analisi del sentiment e il risultato associato.
# Importare le librerie
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
#-------------------------------------
# CLASSI PER L'ANALISI DEL SENTIMEMNT
#-------------------------------------
class SentimentCharacteristic(BaseModel):
characteristic: str = Field(..., description="Caratteristica menzionata nella richiesta (es. difettoso, utile)")
type: str = Field(..., description="Tipo di caratteristica (es. positiva, negativa)")
class SentimentAnalysisResult(BaseModel):
request_classification: str = Field(..., description="Classificazione della richiesta")
title: str = Field(..., max_length=50, description="Titolo della richiesta (max 5 parole)")
sentiment: str = Field(..., description="Tipo di sentimento identificato (es. Positivo, Negativo, Neutro)")
anger_present: bool = Field(..., description="Indica se la richiesta esprime rabbia")
product: str = Field(..., description="Nome del prodotto menzionato")
characteristics: List[SentimentCharacteristic] = Field(..., description="Caratteristiche positive o negative identificate")
confidence_sentiment: int = Field(..., ge=1, le=5, description="Grado di confidenza del sentimento su una scala da 1 a 5")
confidence_anger: int = Field(..., ge=1, le=5, description="Grado di confidenza della presenza di rabbia su una scala da 1 a 5")
additional_info: Optional[str] = Field(default=None, description="Informazioni aggiuntive per la classificazione della richiesta")
Visualizzare lo schema
# Visualizzare lo schema della classe SentimentAnalysisResult
import json
print(json.dumps(SentimentAnalysisResult.model_json_schema(), indent=4))
Cliccare per visualizzare lo schema JSON in dettaglio
"$defs": {
"SentimentCharacteristic": {
"properties": {
"characteristic": {
"description": "Caratteristica menzionata nella richiesta (es. difettoso, utile)",
"title": "Characteristic",
"type": "string"
},
"type": {
"description": "Tipo di caratteristica (es. positiva, negativa)",
"title": "Type",
"type": "string"
}
},
"required": [
"characteristic",
"type"
],
"title": "SentimentCharacteristic",
"type": "object"
}
},
"properties": {
"request_classification": {
"description": "Classificazione della richiesta",
"title": "Request Classification",
"type": "string"
},
"title": {
"description": "Titolo della richiesta (max 5 parole)",
"maxLength": 50,
"title": "Title",
"type": "string"
},
"sentiment": {
"description": "Tipo di sentimento identificato (es. Positivo, Negativo, Neutro)",
"title": "Sentiment",
"type": "string"
},
"anger_present": {
"description": "Indica se la richiesta esprime rabbia",
"title": "Anger Present",
"type": "boolean"
},
"product": {
"description": "Nome del prodotto menzionato",
"title": "Product",
"type": "string"
},
"characteristics": {
"description": "Caratteristiche positive o negative identificate",
"items": {
"$ref": "#/$defs/SentimentCharacteristic"
},
"title": "Characteristics",
"type": "array"
},
"confidence_sentiment": {
"description": "Grado di confidenza del sentimento su una scala da 1 a 5",
"maximum": 5,
"minimum": 1,
"title": "Confidence Sentiment",
"type": "integer"
},
"confidence_anger": {
"description": "Grado di confidenza della presenza di rabbia su una scala da 1 a 5",
"maximum": 5,
"minimum": 1,
"title": "Confidence Anger",
"type": "integer"
},
"additional_info": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Informazioni aggiuntive per la classificazione della richiesta",
"title": "Additional Info"
}
},
"required": [
"request_classification",
"title",
"sentiment",
"anger_present",
"product",
"characteristics",
"confidence_sentiment",
"confidence_anger"
],
"title": "SentimentAnalysisResult",
"type": "object"
}
Dopo aver definito lo schema, possiamo costruire simulare delle richieste di assistenza per testare come analizzare il sentiment della richiesta ed estrarre informazioni, in modo da testare il funzionamento in seguito.
Definire le richieste di assistenza di input
Queste richieste sono esempi (sintetici) di feedback o domande che i clienti di un negozio online di design per arredamenti potrebbero inviare al servizio clienti.
#---------------------------
# RICHIESTE DI ASSISTENZA
#---------------------------
# Queste richieste rappresentano il prompt dell'utente da passare al modello
# Per testare le richieste nel palyground copiare e incollare solamnete il testo
richiesta_1= """ Volevo solo dirvi che il vaso che ho ordinato la settimana scorsa, il modello "Soffio di Primavera", è ancora più bello dal vivo che in foto sul sito! Si adatta perfettamente al mio soggiorno e ha ricevuto un sacco di complimenti.
L'imballaggio era fatto benissimo ed è arrivato tutto in perfette condizioni. Sono davvero contenta dell'acquisto!
"""
richiesta_2= """ Buongiorno, vorrei sapere se è possibile avere maggiori informazioni sul tavolino "Linee Essenziali" che ho aggiunto al carrello.
In particolare, mi interesserebbe conoscere il peso esatto e se il piano è resistente ai liquidi.
Non ho trovato queste specifiche nella descrizione del prodotto. Grazie.
"""
richiesta_3 = """Salve, ho ricevuto oggi la lampada da terra "Ombre Delicate" che avevo ordinato. Purtroppo, ho notato che la base presenta un graffio piuttosto evidente su un lato.
L'imballaggio esterno era integro, quindi credo sia un difetto pre-spedizione. Sono un po' deluso perché era un pezzo che desideravo molto.
Vorrei capire come posso procedere per la sostituzione
"""
richiesta_4 = """Ma è incredibile! Ho aspettato quasi due settimane per ricevere la libreria modulare "Spazio Vivo" e quando finalmente arriva, manca un intero ripiano! Ho controllato il manuale e la lista dei pezzi, e ne manca uno.
Ho già provato a contattarvi telefonicamente due volte, ma non risponde nessuno! Sono furioso per la vostra disorganizzazione e per il tempo che mi state facendo perdere. Pretendo che mi spediate immediatamente il pezzo mancante senza ulteriori spese!
"""
Prompt d’inferenza del sentiment per il modello LLM
Un prompt dettagliato è essenziale per l’accurata analisi del sentiment. Di seguito è riportato un esempio di prompt in formato da utilizzare per istruire il modello LLM a generare una risposta accurata classificando e inferendo le informazioni secondo lo schema fornito :
#---------------------------
# PROMPT DI SISTEMA
#---------------------------
# Per testare il prompt di sistema nel palyground copiare e incollare solamnete il testo
system_prompt = """
# ISTRUZIONI PER IL MODELLO
Sei un esperto analista di richieste dei clineti. Il tuo compito è analizzare le richieste degli utenti sguendo le seguneti istruzioni.
## Istruzioni per l'Analisi del sentiment
Analizza il seguente testo per inferire informazioni relative al sentimento del cliente.
1. **Classificazione della richiesta** (`request_classification`): Classifica la richiesta come "Problema tecnico", "Richiesta di informazioni", "Richiesta di assistenza", "Feedback positivo" o simile.
2. **Titolo** (`title`): Fornisci un titolo conciso che riassuma la richiesta in massimo cinque parole.
3. **Sentiment** (`sentiment`): Determina se il sentimento è positivo, negativo o neutro.
4. **Presenza di rabbia** (`anger_present`): Valuta se il testo esprime rabbia e fornisci una risposta "vero" o "falso".
5. **Prodotto** (`product`): Identifica il nome del prodotto a cui si riferisce il cliente.
6. **Caratteristiche** (`characteristics`): Elenca le caratteristiche positive o negative menzionate nel testo con la loro tipologia. Questo campo sarà una lista di oggetti JSON, dove ogni oggetto conterrà:
* `characteristic`: La caratteristica menzionata.
* `type`: Il tipo di sentimento associato alla caratteristica ("positiva" o "negativa").
7. **Confidenza del sentimento** (`confidence_sentiment`): Indica il grado di confidenza sulla determinazione del sentimento su una scala da 1 a 5.
8. **Confidenza della rabbia** (`confidence_anger`): Indica il grado di confidenza sulla valutazione della presenza di rabbia su una scala da 1 a 5.
9. **Informazioni aggiuntive** (`additional_info`): Fornisci ulteriori dettagli utili per la classificazione della richiesta.
La richiesta di assistenza è la seguente:
"Sono rimasto estremamente soddisfatto della lampada da tavolo che ho acquistato. L'illuminazione è perfetta e si adatta benissimo al mio salotto. Ottimo prodotto!"
### Output atteso
Fornisci un output strutturato in formato JSON che includa:
```json
{
"request_classification": "Feedback positivo",
"title": "Soddisfatto della lampada",
"sentiment": "positivo",
"anger_present": "falso",
"product": "lampada da tavolo",
"characteristics": [
{
"characteristic": "illuminazione perfetta",
"type": "positiva"
},
{
"characteristic": "si adatta benissimo",
"type": "positiva"
},
{
"characteristic": "ottimo prodotto",
"type": "positiva"
}
],
"confidence_sentiment": 5,
"confidence_anger": 1,
"additional_info": "Il cliente esprime forte soddisfazione per il prodotto acquistato."
}
"""Per testare il prompt nel playground di Google Gemini seguire i seguenti passaggi:
- Accedere al Playground di Google AI Studio e accedere.
- Copiare e incollare il prompt contenete l’esempio JSON, nelle istruzioni di sistema
- Selezionale l’opzione per l’output strutturato JSON, nella sezione dei Tools.
- Se necessario, regolare i parametri del modello, temperatura e token massimi di output.
- Copiare e incollare il testo della recensione nella sezione di prompt e cliccare “Run” per inviare il testi al modello.
- Verificare che la risposta sia nel formato desiderato (, che il contenuto sia accurato e coerente.
- Rivedere e reiterare il prompt se l’output è errato o incompleto.
Output: JSON
{
"request_classification": "Feedback positivo",
"title": "Vaso Soffio di Primavera eccellente",
"sentiment": "positivo",
"anger_present": "falso",
"product": "vaso Soffio di Primavera",
"characteristics": [
{
"characteristic": "ancora più bello dal vivo che in foto",
"type": "positiva"
},
{
"characteristic": "si adatta perfettamente",
"type": "positiva"
},
{
"characteristic": "un sacco di complimenti",
"type": "positiva"
},
{
"characteristic": "imballaggio fatto benissimo",
"type": "positiva"
},
{
"characteristic": "arrivato tutto in perfette condizioni",
"type": "positiva"
}
],
"confidence_sentiment": 5,
"confidence_anger": 1,
"additional_info": "Il cliente è molto contento del vaso 'Soffio di Primavera', ne elogia l'estetica, l'adattabilità all'ambiente, e l'imballaggio protettivo."
}Use Case 2: Analizzare un prodotto di design
Immaginiamo di dover gestire un vasto catalogo di prodotti di arredamento, ad esempio per un sito e-commerce, un sistema di gestione dell’inventario o per analisi di mercato sulle tendenze di design. Analizzare manualmente ogni immagine per estrarre informazioni chiave come tipo di prodotto, materiali, colori e stile sarebbe estremamente dispendioso in termini di tempo e soggetto a inconsistenza.
Il caso d’uso qui è automatizzare l’estrazione di informazioni dettagliate e strutturate direttamente dalle immagini di prodotti di arredamento utilizzando un modello di intelligenza artificiale (AI). L’obiettivo è ottenere dati coerenti e facilmente utilizzabili per popolare database, abilitare filtri di ricerca avanzati (es. “mostrami tutte le sedie in legno stile scandinavo di colore bianco”), generare descrizioni o alimentare ulteriori analisi.
Input modello:




Creare gli schemi Pydantic per l’analisi del concept di product design
Per garantire che l’AI restituisca i dati nel formato desiderato e con le informazioni rilevanti, definiamo uno schema preciso. Questo schema funge da contratto, specificando esattamente quali campi informativi devono essere estratti, il loro tipo di dato (testo, numero, lista, booleano), le opzioni consentite per campi specifici (come categorie, materiali o stili) e quali campi sono obbligatori.
Nel nostro caso specifico, ci concentriamo esclusivamente sulla categoria “Arredamento” e abbiamo definito lo schema ProductInfoArredamento (rappresentato in formato JSON Schema nel prompt, ma che potrebbe essere implementato usando librerie come Pydantic in Python). Questo schema guida l’AI nell’identificare:
- Il tipo specifico di prodotto (product_type)
- La categoria principale all’interno dell’arredamento (category), scegliendo tra: Mobili, Illuminazione, Tessili per la casa, Decorazioni, Arredo bagno.
- I materiali (materials) e gli stili (style) predominanti, selezionandoli da liste predefinite.
- I colori principali (colors) con i loro nomi e codici esadecimali.
- La presenza di un logo (has_logo).
- Eventuali caratteristiche distintive (features).
- Un livello di confidenza (confidence) sull’analisi.
- Note aggiuntive (additional_notes).
Utilizzando un prompt “few-shot” che include questo schema dettagliato e un esempio, istruiamo l’AI a comportarsi come un esperto analista di immagini di arredamento e a restituire l’output nel formato JSON strutturato richiesto, pronto per essere elaborato automaticamente.
Definiamo ora un modello Pydantic per definire lo schema d’estrazione:
# Importare le librerie
from pydantic import BaseModel, Field
from typing import List, Optional
from typing import Literal
from datetime import datetime
from enum import Enum
#-----------------------------------------------
# CLASSI PER L'ANALISI DI PRODOTTI DI DESIGN
#----------------------------------------------
class Color(BaseModel):
name: str = Field(..., description="Nome del colore predominante (es. 'Rosso', 'Blu navy', 'Verde oliva')")
hex: str = Field(..., description="Codice esadecimale del colore (es. '#FF0000', '#000080', '#808000')")
class Material(str, Enum):
WOOD = "Legno"
METAL = "Metallo"
GLASS = "Vetro"
FABRIC = "Tessuto"
LEATHER = "Pelle"
CERAMIC = "Ceramica"
PLASTIC = "Plastica"
STONE = "Pietra"
OTHER = "Altro"
class Style(str, Enum):
MODERN = "Moderno"
CONTEMPORARY = "Contemporaneo"
INDUSTRIAL = "Industriale"
SCANDINAVIAN = "Scandinavo"
RUSTIC = "Rustico"
VINTAGE = "Vintage"
MINIMALIST = "Minimalista"
ECLECTIC = "Eclettico"
CLASSIC = "Classico"
ART_DECO = "Art Déco"
BOHEMIAN = "Boho"
FARMHOUSE = "Rustico Moderno"
OTHER = "Altro"
class ProductInfoArredamento(BaseModel):
product_type: str = Field(..., description="Tipo specifico di prodotto identificato (es. 'Divano angolare in pelle', 'Lampada da tavolo in ceramica', 'Mensola a muro in legno massello')")
category: Literal["Mobili", "Illuminazione", "Tessili per la casa", "Decorazioni", "Arredo bagno"] = Field(..., description="Categoria principale del prodotto di arredamento (uno tra: 'Mobili', 'Illuminazione', 'Tessili per la casa', 'Decorazioni', 'Arredo bagno')")
materials: Optional[List[Material]] = Field(None, description="Materiali principali del prodotto (es. ['Legno', 'Metallo'])")
style: Optional[List[Style]] = Field(None, description="Stili di design identificati nel prodotto (es. ['Moderno', 'Industriale'])")
colors: List[Color] = Field(default_factory=list, description="Elenco dei colori predominanti nel prodotto (es. [{'name': 'Grigio chiaro', 'hex': '#D3D3D3'}, {'name': 'Bianco', 'hex': '#FFFFFF'}])")
has_logo: bool = Field(..., description="Indica se il prodotto presenta un logo visibile (True se presente, False altrimenti)")
features: List[str] = Field(default_factory=list, description="Elenco delle caratteristiche speciali del prodotto (es. ['Reclinabile', 'Estensibile', 'Impermeabile', 'Con contenitore', 'A risparmio energetico'])")
confidence: float = Field(..., description="Livello di confidenza dell'analisi nell'identificazione del prodotto e delle sue caratteristiche (valore tra 0.0 e 1.0, dove 1.0 indica la massima confidenza)")
additional_notes: Optional[str] = Field(None, description="Note aggiuntive sull'analisi del prodotto. Descrizione del prodotto")
Cliccare per visualizzare lo schema JSON in dettaglio
{
"$defs": {
"Color": {
"properties": {
"name": {
"description": "Nome del colore predominante (es. 'Rosso', 'Blu navy', 'Verde oliva')",
"title": "Name",
"type": "string"
},
"hex": {
"description": "Codice esadecimale del colore (es. '#FF0000', '#000080', '#808000')",
"title": "Hex",
"type": "string"
}
},
"required": [
"name",
"hex"
],
"title": "Color",
"type": "object"
},
"Material": {
"enum": [
"Legno",
"Metallo",
"Vetro",
"Tessuto",
"Pelle",
"Ceramica",
"Plastica",
"Pietra",
"Altro"
],
"title": "Material",
"type": "string"
},
"Style": {
"enum": [
"Moderno",
"Contemporaneo",
"Industriale",
"Scandinavo",
"Rustico",
"Vintage",
"Minimalista",
"Eclettico",
"Classico",
"Art D\u00e9co",
"Boho",
"Rustico Moderno",
"Altro"
],
"title": "Style",
"type": "string"
}
},
"properties": {
"product_type": {
"description": "Tipo specifico di prodotto identificato (es. 'Divano angolare in pelle', 'Lampada da tavolo in ceramica', 'Mensola a muro in legno massello')",
"title": "Product Type",
"type": "string"
},
"category": {
"description": "Categoria principale del prodotto di arredamento (uno tra: 'Mobili', 'Illuminazione', 'Tessili per la casa', 'Decorazioni', 'Arredo bagno')",
"enum": [
"Mobili",
"Illuminazione",
"Tessili per la casa",
"Decorazioni",
"Arredo bagno"
],
"title": "Category",
"type": "string"
},
"materials": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/Material"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Materiali principali del prodotto (es. ['Legno', 'Metallo'])",
"title": "Materials"
},
"style": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/Style"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Stili di design identificati nel prodotto (es. ['Moderno', 'Industriale'])",
"title": "Style"
},
"colors": {
"description": "Elenco dei colori predominanti nel prodotto (es. [{'name': 'Grigio chiaro', 'hex': '#D3D3D3'}, {'name': 'Bianco', 'hex': '#FFFFFF'}])",
"items": {
"$ref": "#/$defs/Color"
},
"title": "Colors",
"type": "array"
},
"has_logo": {
"description": "Indica se il prodotto presenta un logo visibile (True se presente, False altrimenti)",
"title": "Has Logo",
"type": "boolean"
},
"features": {
"description": "Elenco delle caratteristiche speciali del prodotto (es. ['Reclinabile', 'Estensibile', 'Impermeabile', 'Con contenitore', 'A risparmio energetico'])",
"items": {
"type": "string"
},
"title": "Features",
"type": "array"
},
"confidence": {
"description": "Livello di confidenza dell'analisi nell'identificazione del prodotto e delle sue caratteristiche (valore tra 0.0 e 1.0, dove 1.0 indica la massima confidenza)",
"title": "Confidence",
"type": "number"
},
"additional_notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Note aggiuntive sull'analisi del prodotto",
"title": "Additional Notes"
}
},
"required": [
"product_type",
"category",
"has_logo",
"confidence"
],
"title": "ProductInfoArredamento",
"type": "object"
}Prompt d’inferenza del prodotto di design per il modello LLM
Per ottenere risultati efficaci a un LLM come Google Gemini, per inferire correttamente le informazioni dobbiamo fornire un prompt dettagliato e ben strutturato. Di seguito un esempio di prompt:
#---------------------------
# PROMPT DI SISTEMA
#---------------------------
# Per testare il prompt di sistema nel palyground copiare e incollare solamnete il testo
SYSTEM_PROMPT = """
# Sei un esperto analizzatore di immagini specializzato in prodotti di arredamento e design d'interni. Il tuo compito è analizzare l'immagine fornita e restituire un'analisi dettagliata in formato JSON, aderendo rigorosamente allo schema `ProductInfoArredamento`.
Analizza l'immagine del prodotto di arredamento fornita e restituisci le seguenti informazioni in un formato JSON strutturato secondo lo schema `ProductInfoArredamento`:
1. **product_type** (string, obbligatorio): Descrivi il tipo *specifico* di prodotto identificato (es. "Divano angolare in pelle", "Lampada da tavolo in ceramica", "Mensola a muro in legno massello").
2. **category** (string, obbligatorio): Specifica la categoria principale del prodotto scegliendo *ESCLUSIVAMENTE* tra le seguenti opzioni:
* Mobili
* Illuminazione
* Tessili per la casa
* Decorazioni
* Arredo bagno
3. **materials** (array di stringhe o null, opzionale): Elenca i materiali principali del prodotto, scegliendo dalla seguente lista definita (`$defs/Material`). Se non identificabili o non applicabile, restituisci `null`.
* Legno
* Metallo
* Vetro
* Tessuto
* Pelle
* Ceramica
* Plastica
* Pietra
* Altro
4. **style** (array di stringhe o null, opzionale): Identifica gli stili di design del prodotto, scegliendo dalla seguente lista definita (`$defs/Style`). Se non identificabili o non applicabile, restituisci `null`.
* Moderno
* Contemporaneo
* Industriale
* Scandinavo
* Rustico
* Vintage
* Minimalista
* Eclettico
* Classico
* Art Déco
* Boho
* Rustico Moderno
* Altro
5. **colors** (array di oggetti Color o null, opzionale): Fornisci un elenco dei colori predominanti nel prodotto. Ogni colore deve avere un oggetto con:
* `name`: Nome del colore (es. "Grigio chiaro").
* `hex`: Codice esadecimale (es. "#D3D3D3").
Se non identificabili o non applicabile, restituisci `null` o un array vuoto `[]`.
6. **has_logo** (boolean, obbligatorio): Indica se il prodotto presenta un logo visibile (`True` se presente, `False` altrimenti).
7. **features** (array di stringhe o null, opzionale): Elenca le caratteristiche speciali osservabili del prodotto (es. ["Reclinabile", "Estensibile", "Con contenitore", "A risparmio energetico"]). Se non presenti o non applicabile, restituisci `null` o un array vuoto `[]`.
8. **confidence** (number, obbligatorio): Fornisci un valore numerico (float) compreso tra 0.0 e 1.0 che indica la tua certezza nell'analisi complessiva (identificazione del prodotto e delle sue caratteristiche).
9. **additional_notes** (string o null, opzionale): Aggiungi eventuali note o osservazioni rilevanti non coperte dagli altri campi. Se non ci sono note, restituisci `null`.
---
## Esempio di Analisi
**Input Immagine (Descrizione Concettuale):** Una lampada da tavolo con base in ceramica bianca opaca e paralume in tessuto beige, stile moderno/scandinavo.
**Output JSON Atteso:**
```json
{
"product_type": "Lampada da tavolo",
"category": "Illuminazione",
"materials": ["Ceramica", "Tessuto"],
"style": ["Moderno", "Scandinavo"],
"colors": [
{"name": "Bianco", "hex": "#FFFFFF"},
{"name": "Beige", "hex": "#F5F5DC"}
],
"has_logo": false,
"features": ["Base in ceramica opaca", "Con tessuto decorativo"],
"confidence": 0.95,
"additional_notes": "Il paralume sembra essere di forma cilindrica..."
}
"""Per testare il prompt nel playground di Google Gemini seguire i seguenti passaggi:
- Accedere al Playground di Google AI Studio e accedere.
- Copiare e incollare il prompt contenete l’esempio JSON, nelle istruzioni di sistema
- Selezionale l’opzione per l’output strutturato JSON, nella sezione dei Tools.
- Se necessario, regolare i parametri del modello, temperatura e token massimi di output.
- Importare l’immagine e premere “Run”
- Verificare che la risposta sia nel formato desiderato, che il contenuto sia accurato e coerente.
- Rivedere e reiterare il prompt se l’output è errato o incompleto.
Cliccare per visualizzare l’analisi dell’immagine 1
{
"product_type": "Divano a due posti",
"category": "Mobili",
"materials": ["Tessuto"],
"style": ["Moderno"],
"colors": [
{
"name": "Blu",
"hex": "#4682B4"
}
],
"has_logo": false,
"features": ["Cuscini inclusi"],
"confidence": 0.9,
"additional_notes": "Il divano sembra avere un design confortevole e accogliente."
}Cliccare per visualizzare l’analisi dell’immagine 2
{
"product_type": "Divano a tre posti",
"category": "Mobili",
"materials": ["Tessuto"],
"style": ["Moderno"],
"colors": [
{
"name": "Blu",
"hex": "#191970"
},
{
"name": "Beige",
"hex": "#F5F5DC"
}
],
"has_logo": false,
"features": ["Cuscini inclusi"],
"confidence": 0.95,
"additional_notes": "Il divano presenta cuciture decorative a contrasto."
}Cliccare per visualizzare l’analisi dell’immagine 4
{
"product_type": "Divano a due posti in velluto",
"category": "Mobili",
"materials": ["Tessuto", "Legno"],
"style": ["Moderno"],
"colors": [
{
"name": "Blu",
"hex": "#00008B"
},
{
"name": "Grigio",
"hex": "#808080"
}
],
"has_logo": false,
"features": ["Gambe in legno"],
"confidence": 0.95,
"additional_notes": "Il divano ha un rivestimento in velluto blu e gambe sottili in legno."
}Cliccare per visualizzare l’analisi dell’immagine 3
{
"product_type": "Divano a tre posti in velluto",
"category": "Mobili",
"materials": ["Tessuto", "Legno"],
"style": ["Moderno"],
"colors": [
{
"name": "Blu",
"hex": "#000080"
},
{
"name": "Beige",
"hex": "#F5F5DC"
}
],
"has_logo": false,
"features": ["Gambe in legno"],
"confidence": 0.95,
"additional_notes": "Il divano ha un rivestimento in velluto blu e gambe in legno chiaro."
}Progettare una funzione di estrazione dati
Adesso, possiamo implementare una funzione che effettua il processo di analisi dell’immagine usando Google Gemini e restituisce la risposta strutturata secondo le nostre istruzioni e il nostro schema di estrazione definito.
#---------------------------
# FUNZIONE DI ANALISI
#---------------------------
# @title Definire la funzione di analisi
import base64
import os
from google import genai
from google.genai import types
import pydantic
def generate(image_path):
client = genai.Client(
api_key=os.environ.get("GEMINI_API_KEY"),
)
files = [
# Assicurarsi che il file sia disponibile nella directory di lavoro del sistema locale o modificare il percorso del file.
client.files.upload(file=image_path),
]
model = "gemini-2.0-flash"
contents = types.Content(
role="user",
parts=[
types.Part.from_uri(
file_uri=files[0].uri,
mime_type=files[0].mime_type,
),
types.Part.from_text(text="ANALIZZA IN MODO DETTAGLIATO L'IMMAGINE ALLEGATA CONSIDERA TUTTE LE CARATTERISTICHE DELL'OGGETTO")
],
)
generate_content_config = types.GenerateContentConfig(
temperature=0.5,
response_mime_type="application/json",
response_schema= ProductInfoArredamento,
system_instruction=[
types.Part.from_text(text= SYSTEM_PROMPT),
],
)
response = client.models.generate_content(
model=model,
contents=contents,
config=generate_content_config,
)
if response.text is not None:
try:
analysis_result = ProductInfoArredamento.model_validate_json(response.text)
except pydantic.ValidationError as e:
print(f"Error parsing JSON response: {e}")
return None
else:
print("Error: response.text is None. The API response might be empty.")
return None
return analysis_resultApplicazione partica
Di seguito si riporta un’applicazione pratica di quanto descritto nei paragrafi precedenti. Il video illustra un modello di analisi per l’estrazione di informazioni da immagini specifiche per il settore dell’arredamento divani.
Il modulo rappresenta un modello di analisi; tuttavia, può essere trasformato in un’applicazione o servizio digitale (API) integrabile in servizi software o siti web su richiesta dell’utente, offrendo una maggiore flessibilità per soddisfare esigenze specifiche.
Questa trasformazione consente agli sviluppatori di personalizzare le funzionalità dell’API in base ai requisiti del progetto, facilitando così l’interazione tra diverse piattaforme e migliorando l’esperienza utente complessiva. Inoltre, la possibilità di integrare questo servizio in vari contesti, come e-commerce, strumenti di collaborazione o sistemi CRM, permette di ampliare ulteriormente le potenzialità offerte, garantendo soluzioni innovative e scalabili nel tempo.
