Definér skemaer med Pydantic
På denne side
Pydantic: Fundamentet for brugerdefinerede strukturerede outputs i Python
Pydantic er det mest populære bibliotek til validering af data i Python. Det lader dig definere datamodeller med strenge typer, hvilket er præcis det, Mistral API bruger til brugerdefinerede strukturerede outputs. Hvis du arbejder i Python, bliver Pydantic dit primære værktøj til at beskrive output-skemaer: det, du skriver i en klasse, er det, modellen bliver begrænset til at producere.
Her er de gode nyheder om installation: Pydantic er inkluderet som en afhængighed i Mistral SDK’et. Hvis du allerede har installeret mistralai, behøver du ikke gøre noget andet.
pip install mistralai
# Pydantic v2 er inkluderet automatisk
Et hurtigt versionstjek undgår overraskelser, da syntaksen for validatorer ændrede sig mellem hovedversionerne:
import pydantic
print(pydantic.__version__) # 2.x kræves
Definér en simpel model
En Pydantic-model er en klasse, der arver fra BaseModel, hvor hver attribut er et felt med en eksplicit type.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Denne model fortæller Mistral: „Dit output skal være et JSON-objekt med præcis disse 4 felter, alle af typen streng.” Der er ikke behov for yderligere instrukser i prompten for at få denne struktur.
Typer, du vil bruge
Pydantic understøtter alle standard Python-typer, og Mistral forstår dem alle. Følgende model samler dem i et realistisk tilfælde – analyse af en support-billet – og viser, hvordan de kombineres: basistyper til simple felter, Optional til en ansvarlig, der endnu ikke er udpeget, Enum til en prioritet, der kun kan antage fire værdier, og lister til tags og relaterede ID’er.
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):
# Basistyper
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Valgfrie typer
assignee: Optional[str] = None
# Enums (begrænsede værdier)
priority: Priority
# Lister
tags: list[str]
related_ids: list[int]
Her er det tilsvarende spikkeark:
| Type | Betydning |
|---|---|
str | streng |
int | heltal |
float | decimaltal |
bool | boolesk (sand/falsk) |
list[T] | liste over elementer af type T |
Optional[T] | felt, der kan være null |
Enum | værdi fra en endelig mængde |
Enums fortjener særlig omtale: de er den eneste måde at garantere på, at en prioritet aldrig bliver "very urgent" eller "P1" afhængigt af modellens lune.
Næstede modeller
Data i den virkelige verden er sjældent flade. En kontakt tilhører en virksomhed, som har en adresse. Pydantic lader dig næste modeller så dybt, som det er nødvendigt, og Mistral følger hierarkiet.
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 # Næstet model
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # To-niveau næstning
Det genererede JSON reproducerer præcis denne træstruktur:
{
"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"
}
}
}
Den samme mekanisme udtrækker flere elementer på én gang: en model omslutter en liste over en anden model, og du henter et komplet katalog i et enkelt kald.
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
Guid modellen med beskrivelser
Et feltnavn fortæller ikke hele historien. score kunne betyde en karakter ud af 10, en procentdel eller en værdi mellem 0 og 1 – modellen skal gætte. Beskrivelser fjerner denne tvetydighed: de inkluderes i JSON-skemaet, der sendes til Mistral, og fungerer som instrukser pr. felt.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Samlet stemning: 'positive', 'negative' eller 'neutral'"
)
score: float = Field(
description="Konfidensscore mellem 0,0 og 1,0"
)
keywords: list[str] = Field(
description="De 3-5 vigtigste nøgleord fra teksten"
)
summary: str = Field(
description="Resumé på maksimalt én sætning"
)
Jo mere præcise disse beskrivelser er, desto bedre bliver outputkvaliteten. Dette er den mest effektive del af hele opsætningen: få velvalgte ord erstatter ofte et helt afsnit i prompten.
Field sætter også standardværdier. I næste eksempel defaulter sproget til "fr", hvis modellen ikke finder informationen, ordantallet forbliver None, hvis det ikke kan bestemmes, og tags starter som en tom liste takket være 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 sprogkode")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Felter med standardværdier udfyldes af modellen, hvis den finder informationen, eller beholder standardværdien ellers.
Validering følger gratis med
Sidst men ikke mindst: validering er automatisk. Hvis en værdi ikke matcher den erklærede type, kaster Pydantic øjeblikkeligt en ValidationError, der angiver præcis, hvilket felt der er galt, uden at du skal skrive en eneste linje tjekkode.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Typefejl
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 valideringsfejl for SentimentAnalysis
# score
# Input skal være et gyldigt tal [type=float_parsing, ...]
Al den manuelle verifikationskode, der blev skrevet i den foregående lektion, forsvinder her og erstattes af modeldeklarationen.
Vigtige pointer
- Pydantic
BaseModeler grundlaget for alle brugerdefinerede skemaer i Python - Brug eksplicitte typer:
str,int,float,bool,list[T],Optional[T] - Næstede modeller muliggør komplekse JSON-strukturer
Field(description=...)forbedrer outputkvaliteten ved at guide modellen- Validering er automatisk – typefejl opdages øjeblikkeligt