Guide

Outlines : une structure imposée à la sortie des modèles

Outlines impose la structure de la sortie d'un LLM par masquage de tokens : JSON, regex, grammaires. Modèles locaux ou boîte noire, Apache 2.0, face à Instructor.

L'équipe CodeWorlds19 min de lecture ·

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

Crée un compte gratuit→
Dans cet article8

Outlines ne demande pas à un modèle un JSON valide, il lui retire la possibilité de produire autre chose. À chaque étape de décodage, il masque les tokens qui briseraient le schéma, de sorte que la sortie est correcte par construction et non parce qu'on a réussi à convaincre le modèle. La version 1.3.3 est sortie le 6 août 2026 sous licence Apache 2.0.

En quoi imposer diffère de demander

L'approche habituelle des réponses structurées ressemble à ceci : vous envoyez un prompt qui décrit le schéma, vous recevez du texte, vous essayez de l'analyser et, en cas d'échec, vous redemandez. C'est la boucle demander puis vérifier. À tout moment, le modèle peut émettre une phrase d'introduction, un triple accent grave avec une étiquette de langage ou une virgule finale dans un tableau, et vous ne l'apprenez qu'après coup.

Outlines descend d'un niveau. Il transforme le schéma en expression régulière, l'expression régulière en automate fini et l'automate en un objet appelé processeur de logits. Cet objet reçoit le vecteur de probabilités sur tout le vocabulaire avant chaque étape de décodage et met à zéro les positions que l'état courant de l'automate interdit. Si l'automate se trouve juste après la clé "total" et ses deux-points, alors chaque token autre qu'un chiffre, un signe moins ou une espace a une probabilité nulle. Le modèle n'a physiquement rien d'autre à choisir.

Il y a deux conséquences et il faut les comprendre avant de s'engager. La première est bonne : il n'existe aucun chemin où la sortie ne s'analyse pas selon le schéma, donc toute une classe d'erreurs et tout le code de gestion des nouvelles tentatives disparaissent. La seconde est moins agréable : la garantie est purement syntaxique. Un modèle forcé de remplir le champ currency y mettra trois lettres, mais personne ne promet que ce sont les lettres de la bonne devise. Une structure imposée ne transforme pas une hallucination en vérité, elle lui donne seulement une forme régulière.

La construction de l'automate revient à l'un des trois backends. Le backend par défaut pour les schémas JSON et les expressions régulières est outlines_core, le paquet Rust compagnon, épinglé exactement à la version 0.2.14. Pour les grammaires hors contexte, la valeur par défaut est llguidance. La troisième option est xgrammar. Vous choisissez un backend avec l'argument backend du constructeur Generator, et les constantes JSON_SCHEMA_DEFAULT_BACKEND, REGEX_DEFAULT_BACKEND et CFG_DEFAULT_BACKEND du module outlines.backends indiquent clairement ce qui est choisi quand vous ne passez rien.

Compiler l'automate coûte du temps. La docstring de la classe SteerableGenerator le dit directement : le processeur peut être assez coûteux à construire, c'est pourquoi le générateur le stocke. La conclusion pratique est que vous créez un Generator une fois par schéma et que vous le conservez, plutôt que d'en construire un dans une boucle de requêtes. Il existe aussi un cache sur disque, par défaut dans HOMEDIR/.cache/outlines, contrôlé par la variable OUTLINES_CACHE_DIR et, en second lieu, par XDG_CACHE_HOME. Les fonctions outlines.clear_cache, outlines.disable_cache et outlines.get_cache sont exposées au niveau supérieur du paquet.

Modèles pilotables et modèles boîte noire

C'est le cœur de la bibliothèque et le malentendu le plus fréquent. Le masquage de tokens exige l'accès à la distribution de probabilités, donc aux poids du modèle ou à un moteur qui expose cet accès. Outlines répartit donc ses intégrations en deux groupes, et il le fait dans le code et non dans la documentation.

