Složité vzory: vnořené seznamy, výčty, unie
Na této stránce
Složité vzory: vnořené seznamy, výčty, unie
Jednoduché případy extrakce (plochý objekt s textovými poli) se řeší snadno. Skutečné výzvy přicházejí se složitými strukturami: seznamy vnořených objektů, podmíněné typy a polymorfní pole. Tato lekce ti ukáže, jak navrhnout robustní schémata pro tyto pokročilé případy.
Vnořené seznamy
Nejčastějším vzorem v produkci je extrakce seznamu objektů, kde každý objekt obsahuje vlastní podseznamy. Schéma níže popisuje vzdělávací program se třemi úrovněmi: objekt programu s názvem a délkou trvání, pole modulů, z nichž každý má název a textové cíle, a nakonec lekce pro každý modul, popsané názvem, délkou v minutách a typem omezeným pomocí enum.
To, co musí model zvládnout, jde nad rámec pouhého čtení: musí přiřadit každou lekci ke správnému modulu, což znamená, že musí pochopit hierarchii, která je někdy vyjádřena pouze úrovněmi nadpisů. Proto jsou na třetí úrovni velmi konkrétní pole – délka v minutách místo obecného „trvání“, které je někdy vyjádřeno v hodinách, jindy v sezeních. Čím přesnější jsou listové uzly stromu, tím méně model váhá.
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
}
Výčty pro omezení hodnot
Výčty (enums) jsou nejspolehlivějším způsobem, jak omezit možné hodnoty pole. Strukturovaný výstup je aplikuje na úrovni generování: na rozdíl od instrukce napsané v promptu je nelze ignorovat ani ve dnech statistické únavy. To z nich činí cenný nástroj, když extrahovaná hodnota napájí příkaz switch, indexovaný sloupec nebo směrovací pravidlo – tři místa, kde neočekávaná hodnota nezpůsobí tvrdou chybu, ale spíše ticho.
Následující schéma klasifikace třídí příchozí požadavky podél čtyř os: categorie_principale určuje příslušné oddělení, sous_categorie jej upřesňuje v rámci tohoto oddělení, priorite slouží k řazení fronty a action_requise určuje, co s tiketem dělat. Jeden bod návrhu si zaslouží pozornost: dvanáct hodnot sous_categorie je zploštěno, nikoli připojeno k jejich nadřazené kategorii, protože striktní režim nenabízí podmíněnou závislost mezi dvěma enum. Nic tedy nebrání kombinaci „juridique“ a „recrutement“ a tuto konzistenci je třeba ověřit až po přijetí.
# 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
}
Simulace typových unií
JSON Schema podporuje anyOf pro podmíněné typy, ale striktní strukturovaný výstup OpenAI má omezení. Doporučený vzor používá diskriminační pole: definuješ jeden objekt dostatečně široký na pokrytí všech případů a pole type indikuje, který z nich popisuješ.
# 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
}
Trikem je učinit jakékoli pole specifické pro jediný typ jako nullable pomocí notace "type": ["string", "null"]". Pro schůzku jsou pole participantsalieuvyplněna; pro připomenutí mají hodnotunull. Tvůj kód pak nejprve přečte diskriminátor a okamžitě ví, které klíče dávají smysl – přesně tak, jak bys četl označenou unii v typovaném jazyce. Cena, kterou zaplatíš – upovídanější schéma a nutnost zpracovávat null` – zůstává preferovatelná oproti třem samostatným voláním.
Rekurzivní objekty
Pro stromové struktury – menu, organizační schémata, vlákna diskusí – použij $defs pro rekurzivní reference. Princip spočívá v pojmenování opakujícího se tvaru jednou a následné odkazování na něj zevnitř sebe sama. Zde komentář obsahuje pole odpovědí, kde každý prvek je zase komentářem: hloubka není pevně stanovena v době zápisu, následuje hloubku analyzovaného dokumentu. Je to jediný rozumný způsob, jak zpracovat vlákno diskuse bez předchozí znalosti, zda má dvě úrovně odpovědí nebo sedm.
# 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
}
}
}
Vzor: extrakce více entit
Když text obsahuje více typů entit, pokušení spustit jednu extrakci pro každou rodinu je velké. Schéma pro více entit dělá více: vyžaduje osoby, organizace, data a částky v jediném průchodu. Přínos není jen v úspoře volání; model vidí text jednou a může propojit to, co v něm najde – přiřadit osobu k její organizaci, spojit částku s kontextem, který jí dává smysl.
Duplikace u dat, date_brute a date_iso, si zaslouží být ve tvých schématech zachována tak, jak je: zachovává původní formulaci pro audit a zároveň poskytuje normalizovanou hodnotu. Pole contexte, přítomné u dat i částek, hraje stejnou roli: bez něj nikdo neví, zda 12 000 eur byla nabídka, pokuta nebo roční rozpočet.
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
}
Osvědčené postupy pro složitá schémata
Čtyři návyky zabrání většině zklamání. Začni jednoduše: ověř plochý objekt na svých reálných datech před přidáním jakéhokoli vnoření, jinak nezjistíš, zda selhání pochází ze schématu, nebo z obtížnosti úkolu. Dále se vzdej volitelného pole, které striktní režim zakazuje, a místo toho jej učiň nullable. Také respektuj empirický limit – beyond tři nebo čtyři úrovně vnoření kvalita klesá a je lepší rozdělit extrakci do dvou průchodů: nejprve seznam modulů, pak jedno volání na modul pro detailní popis jeho lekcí. Nakonec měj na paměti rozdělení práce: schéma a jeho výčty omezují strukturu, systémový prompt řídí obsah. Pokud model správně třídí, ale extrahuje špatné informace, je to prompt, který musíš upravit.
Případ, který testuje vše: organizační schéma
Zabývej se rekurzivním případem, nejnaučnější částí lekce. Definuj schéma pro extrakci organizačního schématu společnosti, kde každý zaměstnanec může mít podřízené, kteří jsou sami zaměstnanci. Otestuj jej na textu popisujícím organizaci patnácti až dvaceti lidí, napsaném prózou, nikoli jako seznam: zde musí model odvodit reportingové linie z frází jako „reportuje“ nebo „v týmu“.
Ověř, zda jsou hierarchické vztahy správně vnořeny, a dávej pozor na lidi zmíněné daleko od jejich manažera – to je obvyklý bod zlomu. Nakonec přidej výčty pro role (vedení, management, operativní pracovníci) a pozoruj, zda omezení zlepší, nebo zhorší reportingovou linii: vynucení kategorizace může modelu pomoci, nebo jej na hybridních profilech tlačit k libovolným volbám.
Klíčové poznatky
- Vnořené seznamy jsou nejčastějším vzorem v produkci
- Výčty se aplikují na úrovni generování – využívej je
- Simuluj unie pomocí diskriminačního pole a nullable polí
$defsumožňuje rekurzivní struktury (komentáře, stromy)- Omez hloubku vnoření na 3–4 úrovně