Instructor : Fini le parsing foireux, tes LLMs vont cracher du JSON propre

import instructor
from openai import OpenAI
from pydantic import BaseModel

class Article(BaseModel):
    titre: str
    resume: str

client = instructor.from_openai(OpenAI())

for article in client.chat.completions.create_iterable(
    model="gpt-4o-mini",
    response_model=Article,
    messages=[{
        "role": "user",
        "content": "Liste trois actualités IA du jour, avec un résumé.",
    }],
):
    print("-", article.titre)
    print(" ", article.resume)

Chaque itération renvoie un objet Article complet et validé. Cette API est idéale pour l'extraction de listes d'entités, la génération de jeux de données ou la structuration de documents longs en séries d'éléments homogènes.

Unions et champs optionnels

La réalité n'est pas toujours uniforme : un message peut être tantôt une simple phrase, tantôt une commande structurée. Pydantic gère cela avec les unions discriminées, et Instructor s'en accommode parfaitement. Le modèle choisit lui-même la classe qui correspond à l'entrée.

from typing import Annotated, Union, Literal
from pydantic import BaseModel, Field
import instructor
from openai import OpenAI

class Message(BaseModel):
    type: Literal["message"]
    texte: str

class Commande(BaseModel):
    type: Literal["commande"]
    action: str
    parametres: dict

# Union discriminée : le champ "type" détermine la classe retenue
Action = Annotated[Union[Message, Commande], Field(discriminator="type")]

client = instructor.from_openai(OpenAI())

action = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Action,
    messages=[{"role": "user", "content": "Programme une alarme à 7h demain."}],
)

print(type(action).__name__)   # Commande
print(action.action)

Les champs optionnels (Optional[...]) fonctionnent sur le même principe : le modèle renseigne le champ s'il trouve l'information, le laisse à None sinon. Cette souplesse est indispensable pour l'extraction depuis des textes hétérogènes où toutes les informations ne sont pas toujours présentes.

Valider avec tes propres règles

Au-delà des contraintes prédéfinies de Field, tu peux écrire des validateurs Pydantic sur mesure. L'intérêt est double : la règle est appliquée strictement, et si elle échoue, Instructor transmet l'erreur au modèle pour qu'il se corrige. C'est un pont direct entre tes règles métier et la génération.

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

class Utilisateur(BaseModel):
    nom: str
    email: str

    @field_validator("email")
    @classmethod
    def email_valide(cls, v):
        if "@" not in v or "." not in v:
            raise ValueError("adresse email invalide")
        return v

client = instructor.from_openai(OpenAI())

# Le modèle fournit un email mal formé : le validateur le refuse,
# et Instructor redemande une valeur correcte.
utilisateur = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Utilisateur,
    messages=[{"role": "user", "content": "Jean, email: jean.sans-arobase"}],
)
print(utilisateur.email)

Cette mécanique transforme Pydantic en véritable langage de contraintes métier : format d'email, plages de dates, cohérence entre champs, tout ce que tu sais exprimer en Python devient une règle que le modèle est contraint de respecter.

Instructor face aux alternatives

Instructor n'est pas la seule façon d'obtenir du JSON structuré. Pour situer l'outil, voici comment il se compare aux approches voisines :

• Function calling brut : tu écris toi-même le schéma, tu valides la sortie et tu gères les retries. Instructor automatise exactement ce travail, avec moins de code.
• LangChain et ses output parsers : un écosystème riche mais lourd, avec de nombreuses couches d'abstraction. Instructor se concentre sur une seule chose et la fait proprement.
• Guidance ou Outlines : une génération contrainte au niveau des tokens, très puissante pour des formats exotiques, mais plus complexe à mettre en œuvre. Instructor couvre l'immense majorité des besoins avec Pydantic.

Le point commun de ces alternatives : elles exigent de comprendre le mécanisme de structuration du modèle. Instructor, lui, te laisse raisonner uniquement en termes de classes Pydantic, ce qui réduit considérablement la charge cognitive.

Cas d'usage concrets

Partout où un LLM doit produire une sortie exploitable par du code, Instructor a sa place. Quelques scénarios typiques :

• Extraction d'entités depuis des documents : factures, CV, contrats transformés en objets exploitables.
• Classification de textes avec une justification structurée plutôt qu'une simple étiquette.
• Génération de jeux de données synthétiques typés pour tester une application.
• Structuration des réponses d'un chatbot : intention, entités détectées, prochaine action.
• Conversion de texte libre en JSON pour alimenter une API ou une base de données.

Dans chacun de ces cas, la sortie structurée est le produit, pas un détail. La fiabilité qu'apporte Instructor, avec ses retries et sa validation, fait la différence entre un prototype qui marche sur un exemple et un composant digne de la production.

Observabilité et journalisation

Quand une extraction échoue ou se répète, tu veux comprendre pourquoi. Instructor journalise ses appels et ses tentatives de correction via le logger Python standard, ce qui te permet de suivre le dialogue avec le modèle.

import logging

# Affiche les appels et les cycles de correction d'Instructor
logging.basicConfig(level=logging.INFO)

# En production, branche un système d'observabilité (Langfuse, LangSmith)
# via les callbacks du client pour tracer chaque extraction et son coût.

Une bonne visibilité sur les corrections est précieuse : si un modèle retente sans cesse sur un champ, c'est souvent le signe d'une contrainte mal formulée ou d'un schéma ambigu. Les journaux d'Instructor te montrent exactement ce que le modèle a produit et pourquoi cela a été refusé.

Migrer depuis le parsing manuel

