Schema's definiëren met Pydantic
Op deze pagina
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:
| Type | Betekenis |
|---|---|
str | string |
int | geheel getal |
float | decimaal getal |
bool | boolean (waar/onwaar) |
list[T] | lijst van elementen van type T |
Optional[T] | veld dat null kan zijn |
Enum | waarde 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
BaseModelis 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