Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Mustrid keerukatele juhtumitele: pesastatud loendid, loendid, liit tüübid

Õppetund 12 / 16 Värskendatud 28. juuli 2026 Arendajatele
Sellel lehel
  1. Mustrid keerukatele juhtumitele: pesastatud loendid, loendid, liit tüübid
  2. Pesastatud loendid
  3. Väärtuste piiramine enumidega
  4. Liit tüüpide simuleerimine
  5. Rekursiivsed objektid
  6. Muster: mitme üksuse ekstraheerimine
  7. Parimad tavad keerukate skeemide jaoks
  8. Juhtum, mis paneb kõige proovile: organisatsiooniskeem
  9. Peamised punktid

Mustrid keerukatele juhtumitele: pesastatud loendid, loendid, liit tüübid

Lihtsad ekstraheerimisjuhtumid (lame objekt tekstiväljadega) on kerge lahendada. Tõelised väljakutsed tekivad keerukate struktuuridega: pesastatud objektide loendid, tingimuslikud tüübid ja polümorfsed väljad. Selles õppetükis näitame, kuidas nende täiustatud juhtumite jaoks kavandada töökindlaid skeeme.

Pesastatud loendid

Tootmiskeskkonnas on kõige levinum muster ekstraheerida objektide loend, kus iga objekt sisaldab omakorda alamloendeid. Allpool olev skeem kirjeldab koolitusprogrammi kolmel tasandil: programmiobjekt pealkirja ja kestusega, moodulite massiiv, millest ühel on pealkiri ja tekstilised eesmärgid, ning lõpuks iga mooduli tunnid, mida kirjeldavad pealkiri, kestus minutites ja tüüp, mida piirab enum.

See, milles mudel siin peab edu saavutama, läheb kaugemale lugemisest: see peab siduma iga tunni õige mooduliga, mis tähendab, et see peab mõistma hierarhiat, mida vahel edastavad ainult pealkirjade tasemed. Seetõttu on kolmanda taseme väljad väga konkreetsed – kestus minutites, mitte üldine “kestus”, mida väljendatakse kord tundides, kord sessioonides. Mida täpsemad on puu lehesõlmed, seda vähem mudel kõhkleb.

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äärtuste piiramine enumidega

Enumid on kõige usaldusväärsem viis välja võimalike väärtuste piiramiseks. Structured Output rakendab neid genereerimise tasandil: erinevalt vihjes kirjutatud juhisest ei saa neid statistilise väsimuse päeval eirata. See teeb need väärtuslikuks, kui ekstraheeritud väärtus toidab switch-lause, indekseeritud veeru või suunamisreegli – kolm kohta, kus ootamatu väärtus ei põhjusta kriitilist viga, vaid pigem vaikust.

Järgnev klassifitseerimisskeem sorteerib sissetulevad taotlused nelja telje järgi: categorie_principale leiab asjakohase osakonna, sous_categorie täpsustab seda selle osakonna sees, priorite teenib järjekorra sorteerimist ja action_requise määrab, mida piletiga ette võtta. Üks kujunduspunkt väärib tähelepanu: sous_categorie kaksteist väärtust on lamestatud, mitte seotud oma ema-kategooriaga, kuna range režiim ei paku tingimuslikku sõltuvust kahe enumi vahel. Seega ei takista miski kombinatsiooni “juridique” ja “recrutement” ning seda järjepidevust tuleb kontrollida pärast vastuvõttu.

# 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
}

Liit tüüpide simuleerimine

JSON Schema toetab tingimuslike tüüpide jaoks anyOf-d, kuid OpenAI range Structured Output-il on piirangud. Soovitatud muster on kasutada diskriminaatorvälja: defineerid ühe objekti, mis on piisavalt lai, et katta kõik juhtumid, ja väli type näitab, millist neist sa kirjeldad.

# 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
}

Nipp on muuta iga üksikule tüübile omane väli nullitavaks, kasutades notatsiooni "type": ["string", "null"]. Koosoleku puhul on participants ja lieu täidetud; meeldetuletuse puhul on need võrdsed null-iga. Sinu kood loeb esmalt diskriminaatori ja teab kohe, millised võtmed on mõttekad – täpselt nii, nagu loeksid sildistatud liitu tüübitud keeles. Hind, mida tuleb maksta – sõnaohtram skeem ja käsitletavad null-väärtused – on eelistatav kolmele eraldiseisvale väljakutsele.

