Pydantic BaseModel im Detail

Pydantic: Der ideale Partner

Pydantic ist die Standard-Bibliothek für Datenvalidierung in Python. In Kombination mit den strukturierten Ausgaben von Grok wird es zu einem unverzichtbaren Werkzeug: Sie definieren Ihre Schemas als Python-Klassen, und das Modell füllt diese Klassen automatisch aus.

Grundlagen von Pydantic für strukturierte Ausgaben

Sie erstellen ein Pydantic-Modell, indem Sie von BaseModel erben. Jedes Attribut mit einer Typangabe wird zu einem Feld im JSON-Schema:

from pydantic import BaseModel

class Produit(BaseModel):
    nom: str
    prix: float
    en_stock: bool
    categorie: str

Dieses Modell generiert automatisch das äquivalente JSON-Schema. Sie müssen nichts anderes schreiben.

Unterstützte Python-Typen

Hier ist die Zuordnung zwischen Python-Typen und JSON-Schema-Typen:

class ExempleComplet(BaseModel):
    # Skalare
    texte: str                    # → "type": "string"
    nombre: float                 # → "type": "number"
    entier: int                   # → "type": "number"
    actif: bool                   # → "type": "boolean"

    # Optionale Werte
    note: str | None              # → anyOf string/null

    # Sammlungen
    tags: list[str]               # → Array von Strings
    scores: list[float]           # → Array von Zahlen

    # Aufzählungen
    niveau: str                   # + enum im Field

Verschachtelte Modelle

Die wahre Stärke von Pydantic liegt in der Verschachtelung von Modellen:

class Adresse(BaseModel):
    rue: str
    ville: str
    code_postal: str
    pays: str

class Competence(BaseModel):
    nom: str
    niveau: str  # "debutant", "intermediaire", "expert"
    annees: int

class Candidat(BaseModel):
    prenom: str
    nom: str
    email: str
    adresse: Adresse
    competences: list[Competence]
    disponible: bool
    pretention_salariale: float | None

Wenn Sie Candidat als response_format übergeben, füllt das Modell die gesamte Hierarchie aus: die vollständige Adresse, jede Fähigkeit mit ihren Details und so weiter.

Aufzählungen mit Pydantic

Um vordefinierte Werte durchzusetzen, verwenden Sie Python’s Literal:

from typing import Literal

class Ticket(BaseModel):
    titre: str
    description: str
    priorite: Literal["basse", "moyenne", "haute", "critique"]
    statut: Literal["ouvert", "en_cours", "resolu", "ferme"]
    type: Literal["bug", "feature", "documentation"]

Das Modell kann nur die aufgeführten Werte zurückgeben. Jeder andere Wert ist unmöglich.

Verwendung von parse()

response, ticket = client.chat.parse(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Der Login-Button funktioniert nicht auf dem Mobilgerät"
    }],
    response_format=Ticket
)

print(ticket.priorite)  # "haute"
print(ticket.type)       # "bug"
print(ticket.statut)     # "ouvert"

Verwendung von response_format

response = client.chat.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Der Login-Button funktioniert nicht auf dem Mobilgerät"
    }],
    response_format=Ticket
)

ticket = Ticket.model_validate_json(
    response.choices[0].message.content
)

Standardwerte und Dokumentation

Sie können Beschreibungen für Ihre Felder mit Field hinzufügen. Diese Beschreibungen helfen dem Modell, besser zu verstehen, was Sie erwarten:

from pydantic import BaseModel, Field

class AnalyseSentiment(BaseModel):
    texte_original: str = Field(
        description="Der analysierte Text in roher Form"
    )
    sentiment: Literal["positif", "negatif", "neutre"] = Field(
        description="Das vorherrschende Sentiment des Textes"
    )
    score_confiance: float = Field(
        description="Vertrauensscore zwischen 0,0 und 1,0"
    )
    mots_cles: list[str] = Field(
        description="Die 3 bis 5 wichtigsten Schlüsselwörter"
    )

Die Beschreibungen in Field werden im an das Modell gesendeten JSON-Schema enthalten. Sie verbessern die Qualität der Antworten.

Kernaussagen

• Pydantic wandelt Ihre Python-Klassen automatisch in JSON-Schemas um.
• Die Verschachtelung von Modellen ermöglicht die Strukturierung komplexer Daten.
• Literal ersetzt enum, um vordefinierte Werte durchzusetzen.
• str | None macht ein Feld optional (kann null sein).
• Field(description=...) verbessert die Qualität der Modellantworten.
• Funktioniert mit parse() (automatisch) und response_format (manuell).