Definice schémat pomocí Pydantic
Na této stránce
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:
| Typ | Význam |
|---|---|
str | řetězec |
int | celé číslo |
float | desetinné číslo |
bool | boolean (pravda/nepravda) |
list[T] | seznam prvků typu T |
Optional[T] | pole, které může být null |
Enum | hodnota 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
Navedení modelu pomocí popisů
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
BaseModelz 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ě