Pydantic + OpenAI: Der sauberste Weg, um strukturierte Ausgaben von LLMs zu erhalten

Pydantic + OpenAI: Der sauberste Weg, strukturierte Ausgaben von LLMs zu erhalten

Große Sprachmodelle (LLMs) sind bemerkenswert gut darin, menschenähnlichen Text zu generieren, aber sie produzieren oft unstrukturierte oder semi-strukturierte Ausgaben, die umfangreiche Nachbearbeitung erfordern. Wenn du Produktionsanwendungen baust – sei es für Datenextraktion, Inhaltsmoderation oder automatisierte Berichterstellung – benötigst du zuverlässige, typisierte und validierte Daten. Hier kommen Pydantic und OpenAI ins Spiel: eine leistungsstarke Kombination, mit der du genau die Ausgabestruktur definieren kannst, die du haben möchtest, und das LLM liefert sie in einem sauberen, vorhersagbaren Format.

Dieser Artikel führt dich durch die praktischen Schritte zur Einrichtung von Pydantic mit OpenAI, von der Installation bis zur praktischen Anwendung. Am Ende hast du ein wiederverwendbares Muster, um mit minimalem Boilerplate strukturierte Ausgaben von GPT-Modellen zu erhalten.

Warum strukturierte Ausgaben wichtig sind

Wenn du einem LLM eine Frage stellst, bekommst du normalerweise einen Textabsatz zurück. Für einen Chatbot ist das in Ordnung. Aber wenn du eine Liste von Kundennamen, Daten und Beträgen aus einer E-Mail extrahieren oder ein JSON-Objekt für eine Datenbank generieren musst, wird Rohtext zum Problem. Du könntest versuchen, die Ausgabe mit Regex oder einem zweiten LLM-Aufruf zu parsen, aber diese Ansätze sind spröde und fehleranfällig.

Strukturierte Ausgaben lösen dies, indem sie das Modell dazu zwingen, Daten zu produzieren, die einem vordefinierten Schema entsprechen. Hier glänzt Pydantic. Pydantic ist eine Python-Bibliothek zur Datenvalidierung mit Python-Typannotationen. In Kombination mit OpenAIs Function Calling oder strukturierten Ausgabefähigkeiten erhältst du:

• **Typsicherheit** – Die Ausgabe wird automatisch gegen dein Schema validiert.
• **Kein manuelles Parsen** – Das Modell gibt eine Pydantic-Modellinstanz zurück, keinen Rohtext.
• **Klare Verträge** – Dein Code weiß genau, welche Felder zu erwarten sind.

Voraussetzungen

Bevor es losgeht, stelle sicher, dass du Folgendes hast:

• **Python 3.9+** – Pydantic v2 benötigt Python 3.9 oder höher.
• **Einen OpenAI-API-Schlüssel** – Du benötigst einen gültigen Schlüssel mit Zugriff auf GPT-4- oder GPT-3.5-Turbo-Modelle, die Function Calling unterstützen.
• **Grundlegende Python-Kenntnisse** – Du solltest Klassen, Typen und asynchrone Programmierung verstehen (optional, aber hilfreich).

Schritt-für-Schritt-Installation

Wir richten eine saubere Umgebung ein und installieren die notwendigen Bibliotheken.

1. Virtuelle Umgebung erstellen und aktivieren

Das Isolieren von Abhängigkeiten verhindert Konflikte mit anderen Projekten.

python -m venv pydantic_openai_env
source pydantic_openai_env/bin/activate  # Unter Windows: pydantic_openai_env\Scripts\activate

2. Pydantic und die OpenAI-Python-Bibliothek installieren

Pydantic v2 ist die aktuelle Hauptversion. Die OpenAI-Bibliothek enthält Unterstützung für Function Calling und strukturierte Ausgaben.

pip install pydantic openai

3. Installation überprüfen

Führe eine kurze Prüfung durch, um zu bestätigen, dass beide Bibliotheken verfügbar sind.

import pydantic
import openai
print(f"Pydantic-Version: {pydantic.__version__}")
print(f"OpenAI-Bibliotheksversion: {openai.__version__}")

Wenn du Versionsnummern siehst (z. B. `2.5.0` für Pydantic und `1.6.0` für OpenAI), bist du bereit.

4. OpenAI-API-Schlüssel setzen

Speichere deinen Schlüssel aus Sicherheitsgründen als Umgebungsvariable.

export OPENAI_API_KEY="dein-api-schluessel-hier"

Du kannst ihn auch in deinem Python-Skript setzen, aber die Verwendung von Umgebungsvariablen wird für die Produktion empfohlen.

Kernkonzept: Definieren eines Pydantic-Modells

