Guide

Instructor, des sorties structurées à partir de modèles de langage

Instructor ajoute response_model à un client LLM et renvoie un objet Pydantic validé. Trois paquets au même nom, licence, modes, retries, streaming et pièges.

L'équipe CodeWorlds16 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Instructor enveloppe un client de modèle de langage et ajoute un paramètre à l'appel, response_model. Au lieu d'une chaîne, tu obtiens un objet Pydantic validé, et quand la validation échoue, la bibliothèque renvoie la requête avec le texte de l'erreur. La version Python est la 1.15.4, publiée le 28 juin 2026, sous licence MIT.

Ce qu'Instructor fait réellement

Le mécanisme est simple et il est bon qu'il le reste, car la prévisibilité de la bibliothèque en dépend. Tu passes une classe qui dérive de BaseModel. Instructor la transforme en JSON Schema, place ce schéma dans une définition d'outil ou dans le champ response_format, envoie la requête, reçoit les arguments de l'appel d'outil et les fait passer par model_validate_json. Si Pydantic lève ValidationError, la bibliothèque ajoute la réponse du modèle ainsi qu'un nouveau message utilisateur contenant Validation Error found: avec le texte de l'exception et la phrase Recall the function correctly, fix the errors, puis répète l'appel. Quand les tentatives sont épuisées, tu obtiens InstructorRetryException.

C'est tout. Instructor n'est pas un framework d'agents, il ne tient aucun registre d'outils, il ne gère pas la mémoire de conversation et il n'a rien à voir avec la recherche sémantique. Si tu cherches une couche d'orchestration avec une boucle d'agent et de l'injection de dépendances, Pydantic AI est plus proche de ce que tu veux. Si c'est l'optimisation de prompts qui t'intéresse, regarde DSPy. Instructor se place délibérément plus bas et fait une seule chose.

La couche est fine, la liste de dépendances ne l'est pas. Le paquet instructor 1.15.4 tire dix bibliothèques : openai dans la plage de 2.0.0 à 3.0.0, pydantic à partir de 2.8.0, pydantic-core, tenacity à partir de 8.2.3, jiter, jinja2, docstring-parser, requests, rich et typer, plus aiohttp à partir de 3.9.1. Cela signifie que même si tu travailles exclusivement avec Anthropic, le paquet OpenAI atterrit quand même dans ton environnement. La prise en charge des autres fournisseurs vient d'extras, par exemple instructor[anthropic] ou instructor[google-genai]. Le Python requis est au moins 3.9 et inférieur à 4.0.

Trois paquets qui partagent un même nom

C'est le faux pas le plus courant à la première installation et la raison pour laquelle cette section est si haute. Trois entités aux noms similaires existent dans les registres et une seule est celle dont parle la documentation.

PaquetRegistreVersionLicenceDernier changementEst-ce Instructor
instructorPyPI1.15.4MIT28 juin 2026oui, c'est le projet
instructornpm1.0.0ISC19 juin 2022non, un nom mis de côté
@instructor-ai/instructornpm1.7.0MIT27 janvier 2025oui, mais le portage TypeScript

Le paquet instructor sur npm n'a rien à voir avec ce projet et n'en a jamais eu. L'archive décompressée contient exactement deux fichiers : package.json de 450 octets et README.md de 222 octets. Il n'y a pas une seule ligne de code, pas de fichier de licence, et le champ repository pointe vers github.com/npm/deprecate-holder. Le README déclare clairement que le paquet est déprécié et que npm garde le nom pour que personne ne le prenne à des fins malveillantes. L'entrée du registre a été créée en février 2016, sept ans avant l'existence d'Instructor. Donc npm install instructor te donne une coquille vide sans aucun avertissement que tu as choisi le mauvais paquet.

La version TypeScript s'appelle @instructor-ai/instructor et c'est le bon équivalent. Ici le problème est différent et pire dans ses conséquences : la version 1.7.0 a été publiée le 27 janvier 2025 et rien n'a changé depuis. La branche principale du dépôt 567-labs/instructor-js porte toujours 1.7.0 dans package.json, le dernier tag de version est v1.7.0, et le dépôt compte environ 802 étoiles contre 13 761 pour la version Python. Ce n'est pas un projet activement maintenu, c'est un projet qui s'est arrêté il y a plus d'un an et demi. Si tu écris du TypeScript et que tu as besoin de quelque chose qui suive les changements des fournisseurs, considère ce paquet comme un risque plutôt qu'une option équivalente.

