Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Definiraj sheme s Pydanticom

Lekcija 7 od 12 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Pydantic: temelj prilagojenih strukturiranih izhodov v Pythonu
  2. Definiraj preprost model
  3. Tipi, ki jih boš uporabljal
  4. Gnezdeni modeli
  5. Usmerjaj model z opisi
  6. Preverjanje veljavnosti je brezplačno
  7. Ključne ugotovitve

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:

TipPomen
strniz
intcelo število
floatdecimalno število
boolboolean (true/false)
list[T]seznam elementov tipa T
Optional[T]polje, ki je lahko null
Enumvrednost 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 BaseModel je 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