Komplexe Muster: verschachtelte Listen, Enums, Unionen
Auf dieser Seite
Komplexe Muster: verschachtelte Listen, Enums, Unionen
Einfache Extraktionsfälle (ein flaches Objekt mit Textfeldern) sind leicht zu handhaben. Die echten Herausforderungen treten mit komplexen Strukturen auf: verschachtelte Objektlisten, bedingte Typen und polymorphe Felder. In dieser Lektion zeigen wir Ihnen, wie Sie robuste Schemas für diese fortgeschrittenen Fälle entwerfen.
Verschachtelte Listen
Das häufigste Muster in der Produktion umfasst das Extrahieren einer Liste von Objekten, wobei jedes Objekt seine eigenen Unterlisten enthält. Das folgende Schema beschreibt ein Schulungsprogramm mit drei Ebenen: das Programm-Objekt mit Titel und Dauer, ein Array von Modulen, jedes mit Titel und Text-Zielen, und schließlich die Lektionen für jedes Modul, beschrieben durch einen Titel, eine Dauer in Minuten und einen Typ, der durch eine enum eingeschränkt ist.
Was das Modell hier erfolgreich leisten muss, geht über das reine Lesen hinaus: Es muss jede Lektion dem korrekten Modul zuordnen, was bedeutet, dass es eine Hierarchie verstehen muss, die manchmal nur durch Überschriftenebenen vermittelt wird. Daher sind die sehr konkreten Felder auf der dritten Ebene entscheidend – eine Dauer in Minuten statt einer generischen „Dauer”, die manchmal in Stunden, manchmal in Sitzungen ausgedrückt wird. Je präziser die Blattknoten des Baums sind, desto weniger zögert das Modell.
import json
from openai import OpenAI
client = OpenAI()
# Schema: Extrahieren eines Schulungsprogramms mit Modulen und Lektionen
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 zur Einschränkung von Werten
Enums sind der zuverlässigste Weg, um die möglichen Werte eines Feldes einzuschränken. Strukturierte Ausgabe wendet sie auf der Generierungsebene an: Im Gegensatz zu einer im Prompt formulierten Anweisung können sie an einem Tag der statistischen Ermüdung nicht ignoriert werden. Dies macht sie wertvoll, wenn der extrahierte Wert eine switch-Anweisung, eine indizierte Spalte oder eine Routing-Regel speist – drei Bereiche, in denen ein unerwarteter Wert keinen harten Fehler verursacht, sondern eher Stille.
Das folgende Klassifizierungsschema sortert eingehende Anfragen entlang von vier Achsen: categorie_principale lokalisiert die relevante Abteilung, sous_categorie verfeinert diese innerhalb der Abteilung, priorite dient der Warteschlangensortierung und action_requise bestimmt, was mit dem Ticket zu tun ist. Ein Designpunkt verdient Aufmerksamkeit: Die zwölf Werte von sous_categorie werden abgeflacht und nicht ihrer übergeordneten Kategorie zugeordnet, da Strict Mode keine bedingte Abhängigkeit zwischen zwei enums bietet. Es ist daher nichts, was die Kombination „juridique” und „recrutement” verhindert, und diese Konsistenz muss nach der Ankunft verifiziert werden.
# Mehrstufiges Klassifizierungssystem
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
}
Simulation von Typunionen
JSON Schema unterstützt anyOf für bedingte Typen, aber OpenAIs strikte Strukturierte Ausgabe hat Einschränkungen. Das empfohlene Muster besteht darin, ein Diskriminator-Feld zu verwenden: Sie definieren ein einzelnes Objekt, breit genug, um alle Fälle abzudecken, und ein type-Feld zeigt an, welches Sie beschreiben.
# Muster: Ein Ereignis kann eine Besprechung, eine Aufgabe oder eine Erinnerung sein
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
}
Der Trick besteht darin, jedes Feld, das für einen einzelnen Typ spezifisch ist, als nullable zu definieren, unter Verwendung der Notation "type": ["string", "null"]. Für eine Besprechung sind participants und lieu ausgefüllt; für eine Erinnerung sind sie gleich null. Ihr Code liest dann zuerst den Diskriminator und weiß sofort, welche Schlüssel Sinn ergeben – genau das, was Sie bei einer tagged union in einer typisierten Sprache tun würden. Der Preis, ein ausführlicheres Schema und nulls zu verarbeiten, bleibt vorzuziehen gegenüber drei separaten Aufrufen.
Rekursive Objekte
Für Baumstrukturen – Menüs, Organigramme, Diskussionsfäden – verwenden Sie $defs für rekursive Verweise. Das Prinzip besteht darin, die sich wiederholende Form einmal zu benennen und dann von sich selbst aus darauf zu verweisen. Hier enthält ein Kommentar ein Array von Antworten, wobei jedes Element wiederum ein Kommentar ist: Die Tiefe ist zum Schreibzeitpunkt nicht festgelegt; sie folgt der des analysierten Dokuments. Dies ist der einzige vernünftige Weg, um einen Diskussionsfaden zu verarbeiten, ohne vorher zu wissen, ob er zwei Ebenen von Antworten oder sieben hat.
# Struktur eines Kommentars mit verschachtelten Antworten
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: Extraktion mehrerer Entitäten
Wenn ein Text mehrere Arten von Entitäten enthält, ist die Versuchung groß, eine Extraktion pro Familie durchzuführen. Das Schema für mehrere Entitäten leistet besser: Es fordert Personen, Organisationen, Daten und Beträge in einem Durchgang an. Der Vorteil besteht nicht nur in der Einsparung von Aufrufen; vielmehr sieht das Modell den Text einmal und kann das, was es dort findet, in Beziehung setzen – eine Person ihrer Organisation zuordnen, einen Betrag dem Kontext zuordnen, der ihm Bedeutung verleiht.
Die Duplizierung bei Daten, date_brute und date_iso, verdient es, in Ihren eigenen Schemas so belassen zu werden: Sie bewahrt die ursprüngliche Formulierung für die Prüfung auf, während sie einen normalisierten Wert bereitstellt. Das contexte-Feld, das bei Daten und Beträgen vorhanden ist, spielt dieselbe Rolle: Ohne es weiß niemand, ob 12.000 Euro ein Angebot, eine Strafe oder ein Jahresbudget waren.
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
}
Best Practices für komplexe Schemas
Vier Gewohnheiten vermeiden die meisten Enttäuschungen. Beginnen Sie einfach: Validieren Sie ein flaches Objekt auf Ihren echten Daten, bevor Sie jede Verschachtelung hinzufügen, sonst werden Sie nicht wissen, ob ein Fehler vom Schema oder von der Schwierigkeit der Aufgabe stammt. Geben Sie dann auf das optionale Feld auf, das Strict Mode untersagt, und machen Sie es stattdessen nullable. Beachten Sie auch eine empirische Grenze – jenseits von drei oder vier Ebenen der Verschachtelung sinkt die Qualität, und es ist besser, die Extraktion in zwei Durchgänge aufzuteilen: zuerst die Liste der Module, dann einen Aufruf pro Modul, um die Details seiner Lektionen zu erläutern. Denken Sie schließlich an die Arbeitsteilung: Das Schema und seine Enums beschränken die Struktur, der System-Prompt leitet den Inhalt. Wenn das Modell korrekt sortiert, aber die falschen Informationen extrahiert, müssen Sie den Prompt anpassen.
Der Fall, der alles testet: das Organigramm
Greifen Sie den rekursiven Fall an, den lehrreichsten Teil der Lektion. Definieren Sie ein Schema, um ein Firmenorganigramm zu extrahieren, bei dem jeder Mitarbeiter Unterordinate haben kann, die ihrerseits Mitarbeiter sind. Testen Sie es an einem Text, der eine Organisation von fünfzehn bis zwanzig Personen beschreibt, geschrieben in Prosa und nicht als Liste: Hier muss das Modell Berichtslinien aus Phrasen wie „berichtet an” oder „im Team von” ableiten.
Stellen Sie sicher, dass hierarchische Beziehungen korrekt verschachtelt sind, und achten Sie auf Personen, die weit von ihrem Vorgesetzten erwähnt werden – dies ist der übliche Bruchpunkt. Fügen Sie schließlich Enums zu Rollen (Geschäftsführung, Management, operativ) hinzu und beobachten Sie, ob die Einschränkung die Berichtslinie verbessert oder verschlechtert: Das Erzwingen einer Kategorisierung kann dem Modell helfen oder es zu willkürlichen Entscheidungen bei hybriden Profilen drängen.
Kernaussagen
- Verschachtelte Listen sind das häufigste Muster in der Produktion
- Enums werden auf der Generierungsebene angewendet – nutzen Sie sie
- Simulieren Sie Unionen mit einem Diskriminator-Feld und nullable Feldern
$defsermöglicht rekursive Strukturen (Kommentare, Bäume)- Begrenzen Sie die Verschachtelungstiefe auf 3-4 Ebenen