Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Définir des schémas avec Pydantic

Lektion 7 av 12 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Pydantic : le socle des sorties structurées personnalisées en Python
  2. Définir un modèle simple
  3. Les types que tu utiliseras
  4. Modèles imbriqués
  5. Guider le modèle avec des descriptions
  6. La validation est incluse gratuitement
  7. Viktiga punkter

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 :

TypeSignification
strchaîne de caractères
intentier
floatnombre décimal
boolbooléen (vrai/faux)
list[T]liste d’éléments de type T
Optional[T]champ pouvant être null
Enumvaleur 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

  • BaseModel de 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