Definēt shēmas ar Pydantic
Šajā lapā
Pydantic: Pielāgotu strukturētu izvades datu pamats Python valodā
Pydantic ir populārākā datu validācijas bibliotēka Python valodā. Tā ļauj definēt datu modeļus ar stingriem tipiem, kas ir tieši tas, ko Mistral API izmanto pielāgotām strukturētām izvades datu kopām. Ja strādā Python vidē, Pydantic kļūst par tavu galveno rīku izvades shēmu aprakstīšanai: tas, ko uzraksti klasē, ir tas, kam modelim būs jāatbilst.
Labā ziņa par instalēšanu: Pydantic ir iekļauta kā Mistral SDK atkarība. Ja tev jau ir instalēts mistralai, tev nekas cits nav jādara.
pip install mistralai
# Pydantic v2 tiek iekļauta automātiski
Ātra versijas pārbaude novērsīs neparedzētus pārsteigumus, jo validatoru sintakse mainījās starp galvenajām versijām:
import pydantic
print(pydantic.__version__) # Nepieciešama 2.x versija
Vienkārša modeļa definēšana
Pydantic modelis ir klase, kas mantota no BaseModel, kur katrs atribūts ir lauks ar eksplicītu tipu.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Šis modelis norāda Mistral: „Tavai izvadei ir jābūt JSON objektam ar tieši šiem 4 laukiem, un visiem tiem ir jābūt virkņu (string) tipam.” Lai iegūtu šo struktūru, papildu instrukcijas uzvednē (prompt) nav nepieciešamas.
Tipi, kurus izmantosi
Pydantic atbalsta visus standarta Python tipus, un Mistral saprot tos visus. Tālāk redzamais modelis apvieno tos reālistiskā scenārijā – atbalsta biļetes analīzē – un parāda, kā tie darbojas kopā: pamata tipi vienkāršiem laukiem, Optional izpildītājam, kurš vēl nav noteikts, Enum prioritātei, kas var pieņemt tikai četras vērtības, un saraksti tagiem un saistītajiem 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):
# Pamata tipi
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Neobligāti tipi
assignee: Optional[str] = None
# Enumerācijas (ierobežotas vērtības)
priority: Priority
# Saraksti
tags: list[str]
related_ids: list[int]
Lūk, atbilstošā ātrā atsauce:
| Tips | Nozīme |
|---|---|
str | virkne (string) |
int | vesels skaitlis |
float | decimālskaitlis |
bool | loģiskā vērtība (patiess/nepatiess) |
list[T] | T tipa elementu saraksts |
Optional[T] | lauks, kas var būt null |
Enum | vērtība no galīgas kopas |
Enumerācijas (Enum) ir pelnījušas īpašu pieminēšanu: tās ir vienīgais veids, kā garantēt, ka prioritāte nekad nebūs "very urgent" vai "P1" atkarībā no modeļa noskaņojuma.
Ligzdotie modeļi
Reāli dati reti ir plakani. Kontaktpersona pieder uzņēmumam, kuram ir adrese. Pydantic ļauj ligzdot modeļus tik dziļi, cik nepieciešams, un Mistral seko šai hierarhijai.
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 # Ligzdots modelis
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Divu līmeņu ligzdošana
Ģenerētais JSON precīzi atveido šo koka struktūru:
{
"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 mehānisms ļauj vienlaikus izgūt vairākus vienumus: modelis aptver cita modeļa sarakstu, un tu vienā zvanā iegūsti pilnu katalogu.
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
Modeļa vadīšana ar aprakstiem
Lauka nosaukums vien nepasaka visu stāstu. score var nozīmēt vērtējumu no 10 ballēm, procentus vai vērtību starp 0 un 1 – modelim tas ir jāmin. Apraksti novērš šo neskaidrību: tie tiek iekļauti JSON shēmā, kas tiek nosūtīta Mistral, un darbojas kā instrukcijas katram laukam atsevišķi.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Kopējā noskaņa: 'positive', 'negative' vai 'neutral'"
)
score: float = Field(
description="Pārliecības vērtējums robežās no 0.0 līdz 1.0"
)
keywords: list[str] = Field(
description="3–5 galvenie atslēgvārdi no teksta"
)
summary: str = Field(
description="Kopsavilkums maksimāli vienā teikumā"
)
Jo precīzāki ir šie apraksti, jo augstāka ir izvades kvalitāte. Šī ir vissvarīgākā visa iestatījuma daļa: daži labi izvēlēti vārdi bieži vien aizstāj veselu uzvednes (prompt) rindkopu.
Field arī iestata noklusējuma vērtības. Nākamajā piemērā valoda pēc noklusējuma ir "fr", ja modelis neatrod informāciju, vārdu skaits paliek None, ja to nevar noteikt, un tagi sākas kā tukšs saraksts, pateicoties 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 valodas kods")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Lauki ar noklusējuma vērtībām tiks aizpildīti ar modeļa ģenerētiem datiem, ja tas atradīs informāciju, vai arī saglabās noklusējuma vērtību pretējā gadījumā.
Validācija ir bezmaksas bonuss
Visbeidzot, bet ne mazāk svarīgi: validācija ir automātiska. Ja vērtība neatbilst deklarētajam tipam, Pydantic uzreiz izraisa ValidationError, norādot tieši to lauku, kurā ir kļūda, un tev nav jāraksta neviena pārbaudes koda rinda.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Tipa kļūda
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 validācijas kļūda priekš SentimentAnalysis
# score
# Ievadei jābūt derīgam skaitlim [type=float_parsing, ...]
Visi manuālie pārbaudes kodi, kas tika rakstīti iepriekšējā nodarbībā, šeit pazūd, tos aizstājot modeļa deklarācija.
Galvenās atziņas
- Pydantic
BaseModelir visu pielāgoto shēmu pamats Python valodā - Izmanto eksplicītus tipus:
str,int,float,bool,list[T],Optional[T] - Ligzdotie modeļi ļauj veidot sarežģītas JSON struktūras
Field(description=...)uzlabo izvades kvalitāti, virzot modeli- Validācija ir automātiska – tipa kļūdas tiek noteiktas uzreiz