Pydantic + OpenAI : La manière la plus propre d'obtenir des sorties structurées des LLMs

Pydantic + OpenAI : La méthode la plus propre pour obtenir des sorties structurées des LLM

Les grands modèles de langage (LLM) sont remarquablement doués pour générer du texte semblable à celui d'un humain, mais ils produisent souvent des sorties non structurées ou semi-structurées qui nécessitent un post-traitement important. Lorsque vous créez des applications de production — que ce soit pour l'extraction de données, la modération de contenu ou la génération de rapports automatisés — vous avez besoin de données fiables, typées et validées. C'est là qu'interviennent Pydantic et OpenAI : une combinaison puissante qui vous permet de définir exactement la structure de sortie souhaitée, et de faire en sorte que le LLM la fournisse dans un format propre et prévisible.

Cet article vous guide à travers les étapes pratiques pour configurer Pydantic avec OpenAI, de l'installation à une utilisation concrète. À la fin, vous disposerez d'un modèle réutilisable pour obtenir des sorties structurées des modèles GPT avec un minimum de code passe-partout.

Pourquoi les sorties structurées sont importantes

Lorsque vous posez une question à un LLM, vous obtenez généralement un paragraphe de texte. Pour un chatbot, c'est acceptable. Mais si vous devez extraire une liste de noms de clients, de dates et de montants à partir d'un e-mail, ou générer un objet JSON pour une base de données, le texte brut devient un problème. Vous pourriez essayer d'analyser la sortie avec des expressions régulières ou un deuxième appel LLM, mais ces approches sont fragiles et sujettes aux erreurs.

Les sorties structurées résolvent ce problème en contraignant le modèle à produire des données qui correspondent à un schéma prédéfini. C'est là que Pydantic excelle. Pydantic est une bibliothèque Python pour la validation de données utilisant les annotations de type Python. Lorsqu'elle est combinée avec les capacités d'appel de fonction ou de sortie structurée d'OpenAI, vous obtenez :

• **Sécurité des types** – La sortie est automatiquement validée par rapport à votre schéma.
• **Aucun analyse manuelle** – Le modèle renvoie une instance de modèle Pydantic, pas du texte brut.
• **Contrats clairs** – Votre code sait exactement à quels champs s'attendre.

Prérequis

Avant de commencer, assurez-vous d'avoir les éléments suivants :

• **Python 3.9+** – Pydantic v2 nécessite Python 3.9 ou une version ultérieure.
• **Une clé API OpenAI** – Vous avez besoin d'une clé valide avec accès aux modèles GPT-4 ou GPT-3.5-turbo prenant en charge l'appel de fonction.
• **Une familiarité de base avec Python** – Vous devez comprendre les classes, les types et la programmation asynchrone (facultatif mais utile).

Installation étape par étape

Nous allons configurer un environnement propre et installer les bibliothèques nécessaires.

1. Créer et activer un environnement virtuel

L'isolation des dépendances évite les conflits avec d'autres projets.

python -m venv pydantic_openai_env
source pydantic_openai_env/bin/activate  # Sur Windows : pydantic_openai_env\Scripts\activate

2. Installer Pydantic et la bibliothèque Python OpenAI

Pydantic v2 est la version majeure actuelle. La bibliothèque OpenAI inclut la prise en charge de l'appel de fonction et des sorties structurées.

pip install pydantic openai

3. Vérifier l'installation

Effectuez une vérification rapide pour confirmer que les deux bibliothèques sont disponibles.

import pydantic
import openai
print(f"Version de Pydantic : {pydantic.__version__}")
print(f"Version de la bibliothèque OpenAI : {openai.__version__}")

Si vous voyez des numéros de version (par exemple, `2.5.0` pour Pydantic et `1.6.0` pour OpenAI), vous êtes prêt.

4. Définir votre clé API OpenAI

Stockez votre clé en tant que variable d'environnement pour des raisons de sécurité.

export OPENAI_API_KEY="votre-clé-api-ici"

Vous pouvez également la définir dans votre script Python, mais l'utilisation de variables d'environnement est recommandée pour la production.

Concept fondamental : Définir un modèle Pydantic

Un modèle Pydantic est une classe qui hérite de `BaseModel`. Chaque champ est annoté avec un type, et des valeurs par défaut ou des validateurs facultatifs peuvent être ajoutés.

