AI Engineering Academy · Leçon

Instructor : extraction typée avec Pydantic

Leçon 1 sur 413 étapes

Instructor : extraction typée avec Pydantic est une leçon AI Engineering Academy gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Engineering Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Engineering Academy comprend 4 leçons au total.

Qu’est-ce que la bibliothèque d’extraction ?

La bibliothèque d’extraction est une fine couche qui s’appuie sur le client OpenAI et rend l’extraction structurée fiable. Au lieu d’espérer que le modèle renvoie un JSON valide, elle impose votre schéma Pydantic et effectue automatiquement une nouvelle tentative en cas d’échec de la validation. Elle vous évite d’écrire vous-même une logique personnalisée d’analyse et de nouvelle tentative.

Installer la bibliothèque d’extraction

Installez la bibliothèque d’extraction avec une seule commande pip. Elle nécessite pydantic v2 et le SDK openai. Une fois l’installation terminée, vous appliquez un correctif au client OpenAI avec instructor.patch() afin d’obtenir le client amélioré qui prend en charge le paramètre response_model lors de chaque appel.

pip install instructor openai pydantic

Appliquer un correctif au client OpenAI

La bibliothèque d’extraction fonctionne en appliquant un correctif au client OpenAI standard. L’appel à instructor.from_openai(client) renvoie un nouveau client dont chaque appel à chat.completions.create accepte un argument nommé response_model. L’appel à l’API sous-jacente reste identique : la bibliothèque ajoute simplement l’imposition du schéma par-dessus.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Définir votre schéma Pydantic

Définissez la structure des données que vous souhaitez obtenir du modèle sous la forme d’un BaseModel Pydantic. Les noms et les types des champs, ainsi que leur documentation intégrée, sont automatiquement convertis en schéma JSON envoyé au modèle. Utilisez des noms de champs clairs et descriptifs afin que le modèle comprenne ce qu’il doit renseigner. Ajoutez des validateurs pour les règles métier.

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

Effectuer un appel d’extraction

Passez la classe de votre modèle Pydantic au client corrigé dans response_model. La bibliothèque construit un appel d’outil en arrière-plan, le modèle renseigne les champs, puis la bibliothèque désérialise le résultat en objet Python typé. Vous bénéficiez ainsi de la complétion automatique complète de votre environnement de développement et de la sécurité des types pour les données renvoyées.

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

Nouvelle tentative automatique en cas d’échec de validation

Si les données renvoyées par le modèle échouent à la validation Pydantic, la bibliothèque renvoie automatiquement l’erreur de validation au modèle et lui demande de corriger sa réponse. Vous pouvez configurer le nombre maximal de nouvelles tentatives avec le paramètre max_retries. Cette boucle d’auto-correction élimine la plupart des échecs isolés d’extraction sans code supplémentaire.

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

Modèles imbriqués pour les structures complexes

La bibliothèque gère parfaitement les modèles Pydantic imbriqués. Vous pouvez définir des schémas profondément imbriqués avec des listes, des sous-objets facultatifs et des unions discriminées. Le modèle reçoit l’intégralité du schéma JSON et doit renseigner tous les champs obligatoires, ce qui est idéal pour extraire des objets structurés tels que des factures ou des CV comportant plusieurs sections.

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

Extractions partielles en flux continu

Pour les tâches d’extraction volumineuses, la bibliothèque prend en charge le flux partiel via instructor.Partial[YourModel]. À mesure que le modèle génère des jetons, vous recevez en temps réel des instances de modèle partiellement renseignées. Cette approche est utile pour afficher la progression dans une interface ou traiter les champs dès leur arrivée, plutôt que d’attendre la réponse complète.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

Extraire des listes d’objets

Lorsque vous devez extraire plusieurs entités d’un même document, encapsulez votre modèle dans List[YourModel]. La bibliothèque gère le schéma du tableau JSON et désérialise chaque élément en objet Python typé. Cette méthode convient bien pour extraire toutes les personnes mentionnées dans un article, toutes les transactions d’un relevé ou toutes les dates d’un contrat.

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

Choisir le modèle adapté à l’extraction

Toutes les extractions ne nécessitent pas GPT-4o. Pour les schémas simples et plats comportant moins de 10 champs, gpt-4o-mini produit des résultats presque identiques pour un dixième du coût. Utilisez GPT-4o pour les schémas imbriqués complexes, les documents longs ou les cas où le rappel est important. Évaluez toujours les modèles sur un échantillon de vos données réelles avant d’en choisir un pour la production.

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

Journalisation et débogage des extractions

La bibliothèque expose un système de hooks pour la supervision. Enregistrez une fonction de rappel on_completion afin de journaliser la réponse brute de l’API, l’utilisation des jetons et le nombre de nouvelles tentatives pour chaque extraction. Vous pourrez ainsi identifier les types de documents qui provoquent le plus d’échecs et adapter vos schémas ou vos invites en conséquence.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

Vérification rapide

Vérifiez votre compréhension de la bibliothèque d’extraction typée.

Réponds-y dans la leçon interactive

Récapitulatif de la leçon

Dans cette leçon, vous avez appris que la bibliothèque applique un correctif au client OpenAI pour accepter un paramètre response_model qui impose les schémas Pydantic, que la nouvelle tentative automatique en cas d’échec de validation rend l’extraction robuste sans gestion manuelle des erreurs, et que les modèles imbriqués et l’extraction de listes permettent d’analyser des documents complexes contenant plusieurs entités pour obtenir des objets Python entièrement typés. La prochaine étape consiste à gérer les données partielles et manquantes dans les schémas extraits.

Gratuit pour commencer

Apprends Python avec un tuteur IA — gratuit

Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.

Cours: 30
Leçons: 120

Commencer gratuitement Voir le cours complet

Questions Fréquemment Posées

La leçon « Instructor : extraction typée avec Pydantic » est-elle gratuite ?

Oui — le texte complet de « Instructor : extraction typée avec Pydantic » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Engineering Academy, passe à CoddyKit PRO. Le cours AI Engineering Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Instructor : extraction typée avec Pydantic » ?

Utilisez la bibliothèque instructor pour modifier le client OpenAI afin qu’il réessaie automatiquement et valide les réponses par rapport à votre schéma Pydantic jusqu’à ce que l’extraction réussisse. Tu pratiques AI Engineering Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer AI Engineering Academy ?

Aucune expérience préalable n'est requise. AI Engineering Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « Instructor : extraction typée avec Pydantic » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon AI Engineering Academy ?

Oui. Chaque leçon AI Engineering Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Instructor : extraction typée avec Pydantic
Gérer les données partielles et manquantes
Traitement par lots avec l’asynchronisme et des files d’attente
Évolution des schémas et compatibilité descendante

← Retour à AI Engineering Academy