Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Definice schémat pomocí Pydantic

Lekce 7 z 12 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Pydantic: Základ vlastních strukturovaných výstupů v Pythonu
  2. Definice jednoduchého modelu
  3. Typy, které budeš používat
  4. Vnořené modely
  5. Navedení modelu pomocí popisů
  6. Validace zdarma
  7. Klíčové poznatky

Pydantic: Základ vlastních strukturovaných výstupů v Pythonu

Pydantic je nejoblíbenější knihovna pro validaci dat v Pythonu. Umožňuje ti definovat datové modely se striktními typy, což je přesně to, co API Mistral využívá pro vlastní strukturované výstupy (Custom Structured Outputs). Pokud pracuješ v Pythonu, stane se Pydantic tvým hlavním nástrojem pro popis schémat výstupu: to, co napíšeš do třídy, určuje, k jakému formátu bude model omezen.

Dobrou zprávou je instalace: Pydantic je zahrnut jako závislost SDK Mistral. Pokud již máš nainstalováno mistralai, nemusíš dělat nic dalšího.

pip install mistralai
# Pydantic v2 je zahrnut automaticky

Rychlá kontrola verze předejde překvapením, protože syntaxe validátorů se mezi hlavními verzemi změnila:

import pydantic
print(pydantic.__version__)  # Vyžadována verze 2.x

Definice jednoduchého modelu

Model Pydantic je třída dědící od BaseModel, kde každý atribut představuje pole s explicitním typem.

from pydantic import BaseModel

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

Tento model říká Mistralu: „Tvůj výstup musí být JSON objekt obsahující přesně tyto 4 pole, všechna typu řetězec.“ K získání této struktury nejsou v promptu potřeba žádné další instrukce.

Typy, které budeš používat

Pydantic podporuje všechny standardní typy Pythonu a Mistral jim všem rozumí. Následující model je spojuje dohromady v realistickém případě – analýze supportního ticketu – a ukazuje, jak se kombinují: základní typy pro jednoduchá pole, Optional pro přiřazenou osobu, která ještě není určena, Enum pro prioritu, která může nabývat pouze čtyř hodnot, a seznamy pro štítky a související 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

    # Volitelné typy
    assignee: Optional[str] = None

    # Enumy (omezené hodnoty)
    priority: Priority

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

Zde je odpovídající tahák:

TypVýznam
strřetězec
intcelé číslo
floatdesetinné číslo
boolboolean (pravda/nepravda)
list[T]seznam prvků typu T
Optional[T]pole, které může být null
Enumhodnota z konečné množiny

Enumy si zaslouží zvláštní zmínku: jsou jediným způsobem, jak zaručit, že priorita nikdy nebude "very urgent" nebo "P1" v závislosti na náladě modelu.

Vnořené modely

Data v reálném světě jsou zřídka plochá. Kontakt patří ke společnosti, která má adresu. Pydantic ti umožňuje vnořovat modely do libovolné hloubky a Mistral tuto hierarchii dodržuje.

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  # Vnořený model

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Dvouúrovňové vnoření

Vygenerovaný JSON přesně reprodukuje tuto stromovou strukturu:

{
  "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"
    }
  }
}

Stejný mechanismus umožňuje extrahovat najednou více položek: model obalí seznam jiného modelu a ty získáš kompletní katalog jediným volání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

Název pole neposkytuje celý obraz. score může znamenat známku do 10, procentuální vyjádření nebo hodnotu mezi 0 a 1 – model musí hádat. Popisy tuto nejednoznačnost odstraňují: jsou zahrnuty v JSON schématu odeslaném Mistralu a fungují jako instrukce pro jednotlivá pole.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Celková nálada: 'positive', 'negative' nebo 'neutral'"
    )
    score: float = Field(
        description="Skóre důvěryhodnosti mezi 0.0 a 1.0"
    )
    keywords: list[str] = Field(
        description="3 až 5 hlavních klíčových slov z textu"
    )
    summary: str = Field(
        description="Shrnutí maximálně v jedné větě"
    )

Čím přesnější jsou tyto popisy, tím lepší je kvalita výstupu. Toto je část celého nastavení s největším pákovým efektem: několik dobře zvolených slov často nahradí celý odstavec promptu.

Field také nastavuje výchozí hodnoty. V následujícím příkladu jazyk defaultně nabývá hodnoty "fr", pokud model informaci nenajde, počet slov zůstává None, pokud jej nelze určit, a štítky začínají jako prázdný seznam díky 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)

Pole s výchozími hodnotami model vyplní, pokud informaci najde, jinak zachová výchozí hodnotu.

Validace zdarma

V neposlední řadě: validace je automatická. Pokud hodnota neodpovídá deklarovanému typu, Pydantic okamžitě vyvolá ValidationError s přesným uvedením problematického pole, aniž bys musel psát jediný řádek 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, ...]

Veškerý manuální ověřovací kód napsaný v předchozí lekci zde mizí a je nahrazen deklarací modelu.

Klíčové poznatky

  • BaseModel z Pydantic je základem všech vlastních schémat v Pythonu
  • Používej explicitní typy: str, int, float, bool, list[T], Optional[T]
  • Vnořené modely umožňují složité struktury JSON
  • Field(description=...) zlepšuje kvalitu výstupu navedením modelu
  • Validace je automatická – chyby typů jsou detekovány okamžitě