Iddefinixxi Skemi b'Pydantic
F'din il-paġna
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:
| Type | Meaning |
|---|---|
str | string |
int | integer |
float | decimal number |
bool | boolean (true/false) |
list[T] | list of elements of type T |
Optional[T] | field that can be null |
Enum | value 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
BaseModelhija 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