Dans outlines/models/__init__.py, le type SteerableModel est l'union d'exactement trois classes : LlamaCpp, MLXLM et Transformers. Ce n'est que pour celles-ci qu'Outlines construit lui-même le processeur de logits et impose lui-même le schéma. Le type BlackBoxModel couvre Anthropic, Dottxt, Gemini, LMStudio, Ollama, OpenAI, Mistral, SGLang, TGI, VLLM et VLLMOffline, et AsyncBlackBoxModel ajoute des variantes asynchrones de huit d'entre eux. Pour ce second groupe, le type de sortie n'est pas compilé localement, il est transmis au fournisseur sous la forme que celui-ci comprend.

La fabrique Generator vérifie cela avec isinstance et renvoie une classe différente : SteerableGenerator ou BlackBoxGenerator. Si vous essayez de passer votre propre processeur via l'argument processor à un modèle du second groupe, vous obtenez une NotImplementedError qui dit que ce modèle ne prend pas en charge les processeurs de logits. C'est une façon honnête d'exposer la situation, mais il faut la remarquer avant de déployer.

Ce qui se passe avec les fournisseurs fermés est le plus clair dans la méthode format_output_type de l'adaptateur OpenAI. Un modèle Pydantic devient un response_format de type json_schema avec strict: true et un additionalProperties: false imposé. Un simple dict donne le mode json_object. Un type Regex, en revanche, se termine par une TypeError expliquant que ni les sorties fondées sur des expressions régulières ni le mot-clé pattern d'un schéma JSON ne sont disponibles avec OpenAI, et un type CFG se termine par une exception sur l'absence de prise en charge des grammaires. Ollama se comporte de la même façon et rejette aussi Regex et CFG. Le modèle Dottxt, l'API commerciale de l'entreprise derrière la bibliothèque, rejette les deux avec un message disant qu'ils seront bientôt disponibles.

La conclusion est simple. Si votre fournisseur est OpenAI ou Anthropic, Outlines ne vous donne aucune garantie au-delà de celle que le fournisseur donne déjà. C'est alors une couche qui unifie l'interface, pas un mécanisme qui impose quoi que ce soit. La garantie issue du masquage de tokens n'apparaît qu'avec from_transformers, from_llamacpp et from_mlxlm, c'est-à-dire quand les poids se trouvent dans votre processus.

Un piège distinct concerne vLLM. L'adaptateur de serveur envoie les contraintes dans le champ structured_outputs à l'intérieur de extra_body. Un commentaire dans le code dit que ce champ exige un serveur vLLM de version 0.12 au moins, qui a remplacé les anciennes clés guided_json, guided_regex et guided_grammar, et que les serveurs plus anciens ignorent simplement le nouveau champ et renvoient une sortie sans contrainte. Une dégradation silencieuse vers l'absence de garantie est pire qu'une erreur, car rien n'apparaît dans les logs. La variante hors ligne VLLMOffline construit des StructuredOutputsParams et les place dans SamplingParams, tout en comptant comme une boîte noire, car l'application de la contrainte est faite par le moteur vLLM et non par Outlines.

ModèleFonction de chargementQui impose le schémaRegexGrammaire
Transformersfrom_transformersOutlines en localouioui
llama.cppfrom_llamacppOutlines en localouioui
MLXfrom_mlxlmOutlines en localouioui
OpenAIfrom_openaile fournisseurnon, TypeErrornon, TypeError
Ollamafrom_ollamale fournisseurnon, TypeErrornon, TypeError
Serveur vLLMfrom_vllmle serveur vLLMoui, à partir de la version 0.12oui, à partir de la version 0.12
vLLM hors lignefrom_vllm_offlinele moteur vLLMouioui

La version 1.0 et la rupture avec l'interface v0

La version 1.0.0 est arrivée sur PyPI le 18 juin 2025, et la dernière version de la branche zéro, 0.2.3, date du 3 avril 2025. Le fichier release_note.md livré dans le paquet publié explique l'intention : la nouvelle version restreint Outlines à la génération contrainte elle-même et laisse le reste du travail aux bibliothèques d'inférence et à l'utilisateur.