Si tu as déjà du code qui demande du JSON puis le parse à la main, la comparaison avant/après parle d'elle-même. Voici ce que le même besoin donne avec et sans Instructor :

# AVANT : parsing manuel, fragile
import json

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Jean a 34 ans."}],
    response_format={"type": "json_object"},
)
donnees = json.loads(resp.choices[0].message.content)  # peut lever une exception
nom = donnees.get("nom")      # aucune garantie de type ni de présence
age = donnees.get("age")      # idem

# APRÈS : Instructor
utilisateur = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=Utilisateur,
    messages=[{"role": "user", "content": "Jean a 34 ans."}],
)
nom = utilisateur.nom   # str, garanti présent
age = utilisateur.age   # int, garanti valide

Le code « après » est plus court, plus lisible, et surtout plus sûr : plus de json.loads qui peut planter, plus de .get() qui renvoie None silencieusement, plus de vérification manuelle des types. La classe Pydantic joue le rôle de contrat, et Instructor s'assure qu'il est respecté.

Choisir le bon modèle pour la structuration

Tous les modèles ne se valent pas pour produire du JSON structuré. Quelques repères pour orienter ton choix :

• Modèles avec function calling robuste (GPT, Claude) : utilise le mode TOOLS, c'est le plus fiable.
• Modèles avec mode JSON natif : le mode JSON est plus économique et suffisant pour des schémas simples.
• Modèles locaux via Ollama : le mode MD_JSON est souvent le plus robuste, ou TOOLS si le modèle le supporte.
• Schémas complexes ou imbriqués : préfère un modèle plus grand, la structuration exige de la rigueur et de la constance.

Une bonne règle de départ : commence avec un modèle raisonnablement grand pour valider ton schéma, puis redescends vers un modèle plus petit ou local en vérifiant que la qualité d'extraction se maintient. La portabilité d'Instructor rend cette itération quasi gratuite.

Extraire depuis un texte long

Les modèles ont une fenêtre de contexte limitée : impossible d'envoyer un document de cent pages d'un bloc. La technique classique consiste à découper le texte en morceaux, puis à extraire la structure de chaque morceau. Instructor s'intègre naturellement dans ce genre de pipeline.

import instructor
from openai import OpenAI
from pydantic import BaseModel

class Evenement(BaseModel):
    date: str
    lieu: str
    description: str

client = instructor.from_openai(OpenAI())

def decouper(texte, taille=2000):
    # Découpe un texte long en morceaux de taille fixe
    return [texte[i:i + taille] for i in range(0, len(texte), taille)]

texte = "..."  # remplace par ton document complet

evenements = []
for extrait in decouper(texte):
    evt = client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=Evenement,
        messages=[{"role": "user", "content": f"Extrais l'événement décrit : {extrait}"}],
    )
    evenements.append(evt)

print(len(evenements), "événements extraits")
for evt in evenements:
    print(evt.date, "-", evt.lieu)

Chaque morceau produit un objet Evenement validé, et la liste finale est proprement typée. Ce patron « découper puis extraire » est au cœur de la plupart des pipelines de traitement documentaire, et la fiabilité d'Instructor évite qu'une extraction ratée sur un seul morceau ne corrompe tout le lot.

Pour des documents réellement structurés (PDF, tableaux), combine Instructor avec un parseur de document en amont, puis applique l'extraction sur le texte nettoyé. La qualité de l'entrée conditionne directement celle de la sortie, comme toujours en traitement du langage.

Aller plus loin : agents et pipelines

Instructor n'est qu'une brique. Dans une architecture réelle, il s'assemble naturellement avec d'autres outils : un agent qui décide de déclencher une extraction, un pipeline qui enchaîne plusieurs étapes de structuration, ou une API qui expose l'extraction comme un service. Sa simplicité en fait un composant facile à composer.

Tu peux par exemple construire un agent qui, face à un texte, choisit le bon schéma d'extraction via une union discriminée, puis alimente une base de données avec le résultat validé. La garantie de type offerte par Pydantic rend chaque étape fiable et testable, ce qui est le fondement d'un pipeline robuste.

De la même façon, rien n'empêche d'utiliser Instructor à l'intérieur d'un agent LangChain ou d'un script autonome : c'est une bibliothèque de structuration, pas un framework qui impose sa façon de faire. Elle s'insère là où tu as besoin d'une sortie fiable, et disparaît ailleurs.

L'essentiel à retenir

• Décris la sortie attendue avec Pydantic, pas avec des instructions floues dans le prompt.
• Laisse Instructor gérer la validation et les retries automatiques.
• Choisis le mode selon ton modèle : TOOLS, JSON ou MD_JSON.
• Le même code fonctionne sur OpenAI, Anthropic, Mistral et les modèles locaux.

Conclusion

Instructor remplace le parsing défensif par un contrat clair : tu décris ce que tu veux avec Pydantic, et tu reçois un objet validé. Les retries automatiques, la portabilité multi-fournisseurs et le support asynchrone en font un outil incontournable dès que ton application consomme des sorties structurées de LLM : extraction d'entités, classification, génération de formulaires, structuration de documents.

Le réflexe à adopter : chaque fois que tu t'apprêtes à écrire json.loads sur la sortie d'un LLM, demande-toi si une classe Pydantic et Instructor ne feraient pas le travail plus proprement. Dans l'immense majorité des cas, la réponse est oui.

Sources

• Documentation officielle d'Instructor
• Dépôt GitHub jxnl/instructor
• Documentation Pydantic
• Modes d'Instructor (tools, json, MD_JSON)
• Retries et validation