Definovanie schém pomocou Pydantic
Na tejto strane
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:
| Typ | Význam |
|---|---|
str | reťazec |
int | celé číslo |
float | desatinné číslo |
bool | boolean (pravda/nepravda) |
list[T] | zoznam prvkov typu T |
Optional[T] | pole, ktoré môže byť null |
Enum | hodnota 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
BaseModelz 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