Quatre changements cassent tout ce qui était écrit avant. D'abord, les fonctions de chargement du module models, comme models.transformers ou models.openai, ont été remplacées par des équivalents préfixés par from_, qui prennent une instance de moteur ou de client déjà construite au lieu d'un nom de modèle et d'un dictionnaire de paramètres. Ensuite, le module generate avec generate.json et generate.choice a disparu au profit d'un constructeur unique Generator qui accepte n'importe quel type de sortie pris en charge. Troisièmement, TransformersVision a cédé la place à TransformersMultiModal, chargé via from_transformers avec un processeur au lieu d'un tokenizer. Quatrièmement, la classe Function a été remplacée par Application, qui ne prend aucun modèle à la construction, seulement à l'appel, et lit les variables de template dans un dictionnaire plutôt que dans des arguments nommés. L'intégration d'ExLlamaV2 a été supprimée sans remplacement.

Les éléments dépréciés n'ont continué à fonctionner, avec un simple avertissement, que jusqu'à la version 1.1.0, publiée le 10 juillet 2025, moins de quatre semaines après la 1.0.0. Tous les tutoriels écrits avant la mi-2025 montrent du code qui ne s'exécutera plus du tout aujourd'hui. Quand vous cherchez des exemples en ligne, c'est un vrai coût, car il y a encore plus d'anciens articles que de nouveaux.

Le rythme de publication est irrégulier. Après la 1.2.0 du 31 juillet 2025 est venue une longue série de versions correctives, et la 1.3.0 n'est apparue que le 13 mai 2026. Ensuite, le rythme s'est resserré : 1.3.1 le 30 juin, 1.3.2 le 20 juillet et 1.3.3 le 6 août 2026. Une petite incohérence dans le flux de versions : une entrée intitulée Outlines v1.2.12 y apparaît deux fois, avec des horodatages du 3 mars et du 4 mai 2026. La date PyPI de la 1.3.0 correspond au jour près à la date du flux de versions, donc les chiffres eux-mêmes sont fiables.

Installation, dépendances et licence

Le cœur de la bibliothèque n'embarque aucun moteur. Les dépendances de base sont jinja2, cloudpickle, diskcache, pydantic à partir de 2.0, jsonschema, pillow, typing_extensions, genson et outlines_core épinglé exactement à 0.2.14, publié le 9 janvier 2026, aussi sous Apache 2.0. Le Python requis est au moins 3.10 et inférieur à 3.14.

Bash
# the core alone, no engine
pip install outlines

# a local model through transformers, the only route to a full guarantee on a GPU
pip install "outlines[transformers]"

# llama.cpp and MLX on Apple Silicon
pip install "outlines[llamacpp]"
pip install "outlines[mlxlm]"

# note: this extra installs only the openai package,
# because Outlines talks to a vLLM server over its OpenAI-compatible API
pip install "outlines[vllm]"

# alternative automaton-building backends
pip install "outlines[xgrammar]"
pip install "outlines[llguidance]"

L'extra outlines[vllm] est la source de surprise la plus fréquente. Dans les métadonnées du paquet, il liste une seule dépendance, openai, car l'intégration de vLLM passe par l'API compatible OpenAI. Il faut installer vLLM lui-même séparément, et si vous voulez le mode hors ligne, le paquet vllm doit de toute façon être dans l'environnement. De même, outlines[sglang] n'apporte que openai, et outlines[tgi] que huggingface_hub.

La licence est un cas d'école, et après une série de projets où la déclaration ne concorde pas avec le contenu, c'est un changement agréable. Trois sources indépendantes disent la même chose. Le champ license sur PyPI contient Apache-2.0, un véritable identifiant SPDX plutôt que tout le texte de la licence collé. Le fichier LICENSE sur la branche principale du dépôt dottxt-ai/outlines répond avec le code 200 et contient le texte complet d'Apache 2.0 avec la mention Copyright 2023- The Outlines developers, tandis que la variante LICENSE.md n'existe pas et renvoie 404. Le wheel publié outlines-1.3.3-py3-none-any.whl contient un seul fichier dans outlines-1.3.3.dist-info/licenses/, à savoir LICENSE, de nouveau avec le texte d'Apache 2.0, et il contient du vrai code et non des métadonnées seules. La seule chose qui manque est un classifieur License :: OSI Approved dans la liste des classifieurs PyPI, qui ne contient que Programming Language :: Python :: 3. Les outils qui lisent les classifieurs au lieu du champ license peuvent donc afficher un blanc.

