Définir des schémas avec Pydantic
På denna sida
Pydantic : le socle des sorties structurées personnalisées en Python
Pydantic est la bibliothèque de validation de données la plus populaire en Python. Elle te permet de définir des modèles de données avec des types stricts, ce qui correspond exactement à ce que l’API Mistral utilise pour les sorties structurées personnalisées. Si tu travailles en Python, Pydantic devient ton outil principal pour décrire les schémas de sortie : ce que tu écris dans une classe est ce que le modèle sera contraint de produire.
Voici la bonne nouvelle concernant l’installation : Pydantic est inclus comme dépendance du SDK Mistral. Si tu as déjà installé mistralai, tu n’as rien d’autre à faire.
pip install mistralai
# Pydantic v2 est inclus automatiquement
Une vérification rapide de la version évite les surprises, car la syntaxe des validateurs a changé entre les versions majeures :
import pydantic
print(pydantic.__version__) # 2.x requis
Définir un modèle simple
Un modèle Pydantic est une classe qui hérite de BaseModel, où chaque attribut est un champ avec un type explicite.
from pydantic import BaseModel
class Contact(BaseModel):
name: str
email: str
phone: str
company: str
Ce modèle indique à Mistral : « Ta sortie doit être un objet JSON avec exactement ces 4 champs, tous de type chaîne de caractères. » Aucune instruction supplémentaire n’est nécessaire dans le prompt pour obtenir cette structure.
Les types que tu utiliseras
Pydantic prend en charge tous les types Python standards, et Mistral les comprend tous. Le modèle suivant les rassemble dans un cas réaliste — l’analyse d’un ticket de support — et montre comment ils se combinent : types de base pour les champs simples, Optional pour un assignataire non encore désigné, Enum pour une priorité ne pouvant prendre que quatre valeurs, et listes pour les étiquettes et les ID associés.
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):
# Types de base
title: str
description: str
ticket_id: int
confidence: float
is_urgent: bool
# Types optionnels
assignee: Optional[str] = None
# Énumérations (valeurs contraintes)
priority: Priority
# Listes
tags: list[str]
related_ids: list[int]
Voici l’antisèche correspondante :
| Type | Signification |
|---|---|
str | chaîne de caractères |
int | entier |
float | nombre décimal |
bool | booléen (vrai/faux) |
list[T] | liste d’éléments de type T |
Optional[T] | champ pouvant être null |
Enum | valeur issue d’un ensemble fini |
Les énumérations méritent une mention spéciale : elles sont le seul moyen de garantir qu’une priorité ne sera jamais "very urgent" ou "P1" selon l’humeur du modèle.
Modèles imbriqués
Les données du monde réel sont rarement plates. Un contact appartient à une entreprise, qui possède elle-même une adresse. Pydantic te permet d’imbriquer des modèles aussi profondément que nécessaire, et Mistral suit la hiérarchie.
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 # Modèle imbriqué
class Person(BaseModel):
first_name: str
last_name: str
email: str
role: str
company: Company # Imbrication à deux niveaux
Le JSON généré reproduit exactement cette structure arborescente :
{
"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"
}
}
}
Le même mécanisme permet d’extraire plusieurs éléments à la fois : un modèle enveloppe une liste d’un autre modèle, et tu récupères un catalogue complet en un seul appel.
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
Guider le modèle avec des descriptions
Un nom de champ ne raconte pas toute l’histoire. score pourrait signifier une note sur 10, un pourcentage ou une valeur entre 0 et 1 — le modèle doit deviner. Les descriptions lèvent cette ambiguïté : elles sont incluses dans le schéma JSON envoyé à Mistral et agissent comme des instructions par champ.
from pydantic import BaseModel, Field
class SentimentAnalysis(BaseModel):
sentiment: str = Field(
description="Sentiment global : 'positive', 'negative' ou 'neutral'"
)
score: float = Field(
description="Score de confiance entre 0.0 et 1.0"
)
keywords: list[str] = Field(
description="Les 3 à 5 mots-clés principaux du texte"
)
summary: str = Field(
description="Résumé en une phrase maximum"
)
Plus ces descriptions sont précises, meilleure est la qualité de la sortie. C’est la partie la plus rentable de toute la configuration : quelques mots bien choisis remplacent souvent un paragraphe entier de prompt.
Field permet également de définir des valeurs par défaut. Dans l’exemple suivant, la langue vaut par défaut "fr" si le modèle ne trouve pas l’information, le nombre de mots reste None s’il ne peut être déterminé, et les étiquettes commencent par une liste vide grâce à default_factory.
from pydantic import BaseModel, Field
from typing import Optional
class ArticleMetadata(BaseModel):
title: str
author: str
language: str = Field(default="fr", description="Code de langue ISO 639-1")
word_count: Optional[int] = None
tags: list[str] = Field(default_factory=list)
Les champs avec des valeurs par défaut seront remplis par le modèle s’il trouve l’information, ou conserveront la valeur par défaut dans le cas contraire.
La validation est incluse gratuitement
Enfin, dernier point mais non des moindres : la validation est automatique. Si une valeur ne correspond pas au type déclaré, Pydantic lève immédiatement une ValidationError indiquant exactement quel champ est en cause, sans que tu aies à écrire une seule ligne de code de vérification.
from pydantic import ValidationError
try:
analysis = SentimentAnalysis(
sentiment="positive",
score="not a number", # Erreur de type
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, ...]
Tout le code de vérification manuel écrit dans la leçon précédente disparaît ici, remplacé par la déclaration du modèle.
Viktiga punkter
BaseModelde Pydantic est la base de tous les schémas personnalisés en Python- Utilise des types explicites :
str,int,float,bool,list[T],Optional[T] - Les modèles imbriqués permettent des structures JSON complexes
Field(description=...)améliore la qualité de la sortie en guidant le modèle- La validation est automatique : les erreurs de type sont détectées immédiatement