Schemas mit Pydantic definieren

Pydantic: Die Grundlage für benutzerdefinierte strukturierte Ausgaben in Python

Pydantic ist die beliebteste Datenvalidierungsbibliothek in Python. Sie ermöglicht die Definition von Datenmodellen mit strengen Typen, genau das, was die Mistral-API für benutzerdefinierte strukturierte Ausgaben verwendet. Wenn Sie in Python arbeiten, wird Pydantic zu Ihrem primären Werkzeug zur Beschreibung von Ausgabeschemas: Das, was Sie in einer Klasse schreiben, ist das, woran das Modell gebunden ist, was es produzieren soll.

Die gute Nachricht zur Installation: Pydantic ist als Abhängigkeit des Mistral SDK enthalten. Wenn Sie bereits mistralai installiert haben, müssen Sie nichts anderes tun.

pip install mistralai
# Pydantic v2 wird automatisch mitgeliefert

Eine schnelle Versionsprüfung vermeidet Überraschungen, da sich die Syntax der Validatoren zwischen den Hauptversionen geändert hat:

import pydantic
print(pydantic.__version__)  # 2.x erforderlich

Ein einfaches Modell definieren

Ein Pydantic-Modell ist eine Klasse, die von BaseModel erbt, wobei jedes Attribut ein Feld mit einem expliziten Typ ist.

from pydantic import BaseModel

class Kontakt(BaseModel):
    name: str
    email: str
    phone: str
    company: str

Dieses Modell sagt Mistral: „Ihre Ausgabe muss ein JSON-Objekt mit genau diesen 4 Feldern sein, alle vom Typ string.” Für diese Struktur sind keine zusätzlichen Anweisungen im Prompt erforderlich.

Typen, die Sie verwenden werden

Pydantic unterstützt alle Standard-Python-Typen, und Mistral versteht sie alle. Das folgende Modell bringt sie in einem realistischen Fall zusammen – die Analyse eines Support-Tickets – und zeigt, wie sie kombiniert werden: Basistypen für einfache Felder, Optional für einen noch nicht zugewiesenen Zuweisenden, Enum für eine Priorität, die nur vier Werte annehmen kann, und Listen für Tags und verwandte IDs.

from pydantic import BaseModel
from typing import Optional
from enum import Enum

class Prioritaet(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"
    critical = "critical"

class TicketAnalyse(BaseModel):
    # Basistypen
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Optional-Typen
    assignee: Optional[str] = None

    # Enums (eingeschränkte Werte)
    priority: Priority

    # Listen
    tags: list[str]
    related_ids: list[int]

Hier ist die entsprechende Schnellübersicht:

Enums verdienen eine besondere Erwähnung: Sie sind der einzige Weg, um sicherzustellen, dass eine Priorität niemals „very urgent” oder „P1” sein wird, abhängig von der Stimmung des Modells.

Verschachtelte Modelle

Echte Daten sind selten flach. Ein Kontakt gehört zu einem Unternehmen, das eine Adresse hat. Pydantic ermöglicht es, Modelle so tief wie nötig zu verschachteln, und Mistral folgt der Hierarchie.

from pydantic import BaseModel
from typing import Optional

class Adresse(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Unternehmen(BaseModel):
    name: str
    industry: str
    address: Adresse  # Verschachteltes Modell

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Unternehmen  # Zweistufige Verschachtelung

Das generierte JSON reproduziert diese Baumstruktur exakt:

{
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "[email protected]",
  "role": "Vertriebsleiter",
  "company": {
    "name": "TechVision SAS",
    "industry": "Technologie",
    "address": {
      "street": "42 rue de la Paix",
      "city": "Paris",
      "postal_code": "75002",
      "country": "France"
    }
  }
}

Der gleiche Mechanismus extrahiert mehrere Elemente gleichzeitig: Ein Modell umschließt eine Liste eines anderen Modells, und Sie erhalten einen vollständigen Katalog in einem einzigen Aufruf.

from pydantic import BaseModel

class Produkt(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

class Katalog(BaseModel):
    products: list[Produkt]
    total_count: int

Leiten Sie das Modell mit Beschreibungen

Ein Feldname erzählt nicht die ganze Geschichte. score könnte eine Note von 10, ein Prozentsatz oder ein Wert zwischen 0 und 1 bedeuten – das Modell muss raten. Beschreibungen beseitigen diese Mehrdeutigkeit: Sie werden im JSON-Schema gesendet, das an Mistral geht, und wirken als Feldanweisungen.

from pydantic import BaseModel, Field

class Stimmungsanalyse(BaseModel):
    sentiment: str = Field(
        description="Gesamte Stimmung: 'positive', 'negative' oder 'neutral'"
    )
    score: float = Field(
        description="Vertrauensscore zwischen 0,0 und 1,0"
    )
    keywords: list[str] = Field(
        description="Die 3-5 wichtigsten Schlüsselwörter aus dem Text"
    )
    summary: str = Field(
        description="Zusammenfassung in maximal einem Satz"
    )

Je präziser diese Beschreibungen sind, desto besser ist die Ausgabequalität. Dies ist der Teil mit der höchsten Hebelwirkung der gesamten Einrichtung: Ein paar gut gewählte Wörter ersetzen oft einen ganzen Absatz im Prompt.

Field setzt auch Standardwerte. Im nächsten Beispiel lautet die Sprache standardmäßig „fr”, wenn das Modell die Information nicht findet, die Wortanzahl bleibt None, wenn sie nicht bestimmt werden kann, und Tags beginnen als leere Liste dank default_factory.

from pydantic import BaseModel, Field
from typing import Optional

class ArtikelMetadaten(BaseModel):
    title: str
    author: str
    language: str = Field(default="fr", description="ISO 639-1 Sprachcode")
    word_count: Optional[int] = None
    tags: list[str] = Field(default_factory=list)

Felder mit Standardwerten werden vom Modell ausgefüllt, wenn es die Information findet, oder behalten den Standardwert, andernfalls.

Validierung kommt automatisch

Letztendlich: Validierung ist automatisch. Wenn ein Wert nicht dem deklarierten Typ entspricht, wirft Pydantic sofort eine ValidationError, die genau angibt, welches Feld schuld ist, ohne dass Sie eine einzige Zeile Prüfcod schreiben müssen.

from pydantic import ValidationError

try:
    analyse = Stimmungsanalyse(
        sentiment="positive",
        score="noch keine Zahl",  # Typfehler
        keywords=["test"],
        summary="Zusammenfassung"
    )
except ValidationError as e:
    print(e)
    # 1 Validierungsfehler für Stimmungsanalyse
    # score
    #   Input sollte eine gültige Zahl sein [type=float_parsing, ...]

All der manuelle Verifikationscode, der in der vorherigen Lektion geschrieben wurde, verschwindet hier, ersetzt durch die Modelldeklaration.

Kernaussagen

• Pydantic BaseModel ist die Basis aller benutzerdefinierten Schemas in Python
• Verwenden Sie explizite Typen: str, int, float, bool, list[T], Optional[T]
• Verschachtelte Modelle ermöglichen komplexe JSON-Strukturen
• Field(description=...) verbessert die Ausgabequalität, indem es das Modell leitet
• Validierung ist automatisch – Typfehler werden sofort erkannt