Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Iddefinixxi Skemi b'Pydantic

Lezzjoni 7 / 12 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Pydantic: Il-Fondazzjoni ta’ Outputs Strutturati Custom f’Python
  2. Iddefinixxi Mudell Sempliċi
  3. Tipi li Se Tuża
  4. Mudelli Mbejjna (Nested Models)
  5. Iggwida l-Mudell b’Deskrizzjonijiet
  6. Il-Validazzjoni Tiġi B’Xejn
  7. Punti Ewlenin

Pydantic: Il-Fondazzjoni ta’ Outputs Strutturati Custom f’Python

Pydantic hija l-aktar librerija popolari għall-validazzjoni tad-data f’Python. Tippermettilek tiddefinixxi mudelli tad-data b’tipi stretti, li huwa eżattament dak li l-API ta’ Mistral tuża għal Outputs Strutturati Custom. Jekk taħdem b’Python, Pydantic issir l-għodda primarja tiegħek biex tiddeskrivi skemi tal-output: dak li tikteb f’klassi huwa dak li l-mudell ikun imġiegħel jipproduċi.

Hawnhekk hemm l-aħbar tajba dwar l-installazzjoni: Pydantic hija inkluża bħala dipendenza tal-SDK ta’ Mistral. Jekk diġà għandek mistralai installat, m’għandekx għalfejn tagħmel xejn ieħor.

pip install mistralai
# Pydantic v2 is included automatically

Verifika rapida tal-verżjoni tevita sorpriżi, peress li s-sintassi tal-validatur inbidlet bejn verżjonijiet maġġuri:

import pydantic
print(pydantic.__version__)  # 2.x required

Iddefinixxi Mudell Sempliċi

Mudell ta’ Pydantic huwa klassi li tirredita minn BaseModel, fejn kull attribut huwa qasam b’tip espliċitu.

from pydantic import BaseModel

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

Dan il-mudell jgħid lil Mistral: “L-output tiegħek irid ikun oġġett JSON b’eżattament dawn l-4 oqsma, kollha tat-tip string.” M’hemmx bżonn ta’ istruzzjonijiet addizzjonali fil-prompt biex tikseb din l-istruttura.

Tipi li Se Tuża

Pydantic jappoġġja t-tipi kollha standard ta’ Python, u Mistral jifhimhom kollha. Il-mudell li ġej iġibhom flimkien f’każ realistiku—l-analiżi ta’ tikketta ta’ appoġġ—u juri kif jingħaqdu: tipi bażiċi għal oqsma sempliċi, Optional għal persuna assenjata li għadha ma ġietx iddeżinjata, Enum għal prijorità li tista’ tieħu biss erba’ valuri, u listi għat-tikketti u l-IDs relatati.

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

    # Optional types
    assignee: Optional[str] = None

    # Enums (constrained values)
    priority: Priority

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

Hawnhekk hawn il-cheat sheet korrispondenti:

TypeMeaning
strstring
intinteger
floatdecimal number
boolboolean (true/false)
list[T]list of elements of type T
Optional[T]field that can be null
Enumvalue from a finite set

L-Enums jistħoqqilhom mention speċjali: huma l-uniku mod biex tiggarantixxi li prijorità qatt ma tkun "very urgent" jew "P1" skont il-burdata tal-mudell.

Mudelli Mbejjna (Nested Models)

Id-data tad-dinja reali rari tkun ċatta (flat). Kuntatt jappartjeni għal kumpanija, li għandha indirizz. Pydantic jippermettilek tbejjin il-mudelli kemm ikun meħtieġ, u Mistral isegwi l-ġerarkija.

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  # Nested model

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Two-level nesting

Il-JSON iġġenerat jirriproduċi eżattament din l-istruttura tas-siġra:

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

L-istess mekkaniżmu jestraċi oġġetti multipli f’daqqa: mudell jgħatti lista ta’ mudell ieħor, u tirrikupra katalogu sħiħ f’sejħa waħda.

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

Iggwida l-Mudell b’Deskrizzjonijiet

Isem il-qasam ma jgħidx l-istorja kollha. score jista’ jfisser grad minn 10, perċentwal, jew valur bejn 0 u 1—il-mudell irid jissuspetta. Id-deskrizzjonijiet ineħħu din l-ambigwità: huma inklużi fl-iskema JSON mibgħuta lil Mistral u jaġixxu bħala istruzzjonijiet għal kull qasam.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Overall sentiment: 'positive', 'negative', or 'neutral'"
    )
    score: float = Field(
        description="Confidence score between 0.0 and 1.0"
    )
    keywords: list[str] = Field(
        description="The 3-5 main keywords from the text"
    )
    summary: str = Field(
        description="Summary in one sentence maximum"
    )

Kemm ikunu preċiżi dawn id-deskrizzjonijiet, daqshekk tkun aħjar il-kwalità tal-output. Din hija l-parti bl-aktar impatt fil-konfigurazzjoni kollha: ftit kliem magħżul sew spiss jieħu post paragrafu sħiħ ta’ prompt.

Field jistabbilixxi wkoll valuri default. Fl-eżempju li jmiss, il-lingwa default hija "fr" jekk il-mudell ma jsibx l-informazzjoni, in-numru ta’ kliem jibqa’ None jekk ma jistax jiġi ddeterminat, u t-tikketti jibdew bħala lista vojta grazzi għal default_factory.

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

Oqsma b’valuri default se jimtlew mill-mudell jekk isib l-informazzjoni, jew se jżommu l-valur default inkella.

Il-Validazzjoni Tiġi B’Xejn

L-aħħar iżda mhux l-inqas: il-validazzjoni hija awtomatika. Jekk valur ma jaqbilx mat-tip iddikjarat, Pydantic immedjatament iqajjem ValidationError li jindika eżattament liema qasam huwa ħati, mingħajr ma tikteb linja waħda ta’ kodiċi ta’ verifika.

from pydantic import ValidationError

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

Il-kodiċi kollu ta’ verifika manwali miktub fil-lezzjoni preċedenti jisparixxi hawnhekk, sostitwit mid-dikjarazzjoni tal-mudell.

Punti Ewlenin

  • Pydantic BaseModel hija l-bażi ta’ skemi Custom kollha f’Python
  • Uża tipi espliċiti: str, int, float, bool, list[T], Optional[T]
  • Mudelli mbejjna jippermettu strutturi JSON kumplessi
  • Field(description=...) itejjeb il-kwalità tal-output billi jiggwida l-mudell
  • Il-validazzjoni hija awtomatika—l-iżbalji tat-tip jiġu skoperti immedjatament