Mallit monimutkaisiin rakenteisiin: sisäkkäiset listat, enumit ja unionit
Tällä sivulla
- Mallit monimutkaisiin rakenteisiin: sisäkkäiset listat, enumit ja unionit
- Sisäkkäiset listat
- Arvojen rajoittaminen enumeilla
- Tyyppiyhdistelmien simulointi
- Rekursiiviset objektit
- Malli: monientiteettinen poiminta
- Parhaat käytännöt monimutkaisille skeemoille
- Kaiken testaava tapaus: organisaatiokaavio
- Keskeiset asiat
Mallit monimutkaisiin rakenteisiin: sisäkkäiset listat, enumit ja unionit
Yksinkertaiset tiedonpoimintatapaukset (litteä objekti, jossa on tekstikenttiä) ovat helppoja käsitellä. Todelliset haasteet alkavat monimutkaisista rakenteista: sisäkkäisistä objektilistoista, ehdollisista tyypeistä ja polymorfisista kentistä. Tässä oppitunnissa opit suunnittelemaan vahvoja skeemoja näihin edistyneisiin tapauksiin.
Sisäkkäiset listat
Yleisin tuotantoympäristössä käytetty malli liittyy objektien listan poimimiseen siten, että jokainen objekti sisältää omat alilistansa. Alla oleva skeema kuvaa koulutusohjelmaa kolmella tasolla: ohjelmaobjekti otsikoineen ja kestoineen, moduulien taulukko, jossa kullakin on otsikko ja tekstimuotoiset tavoitteet, sekä lopuksi kunkin moduulin oppitunnit, jotka kuvaillaan otsikolla, kestolla minuutteina ja tyypillä, jota rajoittaa enum.
Tässä mallin on onnistuttava enemmän kuin pelkässä lukemisessa: sen on liitettävä jokainen oppitunti oikeaan moduuliin, mikä tarkoittaa, että sen on ymmärrettävä hierarkia, joka välittyy joskus vain otsikkotasoilla. Siksi puun lehtisolmut ovat erittäin konkreettisia – kesto minuutteina yleisen “keston” sijaan, joka voi olla ilmaistu joskus tunteina, joskus sessioina. Mitä tarkempia puun lehtisolmut ovat, sitä vähemmän malli epäröi.
import json
from openai import OpenAI
client = OpenAI()
# Schema: extract a training program with modules and lessons
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
}
Arvojen rajoittaminen enumeilla
Enumit ovat luotettavin tapa rajoittaa kentän mahdollisia arvoja. Structured Output soveltaa niitä generointitasolla: toisin kuin kehotteeseen kirjoitettu ohje, niitä ei voi ignoroida tilastollisen väsymyksen päivinä. Tämä tekee niistä arvokkaita, kun poimittu arvo syötetään switch-lauseeseen, indeksoituun sarakkeeseen tai reivityssääntöön – kolmeen paikkaan, joissa odottamaton arvo ei aiheuta kovaa virhettä, vaan hiljaisuuden.
Seuraava luokitteluskeema lajittelee saapuvat pyynnöt neljällä akselilla: categorie_principale paikantaa asianomaisen osaston, sous_categorie tarkentaa sitä kyseisen osaston sisällä, priorite palvelee jonon lajittelua ja action_requise määrittää, mitä tiketille tehdään. Yksi suunnittelukohta ansaitsee huomiota: sous_categorie-kentän kaksitoista arvoa on litistetty niiden sijaan, että ne olisi liitetty pääluokkaansa, koska tiukka tila ei tarjoa ehdollista riippuvuutta kahden enum-arvon välillä. Mikään ei siis estä yhdistelmää “juridique” ja “recrutement”, ja tämä johdonmukaisuus on varmistettava vastaanoton jälkeen.
# Multi-level classification system
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
}
Tyyppiyhdistelmien simulointi
JSON Schema tukee anyOf:ää ehdollisille tyypeille, mutta OpenAI:n tiukalla Structured Outputilla on rajoituksia. Suositeltu malli on käyttää erottelukenttää (discriminator): määrittelet yhden objektin, joka on tarpeeksi laaja kattamaan kaikki tapaukset, ja type-kenttä ilmoittaa, kumpaa kuvailet.
# Pattern: an event can be a meeting, a task, or a reminder
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
}
Temppu on tehdä mikä tahansa yksittäiselle tyypille ominainen kenttä null-arvoiseksi käyttämällä merkintää "type": ["string", "null"]. Kokouksessa participants ja lieu täytetään; muistutuksessa ne ovat null. Koodisi lukee ensin erottelukentän ja tietää heti, mitkä avaimet ovat järkeviä – täsmälleen saman lukemisen, jonka tekisit taggatulle unionille tyypitetyssä kielessä. Maksettava hinta, eli laajempi skeema ja käsiteltävät null-arvot, on kuitenkin edullisempi kuin kolme erillistä kutsua.
Rekursiiviset objektit
Puurakenteita varten – kuten valikot, organisaatiokaaviot tai keskusteluketjut – käytä $defs:ää rekursiivisiin viittauksiin. Periaate on nimetä toistuva muoto kerran ja viitata siihen sen sisältä käsin. Tässä kommentti sisältää taulukon vastauksia, joista jokainen alkiosta on puolestaan kommentti: syvyys ei ole kiinteä kirjoitushetkellä, vaan se seuraa analysoitavan asiakirjan syvyyttä. Tämä on ainoa järkevä tapa käsitellä keskusteluketjua tietämättä etukäteen, onko siinä kaksi vai seitsemän vastaus tasoa.
# Structure of a comment with nested replies
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
}
}
}
Malli: monientiteettinen poiminta
Kun teksti sisältää useita entiteettityyppejä, kiusaus on suorittaa yksi poiminta per ryhmä. Monientiteettinen skeema toimii paremmin: se pyytää henkilöitä, organisaatioita, päivämääriä ja summia yhdellä ajokerralla. Hyöty ei ole vain kutsujen säästämisessä; se on siinä, että malli näkee tekstin kerran ja voi yhdistää löytämänsä asiat – liittää henkilön organisaatioonsa tai yhdistää summan kontekstiin, joka antaa sille merkityksen.
Päivämäärien osalta tapahtuva kaksoiskappale, date_brute ja date_iso, kannattaa pitää skeemoissasi sellaisenaan: se säilyttää alkuperäisen muotoilun tarkastusta varten ja tarjoaa samalla normalisoidun arvon. Kenttä contexte, joka esiintyy sekä päivämäärissä että summissa, plays samaa roolia: ilman sitä kukaan ei tiedä, oliko 12 000 euroa tarjous, sakko vai vuosibudjetti.
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
}
Parhaat käytännöt monimutkaisille skeemoille
Neljä tapaa välttää useimmat pettymykset. Aloita yksinkertaisesti: valido litteä objekti todellisilla datallasi ennen minkään sisäkkäisyyden lisäämistä, muuten et tiedä, johtuuko virhe skeemasta vai tehtävän vaikeudesta. Seuraavaksi luovu valinnaisesta kentästä, jonka tiukka tila kieltää, ja tee siitä sen sijaan null-arvoinen. Kunnioita myös empiiristä rajaa – yli kolmen tai neljän sisäkkäisyystason laatu heikkenee, ja on parempi jakaa poiminta kahteen vaiheeseen: ensin moduulien lista, sitten yksi kutsu per moduuli sen oppituntien yksityiskohtiin. Lopuksi pidä mielessä työnjako: skeema ja sen enumit rajoittavat rakennetta, järjestelmäkehote ohjaa sisältöä. Jos malli lajittelee oikein mutta poimii väärää tietoa, kehotetta on hienosäädettävä.
Kaiken testaava tapaus: organisaatiokaavio
Tartu rekursiiviseen tapaukseen, joka on oppitunnin opettavaisin osa. Määrittele skeema yrityksen organisaatiokaavion poimimiseksi siten, että jokaisella työntekijällä voi olla alaisia, jotka ovat itsekin työntekijöitä. Testaa sitä tekstillä, joka kuvaa 15–20 hengen organisaatiota proosamuodossa eikä listana: tässä mallin on pääteltävä raportointisuhteet fraaseista kuten “reports to” tai “within the team of”.
Varmista, että hierarkkiset suhteet on sisäkkäistetty oikein, ja kiinnitä huomiota ihmisiin, jotka mainitaan kaukana esimiehestään – tämä on tavallinen katkoispiste. Lisää lopuksi enumit rooleille (johto, esimiestyö, operatiivinen) ja tarkkaile, parantaako rajoite raportointisuhteita vai heikentääkö se niitä: kategorisoinnin pakottaminen voi auttaa mallia tai työntää sen mielivaltaisiin valintoihin hybridi-profiilien kohdalla.
Keskeiset asiat
- Sisäkkäiset listat ovat yleisin malli tuotantoympäristössä
- Enumit sovelletaan generointitasolla – hyödynnä niitä
- Simuloi unionit erottelukentällä ja null-arvoisilla kentillä
$defsmahdollistaa rekursiiviset rakenteet (kommentit, puut)- Rajoita sisäkkäisyystaso 3–4 tasoon