Modelli complessi: liste annidate, enum, unioni
In questa pagina
Modelli complessi: liste annidate, enum, unioni
I casi di estrazione semplici (un oggetto piatto con campi di testo) sono facili da gestire. Le vere sfide arrivano con strutture complesse: liste di oggetti annidati, tipi condizionali e campi polimorfici. Questa lezione ti mostra come progettare schemi robusti per questi casi avanzati.
Liste annidate
Il modello più comune in produzione consiste nell’estrarre una lista di oggetti dove ogni oggetto contiene a sua volta delle sotto-liste. Lo schema qui sotto descrive un programma di formazione su tre livelli: l’oggetto programma con il suo titolo e la sua durata, un array di moduli ciascuno con un titolo e degli obiettivi testuali, e infine le lezioni per ogni modulo, descritte da un titolo, una durata in minuti e un tipo vincolato da un enum.
Ciò che il modello deve riuscire a fare qui va oltre la semplice lettura: deve associare ogni lezione al modulo corretto, il che significa che deve comprendere una gerarchia talvolta trasmessa solo dai livelli dei titoli. Da qui la necessità di campi molto concreti al terzo livello: una durata in minuti piuttosto che una generica “durata” espressa a volte in ore, a volte in sessioni. Più i nodi foglia dell’albero sono precisi, meno il modello esita.
import json
from openai import OpenAI
client = OpenAI()
# Schema: estrai un programma di formazione con moduli e lezioni
formation_schema = {
"type": "object",
"properties": {
"titre": {"type": "string"},
"duree_totale_heures": {"type": "number"},
"modules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"titre_module": {"type": "string"},
"objectifs": {
"type": "array",
"items": {"type": "string"}
},
"lecons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"titre_lecon": {"type": "string"},
"duree_minutes": {"type": "integer"},
"type": {
"type": "string",
"enum": ["theorie", "pratique",
"évaluation"]
}
},
"required": ["titre_lecon",
"duree_minutes", "type"],
"additionalProperties": False
}
}
},
"required": ["titre_module", "objectifs", "lecons"],
"additionalProperties": False
}
}
},
"required": ["titre", "duree_totale_heures", "modules"],
"additionalProperties": False
}
Enum per vincolare i valori
Gli enum sono il modo più affidabile per limitare i valori possibili di un campo. L’Output Strutturato li applica a livello di generazione: a differenza di un’istruzione scritta nel prompt, non possono essere ignorati in un giorno di affaticamento statistico. Questo li rende preziosi quando il valore estratto alimenta un’istruzione switch, una colonna indicizzata o una regola di routing: tre luoghi dove un valore inaspettato non causa un errore bloccante, ma piuttosto il silenzio.
Lo schema di classificazione che segue ordina le richieste in arrivo lungo quattro assi: categorie_principale individua il dipartimento pertinente, sous_categorie lo raffina all’interno di quel dipartimento, priorite serve per l’ordinamento della coda e action_requise determina cosa fare con il ticket. Un punto di progettazione merita attenzione: i dodici valori di sous_categorie sono appiattiti piuttosto che allegati alla loro categoria genitore, perché la modalità strict non offre dipendenze condizionali tra due enum. Nulla impedisce quindi la combinazione “juridique” e “recrutement”, e questa coerenza deve essere verificata dopo la ricezione.
# Sistema di classificazione multilivello
classification_schema = {
"type": "object",
"properties": {
"categorie_principale": {
"type": "string",
"enum": ["technique", "commercial", "juridique",
"rh", "finance"]
},
"sous_categorie": {
"type": "string",
"enum": [
"bug", "feature", "performance",
"devis", "facturation", "contrat",
"recrutement", "conge", "formation",
"budget", "audit", "conformite"
]
},
"priorite": {
"type": "string",
"enum": ["critique", "haute", "moyenne", "basse"]
},
"action_requise": {
"type": "string",
"enum": ["repondre", "escalader", "archiver",
"planifier", "deleguer"]
}
},
"required": ["categorie_principale", "sous_categorie",
"priorite", "action_requise"],
"additionalProperties": False
}
Simulare le unioni di tipi
JSON Schema supporta anyOf per i tipi condizionali, ma l’Output Strutturato strict di OpenAI ha delle limitazioni. Il modello consigliato è usare un campo discriminatore: definisci un singolo oggetto, abbastanza ampio da coprire tutti i casi, e un campo type indica quale stai descrivendo.
# Modello: un evento può essere una riunione, un compito o un promemoria
event_schema = {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["reunion", "tache", "rappel"]
},
"titre": {"type": "string"},
"date": {"type": "string"},
"heure_debut": {"type": ["string", "null"]},
"heure_fin": {"type": ["string", "null"]},
"participants": {
"type": "array",
"items": {"type": "string"}
},
"lieu": {"type": ["string", "null"]},
"priorite": {
"type": ["string", "null"],
"enum": ["haute", "moyenne", "basse", None]
},
"description": {"type": "string"}
},
"required": ["type", "titre", "date", "heure_debut",
"heure_fin", "participants", "lieu",
"priorite", "description"],
"additionalProperties": False
}
Il trucco consiste nel rendere nullable qualsiasi campo specifico di un singolo tipo, usando la notazione "type": ["string", "null"]. Per una riunione, participants e lieu sono compilati; per un promemoria, equivalgono a null. Il tuo codice legge quindi prima il discriminatore e sa immediatamente quali chiavi hanno senso: esattamente la lettura che faresti di un’unione etichettata in un linguaggio tipizzato. Il prezzo da pagare, uno schema più verboso e dei null da gestire, rimane preferibile a tre chiamate separate.
Oggetti ricorsivi
Per le strutture ad albero—menu, organigrammi, thread di discussione—usa $defs per i riferimenti ricorsivi. Il principio è nominare la forma ripetuta una volta sola, quindi riferirla da dentro se stessa. Qui, un commento contiene un array di risposte dove ogni elemento è a sua volta un commento: la profondità non è fissata al momento della scrittura, segue quella del documento analizzato. Questo è l’unico modo ragionevole per elaborare un thread di discussione senza sapere in anticipo se ha due livelli di risposte o sette.
# Struttura di un commento con risposte annidate
comment_schema = {
"type": "object",
"properties": {
"commentaires": {
"type": "array",
"items": {"$ref": "#/$defs/comment"}
}
},
"required": ["commentaires"],
"additionalProperties": False,
"$defs": {
"comment": {
"type": "object",
"properties": {
"auteur": {"type": "string"},
"contenu": {"type": "string"},
"sentiment": {
"type": "string",
"enum": ["positif", "negatif", "neutre"]
},
"reponses": {
"type": "array",
"items": {"$ref": "#/$defs/comment"}
}
},
"required": ["auteur", "contenu", "sentiment",
"reponses"],
"additionalProperties": False
}
}
}
Modello: estrazione multi-entità
Quando un testo contiene più tipi di entità, la tentazione è eseguire un’estrazione per famiglia. Lo schema multi-entità fa di meglio: richiede persone, organizzazioni, date e importi in un’unica passata. Il vantaggio non è solo risparmiare chiamate; è che il modello vede il testo una volta sola e può mettere in relazione ciò che vi trova—associando una persona alla sua organizzazione, collegando un importo al contesto che gli dà significato.
La duplicazione sulle date, date_brute e date_iso, merita di essere mantenuta così com’è nei tuoi schemi: preserva la formulazione originale per l’audit fornendo al contempo un valore normalizzato. Il campo contexte, presente su date e importi, svolge lo stesso ruolo: senza di esso, nessuno saprà se 12.000 euro erano un preventivo, una penalità o un budget annuale.
multi_entity_schema = {
"type": "object",
"properties": {
"personnes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nom": {"type": "string"},
"role": {"type": "string"},
"organisation": {"type": ["string", "null"]}
},
"required": ["nom", "role", "organisation"],
"additionalProperties": False
}
},
"organisations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nom": {"type": "string"},
"type": {
"type": "string",
"enum": ["entreprise", "association",
"administration", "autre"]
},
"secteur": {"type": ["string", "null"]}
},
"required": ["nom", "type", "secteur"],
"additionalProperties": False
}
},
"dates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date_brute": {"type": "string"},
"date_iso": {"type": "string"},
"contexte": {"type": "string"}
},
"required": ["date_brute", "date_iso", "contexte"],
"additionalProperties": False
}
},
"montants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"valeur": {"type": "number"},
"devise": {"type": "string"},
"contexte": {"type": "string"}
},
"required": ["valeur", "devise", "contexte"],
"additionalProperties": False
}
}
},
"required": ["personnes", "organisations", "dates", "montants"],
"additionalProperties": False
}
Best practice per schemi complessi
Quattro abitudini evitano la maggior parte delle delusioni. Inizia semplice: valida un oggetto piatto sui tuoi dati reali prima di aggiungere qualsiasi annidamento, altrimenti non saprai se un fallimento deriva dallo schema o dalla difficoltà del compito. Successivamente, rinuncia al campo opzionale, che la modalità strict proibisce, e rendilo invece nullable. Rispetta anche un limite empirico: oltre tre o quattro livelli di annidamento la qualità cala, ed è meglio dividere l’estrazione in due passate: prima la lista dei moduli, poi una chiamata per modulo per dettagliarne le lezioni. Infine, tieni a mente la divisione dei compiti: lo schema e i suoi enum vincolano la struttura, il prompt di sistema guida il contenuto. Se il modello ordina correttamente ma estrae le informazioni sbagliate, è il prompt che devi modificare.
Il caso che mette tutto alla prova: l’organigramma
Affronta il caso ricorsivo, la parte più educativa della lezione. Definisci uno schema per estrarre l’organigramma di un’azienda, dove ogni dipendente può avere subordinati che sono a loro volta dipendenti. Testalo su un testo che descrive un’organizzazione di quindici-venti persone, scritto in prosa e non come lista: è qui che il modello deve inferire le linee di reporting da frasi come “riporta a” o “all’interno del team di”.
Verifica che le relazioni gerarchiche siano correttamente annidate, facendo attenzione alle persone menzionate lontano dal loro manager: questo è il solito punto di rottura. Infine, aggiungi enum sui ruoli (dirigente, management, operativo) e osserva se il vincolo migliora o degrada la linea di reporting: forzare una categorizzazione può aiutare il modello o spingerlo verso scelte arbitrarie su profili ibridi.
Punti chiave
- Le liste annidate sono il modello più comune in produzione
- Gli enum sono applicati a livello di generazione: sfruttali
- Simula le unioni con un campo discriminatore e campi nullable
$defsabilita le strutture ricorsive (commenti, alberi)- Limita la profondità di annidamento a 3-4 livelli