Voici un modèle simple pour extraire les informations d'une personne à partir d'un texte :

from pydantic import BaseModel, Field
from typing import Optional

class Personne(BaseModel):
    nom: str = Field(description="Le nom complet de la personne")
    age: Optional[int] = Field(None, description="Âge en années, si mentionné")
    email: Optional[str] = Field(None, description="Adresse e-mail, si présente")

La fonction `Field` vous permet d'ajouter des descriptions, des valeurs par défaut et des contraintes. Ces descriptions sont transmises au LLM pour guider sa sortie.

La magie : Combiner Pydantic avec l'appel de fonction OpenAI

L'appel de fonction d'OpenAI vous permet de spécifier un schéma JSON auquel le modèle doit adhérer lors de la génération d'une réponse. Les modèles Pydantic peuvent être automatiquement convertis en ce schéma à l'aide de la méthode `.model_json_schema()`.

Voici un flux de travail complet :

Étape 1 : Définir votre modèle de sortie

Nous allons créer un modèle pour extraire une liste d'avis sur des produits.

from pydantic import BaseModel, Field
from typing import List

class Avis(BaseModel):
    nom_produit: str = Field(description="Nom du produit évalué")
    note: int = Field(ge=1, le=5, description="Note de 1 à 5")
    resume: str = Field(description="Résumé en une phrase de l'avis")

class ListeAvis(BaseModel):
    avis: List[Avis] = Field(description="Liste des avis trouvés dans le texte")

Étape 2 : Préparer le client OpenAI et la définition de la fonction

Nous allons utiliser le client OpenAI (syntaxe v1.0+) et convertir notre modèle en un schéma JSON.

from openai import OpenAI

client = OpenAI()

# Convertir ListeAvis en un schéma JSON
schema_avis = ListeAvis.model_json_schema()

Le schéma ressemblera à un objet JSON Schema standard, qu'OpenAI utilise pour définir les paramètres de la fonction.

Étape 3 : Effectuer l'appel API avec l'appel de fonction

Nous passons le schéma comme définition de fonction et demandons au modèle d'appeler cette fonction.

reponse = client.chat.completions.create(
    model="gpt-4-1106-preview",  # ou "gpt-3.5-turbo-1106"
    messages=[
        {"role": "system", "content": "Vous extrayez des données structurées à partir de l'entrée utilisateur."},
        {"role": "user", "content": "J'ai adoré le nouvel iPhone 15. L'appareil photo est incroyable. Je lui donne 5 étoiles. Aussi, le MacBook Pro est trop cher mais puissant. Je le noterais 3 étoiles."}
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "extraire_avis",
            "description": "Extraire les avis sur les produits du texte d'entrée",
            "parameters": schema_avis
        }
    }],
    tool_choice={"type": "function", "function": {"name": "extraire_avis"}}
)

Étape 4 : Analyser la réponse dans un modèle Pydantic

La réponse du modèle contiendra un argument d'appel de fonction (une chaîne JSON). Nous l'analysons directement dans notre modèle Pydantic.

import json

# Extraire les arguments de l'appel de fonction
appel_outil = reponse.choices[0].message.tool_calls[0]
arguments = json.loads(appel_outil.function.arguments)

# Valider et créer le modèle Pydantic
avis = ListeAvis(**arguments)
print(avis)

Sortie (formatée) :

avis=[
    Avis(nom_produit='iPhone 15', note=5, resume='Adoré l\'appareil photo incroyable.'),
    Avis(nom_produit='MacBook Pro', note=3, resume='Trop cher mais puissant.')
]

Remarquez que le modèle a automatiquement validé la plage de notes (1–5) et analysé la liste. Si le LLM avait renvoyé une note invalide (par exemple, 6), Pydantic aurait levé une `ValidationError`.

Exemples d'utilisation

Explorons deux scénarios pratiques : l'extraction de données structurées à partir d'e-mails et la génération d'objets de configuration.

Exemple 1 : Analyse d'e-mails pour le support client

Imaginez que vous recevez des e-mails de support et que vous devez extraire le type de problème, la priorité et l'identifiant client.

from pydantic import BaseModel, Field
from enum import Enum

class Priorite(str, Enum):
    faible = "faible"
    moyenne = "moyenne"
    elevee = "élevée"

