Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määritä skeemat Pydanticilla

Oppitunti 7 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Pydantic: Mukautettujen jäsenneltyjen tulosteiden perusta Pythonissa
  2. Yksinkertaisen mallin määrittäminen
  3. Käyttämäsi tyypit
  4. Sisäkkäiset mallit
  5. Ohjaa mallia kuvauksilla
  6. Validointi tulee kaupan päälle
  7. Keskeiset asiat

Pydantic: Mukautettujen jäsenneltyjen tulosteiden perusta Pythonissa

Pydantic on Pythonin suosituin datan validointikirjasto. Sen avulla voit määrittää datamalleja tiukoilla tyypeillä, mikä on täsmälleen se tapa, jolla Mistral API hyödyntää mukautettuja jäsenneltyjä tulosteita. Jos työskentelet Pythonilla, Pydanticista tulee ensisijainen työkalusi tulosteskeemojen kuvaamiseen: se, mitä kirjoitat luokkaan, rajoittaa mallin tuottaman tulosteen vastaamaan sitä.

Hyviä uutisia asennuksesta: Pydantic sisältyy Mistral SDK:n riippuvuuksiin. Jos sinulla on jo mistralai asennettuna, sinun ei tarvitse tehdä mitään muuta.

pip install mistralai
# Pydantic v2 sisältyy automaattisesti

Nopea versiotarkistus säästää yllätyksiltä, sillä validaattorisyntaksi muuttui pääversioiden välillä:

import pydantic
print(pydantic.__version__)  # Vaaditaan versio 2.x

Yksinkertaisen mallin määrittäminen

Pydantic-malli on luokka, joka perii BaseModel-luokan, jossa jokainen attribuutti on kenttä, jolla on eksplisiittinen tyyppi.

from pydantic import BaseModel

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

Tämä malli kertoo Mistralille: “Tulosteesi on oltava JSON-objekti, jossa on täsmälleen nämä 4 kenttää, ja kaikkien on oltava merkkijonoja.” Rakenne saadaan aikaan ilman lisäohjeita kehotteessa.

Käyttämäsi tyypit

Pydantic tukee kaikkia vakio-Python-tyyppejä, ja Mistral ymmärtää ne kaikki. Seuraava malli yhdistää ne realistisessa tapauksessa – tukipyyntöä analysoitaessa – ja osoittaa, miten niitä yhdistellään: perustyypit yksinkertaisiin kenttiin, Optional vielä nimeämättömälle vastuuhenkilölle, Enum prioriteetille, joka voi saada vain neljä arvoa, sekä listat tageille ja liittyville tunnisteille.

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):
    # Perustyypit
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Valinnaiset tyypit
    assignee: Optional[str] = None

    # Enumit (rajoitetut arvot)
    priority: Priority

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

Tässä vastaava pikaopas:

TyyppiMerkitys
strmerkkijono
intkokonaisluku
floatdesimaaliluku
booltotuusarvo (true/false)
list[T]listan alkiot, joiden tyyppi on T
Optional[T]kenttä, joka voi olla null
Enumarvo äärellisestä joukosta

Enumit ansaitsevat erityismaininnan: ne ovat ainoa tapa taata, ettei prioriteetti ole koskaan "very urgent" tai "P1" mallin mielentilasta riippuen.

Sisäkkäiset mallit

Todellisen maailman data on harvoin litteää. Yhteystieto kuuluu yritykselle, jolla on osoite. Pydanticin avulla voit sisällyttää malleja toisiinsa niin syvälle kuin tarvitaan, ja Mistral noudattaa hierarkiaa.

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  # Sisäkkäinen malli

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Kahden tason sisäkkäisyys

Generoitu JSON toistaa tämän puurakenteen täsmälleen:

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

Sama mekanismi poimii useita kohteita kerralla: malli käärii toisen mallin listan, ja saat koko luettelon yhdellä kutsulla.

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

Ohjaa mallia kuvauksilla

Kentän nimi ei kerro koko tarinaa. score voi tarkoittaa arvosanaa asteikolla 0–10, prosenttilukua tai arvoa välillä 0–1 – mallin on arvattava. Kuvaukset poistavat tämän epäselvyyden: ne sisällytetään Mistralille lähetettävään JSON-skeemaan ja toimivat kenttäkohtaisina ohjeina.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Yleinen sävy: 'positive', 'negative' tai 'neutral'"
    )
    score: float = Field(
        description="Luottamusarvo välillä 0.0–1.0"
    )
    keywords: list[str] = Field(
        description="Tekstin 3–5 tärkeintä avainsanaa"
    )
    summary: str = Field(
        description="Yhteenveto enintään yhdellä lauseella"
    )

Mitä tarkempia nämä kuvaukset ovat, sitä parempi on tulosteen laatu. Tämä on koko asetelman vaikuttavin osa: muutama hyvin valittu sana korvaa usein kokonaisen kappaleen kehotetta.

Field asettaa myös oletusarvot. Seuraavassa esimerkissä kieli on oletuksena "fr", jos malli ei löydä tietoa, sanamäärä pysyy None:nä, jos sitä ei voida määrittää, ja tagit alkavat tyhjänä listana default_factory-asetuksen ansiosta.

from pydantic import BaseModel, Field
from typing import Optional

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

Kentät, joilla on oletusarvot, täytetään mallin löytäessä tiedon; muuten ne säilyttävät oletusarvon.

Validointi tulee kaupan päälle

Viimeisenä mutta ei vähäisimpänä: validointi on automaattista. Jos arvo ei vastaa ilmoitettua tyyppiä, Pydantic nostaa välittömästi ValidationError-poikkeuksen, joka ilmoittaa täsmälleen, mikä kenttä on viallinen, ilman että sinun tarvitsee kirjoittaa riviäkään tarkistuskoodia.

from pydantic import ValidationError

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

Kaikki edellisessä oppitunnissa kirjoitettu manuaalinen tarkistuskoodi katoaa tässä, korvautuen mallimäärityksellä.

Keskeiset asiat

  • Pydanticin BaseModel on kaikkien Pythonin mukautettujen skeemojen perusta
  • Käytä eksplisiittisiä tyyppejä: str, int, float, bool, list[T], Optional[T]
  • Sisäkkäiset mallit mahdollistavat monimutkaiset JSON-rakenteet
  • Field(description=...) parantaa tulosteen laatua ohjaamalla mallia
  • Validointi on automaattista – tyyppivirheet havaitaan välittömästi