Licence vérifiée à trois endroits

Une déclaration dans un registre est parfois autre chose que le contenu de l'archive publiée, donc j'ai vérifié les deux paquets à trois points indépendants.

SourceVersion PythonVersion TypeScript
Fichier LICENSE du dépôtMIT, Copyright (c) 2023 Jason LiuMIT, Copyright (c) 2024 Jason Liu
Champ license du registreMIT dans les métadonnées PyPIMIT dans les métadonnées npm
Contenu de l'archive publiéeLICENSE dans le répertoire dist-info, 195 fichiers .pyLICENSE dans le répertoire racine, 9 fichiers

Le résultat concorde dans les deux cas et c'est un plaisir rare. La wheel instructor-1.15.4-py3-none-any.whl pèse 252 522 octets, contient 195 fichiers .py et un fichier de licence à instructor-1.15.4.dist-info/licenses/LICENSE, avec l'en-tête de métadonnées License-File qui y pointe. L'archive @instructor-ai/instructor 1.7.0 contient 9 fichiers pour 110 938 octets décompressés, dont un LICENSE avec le texte MIT et un répertoire dist compilé. Nulle part il n'y a de décalage entre la déclaration et le contenu, pas de fichier supplémentaire sous une autre licence, pas de paquet vide qui se fait passer pour du code fonctionnel.

Une chose surprend quand on récupère les sources. L'archive instructor-1.15.4.tar.gz sur PyPI pèse 70 049 678 octets, soit environ 278 fois plus que la wheel. L'archive embarque le dépôt avec la documentation et les images. Installer via pip récupère la wheel et tu ne remarqueras pas la différence, mais un outil qui construit depuis les sources ou un miroir de registre la remarquera certainement.

Il n'y a pas de variante payante. Instructor est une bibliothèque sans service derrière, donc pas de grille tarifaire, pas d'offre gratuite et pas de limites. Les coûts viennent uniquement du fournisseur de modèles, et Instructor ajoute le surcoût que décrit la section sur les retries. En pratique, un petit groupe autour de l'auteur maintient le projet, ce qui, sur 96 versions PyPI, donne un rythme rapide mais aussi le risque habituel de l'open source de n'avoir aucun contrat de support.

Fournisseurs et modes de fonctionnement

Tu choisis un fournisseur soit via une fonction dédiée, soit via une seule chaîne. La fonction from_provider prend une valeur au format provider/model et reconnaît 23 alias : openai, anthropic, google, generative-ai, gemini, vertexai, azure_openai, bedrock, mistral, cohere, groq, cerebras, fireworks, together, anyscale, databricks, deepseek, perplexity, openrouter, litellm, ollama, writer et xai.

Python
import instructor
from pydantic import BaseModel, Field

class Invoice(BaseModel):
    number: str = Field(description="Invoice number from the header")
    net_total: float
    currency: str

client = instructor.from_provider("openai/gpt-4o-mini")

invoice = client.chat.completions.create(
    response_model=Invoice,
    messages=[{"role": "user", "content": raw_text}],
    max_retries=2,
)
print(invoice.net_total, invoice.currency)

La signature de from_provider est model, async_client=False, cache=None et mode=None, les autres arguments étant transmis au constructeur du client du fournisseur. Régler async_client=True renvoie AsyncInstructor au lieu d'Instructor. Le paramètre cache prend un adaptateur, par exemple AutoCache(maxsize=1000) ou RedisCache, et circule ensuite via kwargs jusqu'à l'implémentation du fournisseur.

Le mode décide de la manière dont le schéma arrive dans la requête. L'énumération Mode a des valeurs comme Mode.TOOLS avec la valeur tool_call, Mode.JSON avec la valeur json_mode, Mode.JSON_SCHEMA, Mode.MD_JSON avec la valeur markdown_json_mode, Mode.PARALLEL_TOOLS et Mode.RESPONSES_TOOLS pour la nouvelle interface d'OpenAI. S'y ajoutent des variantes propres à chaque fournisseur, dont Mode.ANTHROPIC_TOOLS, Mode.ANTHROPIC_JSON, Mode.GEMINI_TOOLS, Mode.GENAI_JSON, Mode.COHERE_TOOLS et Mode.BEDROCK_TOOLS.