SourceCe qu'elle déclareFichier présent
Champ license de PyPIApache-2.0sans objet
LICENSE dans le dépôtApache 2.0, Copyright 2023- The Outlines developersoui, code 200
LICENSE.md dans le dépôtaucunenon, code 404
Wheel outlines-1.3.3-py3-none-any.whltexte complet d'Apache 2.0oui, dist-info/licenses/LICENSE
Classifieurs PyPIaucune entrée de licencesans objet

Le risque lié à l'éditeur mérite une réflexion à part. Le projet est mené par l'entreprise dottxt, le dépôt compte environ 15,7 mille étoiles et est activement développé, mais la même entreprise vend une API commerciale, disponible dans la bibliothèque sous le nom from_dottxt. Le site dottxt.ai ne publie aucune grille tarifaire, la sous-page des prix renvoie 404, et la seule voie est un formulaire de contact. Si vous prévoyez de vous appuyer sur la variante payante, il faut d'abord parler à un commercial, car les chiffres ne sont pas publics. La bibliothèque elle-même, sous Apache 2.0, fonctionne bien sûr sans rien de tout cela.

Au-delà de JSON Schema : expressions régulières et grammaires

La prise en charge de JSON Schema est le minimum et tout le monde l'a, y compris Instructor et Pydantic AI. Ce qui distingue Outlines, c'est ce qu'il sait faire au-delà des schémas.

Le module outlines.types expose les fonctions regex, cfg et json_schema ainsi que les classes Regex, CFG, Choice et JsonSchema. S'y ajoute un petit langage pour composer des motifs : either, optional, exactly, at_least, at_most, between, one_or_more et zero_or_more. Le sous-module outlines.types.locale contient des motifs tout faits, pour l'instant seulement américains : locale.us.zip_code vaut \d{5}(?:-\d{4})?, et locale.us.phone_number est un motif de numéro sous forme avec parenthèses ou avec traits d'union. Les sous-modules airports et countries existent mais exigent les extras outlines[airports] et outlines[countries], et sans eux ils lèvent une ImportError avec des instructions d'installation.

Les grammaires hors contexte s'écrivent en syntaxe Lark. Le module outlines.grammars en fournit deux : grammars.json et grammars.arithmetic, chargées par la fonction read_grammar depuis un répertoire contenant json.lark, arithmetic.lark et common.lark. Vous passez votre propre grammaire sous forme de chaîne via cfg. C'est la seule voie quand vous devez imposer un langage qu'un schéma JSON ne peut pas décrire : un fragment SQL, une expression dans votre propre petit langage de configuration, une commande de robot.

Python
import outlines
from pydantic import BaseModel
from transformers import AutoModelForCausalLM, AutoTokenizer

class Invoice(BaseModel):
    number: str
    total: float
    currency: str

model = outlines.from_transformers(
    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
)

# the generator builds the automaton once, so keep it outside the request loop
generator = outlines.Generator(model, Invoice, backend="outlines_core")

raw = generator("Write out invoice number FV/2026/114 for 1249.90 PLN")
invoice = Invoice.model_validate_json(raw)

Remarquez la dernière ligne. Le générateur renvoie une chaîne, pas un objet Pydantic. La méthode SteerableGenerator.__call__ appelle self.model.generate(prompt, self.logits_processor, ...) et renvoie ce que le modèle a retourné. L'analyse en objet est de votre côté, et c'est en cela qu'Outlines diffère d'Instructor, qui renvoie une instance prête à l'emploi.

Python
from outlines.types import regex, either, cfg, json_schema, locale

# an invoice number in one specific format
invoice_no = regex(r"FV/\d{4}/\d{1,4}")

# a choice from a closed list, no guessing
priority = either("low", "medium", "high")