class TicketSupport(BaseModel):
    id_client: str = Field(description="Identifiant client provenant de la signature de l'e-mail")
    type_probleme: str = Field(description="Catégorie du problème : facturation, technique ou compte")
    priorite: Priorite = Field(description="Niveau d'urgence")
    description: str = Field(description="Résumé bref du problème")

Ensuite, utilisez le même modèle que ci-dessus pour extraire ces informations du corps d'un e-mail. Le LLM renverra une instance `TicketSupport` validée.

Exemple 2 : Génération d'objets de configuration

Vous pouvez également générer des configurations complexes et imbriquées, comme des paramètres de connexion à une base de données.

from pydantic import BaseModel, Field
from typing import Dict

class ConfigurationBaseDonnees(BaseModel):
    hote: str = Field(description="Nom d'hôte ou IP de la base de données")
    port: int = Field(ge=1, le=65535, description="Numéro de port")
    identifiants: Dict[str, str] = Field(description="Nom d'utilisateur et mot de passe sous forme de dictionnaire")

Demandez au LLM : « Générez une configuration de base de données pour une instance PostgreSQL fonctionnant sur localhost avec l'utilisateur 'admin' et le mot de passe 'secret123'. » Le modèle renverra une configuration validée.

Bonnes pratiques et conseils

1. **Utilisez des noms de champs et des descriptions descriptifs** – Le LLM les utilise pour comprendre ce que vous voulez. Soyez précis. 2. **Tirez parti des contraintes de type** – Pydantic prend en charge `ge`, `le`, `min_length`, `regex`, etc. Ces contraintes sont encodées dans le schéma JSON et aident le LLM à générer des sorties valides. 3. **Gérez les erreurs avec élégance** – Pydantic lèvera une `ValidationError` si la sortie du modèle ne correspond pas à votre schéma. Encapsulez l'analyse dans un bloc try-except et réessayez avec une invite plus claire. 4. **Gardez les schémas de taille raisonnable** – Des schémas très volumineux (nombreux champs ou imbrication profonde) peuvent dérouter le modèle. Divisez les extractions complexes en plusieurs appels si nécessaire. 5. **Utilisez des énumérations pour les ensembles fixes** – Si un champ ne peut prendre qu'une des quelques valeurs, définissez une classe `Enum`. Cela contraint la sortie du LLM à des options valides.

Limites et considérations

Bien que cette approche soit puissante, elle n'est pas parfaite :

• **Coût** – L'appel de fonction utilise plus de tokens, surtout avec des schémas volumineux. Surveillez votre utilisation de l'API.
• **Prise en charge du modèle** – Tous les modèles OpenAI ne prennent pas en charge l'appel de fonction. Utilisez `gpt-4-1106-preview` ou `gpt-3.5-turbo-1106` pour de meilleurs résultats.
• **Complexité du schéma** – Des schémas extrêmement imbriqués ou récursifs peuvent amener le modèle à halluciner ou à omettre des champs. Gardez-le plat lorsque c'est possible.
• **Latence** – Le traitement supplémentaire pour l'appel de fonction ajoute une petite surcharge (généralement <100 ms).

Conclusion

Pydantic + OpenAI fournit la méthode la plus propre et la plus fiable pour obtenir des sorties structurées des LLM. En définissant un modèle Pydantic, en le convertissant en un schéma JSON et en utilisant l'appel de fonction d'OpenAI, vous éliminez l'analyse manuelle et gagnez en sécurité des types, en validation et en contrats clairs. Ce modèle est idéal pour l'extraction de données, le remplissage de formulaires, la génération de code et toute tâche où vous avez besoin de données structurées et prévisibles à partir du langage naturel.

Commencez modestement : définissez un modèle simple pour votre prochain projet, intégrez-le avec un seul appel API et itérez. Au fur et à mesure que vous vous sentez à l'aise, vous pouvez passer à des flux de travail complexes en plusieurs étapes. La combinaison de la puissance de validation de Pydantic et de la compréhension du langage d'OpenAI change la donne pour la création d'applications d'IA robustes.

*Remarque : Cet article est basé sur des connaissances générales de Pydantic et d'OpenAI en date du début 2025. Pour les dernières mises à jour, consultez la documentation officielle de Pydantic et le journal des modifications de l'API OpenAI.*