Ορισμός Σχημάτων με το Pydantic
Σε αυτήν τη σελίδα
Pydantic: Η βάση για προσαρμοσμένες δομημένες εξόδους στην Python
Το Pydantic είναι η πιο δημοφιλής βιβλιοθήκη επικύρωσης δεδομένων στην Python. Σάς επιτρέπει να ορίζετε μοντέλα δεδομένων με αυστηρούς τύπους, κάτι που χρησιμοποιεί ακριβώς το API της Mistral για τις Προσαρμοσμένες Δομημένες Εξόδους. Αν εργάζεστε σε Python, το Pydantic γίνεται το κύριο εργαλείο σας για την περιγραφή σχημάτων εξόδου: ό,τι γράφετε σε μια κλάση, είναι αυτό στο οποίο θα περιοριστεί το μοντέλο να παράγει.
Τα καλά νέα σχετικά με την εγκατάσταση είναι τα εξής: το Pydantic περιλαμβάνεται ως εξάρτηση του Mistral SDK. Αν έχετε ήδη εγκαταστήσει το mistralai, δεν χρειάζεται να κάνετε τίποτα άλλο.
pip install mistralai
# Το Pydantic v2 περιλαμβάνεται αυτόματα
Ένας γρήγορος έλεγχος της έκδοσης αποφεύγει εκπλήξεις, καθώς η σύνταξη του validator άλλαξε μεταξύ των κύριων εκδόσεων:
import pydantic
print(pydantic.__version__) # Απαιτείται η 2.x
Ορισμός ενός απλού μοντέλου
Ένα μοντέλο Pydantic είναι μια κλάση που κληρονομεί από την BaseModel, όπου κάθε χαρακτηριστικό είναι ένα πεδίο με ρητό τύπο.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Αυτό το μοντέλο λέει στη Mistral: «Η έξοδός σας πρέπει να είναι ένα αντικείμενο JSON με ακριβώς αυτά τα 4 πεδία, όλα τύπου string». Δεν χρειάζονται πρόσθετες οδηγίες στο prompt για να ληφθεί αυτή η δομή.
Τύποι που θα χρησιμοποιήσετε
Το Pydantic υποστηρίζει όλους τους πρότυποικούς τύπους της Python και η Mistral τους κατανοεί όλους. Το παρακάτω μοντέλο τα συνδυάζει σε μια ρεαλιστική περίπτωση—ανάλυση ενός ticket υποστήριξης—και δείχνει πώς συνδυάζονται: βασικοί τύποι για απλά πεδία, Optional για έναν υπεύθυνο που δεν έχει ακόμη οριστεί, Enum για μια προτεραιότητα που μπορεί να πάρει μόνο τέσσερις τιμές, και λίστες για ετικέτες και σχετικά IDs.
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):
# Βασικοί τύποι
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Προαιρετικοί τύποι
assignee: Optional[str] = None
# Enums (περιορισμένες τιμές)
priority: Priority
# Λίστες
tags: list[str]
related_ids: list[int]
Ακολουθεί ο αντίστοιχος συνοπτικός πίνακας:
| Τύπος | Σημασία |
|---|---|
str | string |
int | ακέραιος |
float | δεκαδικός αριθμός |
bool | boolean (true/false) |
list[T] | λίστα στοιχείων τύπου T |
Optional[T] | πεδίο που μπορεί να είναι null |
Enum | τιμή από ένα πεπερασμένο σύνολο |
Τα Enums αξίζουν ιδιαίτερης μνείας: είναι ο μόνος τρόπος για να εγγυηθείτε ότι μια προτεραιότητα δεν θα γίνει ποτέ "very urgent" ή "P1" ανάλογα με τη διάθεση του μοντέλου.
Εμφωλευμένα μοντέλα
Τα δεδομένα του πραγματικού κόσμου σπάνια είναι επίπεδα. Μια επαφή ανήκει σε μια εταιρεία, η οποία έχει μια διεύθυνση. Το Pydantic σάς επιτρέπει να εμφωλεύετε μοντέλα όσο βαθιά χρειάζεται, και η Mistral ακολουθεί την ιεραρχία.
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 # Εμφωλευμένο μοντέλο
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Εμφώλευση δύο επιπέδων
Το παραγόμενο JSON αναπαράγει ακριβώς αυτή τη δομή δέντρου:
{
"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"
}
}
}
Ο ίδιος μηχανισμός εξάγει πολλαπλά στοιχεία ταυτόχρονα: ένα μοντέλο περιβάλλει μια λίστα από ένα άλλο μοντέλο και ανακτάτε έναν πλήρη κατάλογο με μία μόνο κλήση.
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
Καθοδήγηση του μοντέλου με περιγραφές
Το όνομα ενός πεδίου δεν λέει όλη την ιστορία. Το score θα μπορούσε να σημαίνει βαθμό έως το 10, ποσοστό ή τιμή μεταξύ 0 και 1· το μοντέλο πρέπει να μαντέψει. Οι περιγραφές απομακρύνουν αυτή την ασάφεια: περιλαμβάνονται στο σχήμα JSON που αποστέλλεται στη Mistral και λειτουργούν ως οδηγίες ανά πεδίο.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Γενικό συναίσθημα: 'positive', 'negative' ή 'neutral'"
)
score: float = Field(
description="Βαθμός εμπιστοσύνης μεταξύ 0.0 και 1.0"
)
keywords: list[str] = Field(
description="Οι 3-5 κύριες λέξεις-κλειδιά από το κείμενο"
)
summary: str = Field(
description="Σύνοψη σε μία το πολύ πρόταση"
)
Όσο πιο ακριβείς είναι αυτές οι περιγραφές, τόσο καλύτερη είναι η ποιότητα της εξόδου. Αυτό είναι το σημείο με τη μεγαλύτερη απόδοση σε όλη τη ρύθμιση: μερικές καλά επιλεγμένες λέξεις συχνά αντικαθιστούν μια ολόκληρη παράγραφο του prompt.
Το Field ορίζει επίσης προεπιλεγμένες τιμές. Στο επόμενο παράδειγμα, η γλώσσα προεπιλέγεται σε "fr" αν το μοντέλο δεν βρει τις πληροφορίες, ο αριθμός λέξεων παραμένει None αν δεν μπορεί να προσδιοριστεί, και οι ετικέτες ξεκινούν ως μια κενή λίστα χάρη στο default_factory.
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")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Τα πεδία με προεπιλεγμένες τιμές θα συμπληρωθούν από το μοντέλο αν βρει τις πληροφορίες, διαφορετικά θα διατηρήσουν την προεπιλεγμένη τιμή.
Η επικύρωση προσφέρεται δωρεάν
Τέλος, αλλά εξίσου σημαντικό: η επικύρωση είναι αυτόματη. Αν μια τιμή δεν ταιριάζει με τον δηλωμένο τύπο, το Pydantic raises αμέσως ένα ValidationError που υποδεικνύει ακριβώς ποιο πεδίο ευθύνεται, χωρίς εσείς να γράψετε ούτε μία γραμμή κώδικα ελέγχου.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Σφάλμα τύπου
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, ...]
Όλος ο χειροκίνητος κώδικας επαλήθευσης που γράφτηκε στο προηγούμενο μάθημα εξαφανίζεται εδώ, αντικαθιστώμενος από τη δήλωση του μοντέλου.
Βασικά σημεία
- Το
BaseModelτου Pydantic είναι η βάση όλων των προσαρμοσμένων σχημάτων στην Python - Χρησιμοποιήστε ρητούς τύπους:
str,int,float,bool,list[T],Optional[T] - Τα εμφωλευμένα μοντέλα επιτρέπουν σύνθετες δομές JSON
- Το
Field(description=...)βελτιώνει την ποιότητα της εξόδου καθοδηγώντας το μοντέλο - Η επικύρωση είναι αυτόματη—τα σφάλματα τύπου εντοπίζονται αμέσως