# a ready-made pattern from the locale submodule
postal_code = locale.us.zip_code

# a Lark grammar as a string
list_of_items = cfg(r"""
start: "[" item ("," item)* "]"
item: /[a-z]+/
""")

# a JSON schema given directly, with whitespace control
schema = json_schema({"type": "object", "properties": {"n": {"type": "integer"}}})

generator = outlines.Generator(model, invoice_no)

La fonction python_types_to_terms accepte directement un assez grand nombre de types : int, float, bool, str, un dict nu (traduit en grammaire grammars.json), time, date, datetime, les classes Enum, Literal, Union, list, tuple, un dict paramétré, les modèles Pydantic et structures apparentées, un constructeur de schéma de la bibliothèque genson, et même une signature de fonction. Elle a une limite stricte d'imbrication : dépasser le dixième niveau de récursion se termine par une RecursionError. Les modèles de données profondément imbriqués ou récursifs ne passeront tout simplement pas.

Outlines face à Instructor, les calculs

L'énoncé le plus court possible de la différence est celui-ci : Instructor interroge le modèle et réessaie quand la validation échoue, donc il fonctionne avec n'importe quel fournisseur, mais paie les nouvelles tentatives et ne garantit rien. Outlines garantit, mais avec les modèles pilotables il exige que les poids soient dans votre processus. Le reste est du détail.

Faisons les calculs pour Instructor avec une hypothèse explicite, car je n'ai aucune mesure en production : supposons 1200 tokens d'entrée et 300 tokens de sortie par requête, et une nouvelle tentative nécessaire dans 5 pour cent des cas. Sur mille requêtes, cela donne 1000 appels de base plus 50 nouvelles tentatives, soit 1050 appels et 5 pour cent de surcoût sur le nombre de requêtes. L'entrée passe de 1 200 000 à 1 260 000 tokens, la sortie de 300 000 à 315 000. C'est une hypothèse, pas une mesure, et avec un schéma difficile le taux d'erreur est souvent plusieurs fois plus élevé. La valeur par défaut max_retries=3 dans la méthode create d'Instructor signifie au pire quatre appels payants pour une seule requête d'utilisateur.

Du côté d'Outlines avec un modèle pilotable, il n'y a aucune nouvelle tentative, car une sortie non conforme ne peut pas être produite. Vous payez autre chose : du temps de GPU réservé quel que soit le trafic, la compilation de l'automate au démarrage et le travail d'exploitation autour de votre propre moteur que vous pourriez éviter avec LiteLLM ou Ollama. Le point d'équilibre dépend donc de la charge, pas de la technologie elle-même. À quelques centaines de requêtes par jour, un fournisseur payant avec nouvelles tentatives revient moins cher qu'une carte dans le cloud. Avec un flux régulier et important, les proportions s'inversent.

Il y a aussi un avantage d'Instructor que l'on oublie facilement en comparant les garanties. Les validateurs Pydantic peuvent vérifier le sens, pas seulement la forme : qu'une date soit dans le futur, que les lignes d'une facture s'additionnent au total, qu'un identifiant existe dans la base. Un automate dérivé d'un schéma ne peut rien exprimer de tout cela. Si votre problème est le contenu plutôt que la syntaxe, le masquage de tokens ne le résoudra pas et il est plus sensé de se tourner vers Instructor ou Guardrails AI.

FonctionOutlines, modèle pilotableOutlines, boîte noireInstructor
Garantie syntaxiquepar constructionidentique à celle du fournisseuraucune, validation après coup
Nouvelles tentativesn'ont pas lieudépend du fournisseurmax_retries, 3 par défaut
Expressions régulièresouigénéralement TypeErrornon
Grammaires LarkouivLLM et SGLang seulementnon
Validation sémantiquenonnonoui, validateurs Pydantic
Nécessite des poids locauxouinonnon
Renvoieune chaîneune chaîneun objet Pydantic
LicenceApache 2.0Apache 2.0MIT

Erreurs courantes

