Definirea schemelor cu Pydantic
Pe această pagină
Pydantic: Fundamentul ieșirilor structurate personalizate în Python
Pydantic este cea mai populară bibliotecă de validare a datelor din Python. Aceasta vă permite să definiți modele de date cu tipuri stricte, ceea ce este exact ceea ce utilizează API-ul Mistral pentru ieșirile structurate personalizate (Custom Structured Outputs). Dacă lucrați în Python, Pydantic devine instrumentul dumneavoastră principal pentru descrierea schemelor de ieșire: ceea ce scrieți într-o clasă este exact ceea ce modelul va fi constrâns să producă.
Iată vestea bună privind instalarea: Pydantic este inclus ca dependență a SDK-ului Mistral. Dacă aveți deja mistralai instalat, nu trebuie să faceți nimic altceva.
pip install mistralai
# Pydantic v2 este inclus automat
O verificare rapidă a versiunii evită surprizele, deoarece sintaxa validatorilor s-a schimbat între versiunile majore:
import pydantic
print(pydantic.__version__) # Este necesară versiunea 2.x
Definirea unui model simplu
Un model Pydantic este o clasă care moștenește din BaseModel, unde fiecare atribut este un câmp cu un tip explicit.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Acest model îi spune Mistral: „Ieșirea dumneavoastră trebuie să fie un obiect JSON cu exact aceste 4 câmpuri, toate de tip șir de caractere.“ Nu sunt necesare instrucțiuni suplimentare în prompt pentru a obține această structură.
Tipuri pe care le veți utiliza
Pydantic suportă toate tipurile standard Python, iar Mistral le înțelege pe toate. Următorul model le reunește într-un caz realist—analiza unui tichet de suport—și arată cum se combină: tipuri de bază pentru câmpuri simple, Optional pentru un responsabil care nu a fost încă desemnat, Enum pentru o prioritate care poate lua doar patru valori și liste pentru etichete și ID-uri conexe.
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):
# Tipuri de bază
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Tipuri opționale
assignee: Optional[str] = None
# Enumerări (valori constrânse)
priority: Priority
# Liste
tags: list[str]
related_ids: list[int]
Iată fișa sintetică corespunzătoare:
| Tip | Semnificație |
|---|---|
str | șir de caractere |
int | număr întreg |
float | număr zecimal |
bool | boolean (adevărat/fals) |
list[T] | listă de elemente de tipul T |
Optional[T] | câmp care poate fi null |
Enum | valoare dintr-un set finit |
Enumerările merită o mențiune specială: ele sunt singura modalitate de a garanta că o prioritate nu va fi niciodată "very urgent" sau "P1" în funcție de starea de spirit a modelului.
Modele imbricate
Datele din lumea reală sunt rareori plate. Un contact aparține unei companii, care are o adresă. Pydantic vă permite să imbricați modele cât de adânc este necesar, iar Mistral respectă ierarhia.
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 # Model imbricat
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Imbricare pe două niveluri
JSON-ul generat reproduce exact această structură arborescentă:
{
"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"
}
}
}
Același mecanism extrage mai multe elemente simultan: un model învelește o listă de alte modele, iar dumneavoastră recuperați un catalog complet într-o singură apelare.
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
Ghidarea modelului prin descrieri
Numele unui câmp nu spune întreaga poveste. score ar putea însemna o notă din 10, un procentaj sau o valoare între 0 și 1—modelul trebuie să ghicească. Descrierile elimină această ambiguitate: ele sunt incluse în schema JSON trimisă către Mistral și acționează ca instrucțiuni specifice fiecărui câmp.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Sentiment general: 'positive', 'negative' sau 'neutral'"
)
score: float = Field(
description="Scor de încredere între 0.0 și 1.0"
)
keywords: list[str] = Field(
description="Cele 3-5 cuvinte cheie principale din text"
)
summary: str = Field(
description="Rezumat într-o singură propoziție maximum"
)
Cu cât aceste descrieri sunt mai precise, cu atât calitatea ieșirii este mai bună. Aceasta este partea cu cel mai mare impact din întreaga configurare: câțiva cuvinte bine aleși înlocuiesc adesea un întreg paragraf de prompt.
Field setează, de asemenea, valori implicite. În exemplul următor, limba implicită este "fr" dacă modelul nu găsește informația, numărul de cuvinte rămâne None dacă nu poate fi determinat, iar etichetele încep ca o listă goală datorită default_factory.
from pydantic import BaseModel, Field
from typing import Optional
class ArticleMetadata(BaseModel):
title: str
author: str
language: str = Field(default="fr", description="Codul limbii ISO 639-1")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Câmpurile cu valori implicite vor fi completate de model dacă acesta găsește informația sau vor păstra valoarea implicită în caz contrar.
Validarea este inclusă gratuit
Nu în ultimul rând: validarea este automată. Dacă o valoare nu corespunde tipului declarat, Pydantic generează imediat o eroare ValidationError, indicând exact care câmp este problematic, fără ca dumneavoastră să scrieți o singură linie de cod de verificare.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Eroare de tip
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, ...]
Tot codul de verificare manuală scris în lecția anterioară dispare aici, fiind înlocuit de declarația modelului.
Puncte cheie
BaseModeldin Pydantic stă la baza tuturor schemelor personalizate în Python- Utilizați tipuri explicite:
str,int,float,bool,list[T],Optional[T] - Modelele imbricate permit structuri JSON complexe
Field(description=...)îmbunătățește calitatea ieșirii ghidând modelul- Validarea este automată—erorile de tip sunt detectate imediat