Programme Leçon 138 sur 250 · Sorties structurées et appels de fonctions/d'outils
Sorties structurées et appels de fonctions/d'outils

Sorties contraintes / imposées par un schéma

Tu as validé à la main le JSON du modèle dans les leçons précédentes. La pratique moderne agit une étape plus tôt : empêcher le modèle de produire du mauvais JSON dès le départ. C'est le décodage contraint (aussi appelé sorties structurées). Tu donnes un schéma à l'API, et le décodeur n'a le droit de tirer que des tokens qui gardent la sortie valide face à lui. Le modèle ne peut littéralement pas produire un champ manquant ni une valeur du mauvais type.

Avec une API façon OpenAI, tu passes un response_format avec un JSON Schema et strict: true (pour illustrer seulement -> on n'appelle aucun modèle ici) :

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

La suite de ce cours appelle Anthropic, qui offre la même garantie via output_config pour des réponses en JSON garanti et l'usage d'outils strict pour des entrées d'outils parfaitement conformes au schéma :

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

Dans les deux cas, c'est le fournisseur qui impose la contrainte. Mais le décodage contraint ne peut toujours pas vérifier tes règles métier (l'âge est-il plausible ? la devise est-elle l'une de celles que tu acceptes ?), et tous les modèles ou passerelles ne le gèrent pas. Donc tu valides de ton côté quoi qu'il arrive. C'est ce validateur que tu construis maintenant.

Côté Python, le standard de fait pour déclarer et valider cette forme est Pydantic. Tu écris une classe de modèle et la bibliothèque lit, convertit et valide pour toi :

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

Pydantic n'est pas disponible dans ce bac à sable du navigateur, donc tu vas construire la même idée à la main avec la bibliothèque standard. C'est exactement ce que font ces bibliothèques en coulisse, et ça rend les règles impossibles à survoler. Tu écris validate_against_schema(obj, schema).

Le schema est un dict. Chaque valeur est soit une chaîne de nom de type ("int", "float", "str", "bool", "list", "dict"), soit un petit dict de spécification comme {"type": "int", "default": 0}. Ta fonction renvoie un dict de résultat {"ok": bool, "value": dict, "errors": list} :

  • Si obj n'est pas un dict, renvoie ok=False avec une erreur racine et une value vide.
  • Pour chaque champ : s'il est manquant et que la spécification a un "default", mets la valeur par défaut (le passage conversion/défaut). S'il manque sans valeur par défaut, note une erreur.
  • S'il est présent, vérifie son type. En cas de différence, note une erreur qui nomme le champ.
  • Convertis un simple int en float quand un float est demandé (c'est sans perte et sans danger), mais ne convertis rien d'autre.
  • S'il y a eu des erreurs, renvoie ok=False avec les errors rassemblées et une value vide ; sinon renvoie ok=True avec la value validée.

Le piège du bool qui est un int. En Python, bool est une sous-classe de int, donc isinstance(True, int) vaut True et le true de JSON devient le True de Python. Une vérification de type naïve laisserait "age": true passer tranquillement dans un champ int. Refuse explicitement un bool partout où un int ou un float est exigé :

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

Construis-la pour que deux contenus bien formés différents passent tous les deux, qu'un champ manquant et un mauvais type finissent chacun dans errors, qu'une valeur par défaut soit remplie, qu'un int devienne un float, et qu'un bool sournois soit refusé là où un nombre est exigé.

À ton tour

Écris validate_against_schema(obj, schema) qui renvoie {"ok", "value", "errors"}. schema associe chaque champ à une chaîne de nom de type ("int"/"float"/"str"/"bool"/"list"/"dict") ou à un dict de spécification {"type": ..., "default": ...}. Refuse un obj qui n'est pas un dict, note une erreur pour chaque champ manquant (sans valeur par défaut) ou du mauvais type, mets la valeur par défaut quand elle est fournie, convertis un simple int en float, et refuse un bool là où un int ou un float est exigé (le piège du bool qui est un int). Renvoie ok=True avec la value validée seulement quand il n'y a aucune erreur.

Tu as repéré un problème dans cette leçon ? Signale-le · Pose une question sur cette leçon

Cet exercice s'ouvre bientôt

Termine la leçon précédente pour débloquer celle-ci. Tout le cours est gratuit, aucun compte n'est requis, et tu peux lire cette leçon dès maintenant.