Mönster komplexa: nästlade listor, enumereringar, unioner
På denna sida
Mönster komplexa: nästlade listor, enumereringar, unioner
Enkla extraheringsfall (ett platt objekt med textfält) är lätta att hantera. De verkliga utmaningarna dyker upp vid komplexa strukturer: nästlade listor med objekt, villkorliga typer och polymorfa fält. Den här lektionen visar hur du designar robusta scheman för dessa avancerade fall.
Nästlade listor
Det vanligaste mönstret i produktion innebär att extrahera en lista med objekt där varje objekt innehåller sina egna underlistor. Schemat nedan beskriver ett utbildningsprogram med tre nivåer: programobjektet med titel och varaktighet, en array av moduler som var och en har en titel och textmål, och slutligen lektionerna för varje modul, beskrivna av en titel, en varaktighet i minuter och en typ begränsad av en enum.
Det modellen måste lyckas med här går bortom läsning: den måste koppla varje lektion till rätt modul, vilket innebär att den måste förstå en hierarki som ibland bara förmedlas genom rubriknivåer. Därför de mycket konkreta fälten på tredje nivån – en varaktighet i minuter snarare än en generell “varaktighet” som uttrycks ibland i timmar, ibland i sessioner. Ju mer precisa lövnoderna i trädet är, desto mindre tvekar modellen.
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
}
Enumereringar för att begränsa värden
Enumereringar (enums) är det mest tillförlitliga sättet att begränsa de möjliga värdena för ett fält. Strukturerad utdata tillämpar dem på generationsnivå: till skillnad från en instruktion skriven i prompten kan de inte ignoreras en dag av statistisk trötthet. Detta gör dem värdefulla när det extraherade värdet matar in i ett switch-uttryck, en indexerad kolumn eller en routningsregel – tre platser där ett oväntat värde inte orsakar ett hårt fel, utan snarare tystnad.
Klassificeringsschemat som följer sorterar inkommande förfrågningar längs fyra axlar: categorie_principale lokaliserar relevant avdelning, sous_categorie förfinar den inom avdelningen, priorite används för kösortering och action_requise avgör vad som ska göras med ärendet. En designpunkt förtjänar uppmärksamhet: de tolv värdena för sous_categorie är utplattade snarare än kopplade till sin överordnade kategori, eftersom strikt läge inte erbjuder villkorligt beroende mellan två enum. Inget hindrar därför kombinationen “juridique” och “recrutement”, och denna konsistens måste verifieras efter mottagandet.
# 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
}
Simulera typunioner
JSON Schema stöder anyOf för villkorliga typer, men OpenAIs strikta strukturerade utdata har begränsningar. Det rekommenderade mönstret är att använda ett diskriminatorfält: du definierar ett enda objekt, brett nog att täcka alla fall, och ett type-fält indikerar vilket du beskriver.
# 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
}
Tricket är att göra varje fält specifikt för en enda typ nullable, med notationen "type": ["string", "null"]. För ett möte fylls participants och lieu i; för en påminnelse är de lika med null. Din kod läser sedan diskriminatorn först och vet omedelbart vilka nycklar som är meningsfulla – exakt den läsning du skulle göra av en taggad union i ett typat språk. Priset att betala, ett mer utförligt schema och null-värden att hantera, är ändå att föredra framför tre separata anrop.
Rekursiva objekt
För trädstrukturer – menyer, organisationsdiagram, diskussionstrådar – använd $defs för rekursiva referenser. Principen är att namnge den återkommande formen en gång, och sedan referera till den inifrån sig själv. Här innehåller en kommentar en array av svar där varje element i sin tur är en kommentar: djupet är inte fixerat vid skrivtid, det följer det analyserade dokumentets djup. Detta är det enda rimliga sättet att bearbeta en diskussionstråd utan att i förväg veta om den har två svarsnivåer eller sju.
# 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
}
}
}
Mönster: extrahering av flera entiteter
När en text innehåller flera typer av entiteter är frestelsen stor att köra en extrahering per familj. Schemat för flera entiteter gör det bättre: det begär personer, organisationer, datum och belopp i ett enda pass. Fördelen är inte bara att spara anrop; det är att modellen ser texten en gång och kan relatera det den hittar där – koppla en person till deras organisation, associera ett belopp med den kontext som ger det mening.
Duplikationen på datum, date_brute och date_iso, förtjänar att behållas som den är i dina egna scheman: den bevarar den ursprungliga formuleringen för granskning samtidigt som den tillhandahåller ett normaliserat värde. Fältet contexte, som finns på datum och belopp, spelar samma roll: utan det kommer ingen att veta om 12 000 euro var en offert, ett vite eller en årsbudget.
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
}
Bästa praxis för komplexa scheman
Fyra vanor undviker de flesta besvikelser. Börja enkelt: validera ett platt objekt på dina verkliga data innan du lägger till någon nästling, annars vet du inte om ett fel kommer från schemat eller uppgiftens svårighetsgrad. Ge sedan upp det valfria fältet, vilket strikt läge förbjuder, och gör det nullable istället. Respektera också en empirisk gräns – bortom tre eller fyra nivåer av nästling sjunker kvaliteten, och det är bättre att dela upp extraheringen i två pass: först listan över moduler, sedan ett anrop per modul för att detaljera dess lektioner. Ha slutligen arbetsfördelningen i åtanke: schemat och dess enumereringar begränsar strukturen, systemprompten styr innehållet. Om modellen sorterar korrekt men extraherar fel information, är det prompten du behöver justera.
Fallet som testar allt: organisationsdiagrammet
Ta dig an det rekursiva fallet, den mest lärorika delen av lektionen. Definiera ett schema för att extrahera ett företags organisationsdiagram, där varje anställd kan ha underordnade som i sin tur är anställda. Testa det på en text som beskriver en organisation på femton till tjugo personer, skriven i prosa och inte som en lista: här måste modellen härleda rapporteringslinjer från fraser som “rapporterar till” eller “inom teamet för”.
Verifiera att hierarkiska relationer är korrekt nästlade, och håll utkik efter personer som nämns långt ifrån sin chef – detta är den vanliga brytpunkten. Lägg slutligen till enumereringar på roller (ledningsgrupp, chefer, operativ personal) och observera om begränsningen förbättrar eller försämrar rapporteringslinjen: att tvinga fram en kategorisering kan hjälpa modellen eller knuffa den mot godtyckliga val för hybrida profiler.
Viktiga punkter
- Nästlade listor är det vanligaste mönstret i produktion
- Enumereringar tillämpas på generationsnivå – utnyttja dem
- Simulera unioner med ett diskriminatorfält och nullable-fält
$defsmöjliggör rekursiva strukturer (kommentarer, träd)- Begränsa nästlingsdjupet till 3–4 nivåer