La première, et la plus coûteuse, est de croire que from_openai vous donne la garantie du masquage de tokens. Ce n'est pas le cas. Vous obtenez le response_format du fournisseur, exactement ce que vous obtiendriez sans Outlines, simplement via une autre interface. Un code qui passe les tests en local sur from_transformers perd la propriété sur laquelle il a été construit dès que vous passez à OpenAI.

La deuxième est la dégradation silencieuse avec un vLLM antérieur à 0.12. Le champ structured_outputs est alors ignoré, la requête se termine avec un code de succès et la sortie ne porte aucune contrainte. Vérifiez la version du serveur avant de conclure que l'application de la contrainte fonctionne, et ajoutez de votre côté une assertion d'analyse comme filet de sécurité.

La troisième est de construire un Generator dans le gestionnaire de requêtes. Compiler un automate à partir d'un schéma complexe peut prendre un temps notable, et la classe est conçue pour que le processeur soit construit une fois et conservé. Dans un service web, créez les générateurs au démarrage du processus, un par schéma.

La quatrième est de confondre correction syntaxique et vérité. Un schéma imposé garantit que le champ total sera un nombre. Il ne garantit pas que c'est le bon nombre de la facture. Une couche qui vérifie le sens reste nécessaire.

La cinquième est de copier du code issu de tutoriels écrits avant la mi-2025. Des appels comme models.transformers(...) et generate.json(...) ont disparu dans la 1.1.0. Si un exemple ne contient ni from_ dans le nom de la fonction de chargement ni le constructeur Generator, il précède la rupture.

La sixième est d'installer outlines[vllm] en s'attendant à voir apparaître vLLM. Ce qui apparaît, c'est openai. Vérifiez la liste des dépendances de l'extra avant de construire une image de conteneur sans véritable moteur. Les modèles locaux viennent généralement de Hugging Face, ce qui est une étape séparée et un coût séparé en espace disque.

FAQ

Outlines fonctionne-t-il avec OpenAI et Anthropic ?

Oui, mais en mode boîte noire. La contrainte est transmise au fournisseur comme response_format, et Outlines ne voit jamais la distribution de probabilités et ne masque rien. Les expressions régulières et les grammaires n'y sont pas disponibles et se terminent par une TypeError avec un message clair.

Quand la version 1.0 est-elle sortie et les anciens tutoriels fonctionnent-ils encore ?

La version 1.0.0 est apparue sur PyPI le 18 juin 2025. L'ancienne interface a été supprimée dans la 1.1.0 le 10 juillet 2025. Un code qui utilise models.transformers ou generate.json ne s'exécutera pas sur la 1.3.3 actuelle.

La garantie signifie-t-elle que la réponse est factuellement correcte ?

Non. La garantie ne couvre que la forme : la sortie s'analysera toujours selon le schéma. Le contenu des champs peut être inventé, et vous avez toujours besoin d'une validation sémantique ou d'une vérification auprès d'une source de vérité.

Quel backend choisir ?

Les valeurs par défaut sont raisonnables : outlines_core pour les schémas JSON et les expressions régulières, llguidance pour les grammaires. Passez à xgrammar ou llguidance quand la construction de l'automate à partir de votre schéma se révèle trop lente, et comparez les temps sur votre propre cas, car les différences dépendent de la forme du schéma.

Outlines remplace-t-il Instructor ?

Pas dans tous les scénarios. Il le remplace là où vous détenez les poids en local et tenez à une garantie sans nouvelles tentatives. Il ne le remplace pas là où vous utilisez un fournisseur fermé ou avez besoin de validateurs qui vérifient le sens des données plutôt que leur forme.

Quelle taille de schéma Outlines peut-il gérer ?

La limite stricte est le dixième niveau de récursion dans python_types_to_terms, au-delà duquel on obtient une RecursionError. La limite souple est le temps de compilation de l'automate, qui croît avec la complexité du schéma. Mesurez-le sur votre propre schéma avant de déployer.

La documentation du projet se trouve sur dottxt-ai.github.io/outlines, le code source dans le dépôt dottxt-ai/outlines, et les versions et métadonnées sur PyPI.

À lire aussi