Salt la conținutul principal
Română— Alege o limbă
Meniu

Definirea schemelor cu Pydantic

Lecția 7 din 12 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Pydantic: Fundamentul ieșirilor structurate personalizate în Python
  2. Definirea unui model simplu
  3. Tipuri pe care le veți utiliza
  4. Modele imbricate
  5. Ghidarea modelului prin descrieri
  6. Validarea este inclusă gratuit
  7. Puncte cheie

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:

TipSemnificație
strșir de caractere
intnumăr întreg
floatnumăr zecimal
boolboolean (adevărat/fals)
list[T]listă de elemente de tipul T
Optional[T]câmp care poate fi null
Enumvaloare 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

  • BaseModel din 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