Сложни шаблони: вложени списъци, изброими типове, обединения
На тази страница
- Сложни шаблони: вложени списъци, изброими типове, обединения
- Вложени списъци
- Изброими типове (Enums) за ограничаване на стойностите
- Симулиране на обединения от типове
- Рекурсивни обекти
- Шаблон: извличане на множество entities
- Най-добри практики за сложни схеми
- Случаят, който тества всичко: организационната схема
- Ключови изводи
Сложни шаблони: вложени списъци, изброими типове, обединения
Простите случаи на извличане (плосък обект с текстови полета) се обработват лесно. Истинските предизвикателства възникват при сложни структури: списъци с вложени обекти, условни типове и полиморфни полета. Този урок Ви показва как да проектирате надеждни схеми за тези усъвършенствани случаи.
Вложени списъци
Най-честият шаблон в продукционна среда включва извличане на списък от обекти, където всеки обект съдържа свои собствени подсписъци. Схемата по-долу описва учебна програма с три нива: обектът на програмата със заглавие и продължителност, масив от модули, всеки със заглавие и текстови цели, и накрая уроците за всеки модул, описани чрез заглавие, продължителност в минути и тип, ограничен от enum.
Това, което моделът трябва да постигне тук, надхвърля простото четене: той трябва да прикачи всеки урок към правилния модул, което означава, че трябва да разбере йерархия, понякога предадена само чрез нивата на заглавията. Затова са необходими много конкретни полета на третото ниво – продължителност в минути, вместо общо „продължителност“, изразявана ту в часове, ту в сесии. Колкото по-точни са листовите възли на дървото, толкова по-малко моделът се колебае.
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
}
Изброими типове (Enums) за ограничаване на стойностите
Изброимите типове (enums) са най-надеждният начин за ограничаване на възможните стойности на дадено поле. Structured Output ги прилага на ниво генериране: за разлика от инструкция, написана в подкана (prompt), те не могат да бъдат игнорирани в ден на статистическа умора. Това ги прави ценни, когато извлечената стойност захранва оператор switch, индексирана колона или правило за насочване – три места, където неочаквана стойност не причинява фатална грешка, а по-скоро тишина.
Схемата за класификация, която следва, сортира входящите заявки по четири оси: categorie_principale локализира съответния отдел, sous_categorie го уточнява в рамките на този отдел, priorite служи за сортиране на опашката, а action_requise определя какво да се прави с тикета. Един проектантски детайл заслужава внимание: дванадесетте стойности на sous_categorie са изравнени, вместо да бъдат прикачени към родителската им категория, защото строгият режим не предлага условна зависимост между два enum. Нищо следователно не пречи на комбинацията „juridique“ и „recrutement“ и тази съгласуваност трябва да се провери след получаване.
# 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
}
Симулиране на обединения от типове
JSON Schema поддържа anyOf за условни типове, но строгият Structured Output на OpenAI има ограничения. Препоръчителният шаблон е да използвате поле за дискриминатор: дефинирате един обект, достатъчно широк, за да покрие всички случаи, а поле type указва кой от тях описвате.
# 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
}
Трикът е да направите всяко поле, специфично за един тип, допускащо нулева стойност (nullable), използвайки нотацията "type": ["string", "null"]. За среща participants и lieu са попълнени; за напомняне те са равни на null. Вашият код след това чете първо дискриминатора и веднага знае кои ключове имат смисъл – точно както бихте прочели тагирано обединение в типизиран език. Цената, която плащате – по-многословна схема и обработване на null стойности – остава за предпочитане пред три отделни извиквания.
Рекурсивни обекти
За дървовидни структури – менюта, организационни схеми, дискусионни нишки – използвайте $defs за рекурсивни препратки. Принципът е да именувате повтарящата се форма веднъж и след това да я реферирате от самата нея. Тук един коментар съдържа масив от отговори, където всеки елемент от своя страна е коментар: дълбочината не е фиксирана по време на писане, тя следва тази на анализирания документ. Това е единственият разумен начин за обработка на дискусионна нишка, без да знаете предварително дали има две нива на отговори или седем.
# 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
}
}
}
Шаблон: извличане на множество entities
Когато един текст съдържа множество типове entities, изкушението е да се стартира едно извличане за всяко семейство. Схемата за множество entities прави повече: тя изисква хора, организации, дати и суми в един единствен проход. Ползата не е само спестяването на извиквания; тя е в това, че моделът вижда текста веднъж и може да свърже това, което открива там – прикачвайки човек към неговата организация, асоциирайки сума с контекста, който ѝ придава смисъл.
Дублирането при датите, date_brute и date_iso, заслужава да се запази такова, каквото е във Вашите собствени схеми: то запазва оригиналния израз за одит, като същевременно предоставя нормализирана стойност. Полето contexte, присъстващо при датите и сумите, играе същата роля: без него никой няма да знае дали 12 000 евро са били оферта, глоба или годишен бюджет.
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
}
Най-добри практики за сложни схеми
Четири навика избягват повечето разочарования. Започнете просто: валидирайте плосък обект върху Вашите реални данни, преди да добавите каквото и да е влагане, в противен случай няма да знаете дали неуспехът идва от схемата или от трудността на задачата. След това се откажете от незадължителното поле, което строгият режим забранява, и го направете вместо това допускащо нулева стойност (nullable). Също така спазвайте емпиричен лимит – отвъд три или четири нива на влагане качеството спада и е по-добре да разделите извличането на два прохода: първо списъкът с модулите, след това едно извикване на модул за детайлизиране на неговите уроци. Накрая, имайте предвид разделението на труда: схемата и нейните изброими типове ограничават структурата, системната подкана (system prompt) насочва съдържанието. Ако моделът сортира правилно, но извлича грешна информация, това е подканата, която трябва да коригирате.
Случаят, който тества всичко: организационната схема
Започнете с рекурсивния случай, най-поучителната част от урока. Дефинирайте схема за извличане на организационна схема на компания, където всеки служител може да има подчинени, които самите те са служители. Тествайте я върху текст, описващ организация от петнадесет до двадесет души, написан в проза, а не като списък: тук моделът трябва да изведе линиите на докладване от фрази като „докладва на“ или „в екипа на“.
Проверете дали йерархичните връзки са правилно вложени, като внимавате за хора, споменати далеч от техния мениджър – това е обичайната точка на прекъсване. Накрая, добавете изброими типове (enums) за роли (ръководител, мениджър, оперативен служител) и наблюдавайте дали ограничението подобрява или влошава линията на докладване: принуждаването на категоризация може да помогне на модела или да го тласне към произволни избори при хибридни профили.
Ключови изводи
- Вложените списъци са най-честият шаблон в продукционна среда
- Изброимите типове (Enums) се прилагат на ниво генериране – използвайте ги
- Симулирайте обединения с поле за дискриминатор и полета, допускащи нулева стойност
$defsпозволява рекурсивни структури (коментари, дървета)- Ограничете дълбочината на влагане до 3-4 нива