Wzorce złożone: listy zagnieżdżone, wyliczenia, sumy typów
Na tej stronie
- Wzorce złożone: listy zagnieżdżone, wyliczenia, sumy typów
- Listy zagnieżdżone
- Wyliczenia (Enums) do ograniczania wartości
- Symulowanie sum typów (unions)
- Obiekty rekurencyjne
- Wzorzec: ekstrakcja wielu encji
- Najlepsze praktyki dla złożonych schematów
- Przypadek, który testuje wszystko: schemat organizacyjny
- Kluczowe wnioski
Wzorce złożone: listy zagnieżdżone, wyliczenia, sumy typów
Proste przypadki ekstrakcji (płaski obiekt z polami tekstowymi) są łatwe do obsłużenia. Prawdziwe wyzwania pojawiają się przy złożonych strukturach: listach zagnieżdżonych obiektów, typach warunkowych i polach polimorficznych. Ta lekcja pokaże Ci, jak projektować odporne schematy dla tych zaawansowanych przypadków.
Listy zagnieżdżone
Najczęstszym wzorcem w środowisku produkcyjnym jest ekstrakcja listy obiektów, gdzie każdy obiekt zawiera własne podlisty. Poniższy schemat opisuje program szkoleniowy z trzema poziomami: obiekt programu z tytułem i czasem trwania, tablica modułów, z których każdy ma tytuł i cele tekstowe, oraz wreszcie lekcje dla każdego modułu, opisane tytułem, czasem trwania w minutach i typem ograniczonym przez enum.
To, co model musi tutaj osiągnąć, wykracza poza czytanie: musi przypisać każdą lekcję do właściwego modułu, co oznacza, że musi zrozumieć hierarchię, czasami przekazywaną wyłącznie przez poziomy nagłówków. Stąd bardzo konkretne pola na trzecim poziomie – czas trwania w minutach, a nie ogólnikowe „czas trwania“ wyrażany raz w godzinach, a raz w sesjach. Im precyzyjniejsze są liście drzewa, tym mniej model się waha.
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
}
Wyliczenia (Enums) do ograniczania wartości
Wyliczenia (enums) to najpewniejszy sposób na ograniczenie możliwych wartości pola. Ustrukturyzowane wyjście (Structured Output) stosuje je na poziomie generowania: w przeciwieństwie do instrukcji zapisanej w prompcie, nie można ich zignorować w dniu statystycznego zmęczenia modelu. Makes them cenne, gdy wyekstrahowana wartość zasila instrukcję switch, kolumnę indeksowaną lub regułę routingu – w trzech miejscach, gdzie nieoczekiwana wartość nie powoduje twardego błędu, lecz raczej ciszę.
Poniższy schemat klasyfikacji sortuje przychodzące zgłoszenia wzdłuż czterech osi: categorie_principale lokalizuje właściwy dział, sous_categorie doprecyzowuje go w ramach tego działu, priorite służy do sortowania kolejki, a action_requise określa, co zrobić z biletem. Jeden punkt projektowy zasługuje na uwagę: dwanaście wartości sous_categorie jest spłaszczonych, a nie przypisanych do ich kategorii nadrzędnej, ponieważ tryb ścisły nie oferuje warunkowej zależności między dwoma enum. Nic więc nie przeszkadza w połączeniu „juridique“ i „recrutement“, a tę spójność należy zweryfikować po odebraniu danych.
# 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
}
Symulowanie sum typów (unions)
JSON Schema obsługuje anyOf dla typów warunkowych, ale ścisłe Ustrukturyzowane Wyjście OpenAI ma ograniczenia. Zalecanym wzorcem jest użycie pola dyskryminatora: definiujesz pojedynczy obiekt, wystarczająco szeroki, aby objąć wszystkie przypadki, a pole type wskazuje, który z nich opisujesz.
# 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
}
Sztuczka polega na uczynieniu każdego pola specyficznego dla pojedynczego typu jako nullable, używając notacji "type": ["string", "null"]. Dla spotkania pola participants i lieu są wypełnione; dla przypomnienia równe są null. Twój kod najpierw odczytuje dyskryminator i natychmiast wie, które klucze mają sens – dokładnie tak, jak czytałbyś sumę typów z tagiem (tagged union) w języku typowanym. Cena, jaką płacisz, to bardziej rozwlekły schemat i konieczność obsługi null, co jednak pozostaje preferowalne wobec trzech osobnych wywołań.
Obiekty rekurencyjne
Dla struktur drzewiastych – menu, schematów organizacyjnych, wątków dyskusyjnych – użyj $defs do odwołań rekurencyjnych. Zasada polega na nazwaniu powtarzającego się kształtu raz, a następnie odwołaniu się do niego z jego wnętrza. Tutaj komentarz zawiera tablicę odpowiedzi, gdzie każdy element jest z kolei komentarzem: głębokość nie jest ustalana w czasie pisania, lecz podąża za głębokością analizowanego dokumentu. To jedyny rozsądny sposób na przetworzenie wątku dyskusji bez wcześniejszej wiedzy, czy ma on dwa poziomy odpowiedzi, czy siedem.
# 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
}
}
}
Wzorzec: ekstrakcja wielu encji
Gdy tekst zawiera wiele typów encji, pokusa polega na uruchomieniu jednej ekstrakcji na rodzinę. Schemat wielu encji robi to lepiej: żąda osób, organizacji, dat i kwot w jednym przebiegu. Korzyścią nie jest tylko oszczędność wywołań; chodzi o to, że model widzi tekst raz i może powiązać to, co w nim znajdzie – przypisując osobę do jej organizacji, łącząc kwotę z kontekstem, który nadaje jej znaczenie.
Duplikacja przy datach, date_brute i date_iso, zasługuje na pozostawienie jej w Twoich własnych schematach w takiej formie: zachowuje oryginalne sformułowanie do celów audytowych, zapewniając jednocześnie znormalizowaną wartość. Pole contexte, obecne przy datach i kwotach, odgrywa tę samą rolę: bez niego nikt nie będzie wiedział, czy 12 000 euro to była wycena, kara czy budżet roczny.
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
}
Najlepsze praktyki dla złożonych schematów
Cztery nawyki pozwalają uniknąć większości rozczarowań. Zacznij od prostoty: zwaliduj płaski obiekt na swoich rzeczywistych danych przed dodaniem jakiegokolwiek zagnieżdżenia, w przeciwnym razie nie dowiesz się, czy niepowodzenie wynika ze schematu, czy z trudności zadania. Następnie zrezygnuj z pola opcjonalnego, którego tryb ścisły zabrania, i zamiast tego uczyń je nullable. Przestrzegaj również empirycznego limitu – poza trzema lub czterema poziomami zagnieżdżenia jakość spada i lepiej jest podzielić ekstrakcję na dwa przebiegi: najpierw lista modułów, potem jedno wywołanie na moduł w celu uszczegółowienia jego lekcji. Wreszcie, miej na uwadze podział pracy: schemat i jego enumy ograniczają strukturę, prompt systemowy kieruje treścią. Jeśli model sortuje poprawnie, ale ekstrahuje niewłaściwe informacje, to prompt wymaga dostrojenia.
Przypadek, który testuje wszystko: schemat organizacyjny
Zajmij się przypadkiem rekurencyjnym, najbardziej edukacyjną częścią lekcji. Zdefiniuj schemat do ekstrakcji schematu organizacyjnego firmy, gdzie każdy pracownik może mieć podwładnych, którzy sami są pracownikami. Przetestuj go na tekście opisującym organizację piętnastu do dwudziestu osób, napisanym prozą, a nie jako lista: to tutaj model musi wywnioskować linie raportowania z fraz takich jak „raportuje do“ lub „w zespole“.
Zweryfikuj, czy relacje hierarchiczne są poprawnie zagnieżdżone, uważając na osoby wspomniane daleko od ich menedżera – to zazwyczaj punkt krytyczny. Na koniec dodaj enumy dla ról (kierownictwo wyższe, zarządzanie średnie szczebla, pracownicy operacyjni) i obserwuj, czy ograniczenie poprawia, czy pogarsza linię raportowania: wymuszenie kategoryzacji może pomóc modelowi lub popchnąć go ku arbitralnym wyborom w przypadku profili hybrydowych.
Kluczowe wnioski
- Listy zagnieżdżone to najczęstszy wzorzec w środowisku produkcyjnym
- Enumy są stosowane na poziomie generowania – wykorzystaj to
- Symuluj sumy typów za pomocą pola dyskryminatora i pól nullable
$defsumożliwia struktury rekurencyjne (komentarze, drzewa)- Ogranicz głębokość zagnieżdżenia do 3–4 poziomów