Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Määratle skeemid Pydanticuga

Õppetund 7 / 12 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Pydantic: Kohandatud struktureeritud väljundite alustala Pythonis
  2. Lihtsa mudeli defineerimine
  3. Tüübid, mida kasutad
  4. Pesastatud mudelid
  5. Juhenda mudelit kirjeldustega
  6. Valideerimine on tasuta boonuseks
  7. Peamised punktid

Pydantic: Kohandatud struktureeritud väljundite alustala Pythonis

Pydantic on Pythoni populaarseim andmete valideerimise teek. See võimaldab defineerida andmemudeleid rangete tüüpidega, mida Mistral API kasutabki kohandatud struktureeritud väljundite jaoks. Kui töötad Pythonis, on Pydantic sinu peamine vahend väljundiskeemide kirjeldamiseks: see, mida kirjutad klassi, ongi see, milleks mudel sunnitakse väljundi genereerima.

Hea uudis installimise kohta: Pydantic on kaasatud Mistral SDK sõltuvusse. Kui sul on juba mistralai paigaldatud, ei pea sa midagi muud tegema.

pip install mistralai
# Pydantic v2 on automaatselt kaasatud

Kiire versioonikontroll hoiab ära üllatusi, kuna validaatori süntaks muutus põhiversioonide vahel:

import pydantic
print(pydantic.__version__)  # Vajalik on 2.x

Lihtsa mudeli defineerimine

Pydantici mudel on klass, mis pärib BaseModel-ist, kus iga atribuut on väli koos selge tüübiga.

from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    phone: str
    company: str

See mudel ütleb Mistralile: “Sinu väljund peab olema JSON-objekt, millel on täpselt need 4 välja ja kõik on stringi tüüpi.” Selle struktuuri saamiseks ei ole vihjes (prompt) vaja lisada mingeid täiendavaid juhiseid.

Tüübid, mida kasutad

Pydantic toetab kõiki standardsed Pythoni tüüpe ja Mistral mõistab neid kõiki. Järgnev mudel toob need kokku reaalses stsenaariumis – tugipileti analüüsimisel – ja näitab, kuidas need kombineeruvad: lihttüübid lihtsate väljade jaoks, Optional veel määramata vastutava isiku jaoks, Enum prioriteedi jaoks, mis võib võtta ainult nelja väärtust, ja loendid siltide ning seotud ID-de jaoks.

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):
    # Lihttüübid
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Valikulised tüübid
    assignee: Optional[str] = None

    # Enumid (piiratud väärtused)
    priority: Priority

    # Loendid
    tags: list[str]
    related_ids: list[int]

Siin on vastav petuleht:

TüüpTähendus
strstring
inttäisarv
floatkümnendmurdarv
boolboolean (tõene/väär)
list[T]T-tüüpi elementide loend
Optional[T]väli, mis võib olla null
Enumväärtus lõplikust hulgast

Enumid väärivad erilist mainimist: need on ainus viis garanteerida, et prioriteet ei oleks kunagi "very urgent" ega "P1" sõltuvalt mudeli tujust.

Pesastatud mudelid

Reaalmaailma andmed on harva lamedad. Kontakt kuulub ettevõttele, millel on aadress. Pydantic võimaldab mudelite pesastamist nii sügavale kui vaja ja Mistral järgib seda hierarhiat.

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  # Pesastatud mudel

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Kahe taseme pesastamine

Genereeritud JSON reprodutseerib seda puustruktuuri täpselt:

{
  "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"
    }
  }
}

Sama mehhanism võimaldab korraga ekstraheerida mitu elementi: mudel mähib teise mudeli loendi ja saad ühe päringuga kataloogi tervikuna.

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

Juhenda mudelit kirjeldustega

Välja nimi ei räägi kogu lugu. score võib tähendada hinnet skaalal 0–10, protsenti või väärtust vahemikus 0–1 – mudel peab arvama. Kirjeldused kõrvaldavad selle ebaselguse: need lisatakse Mistralile saadetavasse JSON-skeemi ja toimivad iga välja kohta käivate juhistena.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Üldine meeleolu: 'positive', 'negative' või 'neutral'"
    )
    score: float = Field(
        description="Usaldusväärsuse skoor vahemikus 0.0 kuni 1.0"
    )
    keywords: list[str] = Field(
        description="Teksti 3–5 peamist märksõna"
    )
    summary: str = Field(
        description="Kokkuvõte maksimaalselt ühes lauses"
    )

Mida täpsemad need kirjeldused on, seda parem on väljundi kvaliteet. See on kogu seadistuse suurima mõjuga osa: mõned hästi valitud sõnad asendavad sageli tervet lõiku vihjest.

Field määrab ka vaikimisi väärtused. Järgmises näites on keeleks vaikimisi "fr", kui mudel teavet ei leia, sõnade arv jääb None-iks, kui seda ei saa määrata, ja sildid algavad tühja loendina tänu default_factory-le.

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 keelekood")
    word_count: Optional[int] = None
    tags: list[str] = Field(default_factory=list)

Vaikimisi väärtustega väljad täidab mudel, kui ta leiab vastava info, vastasel juhul jääb kehtima vaikimisi väärtus.

Valideerimine on tasuta boonuseks

Viimane, kuid mitte vähem oluline: valideerimine on automaatne. Kui väärtus ei vasta deklareeritud tüübile, tõstab Pydantic kohe ValidationError, mis näitab täpselt, milline väli on vigane, ilma et peaksid kirjutama ühtegi kontrollikoodi rida.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  # Tüübi viga
        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, ...]

Kogu eelmises õppetükis kirjutatud manuaalne kontrollikood kaob siin, asendudes mudeli deklaratsiooniga.

Peamised punktid

  • Pydantici BaseModel on kõigi Pythoni kohandatud skeemide alus
  • Kasuta selgeid tüüpe: str, int, float, bool, list[T], Optional[T]
  • Pesastatud mudelid võimaldavad luua keerukaid JSON-struktuure
  • Field(description=...) parandab väljundi kvaliteeti, juhendades mudelit
  • Valideerimine on automaatne – tüübi vead tuvastatakse koheselt