Ein Pydantic-Modell ist eine Klasse, die von `BaseModel` erbt. Jedes Feld wird mit einem Typ annotiert, und es können optionale Standardwerte oder Validatoren hinzugefügt werden.

Hier ist ein einfaches Modell zum Extrahieren von Personeninformationen aus Text:

from pydantic import BaseModel, Field
from typing import Optional

class Person(BaseModel):
    name: str = Field(description="Der vollständige Name der Person")
    age: Optional[int] = Field(None, description="Alter in Jahren, falls erwähnt")
    email: Optional[str] = Field(None, description="E-Mail-Adresse, falls vorhanden")

Die `Field`-Funktion ermöglicht es dir, Beschreibungen, Standardwerte und Einschränkungen hinzuzufügen. Diese Beschreibungen werden an das LLM weitergegeben, um seine Ausgabe zu lenken.

Die Magie: Kombinieren von Pydantic mit OpenAIs Function Calling

OpenAIs Function Calling ermöglicht es dir, ein JSON-Schema anzugeben, an das sich das Modell bei der Generierung einer Antwort halten muss. Pydantic-Modelle können mit der Methode `.model_json_schema()` automatisch in dieses Schema konvertiert werden.

Hier ist ein vollständiger Workflow:

Schritt 1: Ausgabemodell definieren

Wir erstellen ein Modell zum Extrahieren einer Liste von Produktbewertungen.

from pydantic import BaseModel, Field
from typing import List

class Review(BaseModel):
    product_name: str = Field(description="Name des bewerteten Produkts")
    rating: int = Field(ge=1, le=5, description="Bewertung von 1 bis 5")
    summary: str = Field(description="Ein-Satz-Zusammenfassung der Bewertung")

class ReviewList(BaseModel):
    reviews: List[Review] = Field(description="Liste der im Text gefundenen Bewertungen")

Schritt 2: OpenAI-Client und Funktionsdefinition vorbereiten

Wir verwenden den OpenAI-Client (v1.0+-Syntax) und konvertieren unser Modell in ein JSON-Schema.

from openai import OpenAI

client = OpenAI()

# ReviewList in ein JSON-Schema konvertieren
review_schema = ReviewList.model_json_schema()

Das Schema sieht aus wie ein standardmäßiges JSON-Schema-Objekt, das OpenAI verwendet, um die Funktionsparameter zu definieren.

Schritt 3: API-Aufruf mit Function Calling durchführen

Wir übergeben das Schema als Funktionsdefinition und bitten das Modell, diese Funktion aufzurufen.

response = client.chat.completions.create(
    model="gpt-4-1106-preview",  # oder "gpt-3.5-turbo-1106"
    messages=[
        {"role": "system", "content": "Du extrahierst strukturierte Daten aus Benutzereingaben."},
        {"role": "user", "content": "Ich liebe das neue iPhone 15. Die Kamera ist fantastisch. Ich gebe 5 Sterne. Außerdem ist das MacBook Pro überteuert, aber leistungsstark. Ich würde es mit 3 Sternen bewerten."}
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "extract_reviews",
            "description": "Produktbewertungen aus dem Eingabetext extrahieren",
            "parameters": review_schema
        }
    }],
    tool_choice={"type": "function", "function": {"name": "extract_reviews"}}
)

Schritt 4: Antwort in ein Pydantic-Modell parsen

Die Antwort des Modells enthält ein Funktionsaufruf-Argument (einen JSON-String). Wir parsen es direkt in unser Pydantic-Modell.

import json

# Die Funktionsaufruf-Argumente extrahieren
tool_call = response.choices[0].message.tool_calls[0]
arguments = json.loads(tool_call.function.arguments)

# Validieren und das Pydantic-Modell erstellen
reviews = ReviewList(**arguments)
print(reviews)

Ausgabe (formatiert):

reviews=[
    Review(product_name='iPhone 15', rating=5, summary='Liebe die fantastische Kamera.'),
    Review(product_name='MacBook Pro', rating=3, summary='Überteuert, aber leistungsstark.')
]

Beachte, dass das Modell automatisch den Bewertungsbereich (1–5) validiert und die Liste geparst hat. Wenn das LLM eine ungültige Bewertung (z. B. 6) zurückgegeben hätte, würde Pydantic einen `ValidationError` auslösen.

Anwendungsbeispiele

Lass uns zwei praktische Szenarien erkunden: das Extrahieren strukturierter Daten aus E-Mails und das Generieren von Konfigurationsobjekten.

Beispiel 1: E-Mail-Parsing für den Kundensupport

Stell dir vor, du erhältst Support-E-Mails und musst den Problemtyp, die Priorität und die Kunden-ID extrahieren.

from pydantic import BaseModel, Field
from enum import Enum