Rekursiivsed objektid

Puustruktuuride (menüüd, organisatsiooniskeemid, arutelulõimed) jaoks kasuta rekursiivsete viidete jaoks $defs-i. Põhimõte on nimetada korduv kuju üks kord ja viidata sellele siis seestpoolt iseendale. Siin sisaldab kommentaar vastuste massiivi, kus iga element on omakorda kommentaar: sügavus ei ole kirjutamise ajal fikseeritud, see järgib analüüsitava dokumendi sügavust. See on ainus mõistlik viis töödelda arutelulõnga, teadmata ette, kas sellel on kaks või seitse vastusetaset.

# 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
        }
    }
}

Muster: mitme üksuse ekstraheerimine

Kui tekst sisaldab mitut tüüpi üksusi, on kiusatus teha iga perekonna jaoks eraldi ekstraheerimine. Mitme üksuse skeem teeb seda paremini: see nõuab inimesi, organisatsioone, kuupäevi ja summasid ühe läbimisega. Kasu ei seisne mitte ainult väljakutsete säästmises; see on selles, et mudel näeb teksti üks kord ja saab seostada seda, mida ta seal leiab – sidudes inimese tema organisatsiooniga, seostades summa kontekstiga, mis annab sellele tähenduse.

Kuupäevade dubleerimine, date_brute ja date_iso, väärib sinu enda skeemides alles jätmist: see säilitab auditeerimiseks algse sõnastuse, pakkudes samal ajal normaliseeritud väärtust. Väli contexte, mis esineb nii kuupäevadel kui ka summadel, mängib sama rolli: ilma selleta ei tea keegi, kas 12 000 eurot oli pakkumine, trahv või aastaeelarve.

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
}

Parimad tavad keerukate skeemide jaoks

Neli harjumust väldivad enamikku pettumustest. Alusta lihtsast: valideeri lame objekt oma reaalsetel andmetel enne mis tahes pesastamise lisamist, muidu ei tea sa, kas ebaõnnestumine tuleneb skeemist või ülesande raskusest. Järgmiseks loobu valikulisest väljast, mida range režiim keelab, ja tee selle asemel see nullitavaks. Samuti austa empiirilist piiri – üle kolme või nelja pesastamistaseme kvaliteet langeb ja parem on jagada ekstraheerimine kaheks läbimiseks: esmalt moodulite loend, seejärel üks väljakutse mooduli kohta selle tundide detailsuseks. Lõpuks pea meeles tööjaotust: skeem ja selle enumid piiravad struktuuri, süsteemi vihje juhendab sisu. Kui mudel sorteerib õigesti, kuid ekstraheerib vale teabe, on see vihje, mida pead kohandama.

Juhtum, mis paneb kõige proovile: organisatsiooniskeem

Võta ette rekursiivne juhtum, õppetüki harivaim osa. Defineeri skeem ettevõtte organisatsiooniskeemi ekstraheerimiseks, kus igal töötajal võivad olla alluvad, kes on ise samuti töötajad. Testi seda tekstil, mis kirjeldab viieteistkümne kuni kahekümne inimese organisatsiooni, kirjutatuna proosana, mitte loendina: just siin peab mudel järeldama aruandlusliine fraasidest nagu “aru annab” või “meeskonnas”.

Kontrolli, kas hierarhilised seosed on õigesti pesastatud, pidades silmas inimesi, keda mainitakse kaugel nende juhatajast – see on tavaline purunemispunkt. Lõpuks lisa rollidele enumid (juhtkond, management, operatiivtöö) ja vaata, kas piirang parandab või halvendab aruandlusliini: kategoriseerimise sundimine võib mudelit aidata või suruda seda hübriidprofiilide puhul meelevaldsete valikute tegemisele.

Peamised punktid

  • Pesastatud loendid on tootmiskeskkonnas kõige levinum muster
  • Enume rakendatakse genereerimise tasandil – kasuta neid ära
  • Simuleeri liite diskriminaatorvälja ja nullitavate väljadega
  • $defs võimaldab rekursiivseid struktuure (kommentaarid, puud)
  • Piira pesastamise sügavust 3–4 tasemeni