Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Schema's definiëren met Pydantic

Les 7 van 12 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Pydantic: de basis van aangepaste gestructureerde uitvoer in Python
  2. Een eenvoudig model definiëren
  3. Typen die u zult gebruiken
  4. Geneste modellen
  5. Het model sturen met beschrijvingen
  6. Validatie is gratis inbegrepen
  7. Belangrijkste punten

Pydantic: de basis van aangepaste gestructureerde uitvoer in Python

Pydantic is de populairste bibliotheek voor datavalidatie in Python. Hiermee definieert u datamodellen met strikte typen, precies wat de Mistral API gebruikt voor aangepaste gestructureerde uitvoer (Custom Structured Outputs). Als u in Python werkt, is Pydantic uw primaire hulpmiddel om uitvoerschema’s te beschrijven: wat u in een klasse schrijft, is waartoe het model beperkt wordt.

Het goede nieuws over de installatie: Pydantic is opgenomen als afhankelijkheid van de Mistral SDK. Als u mistralai al hebt geïnstalleerd, hoeft u niets anders te doen.

pip install mistralai
# Pydantic v2 is automatisch inbegrepen

Een snelle versiecontrole voorkomt verrassingen, aangezien de syntaxis van validators is veranderd tussen grote versies:

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

Een eenvoudig model definiëren

Een Pydantic-model is een klasse die overerft van BaseModel, waarbij elk attribuut een veld is met een expliciet type.

from pydantic import BaseModel

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

Dit model vertelt Mistral: “Uw uitvoer moet een JSON-object zijn met precies deze 4 velden, allemaal van het type string.” Er zijn geen aanvullende instructies in de prompt nodig om deze structuur te verkrijgen.

Typen die u zult gebruiken

Pydantic ondersteunt alle standaard Python-typen en Mistral begrijpt ze allemaal. Het volgende model brengt ze samen in een realistisch geval—het analyseren van een supportticket—en laat zien hoe ze combineren: basistypen voor eenvoudige velden, Optional voor een toegewezen persoon die nog niet is aangewezen, Enum voor een prioriteit die slechts vier waarden kan aannemen, en lijsten voor tags en gerelateerde ID’s.

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

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

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

    # Optionele typen
    assignee: Optional[str] = None

    # Enums (beperkte waarden)
    priority: Priority

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

Hier is de bijbehorende spiekbrief:

TypeBetekenis
strstring
intgeheel getal
floatdecimaal getal
boolboolean (waar/onwaar)
list[T]lijst van elementen van type T
Optional[T]veld dat null kan zijn
Enumwaarde uit een eindige set

Enums verdienen speciale vermelding: ze zijn de enige manier om te garanderen dat een prioriteit nooit "very urgent" of "P1" zal zijn, afhankelijk van de bui van het model.

Geneste modellen

Data uit de echte wereld zijn zelden plat. Een contactpersoon behoort tot een bedrijf, dat een adres heeft. Met Pydantic kunt u modellen zo diep nesten als nodig is, en Mistral volgt de hiërarchie.

from pydantic import BaseModel
from typing import Optional

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

class Company(BaseModel):
    name: str
    industry: str
    address: Address  # Genest model

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  // Nesting op twee niveaus

De gegenereerde JSON reproduceert deze boomstructuur exact:

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

Hetzelfde mechanisme haalt meerdere items in één keer op: een model omwikkelt een lijst van een ander model, en u haalt een volledige catalogus op in één enkele aanroep.

from pydantic import BaseModel

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

class Catalog(BaseModel):
    products: list[Product]
    total_count: int

Het model sturen met beschrijvingen

Een veldnaam vertelt niet het hele verhaal. score zou een cijfer op 10 kunnen betekenen, een percentage, of een waarde tussen 0 en 1—het model moet raden. Beschrijvingen verwijderen deze ambiguïteit: ze worden opgenomen in het JSON-schema dat naar Mistral wordt gestuurd en fungeren als instructies per veld.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Algeheel sentiment: 'positive', 'negative' of 'neutral'"
    )
    score: float = Field(
        description="Vertrouwensscore tussen 0.0 en 1.0"
    )
    keywords: list[str] = Field(
        description="De 3-5 belangrijkste trefwoorden uit de tekst"
    )
    summary: str = Field(
        description="Samenvatting in maximaal één zin"
    )

Hoe preciezer deze beschrijvingen zijn, hoe beter de kwaliteit van de uitvoer. Dit is het onderdeel met de grootste hefboomwerking in de hele opzet: een paar goed gekozen woorden vervangen vaak een hele alinea aan prompt-instructies.

Field stelt ook standaardwaarden in. In het volgende voorbeeld wordt de taal standaard "fr" als het model de informatie niet vindt, blijft het aantal woorden None als dit niet kan worden bepaald, en beginnen tags als een lege lijst dankzij default_factory.

from pydantic import BaseModel, Field
from typing import Optional

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

Velden met standaardwaarden worden door het model ingevuld als het de informatie vindt, anders behouden ze de standaardwaarde.

Validatie is gratis inbegrepen

Als laatste, maar zeker niet onbelangrijk: validatie is automatisch. Als een waarde niet overeenkomt met het gedeclareerde type, roept Pydantic onmiddellijk een ValidationError af die exact aangeeft welk veld de fout veroorzaakt, zonder dat u een enkele regel controlecode hoeft te schrijven.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  // Typefout
        keywords=["test"],
        summary="Summary"
    )
except ValidationError as e:
    print(e)
    # 1 validatiefout voor SentimentAnalysis
    # score
    #   Invoer moet een geldig getal zijn [type=float_parsing, ...]

Alle handmatige verificatiecode die in de vorige les is geschreven, verdwijnt hier en wordt vervangen door de modeldeclaratie.

Belangrijkste punten

  • Pydantic BaseModel is de basis van alle aangepaste schema’s in Python
  • Gebruik expliciete typen: str, int, float, bool, list[T], Optional[T]
  • Geneste modellen maken complexe JSON-structuren mogelijk
  • Field(description=...) verbetert de uitvoerkwaliteit door het model te sturen
  • Validatie is automatisch—typefouten worden onmiddellijk gedetecteerd