Python
from openai import OpenAI
import instructor

# tool calling, the default and usually the most reliable
tools = instructor.from_openai(OpenAI(), mode=instructor.Mode.TOOLS)

# JSON mode, when the model has no tool calls
plain_json = instructor.from_openai(OpenAI(), mode=instructor.Mode.JSON)

# schema enforced on the provider side
strict = instructor.from_openai(OpenAI(), mode=instructor.Mode.JSON_SCHEMA)

# last resort: JSON inside a markdown block
markdown = instructor.from_openai(OpenAI(), mode=instructor.Mode.MD_JSON)

Pour le fournisseur openai, la bibliothèque considère six modes comme pris en charge : TOOLS, JSON, JSON_SCHEMA, MD_JSON, PARALLEL_TOOLS et RESPONSES_TOOLS. Trois modes sont silencieusement redirigés vers d'autres parce qu'ils ont été retirés : Mode.FUNCTIONS passe à TOOLS avec un avertissement de dépréciation, Mode.TOOLS_STRICT aussi à TOOLS, et Mode.JSON_O1 à JSON_SCHEMA. Si tu règles l'un des anciens modes et que tu te demandes pourquoi le comportement ne correspond pas au nom, c'est exactement pour cela. La différence pratique entre les modes se résume à ceci : TOOLS et JSON_SCHEMA te donnent un schéma imposé par le fournisseur, tandis que JSON et MD_JSON reposent sur le fait que le modèle suive les instructions, donc leur part de validations échouées est nettement plus élevée.

Retries, validation et hooks

Le paramètre max_retries prend un entier ou une instance Retrying de la bibliothèque tenacity. Avec un entier, Instructor construit la condition d'arrêt stop_after_attempt(max(max_retries, 0) + 1), donc max_retries compte les nouvelles tentatives après la première. Régler max_retries=3 signifie au pire quatre appels à une interface payante, pas trois.

Fais attention à deux valeurs par défaut différentes. La méthode Instructor.create et client.chat.completions.create portent max_retries=3 dans leur signature. La fonction enveloppée directement par instructor.patch a max_retries: int | Retrying = 1 dans le code. Même nom de paramètre, nombre d'appels différent sur la facture, selon le point d'entrée par lequel tu es passé.

Python
from pydantic import BaseModel, field_validator
from instructor.core.exceptions import InstructorRetryException

class Ticket(BaseModel):
    title: str
    priority: str

    @field_validator("priority")
    @classmethod
    def known_priority(cls, value: str) -> str:
        allowed = {"low", "medium", "high"}
        if value not in allowed:
            raise ValueError(f"priority must be one of {sorted(allowed)}")
        return value

try:
    ticket = client.chat.completions.create(
        response_model=Ticket,
        messages=[{"role": "user", "content": report}],
        max_retries=2,
        context={"tenant": "acme"},
        strict=True,
    )
except InstructorRetryException as err:
    print(err.n_attempts, err.total_usage)
    print(err.last_completion)
    print(err.create_kwargs)

L'InstructorRetryException porte un ensemble complet d'informations de diagnostic : last_completion avec la dernière réponse échouée, n_attempts avec le nombre de tentatives, total_usage avec la consommation cumulée de tokens, create_kwargs avec les paramètres de l'appel et failed_attempts avec le détail de chaque essai échoué. Le champ messages existe encore mais le code le marque comme déprécié au profit de create_kwargs.

Les hooks servent à observer l'exécution. Les méthodes client.on, client.off et client.clear prennent l'un de cinq noms d'événements : completion:kwargs, completion:response, completion:error, completion:last_attempt et parse:error. Attacher un compteur à parse:error est le moyen le plus simple de mesurer ce que les retries te coûtent réellement avant que la facture du fournisseur ne le fasse pour toi. Si tu as besoin d'un tableau de bord complet avec un journal des appels, ce flux d'événements s'oriente facilement vers un outil d'observabilité ou vers une passerelle comme LiteLLM ou OpenRouter.

La bibliothèque fournit aussi un validateur adossé à un modèle. La fonction llm_validator prend statement, client, allow_override=False, model="gpt-3.5-turbo" et temperature=0. La valeur par défaut du champ model est clairement obsolète, donc passe-la explicitement plutôt que de te fier à la valeur par défaut.

