Definiraj sheme s Pydanticom
Na tej strani
Pydantic: temelj prilagojenih strukturiranih izhodov v Pythonu
Pydantic je najbolj priljubljena knjižnica za preverjanje veljavnosti podatkov v Pythonu. Omogoča ti definiranje podatkovnih modelov s strogimi tipi, kar je natanko tisto, kar API Mistral uporablja za prilagojene strukturirane izhode. Če delaš v Pythonu, postane Pydantic tvoje glavno orodje za opisovanje shem izhoda: kar napišeš v razredu, je omejitev, ki jo mora model upoštevati pri generiranju.
Dobra novica pri namestitvi: Pydantic je vključen kot odvisnost SDK-ja Mistral. Če že imaš nameščen mistralai, ne potrebuješ storiti ničesar drugega.
pip install mistralai
# Pydantic v2 je samodejno vključen
Hiter pregled različice prepreči presenečenja, saj se je sintaksa validatorjev med glavnimi različicami spremenila:
import pydantic
print(pydantic.__version__) # Zahtevana je različica 2.x
Definiraj preprost model
Model Pydantic je razred, ki deduje od BaseModel, kjer je vsak atribut polje z eksplicitnim tipom.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Ta model sporoča Mistralu: „Tvoj izhod mora biti objekt JSON z natanko temi štirimi polji, vsa tipa string.” Za pridobitev te strukture v pozivu niso potrebna dodatna navodila.
Tipi, ki jih boš uporabljal
Pydantic podpira vse standardne tipe Pythona, Mistral pa jih razume vse. Naslednji model jih združuje v realističnem primeru – analizi podpore strankam – in prikazuje, kako se kombinirajo: osnovni tipi za preprosta polja, Optional za dodeljenega agenta, ki še ni določen, Enum za prioriteto, ki lahko zavzame le štiri vrednosti, in seznami za oznake ter povezane ID-je.
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):
# Osnovni tipi
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Opcijski tipi
assignee: Optional[str] = None
# Enumi (omejene vrednosti)
priority: Priority
# Seznami
tags: list[str]
related_ids: list[int]
Tukaj je ustrezni hitri pregled:
| Tip | Pomen |
|---|---|
str | niz |
int | celo število |
float | decimalno število |
bool | boolean (true/false) |
list[T] | seznam elementov tipa T |
Optional[T] | polje, ki je lahko null |
Enum | vrednost iz končnega nabora |
Enumi si zaslužijo posebno omembo: so edini način, da zagotoviš, da prioriteta nikoli ne bo "very urgent" ali "P1", odvisno od razpoloženja modela.
Gnezdeni modeli
Podatki v realnem svetu redko tvorijo ravno strukturo. Kontakt pripada podjetju, ki ima naslov. Pydantic ti omogoča gnezdenje modelov poljubno globoko, Mistral pa sledi hierarhiji.
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 # Gnezdeni model
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Dvonivojsko gnezdenje
Generirani JSON natanko reproducira to drevesno strukturo:
{
"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"
}
}
}
Isti mehanizem omogoča hkratno ekstrakcijo več elementov: model ovije seznam drugega modela in v enem klicu pridobiš celoten katalog.
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
Usmerjaj model z opisi
Ime polja ne pove celotne zgodbe. score lahko pomeni oceno do 10, odstotek ali vrednost med 0 in 1 – model mora ugibati. Opisi odstranijo to dvoumnost: vključeni so v shemo JSON, poslano Mistralu, in delujejo kot navodila za posamezno polje.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Splošno razpoloženje: 'positive', 'negative' ali 'neutral'"
)
score: float = Field(
description="Ocena zanesljivosti med 0,0 in 1,0"
)
keywords: list[str] = Field(
description="3–5 glavnih ključnih besed iz besedila"
)
summary: str = Field(
description="Povzetek v največ enem stavku"
)
Bolj natančni kot so ti opisi, boljša je kakovost izhoda. To je del celotne nastavitve z največjim učinkom: nekaj dobro izbranih besed pogosto nadomesti cel odstavek poziva.
Field nastavlja tudi privzete vrednosti. V naslednjem primeru je jezik privzeto "fr", če model ne najde informacije, število besed ostane None, če ga ni mogoče določiti, in oznake se začnejo kot prazen seznam zahvaljujoč default_factory.
from pydantic import BaseModel, Field
from typing import Optional
class ArticleMetadata(BaseModel):
title: str
author: str
language: str = Field(default="fr", description="Koda jezika ISO 639-1")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Polja s privzetimi vrednostmi bo model izpolnil, če najde informacijo, sicer pa ohranijo privzeto vrednost.
Preverjanje veljavnosti je brezplačno
Nazadnje, a ne najmanj pomembno: preverjanje veljavnosti je samodejno. Če se vrednost ne ujema z deklariranim tipom, Pydantic takoj sproži ValidationError, ki točno označi, katero polje je problematično, brez da bi moral napisati vrstico kode za preverjanje.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Napaka tipa
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 validation error for SentimentAnalysis
# score
# Input should be a valid number [type=float_parsing, ...]
Vsa ročna koda za preverjanje, napisana v prejšnji lekciji, tu izgine in jo nadomesti deklaracija modela.
Ključne ugotovitve
- Pydantic
BaseModelje osnova vseh prilagojenih shem v Pythonu - Uporabljaj eksplicitne tipe:
str,int,float,bool,list[T],Optional[T] - Gnezdeni modeli omogočajo kompleksne strukture JSON
Field(description=...)izboljša kakovost izhoda z usmerjanjem modela- Preverjanje veljavnosti je samodejno – napake tipov so takoj zaznane