Problèmes résolus par chaque outil
📍 In One Sentence
Les outils de sortie structurée résolvent trois problèmes distincts — imposer un schéma dès la génération, valider ensuite le résultat, et réparer une sortie malformée — et la plupart des stacks n'ont besoin que des deux premiers.
💬 In Plain Terms
Ne choisissez pas sur une liste de fonctionnalités. Demandez quelle panne vous rencontrez vraiment : le modèle ignore votre format, ou il le respecte mais les valeurs sont fausses, ou il renvoie un JSON qui ne se parse même pas. Chaque cas appelle une réponse différente.
Le Structured Output nécessite de résoudre trois problèmes interdépendants : définition de schéma, application via l'API et validation. Différents outils abordent ces problèmes différemment. Instructor gère les trois en Python avec des retries. Outlines élimine l'étape de validation via le décodage contraint. Pydantic AI ajoute la sécurité de type pour les agents. BAML déplace le schéma dans un fichier compilé et répare les sorties imparfaites. LangChain enveloppe les APIs des fournisseurs. Marvin priorise la rapidité du développeur. PromptQuorum valide la cohérence sur tous les modèles.
Problème | Instructor | Outlines | Pydantic AI | BAML | LangChain | Marvin |
|---|---|---|---|---|---|---|
| Définir le schéma | Modèles Pydantic | JSON Schema / GBNF | Modèles Pydantic | Fichiers de classe .baml | Définitions d'outils | Indices de type Python |
| Appliquer sur l'appel API | Retry + validation | Contrainte au niveau token | Natif / outil / prompt | Prompt généré + parseur | Mode JSON du fournisseur | Types de sortie Pydantic AI |
| Valider la réponse | Automatique | Garanti à la génération | Vérifié par type | Schema-aligned parsing | Manuel | Automatique |
Instructor : extraction Pydantic
Instructor est la bibliothèque de Structured Output la plus répandue. Elle enveloppe toute API LLM — OpenAI GPT-5.6, Claude Opus 5, Gemini 3.1 Pro, Ollama, vLLM — et retourne des modèles Pydantic validés plutôt que du texte brut. Instructor gère les retries automatiquement en cas d'échec de validation, ce qui le rend prêt pour la production sans gestion d'erreurs supplémentaire.
- Fonctionne avec tous les grands fournisseurs (OpenAI, Anthropic, Google, Groq, Mistral) et les modèles locaux via Ollama ou vLLM
- Schémas Pydantic v2 : indices de type, règles de validation, descriptions docstring intégrées au schéma
- Retry automatique avec backoff en cas d'échec de validation — aucune gestion d'erreur manuelle requise
- Six implémentations officielles : Python, TypeScript, Ruby, Go, Elixir et Rust
- Open source sous licence MIT, activement maintenu, actuellement en 1.x
- Tarification : gratuit (aucun coût supplémentaire au-delà des appels API LLM)
import instructor
from pydantic import BaseModel
from openai import OpenAI
class User(BaseModel):
name: str
age: int
client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
model="gpt-5.6",
response_model=User,
messages=[{"role": "user", "content": "Extract: John is 25 years old"}]
)
# user.name == "John", user.age == 25Outlines : décodage contraint
Outlines applique la conformité du schéma au moment de la génération de tokens via le décodage contraint. Au lieu de générer des tokens puis de valider, Outlines limite les tokens valides à chaque étape pour correspondre à votre schéma. Cela garantit que la sortie se parse contre votre schéma, sans risque d'hallucination structurelle — c'est précisément ce qui en fait le choix par défaut pour les modèles locaux.
- Backends locaux : transformers, llama.cpp, MLX et tout modèle Hugging Face
- Backends serveur : vLLM, Ollama et NVIDIA NIM
- Les APIs hébergées sont aussi supportées (OpenAI, Gemini) : le même code passe du local au cloud
- Schémas sous forme de modèles Pydantic, JSON Schema, motifs regex, choix littéraux ou grammaires hors contexte
- Conformité structurelle garantie — aucune validation post-génération ni retry nécessaire
- Open source Apache 2.0, actuellement en 1.x, avec un cœur en Rust (outlines-core) pour la performance
Pydantic AI : agents type-safe
Pydantic AI est le framework d'agents de l'équipe derrière Pydantic elle-même. Il combine les modèles Pydantic avec un support de premier ordre pour les conversations d'agents multi-tours, ajoutant une sécurité de type complète aux boucles d'agents tout en appliquant le Structured Output à chaque tour. Il en est à la série 2.x et tourne en production, ce n'est plus une expérimentation.
- Système de type Pydantic v2 — support IDE complet et vérification statique de ce que renvoie un agent
- Trois modes de sortie : Structured Output natif du fournisseur, appels d'outils, et JSON par prompt en repli
- Design async-first pour les applications à haut débit
- Supporte OpenAI, Anthropic, Google, Bedrock, Azure AI Foundry, Groq, Mistral, xAI et Ollama
- Intégrations d'exécution durable (Temporal, DBOS, Prefect) pour que les agents longue durée survivent aux redémarrages
- Appels d'outils intégrés — définir les outils comme des fonctions Python avec indices de type
- Sous licence MIT et gratuit (aucun coût supplémentaire au-delà des appels API LLM)
BAML : fichiers de prompt schema-first
BAML prend le contre-pied des bibliothèques Python : le schéma et le prompt vivent dans un fichier .baml versionné, et un compilateur génère un client typé pour votre langage. Son parseur aligné sur le schéma répare les erreurs que les modèles commettent réellement — blocs markdown autour du JSON, virgules finales, clés sans guillemets, texte de raisonnement avant l'objet — au lieu de lever une erreur et de brûler un retry.
- Schéma et prompt cohabitent dans des fichiers .baml, versionnés et relus comme n'importe quel autre code source
- Génère des clients typés nativement pour Python et TypeScript, plus Go, Java, Ruby, PHP, Rust et C# via des clients OpenAPI générés
- Le schema-aligned parsing (SAP) récupère des objets valides à partir de sorties imparfaites au lieu d'échouer
- Fonctionne avec des modèles dépourvus de tout tool-use ou mode JSON natif
- Streaming typé — les objets partiels arrivent typés, vous affichez les champs au fil de la génération
- Open source Apache 2.0 ; le produit hébergé d'observabilité Boundary Studio est une offre payante distincte
LangChain : APIs unifiées
LangChain expose with_structured_output() sur tous les modèles de chat majeurs, unifiant le Structured Output sur OpenAI, Anthropic, Google et les modèles locaux derrière une seule méthode. Depuis la réécriture 1.x, il lit la capacité native de Structured Output de chaque fournisseur dans son profil de modèle au lieu de la coder en dur, et les agents créés avec create_agent acceptent directement un response_format.
- API unifiée : une méthode .with_structured_output() fonctionne sur tous les fournisseurs
- Convertit automatiquement les définitions d'outils LangChain en formats de schéma spécifiques au fournisseur
- Les agents créés avec create_agent acceptent un response_format pour leur réponse finale
- Le support natif du Structured Output est lu par modèle dans les données de profil du fournisseur à partir de la série 1.1
- Supporte les modèles Pydantic, TypedDict, dataclasses et JSON Schema brut
- Idéal pour les équipes déjà investies dans LangChain ou LangGraph
Marvin : extraction par tâches
Marvin 3.x est le chemin le plus court d'un texte non structuré vers un objet Python typé. Il est bâti sur Pydantic AI : vous obtenez la même couverture de fournisseurs et la même validation avec bien moins de code. Attention : l'API à décorateurs de Marvin 2 a disparu — @marvin.fn a été supprimé en 3.0 au profit de fonctions de haut niveau et d'un moteur d'agents orienté tâches.
- Fonctions en une ligne : marvin.extract, marvin.cast, marvin.classify et marvin.generate
- Bâti sur Pydantic AI : le support des fournisseurs et la validation des sorties sont hérités, pas réimplémentés
- Moteur orienté tâches pour le travail en plusieurs étapes : marvin.run, marvin.Task, marvin.Agent, marvin.Thread
- Les indices de type Python deviennent le schéma — boilerplate minimal pour l'extraction et la classification
- Note de migration : le décorateur @marvin.fn de Marvin 2 n'existe plus ; ces appels doivent être réécrits
- Open source Apache 2.0, maintenu par Prefect, gratuit
PromptQuorum : tests multi-modèles
PromptQuorum n'est pas une bibliothèque de Structured Output en soi, mais une plateforme de test pour valider la cohérence du Structured Output entre les modèles. Exécutez le même prompt simultanément contre GPT-5.6, Claude Opus 5, Gemini 3.1 Pro et 20+ autres modèles. Mesurez la conformité du schéma, la latence et le coût par modèle.
- Dispatch multi-modèles en un seul appel API — tester un prompt contre 25+ modèles
- Métriques de conformité Structured Output — taux de réussite, latence, coût par modèle
- Identifier les modèles qui hallucinent sur votre schéma — éviter le déploiement sur des modèles peu fiables
- Mode consensus — trouver les accords entre des exécutions de modèles indépendantes
- Fonctionne avec Instructor, Outlines, Pydantic AI, BAML, LangChain ou les APIs LLM brutes
- Niveau gratuit disponible, tarification entreprise pour les tests à grand volume
Comparaison côte à côte
Outil | Meilleur usage | Format de schéma | Langage | Modèles locaux | Licence |
|---|---|---|---|---|---|
| Instructor | APIs Python + retries | Modèles Pydantic | Python, TS, Ruby, Go, Elixir, Rust | Oui (Ollama, vLLM) | MIT, gratuit |
| Outlines | Déploiement local | Pydantic, JSON Schema, regex, CFG | Python | Oui (natif) | Apache 2.0, gratuit |
| Pydantic AI | Agents type-safe | Modèles Pydantic | Python | Oui (Ollama) | MIT, gratuit |
| BAML | Équipes polyglottes, modèles instables | Fichiers de classe .baml | Python, TS + 6 via OpenAPI | Oui (compatible OpenAI) | Apache 2.0, observabilité payante |
| LangChain | Chaînes + agents | Définitions d'outils | Python, JS | Oui | MIT, gratuit |
| Marvin | Extract et classify rapides | Indices de type | Python | Oui | Apache 2.0, gratuit |
| PromptQuorum | Tests multi-modèles | Agnostique API | API-first | Via proxy OpenAI | Niveau gratuit + entreprise |
Choisir le bon outil
Commencez par répondre à trois questions : (1) Dans quels langages sont écrits les services qui appellent réellement le modèle ? (2) Avez-vous besoin d'un support de modèles locaux ? (3) Quelle est votre complexité de validation ?
- Utilisez Instructor si : vous construisez des APIs Python et avez besoin de retries automatiques en cas d'échec de validation. Meilleur choix polyvalent.
- Utilisez Outlines si : vous déployez des modèles locaux (llama.cpp, vLLM, MLX) et voulez une conformité de schéma garantie au moment de la génération.
- Utilisez Pydantic AI si : vous construisez des workflows d'agents multi-tours avec sécurité de type sur toutes les étapes, ou avez besoin d'exécution durable.
- Utilisez BAML si : des services Python, TypeScript et Go doivent partager un schéma, ou si votre modèle n'a pas de mode JSON natif fiable.
- Utilisez LangChain si : vous utilisez déjà LangChain ou LangGraph — with_structured_output() est l'ajout le plus simple.
- Utilisez Marvin si : vous voulez un seul appel extract ou classify et n'avez pas besoin de logique de validation propre.
- Utilisez PromptQuorum si : vous devez tester la cohérence du Structured Output sur GPT, Claude et Gemini avant la production.
Ajouter le Structured Output étape par étape
- 1Définir le schéma de sortie — Créez un modèle Pydantic (Python), une classe .baml (BAML), une interface TypeScript ou un JSON Schema décrivant les champs, types et contraintes que le LLM doit retourner.
- 2Choisir une bibliothèque — Instructor pour les APIs Python, Outlines pour les modèles locaux, Pydantic AI pour les agents, BAML pour les équipes polyglottes, LangChain si déjà utilisé, Marvin pour une extraction en une ligne.
- 3Installer et envelopper l'appel LLM — `pip install instructor` (Python), puis passer votre schéma à l'appel API. Instructor gère la validation et les retries.
- 4Tester avec PromptQuorum — Déployer sur PromptQuorum et exécuter votre prompt contre GPT, Claude et Gemini. Mesurer la conformité du schéma par modèle.
- 5Affiner le schéma selon les échecs — Si un modèle échoue la validation, ajouter des exemples à votre prompt ou ajuster les contraintes du schéma. Itérer jusqu'à ce que tous les modèles réussissent.
Erreurs courantes en Structured Output
❌ Traiter tout mode JSON comme une garantie de schéma
Why it hurts: Le mode JSON simple (response_format json_object, contrôle JSON Anthropic) garantit seulement que la réponse est du JSON valide, pas qu'elle respecte vos champs et vos types. Les modes de schéma strict vont plus loin et garantissent la forme, mais aucun ne garantit que les valeurs sont justes : un objet bien formé peut toujours contenir un prix inventé ou une date hallucinée.
Fix: Superposez une validation dans tous les cas : Instructor, Outlines, Pydantic AI ou BAML. Les règles métier appartiennent aux validateurs Pydantic, pas au seul schéma. Tester avec PromptQuorum pour détecter les échecs de conformité par modèle.
❌ Concevoir des schémas trop stricts
Why it hurts: Les schémas trop contraints (petites listes d'énumération, motifs regex très spécifiques) font échouer fréquemment la validation des LLM. Un nombre élevé de retries gaspille des tokens et de l'argent.
Fix: Utiliser PromptQuorum pour tester la rigueur du schéma sur les modèles. Assouplir les contraintes pour atteindre 95%+ de conformité. Utiliser des champs optionnels plutôt qu'obligatoires quand c'est possible.
❌ Ne pas tester les différences entre modèles locaux et API
Why it hurts: Outlines sur llama.cpp se comporte différemment qu'Instructor sur GPT-5.6. Les taux de conformité varient selon le modèle. Construire seulement pour un modèle d'API de pointe puis déployer sur un petit modèle local cause des échecs en production.
Fix: Tester tous les backends de modèles prévus tôt. Utiliser PromptQuorum pour exécuter le même prompt sur des modèles locaux (vLLM, Ollama) et hébergés (OpenAI, Anthropic, Google).
❌ Ignorer l'impact sur la latence et le coût en tokens
Why it hurts: Le Structured Output avec retries coûte plus de tokens. Instructor relance en cas d'échec. Le décodage contraint d'Outlines ajoute un surcoût par token par rapport à la génération libre. Ne pas mesurer le coût par modèle.
Fix: Utiliser le suivi des coûts PromptQuorum. Comparer la latence entre les modèles. Pour les workflows sensibles au budget, préférer Outlines ou BAML (pas de boucle de retry). Pour la précision sur des schémas souples, accepter le coût de retry d'Instructor.
❌ Mélanger les méthodes de validation (aucune cohérence)
Why it hurts: Certaines requêtes utilisent Instructor, d'autres l'analyse JSON brute. Certains modèles validés, d'autres non. Cela conduit à des erreurs incohérentes en production.
Fix: Standardiser sur une approche de validation par base de code. Toutes les requêtes utilisent Instructor, ou toutes utilisent Outlines. La cohérence réduit le temps de débogage par 10.
❌ Copier des tutoriels écrits pour une API remplacée depuis
Why it hurts: Les bibliothèques de Structured Output évoluent vite. Marvin a supprimé le décorateur @marvin.fn en 3.0, LangChain a réorganisé sa documentation lors de la réécriture 1.x, et Outlines a changé sa surface d'imports en 1.0. Le code copié d'un ancien tutoriel échoue dès l'installation.
Fix: Épinglez la version majeure sur laquelle vous développez et vérifiez la documentation actuelle pour la surface de l'API. Préférez le README officiel du dépôt aux billets de blog, et revérifiez à chaque montée de version majeure.
Structured Output et conformité RGPD en France
En France et dans l'espace francophone européen, l'utilisation de LLM avec Structured Output est encadrée par le RGPD et les recommandations de la CNIL.
- Recommandation CNIL : Pour le traitement de données sensibles (données médicales, financières, juridiques), la CNIL recommande les solutions d'inférence locale. Outlines sur des modèles locaux évite tout transfert de données personnelles vers des serveurs tiers.
- RGPD Art. 28 (sous-traitance) : L'utilisation d'APIs LLM tierces pour traiter des données personnelles nécessite un contrat de traitement des données (DPA). Les modèles locaux via Outlines ou llama.cpp contournent cette obligation.
- Minimisation des données (RGPD Art. 5) : Le Structured Output permet une extraction précise — seuls les champs du schéma défini sont traités. Ce principe soutient la minimisation des données exigée par le RGPD.
- BAML et l'inférence locale : BAML fonctionne contre tout endpoint compatible OpenAI ; le même contrat .baml peut donc viser un déploiement vLLM interne, utile quand des services Python et TypeScript partagent un schéma mais que les données ne doivent pas sortir de l'entreprise.
- Secteurs réglementés : Banques, assurances, santé — ces secteurs sont soumis à des réglementations supplémentaires. L'inférence locale avec Outlines est recommandée pour ces cas d'usage.
Qu'est-ce que Structured Output dans les LLMs ?
Structured Output contraint les réponses des LLM à un schéma spécifique — format JSON, champs définis, contraintes de type. Au lieu de texte libre, il retourne des données que votre code peut analyser et valider directement sans gestion d'erreurs.
Quel outil est le meilleur pour les développeurs Python ?
Instructor est le choix Python le plus populaire. Il utilise des modèles Pydantic pour définir les schémas, gère automatiquement les retries et la validation, et supporte toutes les grandes APIs LLM ainsi que les modèles locaux via Ollama ou vLLM. Pydantic AI convient mieux si vous voulez aussi des conversations d'agents multi-tours type-safe, et Marvin est le plus rapide si un simple appel extract ou classify suffit.
Puis-je utiliser Structured Output avec des modèles locaux comme Llama ?
Oui. Outlines se spécialise dans le décodage contraint des modèles locaux — il fonctionne avec transformers, llama.cpp, MLX, vLLM et Ollama, et garantit au moment de la génération que la sortie se parse contre votre schéma. Instructor et Pydantic AI supportent aussi Ollama et vLLM si vous les exécutez comme API, et BAML fonctionne contre tout endpoint compatible OpenAI.
Quelle est la différence entre Instructor et Marvin ?
Instructor enveloppe votre propre client LLM et retourne des modèles Pydantic validés avec retries automatiques : vous gardez la main sur l'appel. Marvin 3.x est bâti sur Pydantic AI et propose plutôt des fonctions en une ligne : marvin.extract, marvin.cast, marvin.classify. Instructor est plus explicite et meilleur pour les validations complexes ; Marvin est plus concis pour une extraction simple. À noter : le décorateur @marvin.fn de Marvin 2 a été supprimé dans Marvin 3.
LangChain supporte-t-il Structured Output ?
Oui. LangChain expose with_structured_output() sur ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI et les autres classes de modèles de chat, et les agents construits avec create_agent acceptent un response_format. Depuis la série 1.x, le support natif du Structured Output de chaque fournisseur est lu dans les données de profil du modèle au lieu d'être codé en dur. Utilisez ceci si vous utilisez déjà LangChain ou LangGraph et souhaitez ajouter l'application de schéma sans changer de bibliothèque.
Comment tester si Structured Output est fiable ?
Utilisez PromptQuorum pour exécuter le même prompt sur plusieurs modèles et mesurer la conformité du schéma. Les modèles diffèrent — GPT-5.6, Claude Opus 5, Gemini 3.1 Pro — et les petits modèles locaux davantage encore. Testez avant de déployer en production et validez localement avec Instructor ou Pydantic.
Qu'entend-on par "décodage contraint" ?
Le décodage contraint limite la génération de tokens aux seules valeurs valides selon votre schéma. Outlines le fait en calculant l'ensemble des tokens suivants valides à chaque étape. Cela garantit que la sortie se parse contre votre schéma sans validation post-génération ni retries, ce qui est plus fiable que le mode JSON simple de l'API. Il contraint la structure, pas la vérité : les champs seront corrects, les valeurs restent à vérifier.
Qu'est-ce que BAML et quand l'utiliser plutôt qu'Instructor ?
BAML est un langage schema-first : vous écrivez le schéma et le prompt dans un fichier .baml et compilez un client typé pour votre langage. Choisissez-le plutôt qu'Instructor quand plusieurs langages appellent le même prompt — un worker Python et un frontend TypeScript partageant un contrat — ou quand votre modèle renvoie du JSON presque valide, car le parseur aligné sur le schéma de BAML répare les blocs markdown, les virgules finales et le texte de raisonnement initial au lieu de brûler un retry. Restez sur Instructor si votre stack est purement Python et que vous voulez garder les schémas en simple code Pydantic.
Puis-je utiliser Structured Output sans bibliothèques ?
Techniquement oui — vous pouvez demander au modèle de retourner du JSON et l'analyser vous-même. Mais l'analyse échouera sur les sorties malformées que les modèles produisent encore, et rien n'impose vos noms de champs ni vos types. Les sept outils résolvent ceci par validation avec retries (Instructor, Marvin), application au décodage (Outlines), réparation à l'analyse (BAML) ou enveloppe des APIs fournisseurs (LangChain, Pydantic AI).
Quel outil a la meilleure documentation ?
LangChain et Pydantic AI ont la documentation la plus complète grâce à leurs ressources d'entreprise. Celle de BAML est étonnamment bonne pour un projet jeune, parce que le langage doit être enseigné. Instructor a d'excellents tutoriels malgré la maintenance communautaire. La documentation Outlines est technique mais approfondie. Celle de Marvin est concise — consultez spécifiquement les pages 3.x, car d'anciens contenus Marvin 2 circulent encore.
Ai-je besoin des sept outils ou juste d'un ?
Commencez par un. Les développeurs Python devraient essayer Instructor ou Pydantic AI. Les équipes avec modèles locaux devraient essayer Outlines. Les équipes polyglottes devraient essayer BAML. Les utilisateurs de LangChain devraient essayer with_structured_output(). Utilisez PromptQuorum pour valider la cohérence sur tous les modèles.
Sources
- Dépôt GitHub Instructor — Dépôt officiel et documentation de la bibliothèque Instructor
- Dépôt GitHub Outlines — Décodage contraint pour la conformité de schéma garantie
- Documentation Pydantic AI — Framework d'agents type-safe avec Structured Output
- Guide Structured Output LangChain — API Structured Output unifiée LangChain
- Documentation BAML — Langage de prompts schema-first et schema-aligned parsing
- Dépôt GitHub Marvin — Bibliothèque d'extraction orientée tâches bâtie sur Pydantic AI