Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Definovanie schém pomocou Pydantic

Lekcia 7 z 12 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Pydantic: Základ vlastných štruktúrovaných výstupov v Pythone
  2. Definovanie jednoduchého modelu
  3. Typy, ktoré budeš používať
  4. Vnorené modely
  5. Usmerňovanie modelu pomocou popisov
  6. Validácia zadarmo
  7. Kľúčové poznatky

Pydantic: Základ vlastných štruktúrovaných výstupov v Pythone

Pydantic je najpopulárnejšia knižnica na validáciu dát v Pythone. Umožňuje ti definovať dátové modely s prísnymi typmi, čo je presne to, čo API Mistral využíva pre vlastné štruktúrované výstupy (Custom Structured Outputs). Ak pracuješ v Pythone, Pydantic sa stáva tvojím hlavným nástrojom na opis schém výstupov: to, čo napíšeš do triedy, určuje obmedzenia toho, čo model vyprodukuje.

Dobrou správou pri inštalácii je, že Pydantic je zahrnutý ako závislosť SDK Mistral. Ak už máš nainštalované mistralai, nemusíš robiť nič ďalšie.

pip install mistralai
# Pydantic v2 je zahrnutý automaticky

Rýchla kontrola verzie predíde prekvapeniam, keďže syntax validátorov sa medzi hlavnými verziami zmenila:

import pydantic
print(pydantic.__version__)  # Vyžaduje sa verzia 2.x

Definovanie jednoduchého modelu

Model Pydantic je trieda, ktorá dedí od BaseModel, kde každý atribút je pole s explicitným typom.

from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    phone: str
    company: str

Tento model hovorí Mistralu: „Tvoj výstup musí byť JSON objekt s presne týmito 4 poľami, všetky typu reťazec.“ Na získanie tejto štruktúry nie sú v prompte potrebné žiadne ďalšie inštrukcie.

Typy, ktoré budeš používať

Pydantic podporuje všetky štandardné typy Pythonu a Mistral im všetkým rozumie. Nasledujúci model ich spája v realistickom prípade – analýze support ticketu – a ukazuje, ako sa kombinujú: základné typy pre jednoduché polia, Optional pre pridelenú osobu, ktorá ešte nie je určená, Enum pre prioritu, ktorá môže nadobúdať iba štyri hodnoty, a zoznamy pre tagy a súvisiace 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):
    # Základné typy
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Voliteľné typy
    assignee: Optional[str] = None

    # Enumy (obmedzené hodnoty)
    priority: Priority

    # Zoznamy
    tags: list[str]
    related_ids: list[int]

Tu je zodpovedajúci ťahák:

TypVýznam
strreťazec
intcelé číslo
floatdesatinné číslo
boolboolean (pravda/nepravda)
list[T]zoznam prvkov typu T
Optional[T]pole, ktoré môže byť null
Enumhodnota z konečnej množiny

Enumy si zaslúžia osobitnú zmienku: sú jediným spôsobom, ako zaručiť, že priorita nikdy nebude "very urgent" alebo "P1" v závislosti od nálady modelu.

Vnorené modely

Reálne dáta sú zriedka ploché. Kontakt patrí spoločnosti, ktorá má adresu. Pydantic ti umožňuje vnárať modely do ľubovoľnej hĺbky a Mistral túto hierarchiu dodržiava.

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  # Vnorený model

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Dvojúrovňové vnorenie

Vygenerovaný JSON presne reprodukuje túto stromovú štruktú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"
    }
  }
}

Ten istý mechanizmus umožňuje extrahovať viacero položiek naraz: model obalí zoznam iného modelu a ty získaš kompletný katalóg jediným volaním.

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

Usmerňovanie modelu pomocou popisov

Názov poľa nepovie celý príbeh. score môže znamenať známku do 10, percentuálny podiel alebo hodnotu medzi 0 a 1 – model musí hádať. Popisy odstraňujú túto nejednoznačnosť: sú zahrnuté v JSON schéme odoslanej do Mistralu a fungujú ako inštrukcie pre jednotlivé polia.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Celková nálada: 'positive', 'negative' alebo 'neutral'"
    )
    score: float = Field(
        description="Skóre istoty medzi 0.0 a 1.0"
    )
    keywords: list[str] = Field(
        description="3 až 5 hlavných kľúčových slov z textu"
    )
    summary: str = Field(
        description="Zhrnutie maximálne v jednej vete"
    )

Čím sú tieto popisy presnejšie, tým vyššia je kvalita výstupu. Toto je najúčinnejšia časť celého nastavenia: niekoľko dobre zvolených slov často nahradí celý odsek promptu.

Field tiež nastavuje predvolené hodnoty. V nasledujúcom príklade sa jazyk predvolene nastaví na "fr", ak model informáciu nenájde, počet slov zostane None, ak ho nie je možné určiť, a tagy začínajú ako prázdny zoznam vďaka default_factory.

from pydantic import BaseModel, Field
from typing import Optional

class ArticleMetadata(BaseModel):
    title: str
    author: str
    language: str = Field(default="fr", description="Kód jazyka ISO 639-1")
    word_count: Optional[int] = None
    tags: list[str] = Field(default_factory=list)

Polia s predvolenými hodnotami model vyplní, ak informáciu nájde, inak zachová predvolenú hodnotu.

Validácia zadarmo

V neposlednom rade: validácia je automatická. Ak hodnota nezodpovedá deklarovanému typu, Pydantic okamžite vyhodí ValidationError, ktorý presne označí problematické pole, bez toho, aby si musel napísať jediný riadok kontrolného kódu.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  # Chyba typu
        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, ...]

Všetok manuálny overovací kód napísaný v predchádzajúcej lekcii tu zmizne a nahradí ho deklarácia modelu.

Kľúčové poznatky

  • BaseModel z Pydantic je základom všetkých vlastných schém v Pythone
  • Používaj explicitné typy: str, int, float, bool, list[T], Optional[T]
  • Vnorené modely umožňujú komplexné štruktúry JSON
  • Field(description=...) zlepšuje kvalitu výstupu usmerňovaním modelu
  • Validácia je automatická – chyby typov sú detegované okamžite