Streaming et modèles auxiliaires

Le client expose quatre façons de produire une réponse. create simple renvoie un objet terminé. create_with_completion renvoie un tuple avec l'objet et la réponse brute du fournisseur, ce qui aide à lire la consommation de tokens. create_iterable renvoie un générateur d'objets quand tu demandes une liste et que tu veux traiter les éléments à mesure qu'ils arrivent. create_partial renvoie un générateur de versions successives, de plus en plus complètes, du même objet.

Python
from instructor import Partial

# successive approximations of one object
for draft in client.chat.completions.create_partial(
    response_model=Invoice,
    messages=[{"role": "user", "content": raw_text}],
    max_retries=1,
):
    render(draft)

# list elements as they are produced
for row in client.chat.completions.create_iterable(
    response_model=Invoice,
    messages=[{"role": "user", "content": batch_text}],
):
    save(row)

# object together with the raw provider response
invoice, completion = client.chat.completions.create_with_completion(
    response_model=Invoice,
    messages=[{"role": "user", "content": raw_text}],
)
print(completion.usage.total_tokens)

Les objets partiels ont une limite facile à oublier : tant que le flux n'est pas terminé, la validation est incomplète, car les champs n'existent tout simplement pas encore. Le streaming convient pour montrer la progression dans une interface, pas pour prendre des décisions sur des données inachevées.

Par ailleurs, le module instructor.dsl contient quelques patterns prêts à l'emploi. Partial[Model] décrit le type partiel. Maybe(Model) crée un modèle avec les champs result, error et message, où error vaut False par défaut et où __bool__ vérifie que result n'est pas None. C'est ainsi que tu obtiens un modèle capable de dire honnêtement que le texte ne contenait rien à extraire, au lieu d'inventer quelque chose. IterableModel, CitationMixin, ListResponse et ResponseList complètent l'ensemble.

Instructor face aux alternatives

CaractéristiqueInstructorPydantic AIDSPyGuardrails AISorties structurées natives
Périmètreschéma de réponse uniquementframework d'agents completoptimisation de promptsvalidation et réparationfonctionnalité du fournisseur
SchémaPydanticPydanticsignaturesvalidateurs personnalisésJSON Schema
Nouvelle tentative en cas d'échecintégréeintégréedépend du moduleintégréeaucune
Changement de fournisseur23 aliasnombreux fournisseursnombreux fournisseursnombreux fournisseursaucun, te lie à un seul
Version1.15.4 pour Python, 1.7.0 pour TypeScriptvoir l'article séparévoir l'article séparévoir l'article séparésans objet
LicenceMITMITMITApache 2.0sans objet

Le choix se ramène à une question : as-tu besoin de quelque chose en plus d'un objet validé ? Si non, Instructor est la plus petite chose que tu puisses utiliser pour ce travail, et son code se lit en une soirée. Si tu construis un agent avec des outils, un historique et des points de reprise, la couche fine cessera vite de suffire. Si tout ce que tu veux est une forme imposée et que tu travailles avec un seul fournisseur, les sorties structurées natives de ce fournisseur règlent la question sans dépendance supplémentaire, au prix d'être lié à une interface. Pour valider le contenu plutôt que la forme, tourne-toi vers Guardrails AI.

Outlines se tient à part, car il résout le même problème par l'autre bout. Instructor demande un résultat au modèle et réessaie quand la validation échoue, donc il fonctionne avec tous les fournisseurs, mais tu paies chaque tentative échouée. Outlines masque des tokens pendant la génération, donc le modèle ne peut rien produire qui viole le schéma et les retries disparaissent. Le prix est dur : l'application de la contrainte ne fonctionne que pour les trois moteurs qui détiennent les poids dans ton processus, et avec OpenAI ou Anthropic la bibliothèque transmet le schéma au fournisseur et n'offre aucune garantie au-delà de celle que le fournisseur donne lui-même.

Erreurs courantes

La première est npm install instructor au lieu de npm install @instructor-ai/instructor. L'installation réussit sans erreur et tu obtiens la coquille dépréciée de npm sans aucun code dedans. Vérifie le nom dans package.json avant de chercher la cause dans ton propre code.

