Sémák definiálása Pydantic segítségével
Ezen az oldalon
Pydantic: Az egyéni strukturált kimenetek alapja Pythonban
A Pydantic a legnépszerűbb adatvalidáló könyvtár Pythonban. Lehetővé teszi szigorú típusokkal rendelkező adatmodellek definiálását, ami pontosan az, amit a Mistral API az egyéni strukturált kimenetekhez használ. Ha Pythonban dolgozol, a Pydantic lesz az elsődleges eszközöd a kimeneti sémák leírására: amit egy osztályban megírsz, ahhoz lesz kényszerítve a modell a kimenet előállításakor.
Jó hír a telepítéssel kapcsolatban: a Pydantic a Mistral SDK függőségeként szerepel. Ha már telepítve van a mistralai, semmi mást nem kell tenned.
pip install mistralai
# A Pydantic v2 automatikusan included
Egy gyors verzióellenőrzés elkerüli a meglepetéseket, mivel a validátor szintaxisa a főverziók között megváltozott:
import pydantic
print(pydantic.__version__) # 2.x szükséges
Egy egyszerű modell definiálása
Egy Pydantic modell egy osztály, amely a BaseModel-ből örököl, ahol minden attribútum egy explicit típussal rendelkező mező.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Ez a modell azt mondja a Mistralnak: „A kimenetednek egy JSON objektumnak kell lennie pontosan ezzel a 4 mezővel, mind string típusúként.“ Nem szükségesek további utasítások a promptban ehhez a struktúrához.
Használandó típusok
A Pydantic támogatja az összes szabványos Python típust, és a Mistral mindegyiket érti. Az alábbi modell egy valós esetet hoz össze – egy támogatási jegy elemzését –, és bemutatja, hogyan kombinálódnak ezek: egyszerű típusok az egyszerű mezőkhöz, Optional egy még ki nem osztott felelőshöz, Enum egy prioritáshoz, amely csak négy értéket vehet fel, valamint listák a címkékhez és kapcsolódó azonosítókhoz.
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):
# Egyszerű típusok
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Opcionális típusok
assignee: Optional[str] = None
# Enumok (korlátozott értékek)
priority: Priority
# Listák
tags: list[str]
related_ids: list[int]
Íme a megfelelő csalólap:
| Típus | Jelentés |
|---|---|
str | karakterlánc |
int | egész szám |
float | tizedes szám |
bool | logikai érték (igaz/hamis) |
list[T] | T típusú elemek listája |
Optional[T] | mező, amely lehet null |
Enum | érték egy véges halmazból |
Az enumok külön említést érdemelnek: ez az egyetlen módja annak, hogy garantáljuk: a prioritás sosem lesz "very urgent" vagy "P1" a modell hangulatától függően.
Beágyazott modellek
A valós adatok ritkán laposak. Egy kapcsolattartó egy céghez tartozik, amelynek van címe. A Pydantic lehetővé teszi a modellek tetszőleges mélységű beágyazását, és a Mistral követi ezt a hierarchiát.
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 # Beágyazott modell
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Két szintű beágyazás
A generált JSON pontosan ezt a fastruktúrát reprodukálja:
{
"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"
}
}
}
Ugyanez a mechanizmus több elem egyszeri kinyerésére is szolgál: egy modell beburkolja egy másik modell listáját, és egyetlen hívással lekérdezed a teljes katalógust.
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
A modell irányítása leírásokkal
Egy mezőnév nem mond el mindent. A score jelenthet egy 10-es skálán elért osztályzatot, egy százalékot vagy egy 0 és 1 közötti értéket – a modellnek kell találgatnia. A leírások megszüntetik ezt a bizonytalanságot: bekerülnek a Mistralnak küldött JSON sémába, és mezőszintű utasításként működnek.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Általános hangulat: 'positive', 'negative' vagy 'neutral'"
)
score: float = Field(
description="Bizalmi score 0.0 és 1.0 között"
)
keywords: list[str] = Field(
description="A szöveg 3-5 fő kulcsszava"
)
summary: str = Field(
description="Összefoglaló maximum egy mondatban"
)
Minél pontosabbak ezek a leírások, annál jobb a kimenet minősége. Ez a teljes beállítás legnagyobb hatású része: néhány jól megválasztott szó gyakran helyettesít egy egész bekezdésnyi promptot.
A Field alapértelmezett értékeket is beállít. A következő példában a nyelv alapértelmezetten "fr", ha a modell nem találja az információt, a szavak száma None marad, ha nem határozható meg, és a címkék üres listával indulnak a 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 nyelvi kód")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Az alapértelmezett értékkel rendelkező mezőket a modell kitölti, ha megtalálja az információt, egyébként pedig megtartja az alapértelmezett értéket.
A validálás ingyen jön
Végül, de nem utolsósorban: a validálás automatikus. Ha egy érték nem egyezik a deklarált típussal, a Pydantic azonnal egy ValidationError kivételt dob, amely pontosan jelzi, melyik mező a hibás, anélkül, hogy egyetlen ellenőrző kódsort is írnál.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Típushiba
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 validálási hiba a SentimentAnalysis esetén
# score
# A bemenetnek érvényes számnak kell lennie [type=float_parsing, ...]
Az előző leckében írt összes manuális ellenőrző kód itt eltűnik, helyét a modelldeklaráció veszi át.
Főbb megállapítások
- A Pydantic
BaseModelaz összes Pythonbeli egyéni séma alapja - Használj explicit típusokat:
str,int,float,bool,list[T],Optional[T] - A beágyazott modellek lehetővé teszik a komplex JSON struktúrákat
- A
Field(description=...)javítja a kimenet minőségét a modell irányításával - A validálás automatikus – a típus hibákat azonnal észleli a rendszer