class Priority(str, Enum):
    low = "niedrig"
    medium = "mittel"
    high = "hoch"

class SupportTicket(BaseModel):
    customer_id: str = Field(description="Kunden-ID aus der E-Mail-Signatur")
    issue_type: str = Field(description="Kategorie des Problems: Abrechnung, technisch oder Konto")
    priority: Priority = Field(description="Dringlichkeitsstufe")
    description: str = Field(description="Kurze Zusammenfassung des Problems")

Dann verwende das gleiche Muster wie oben, um dies aus einem E-Mail-Text zu extrahieren. Das LLM gibt eine validierte `SupportTicket`-Instanz zurück.

Beispiel 2: Generieren von Konfigurationsobjekten

Du kannst auch komplexe verschachtelte Konfigurationen generieren, wie z. B. Datenbankverbindungsparameter.

from pydantic import BaseModel, Field
from typing import Dict

class DatabaseConfig(BaseModel):
    host: str = Field(description="Datenbank-Hostname oder IP")
    port: int = Field(ge=1, le=65535, description="Portnummer")
    credentials: Dict[str, str] = Field(description="Benutzername und Passwort als Dict")

Bitte das LLM: „Generiere eine Datenbankkonfiguration für eine PostgreSQL-Instanz, die auf localhost läuft, mit Benutzer ‚admin‘ und Passwort ‚secret123‘.“ Das Modell gibt eine validierte Konfiguration zurück.

Best Practices und Tipps

1. **Verwende beschreibende Feldnamen und Beschreibungen** – Das LLM verwendet diese, um zu verstehen, was du möchtest. Sei spezifisch. 2. **Nutze Typeinschränkungen** – Pydantic unterstützt `ge`, `le`, `min_length`, `regex` und mehr. Diese Einschränkungen werden im JSON-Schema kodiert und helfen dem LLM, gültige Ausgaben zu generieren. 3. **Behandle Fehler elegant** – Pydantic löst einen `ValidationError` aus, wenn die Modellausgabe nicht deinem Schema entspricht. Wickle das Parsen in einen Try-Except-Block und wiederhole es mit einem klareren Prompt. 4. **Halte Schemas angemessen groß** – Sehr große Schemas (viele Felder oder tiefe Verschachtelung) können das Modell verwirren. Zerlege komplexe Extraktionen bei Bedarf in mehrere Aufrufe. 5. **Verwende Enums für feste Mengen** – Wenn ein Feld nur einen von wenigen Werten annehmen kann, definiere eine `Enum`-Klasse. Dies schränkt die Ausgabe des LLMs auf gültige Optionen ein.

Einschränkungen und Überlegungen

Obwohl dieser Ansatz leistungsstark ist, ist er nicht perfekt:

• **Kosten** – Function Calling verbraucht mehr Tokens, insbesondere bei großen Schemas. Überwache deine API-Nutzung.
• **Modellunterstützung** – Nicht alle OpenAI-Modelle unterstützen Function Calling. Verwende `gpt-4-1106-preview` oder `gpt-3.5-turbo-1106` für beste Ergebnisse.
• **Schema-Komplexität** – Extrem verschachtelte oder rekursive Schemas können dazu führen, dass das Modell halluziniert oder Felder auslässt. Halte es nach Möglichkeit flach.
• **Latenz** – Die zusätzliche Verarbeitung für Function Calling fügt einen kleinen Overhead hinzu (normalerweise <100ms).

Fazit

Pydantic + OpenAI bietet den saubersten und zuverlässigsten Weg, strukturierte Ausgaben von LLMs zu erhalten. Durch das Definieren eines Pydantic-Modells, das Konvertieren in ein JSON-Schema und die Verwendung von OpenAIs Function Calling eliminierst du manuelles Parsen und gewinnst Typsicherheit, Validierung und klare Verträge. Dieses Muster ist ideal für Datenextraktion, Formularausfüllung, Codegenerierung und jede Aufgabe, bei der du vorhersagbare, strukturierte Daten aus natürlicher Sprache benötigst.

Fang klein an: Definiere ein einfaches Modell für dein nächstes Projekt, integriere es mit einem einzigen API-Aufruf und iteriere. Wenn du dich wohlfühlst, kannst du auf komplexe mehrstufige Workflows skalieren. Die Kombination aus Pydantics Validierungsstärke und OpenAIs Sprachverständnis ist ein Game-Changer für den Bau robuster KI-Anwendungen.

*Hinweis: Dieser Artikel basiert auf allgemeinem Wissen über Pydantic und OpenAI Anfang 2025. Die aktuellsten Informationen findest du in der offiziellen Pydantic-Dokumentation und dem OpenAI-API-Änderungsprotokoll.*