Definiowanie schematów za pomocą Pydantic
Na tej stronie
Pydantic: Fundament niestandardowych wyjść strukturalnych w Pythonie
Pydantic to najpopularniejsza biblioteka do walidacji danych w Pythonie. Pozwala definiować modele danych ze ścisłymi typami, co jest dokładnie tym, czego API Mistral używa do niestandardowych wyjść strukturalnych. Jeśli pracujesz w Pythonie, Pydantic staje się Twoim głównym narzędziem do opisywania schematów wyjścia: to, co zapiszesz w klasie, będzie sztywnym ograniczeniem dla tego, co model musi wygenerować.
Dobra wiadomość dotycząca instalacji: Pydantic jest zawarty jako zależność w SDK Mistral. Jeśli masz już zainstalowane mistralai, nie musisz robić nic więcej.
pip install mistralai
# Pydantic v2 jest dołączany automatycznie
Szybkie sprawdzenie wersji uchroni Cię przed niespodziankami, ponieważ składnia walidatorów zmieniła się między głównymi wersjami:
import pydantic
print(pydantic.__version__) # wymagana wersja 2.x
Definiowanie prostego modelu
Model Pydantic to klasa dziedzicząca po BaseModel, w której każdy atrybut jest polem z jawnie określonym typem.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Ten model mówi Mistralowi: „Twoje wyjście musi być obiektem JSON zawierającym dokładnie te 4 pola, wszystkie typu string“. Nie potrzebujesz żadnych dodatkowych instrukcji w prompcie, aby uzyskać tę strukturę.
Typy, których będziesz używać
Pydantic obsługuje wszystkie standardowe typy Pythona, a Mistral rozumie je wszystkie. Poniższy model łączy je w realistycznym scenariuszu – analizie zgłoszenia wsparcia – i pokazuje, jak się komponują: typy podstawowe dla prostych pól, Optional dla osoby odpowiedzialnej, która nie została jeszcze przydzielona, Enum dla priorytetu, który może przyjąć tylko cztery wartości, oraz listy dla tagów i powiązanych identyfikatorów.
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):
# Typy podstawowe
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Typy opcjonalne
assignee: Optional[str] = None
# Enumy (wartości ograniczone)
priority: Priority
# Listy
tags: list[str]
related_ids: list[int]
Oto odpowiednia ściągawka:
| Typ | Znaczenie |
|---|---|
str | ciąg znaków (string) |
int | liczba całkowita |
float | liczba dziesiętna |
bool | wartość logiczna (prawda/fałsz) |
list[T] | lista elementów typu T |
Optional[T] | pole, które może mieć wartość null |
Enum | wartość z skończonego zbioru |
Enumy zasługują na szczególną uwagę: są jedynym sposobem, aby zagwarantować, że priorytet nigdy nie będzie wynosił "very urgent" ani "P1" w zależności od nastroju modelu.
Modele zagnieżdżone
Dane w rzeczywistym świecie rzadko są płaskie. Kontakt należy do firmy, która ma adres. Pydantic pozwala zagnieżdżać modele tak głęboko, jak to konieczne, a Mistral podąża za tą hierarchią.
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 # Zagnieżdżony model
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Zagnieżdżenie dwupoziomowe
Wygenerowany JSON odwzorowuje tę strukturę drzewiastą dokładnie:
{
"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"
}
}
}
Ten sam mechanizm pozwala提取ować wiele elementów jednocześnie: model opakowuje listę innego modelu, a Ty otrzymujesz kompletny katalog w jednym wywołaniu.
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
Prowadzenie modelu za pomocą opisów
Nazwa pola nie mówi wszystkiego. score może oznaczać ocenę w skali do 10, procent lub wartość od 0 do 1 – model musi zgadywać. Opisy usuwają tę niejednoznaczność: są dołączane do schematu JSON wysyłanego do Mistrala i działają jak instrukcje dla każdego pola z osobna.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Ogólny sentyment: 'positive', 'negative' lub 'neutral'"
)
score: float = Field(
description="Współczynnik pewności między 0.0 a 1.0"
)
keywords: list[str] = Field(
description="3-5 głównych słów kluczowych z tekstu"
)
summary: str = Field(
description="Streszczenie w maksymalnie jednym zdaniu"
)
Im precyzyjniejsze są te opisy, tym lepsza jakość wyjścia. To element o największym wpływie w całej konfiguracji: kilka dobrze dobranych słów często zastępuje cały akapit promptu.
Field ustawia również wartości domyślne. W następnym przykładzie język domyślnie przyjmuje wartość "fr", jeśli model nie znajdzie informacji, liczba słów pozostaje None, jeśli nie da się jej ustalić, a tagi startują jako pusta lista dzięki default_factory.
from pydantic import BaseModel, Field
from typing import Optional
class ArticleMetadata(BaseModel):
title: str
author: str
language: str = Field(default="fr", description="Kod języka ISO 639-1")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Pola z wartościami domyślnymi zostaną wypełnione przez model, jeśli znajdzie on odpowiednie informacje, w przeciwnym razie zachowają wartość domyślną.
Walidacja jest darmowa
Na koniec najważniejsze: walidacja jest automatyczna. Jeśli wartość nie pasuje do zadeklarowanego typu, Pydantic natychmiast zgłasza błąd ValidationError, wskazując dokładnie, które pole jest problematyczne, bez konieczności pisania choćby jednej linii kodu sprawdzającego.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Błąd typu
keywords=["test"],
summary="Summary"
)
except ValidationError as e:
print(e)
# 1 błąd walidacji dla SentimentAnalysis
# score
# Input should be a valid number [type=float_parsing, ...]
Cały ręczny kod weryfikacyjny napisany w poprzedniej lekcji znika tutaj, zastąpiony samą deklaracją modelu.
Kluczowe wnioski
- Pydantic
BaseModeljest podstawą wszystkich niestandardowych schematów w Pythonie - Używaj jawnych typów:
str,int,float,bool,list[T],Optional[T] - Zagnieżdżone modele umożliwiają tworzenie złożonych struktur JSON
Field(description=...)poprawia jakość wyjścia, prowadząc model- Walidacja jest automatyczna – błędy typów są wykrywane natychmiast