La deuxième est de traiter le portage TypeScript comme un équivalent. Le paquet @instructor-ai/instructor 1.7.0 fige zod-stream à la version exacte 3.0.0, et cette version déclare des dépendances peer de zod dans la plage ^3.23.3 et d'openai exactement en 4.47.1. Pendant ce temps, npm propose aujourd'hui zod en 4.4.3 et openai en 7.5.0. Instructor lui-même déclare openai en >=4.58.0, ce qui contredit sa propre dépendance interne figée. En pratique, cela signifie que le portage TypeScript te bloque sur la version 3 de Zod et sur une génération du client OpenAI vieille de deux ans.

La troisième est de mal lire max_retries. Une valeur de 3 signifie trois nouvelles tentatives après le premier appel, donc quatre requêtes au fournisseur. Avec un modèle de raisonnement et un gros schéma, cela peut tripler la facture pour une seule requête utilisateur, surtout en mode MD_JSON où la part de validations échouées est la plus élevée.

La quatrième est d'écrire des validateurs qui ne disent rien d'utile au modèle. Le texte de l'exception Pydantic part tel quel dans la requête suivante, donc un message qui dit invalid value gaspille une tentative. Écris dans l'exception quelle valeur est attendue et la deuxième tentative suffit généralement.

La cinquième est d'oublier qu'openai est une dépendance obligatoire. Même installer instructor[anthropic] tire le client OpenAI, car le paquet de base l'exige. Dans un audit de dépendances ou une image de conteneur au régime, c'est une entrée visible. L'extra Anthropic fige en plus anthropic à la version exacte 0.93.0, plutôt qu'une plage, ce qui peut entrer en collision avec une autre bibliothèque du même environnement.

La sixième est strict=True dans un mode qui ne sait rien du comportement strict. Le paramètre existe dans la signature de create quel que soit le mode choisi, mais sa signification dépend du fournisseur, et avec MD_JSON il n'y a rien de l'autre côté pour l'appliquer.

La septième est de s'appuyer sur la valeur par défaut de model dans llm_validator. Le gpt-3.5-turbo qui y est écrit est une relique et renverra soit un résultat faible, soit cessera complètement d'être disponible chez le fournisseur.

FAQ

Quel paquet installer dans un projet Python ?

pip install instructor depuis PyPI, version 1.15.4. C'est le projet, sous licence MIT, avec le dépôt 567-labs/instructor. L'adresse instructor-ai/instructor redirige au même endroit, donc les deux liens de la documentation sont corrects.

La version TypeScript est-elle maintenue ?

En pratique non. La dernière publication de @instructor-ai/instructor était la 1.7.0 le 27 janvier 2025, la branche principale du dépôt porte le même numéro de version et il n'y a pas de tag de version plus récent. Le code fonctionne, mais il ne suit pas les changements de zod et du client OpenAI.

Combien de requêtes supplémentaires les retries coûtent-ils ?

Autant que tu en règles dans max_retries, comptées après la première tentative. La valeur par défaut 3 dans client.chat.completions.create signifie au plus quatre appels. Tu peux mesurer le coût réel en attachant un compteur à l'événement parse:error.

Quand choisir le mode JSON plutôt que l'appel d'outils ?

Quand le modèle ou le fournisseur n'a pas d'appels d'outils, ou quand tu as besoin de Mode.JSON_SCHEMA avec contrainte côté fournisseur. Dans tous les autres cas, Mode.TOOLS produit moins de validations échouées, car le schéma est imposé plutôt que suggéré.

Instructor remplace-t-il un framework d'agents ?

Non. Il n'y a ni boucle d'agent, ni registre d'outils, ni gestion de l'état de la conversation. Il renvoie un objet validé et son rôle s'arrête là, le reste étant assemblé par toi ou pris tout fait dans une autre couche.

Puis-je utiliser Instructor avec un modèle hébergé en local ?

Oui, via l'alias ollama dans from_provider ou via un client compatible OpenAI avec un base_url modifié. Le mode est alors la limite : les petits modèles locaux ont souvent du mal avec les appels d'outils, ce qui laisse Mode.JSON ou Mode.MD_JSON et une part de retries plus élevée.

La documentation de la version Python se trouve sur python.useinstructor.com, le code source dans le dépôt 567-labs/instructor, et le paquet dans le registre PyPI.

À lire aussi