Apibrėžkite schemas su Pydantic
Šiame puslapyje
Pydantic: individualių struktūrizuotų išvesčių pagrindas Python kalboje
Pydantic yra populiariausia duomenų validavimo biblioteka Python kalboje. Ji leidžia apibrėžti duomenų modelius su griežtais tipais, o būtent tai Mistral API naudoja individualioms struktūrizuotoms išvestims. Jei dirbi su Python, Pydantic tampa tavo pagrindiniu įrankiu išvesties schemoms aprašyti: tai, ką parašai klasėje, yra tai, ką modelis bus priverstas sugeneruoti.
Geros naujienos dėl diegimo: Pydantic įtraukta kaip Mistral SDK priklausomybė. Jei jau turi įdiegtą mistralai, daugiau nieko daryti nereikia.
pip install mistralai
# Pydantic v2 įtraukiama automatiškai
Greitas versijos patikrinimas padės išvengti netikėtumų, nes validatoriaus sintaksė skiriasi pagrindinėse versijose:
import pydantic
print(pydantic.__version__) # Būtina 2.x versija
Paprasto modelio apibrėžimas
Pydantic modelis yra klasė, paveldinti iš BaseModel, kurioje kiekvienas atributas yra laukas su aiškiai nurodytu tipu.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Šis modelis nurodo Mistral: „Tavo išvestis turi būti JSON objektas su tiksliai šiais 4 laukais, visi – eilučių tipo.“ Jokių papildomų instrukcijų užklausoje (prompt) šiai struktūrai gauti nereikia.
Tipai, kuriuos naudosite
Pydantic palaiko visus standartinius Python tipus, o Mistral juos visus supranta. Šiame modelyje jie sujungti realiame pavyzdyje – analizuojant pagalbos prašymą (ticket) – ir parodoma, kaip jie derinami: pagrindiniai tipai paprastiems laukams, Optional darbuotojui, kuris dar nepriskirtas, Enum prioritetui, kuris gali įgyti tik keturias reikšmes, ir sąrašai žymoms bei susijusiems ID.
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):
# Pagrindiniai tipai
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Pasirenkami tipai
assignee: Optional[str] = None
# Enum (apribotos reikšmės)
priority: Priority
# Sąrašai
tags: list[str]
related_ids: list[int]
Štai atitinkama trumpa atmintinė:
| Tipas | Reikšmė |
|---|---|
str | eilutė |
int | sveikasis skaičius |
float | dešimtainis skaičius |
bool | loginė reikšmė (true/false) |
list[T] | T tipo elementų sąrašas |
Optional[T] | laukas, kuris gali būti null |
Enum | reikšmė iš baigtinės aibės |
Verta ypatingai paminėti Enum: tai vienintelis būdas garantuoti, kad prioritetas niekada nebus „very urgent“ arba „P1“, priklausomai nuo modelio nuotaikos.
Įdėtieji modeliai
Realaus pasaulio duomenys retai būna plokšti. Kontaktas priklauso įmonei, kuri turi adresą. Pydantic leidžia įdėti modelius vienas į kitą tiek giliai, kiek reikia, o Mistral laikosi šios hierarchijos.
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 # Įdėtasis modelis
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Dviejų lygių įdėjimas
Sugeneruotas JSON tiksliai atkuria šią medžio struktūrą:
{
"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"
}
}
}
Tas pats mechanizmas leidžia vienu metu išgauti kelis elementus: modelis apgaubia kito modelio sąrašą, ir vienu kvietimu gauni visą 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
Modelio nukreipimas naudojant aprašymus
Lauko pavadinimas nepasakoja visos istorijos. score gali reikšti pažymį iš 10, procentinę dalį arba reikšmę tarp 0 ir 1 – modelis turi spėlioti. Aprašymai pašalina šį dviprasmiškumą: jie įtraukiami į JSON schemą, siunčiamą Mistral, ir veikia kaip instrukcijos kiekvienam laukui atskirai.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Bendras nusiteikimas: 'positive', 'negative' arba 'neutral'"
)
score: float = Field(
description="Pasitikėjimo balas tarp 0.0 ir 1.0"
)
keywords: list[str] = Field(
description="3–5 pagrindiniai raktažodžiai iš teksto"
)
summary: str = Field(
description="Santrauka ne ilgesnė nei vienas sakinys"
)
Kuo tikslesni šie aprašymai, tuo geresnė išvesties kokybė. Tai yra didžiausią poveikį daranti viso nustatymo dalis: keli gerai parinkti žodžiai dažnai pakeičia visą pastraipą užklausoje.
Field taip pat nustato numatytąsias reikšmes. Kitame pavyzdyje kalba pagal nutylėjimą yra "fr", jei modelis neranda informacijos, žodžių skaičius lieka None, jei jo negalima nustatyti, o žymos pradedamos kaip tuščias sąrašas dėka 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 kalbos kodas")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Laukai su numatytosiomis reikšmėmis bus užpildyti modelio, jei jis ras informaciją, arba liks su numatytąja reikšme kitu atveju.
Validavimas gaunamas nemokamai
Ir galiausiai: validavimas yra automatinis. Jei reikšmė neatitinka deklaruoto tipo, Pydantic iškart išmeta ValidationError, nurodydamas tiksliai, kuris laukas kaltas, ir tau nereikia rašyti nė vienos tikrinimo kodo eilutės.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Tipo klaida
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 validavimo klaida SentimentAnalysis
# score
# Įvestis turi būti galiojantis skaičius [type=float_parsing, ...]
Visas rankinis tikrinimo kodas, rašytas ankstesnėje pamokoje, čia išnyksta, pakeistas modelio deklaracija.
Svarbiausi punktai
- Pydantic
BaseModelyra visų individualių schemų Python kalboje pagrindas - Naudokite aiškius tipus:
str,int,float,bool,list[T],Optional[T] - Įdėtieji modeliai leidžia kurti sudėtingas JSON struktūras
Field(description=...)gerina išvesties kokybę nukreipdamas modelį- Validavimas yra automatinis – tipo klaidos aptinkamos iškart