Määratle skeemid Pydanticuga
Sellel lehel
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üüp | Tähendus |
|---|---|
str | string |
int | täisarv |
float | kümnendmurdarv |
bool | boolean (tõene/väär) |
list[T] | T-tüüpi elementide loend |
Optional[T] | väli, mis võib olla null |
Enum | vää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
BaseModelon 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