Modele complexe: liste imbricate, enumerații, uniuni
Pe această pagină
Modele complexe: liste imbricate, enumerații, uniuni
Cazurile simple de extracție (un obiect plat cu câmpuri text) sunt ușor de gestionat. Adevăratele provocări apar odată cu structurile complexe: liste de obiecte imbricate, tipuri condiționale și câmpuri polimorfe. Această lecție vă arată cum să proiectați scheme robuste pentru aceste cazuri avansate.
Liste imbricate
Cel mai frecvent model în producție implică extragerea unei liste de obiecte în care fiecare obiect conține propriile sale sub-liste. Schema de mai jos descrie un program de formare cu trei niveluri: obiectul program cu titlul și durata sa, un tablou de module fiecare având un titlu și obiective text, și în final lecțiile pentru fiecare modul, descrise printr-un titlu, o durată în minute și un tip constrâns de o enum.
Ceea ce modelul trebuie să reușească aici depășește simpla citire: trebuie să atașeze fiecare lecție modulului corect, ceea ce înseamnă că trebuie să înțeleagă o ierarhie uneori transmisă doar prin nivelurile de titluri. De aici necesitatea unor câmpuri foarte concrete la al treilea nivel—o durată în minute în loc de o „durată“ generică exprimată uneori în ore, alteori în sesiuni. Cu cât nodurile frunză ale arborelui sunt mai precise, cu atât modelul ezită mai puțin.
import json
from openai import OpenAI
client = OpenAI()
# Schema: extrage un program de formare cu module și lecții
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
}
Enumerații pentru constrângerea valorilor
Enumerațiile sunt cea mai fiabilă metodă de a limita valorile posibile ale unui câmp. Structured Output le aplică la nivelul generării: spre deosebire de o instrucțiune scrisă în prompt, ele nu pot fi ignorate într-o zi de oboseală statistică. Acest lucru le face valoroase atunci când valoarea extrasă alimentează o instrucțiune switch, o coloană indexată sau o regulă de rutare—trei locuri unde o valoare neașteptată nu provoacă o eroare fatală, ci mai degrabă tăcere.
Schema de clasificare care urmează sortează cererile primite pe patru axe: categorie_principale localizează departamentul relevant, sous_categorie îl rafinează în cadrul acelui departament, priorite servește la sortarea cozii, iar action_requise determină ce trebuie făcut cu tichetul. Un punct de design merită atenție: cele douăsprezece valori ale lui sous_categorie sunt aplatizate în loc să fie atașate categoriei lor părinte, deoarece modul strict nu oferă dependență condițională între două enum. Nimic nu împiedică deci combinația „juridique“ și „recrutement“, iar această consistență trebuie verificată după recepție.
# Sistem de clasificare multi-nivel
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
}
Simularea uniunilor de tipuri
JSON Schema suportă anyOf pentru tipuri condiționale, dar Structured Output strict de la OpenAI are limitări. Modelul recomandat este utilizarea unui câmp discriminator: definiți un singur obiect, suficient de larg pentru a acoperi toate cazurile, iar un câmp type indică pe care îl descrieți.
# Model: un eveniment poate fi o întâlnire, o sarcină sau o reamintire
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
}
Trucul constă în a face orice câmp specific unui singur tip nulabil, folosind notația "type": ["string", "null"]. Pentru o întâlnire, participants și lieu sunt completate; pentru o reamintire, ele egalează null. Codul dumneavoastră citește apoi mai întâi discriminatorul și știe imediat care chei au sens—exact citirea pe care ați face-o unei uniuni etichetate într-un limbaj tipizat. Prețul de plătit, o schemă mai verbose și valori null de gestionat, rămâne preferabil față de trei apeluri separate.
Obiecte recursive
Pentru structuri de tip arbore—meniuri, organigrame, fire de discuție—utilizați $defs pentru referințe recursive. Principiul este de a numi forma repetitivă o singură dată, apoi de a o referenția din interiorul ei însăși. Aici, un comentariu conține un tablou de răspunsuri unde fiecare element este la rândul său un comentariu: adâncimea nu este fixată la momentul scrierii, ci urmează cea a documentului analizat. Aceasta este singura modalitate rezonabilă de a procesa un fir de discuție fără a ști dinainte dacă are două niveluri de răspunsuri sau șapte.
# Structura unui comentariu cu răspunsuri imbricate
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
}
}
}
Model: extracție multi-entitate
Când un text conține multiple tipuri de entități, tentația este de a rula o extracție per familie. Schema multi-entitate face mai bine: solicită persoane, organizații, date și sume într-o singură trecere. Beneficiul nu este doar economisirea apelurilor; este faptul că modelul vede textul o singură dată și poate relaționa ceea ce găsește acolo—atașând o persoană de organizația sa, asociind o sumă cu contextul care îi dă sens.
Duplicarea privind datele, date_brute și date_iso, merită păstrată așa cum este în propriile scheme: aceasta păstrează formularea originală pentru audit, oferind în același timp o valoare normalizată. Câmpul contexte, prezent la date și sume, joacă același rol: fără el, nimeni nu va ști dacă 12.000 de euro au fost un deviz, o penalizare sau un buget anual.
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
}
Cele mai bune practici pentru scheme complexe
Patru obiceiuri evită majoritatea dezamăgirilor. Începeți simplu: validați un obiect plat pe datele dumneavoastră reale înainte de a adăuga orice imbricare, altfel nu veți ști dacă un eșec provine din schemă sau din dificultatea sarcinii. În continuare, renunțați la câmpul opțional, pe care modul strict îl interzice, și faceți-l în schimb nulabil. Respectați, de asemenea, o limită empirică—dincolo de trei sau patru niveluri de imbricare calitatea scade, și este mai bine să împărțiți extracția în două treceri: mai întâi lista modulelor, apoi un apel per modul pentru a detalia lecțiile sale. În final, țineți cont de diviziunea muncii: schema și enumerațiile sale constrâng structura, promptul de sistem ghidează conținutul. Dacă modelul sortează corect dar extrage informațiile greșite, promptul este cel pe care trebuie să îl ajustați.
Cazul care testează totul: organigrama
Abordați cazul recursiv, partea cea mai educativă a lecției. Definiți o schemă pentru a extrage organigrama unei companii, unde fiecare angajat poate avea subordonați care sunt la rândul lor angajați. Testați-o pe un text care descrie o organizație de cincisprezece până la douăzeci de persoane, scris în proză și nu sub formă de listă: aici modelul trebuie să deducă liniile de raportare din fraze precum „raportează către“ sau „în cadrul echipei lui“.
Verificați dacă relațiile ierarhice sunt corect imbricate, având grijă la persoanele menționate departe de managerul lor—acesta este punctul obișnuit de rupere. În final, adăugați enumerații pe roluri (executiv, management, operațional) și observați dacă constrângerea îmbunătățește sau degradează linia de raportare: forțarea unei categorizări poate ajuta modelul sau îl poate împinge către alegeri arbitrare în cazul profilurilor hibride.
Puncte cheie
- Listele imbricate sunt cel mai frecvent model în producție
- Enumerațiile sunt aplicate la nivelul generării—exploatați-le
- Simulați uniunile cu un câmp discriminator și câmpuri nulabile
$defspermite structuri recursive (comentarii, arbori)- Limitați adâncimea de imbricare la 3-4 niveluri