Przejdź do głównej treści
Polski— Wybierz język
Menu

Definiowanie schematów za pomocą Pydantic

Lekcja 7 z 12 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Pydantic: Fundament niestandardowych wyjść strukturalnych w Pythonie
  2. Definiowanie prostego modelu
  3. Typy, których będziesz używać
  4. Modele zagnieżdżone
  5. Prowadzenie modelu za pomocą opisów
  6. Walidacja jest darmowa
  7. Kluczowe wnioski

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:

TypZnaczenie
strciąg znaków (string)
intliczba całkowita
floatliczba dziesiętna
boolwartość logiczna (prawda/fałsz)
list[T]lista elementów typu T
Optional[T]pole, które może mieć wartość null
Enumwartość 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 BaseModel jest 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