Une demande d’achat contient trois claviers. Le modèle renvoie quatre claviers, le bon code produit et un total parfaitement calculé. Le JSON est lisible. Le schéma est respecté. La demande reste fausse.
Les sorties structurées, ou structured outputs, contraignent la forme d’une réponse de LLM. Elles ne remplacent ni les règles métier ni le contrôle de fidélité au document source. Pour une équipe data, la décision consiste à déterminer quelles sorties peuvent entrer dans le système, lesquelles doivent être revues et lesquelles doivent être rejetées.
L’atelier téléchargeable rend cette distinction observable. Il contient un schéma, une demande fictive, une référence annotée et 19 cas exécutés localement le 20 octobre 2026. Tous produisent le verdict attendu. Aucun modèle ni service d’achat n’a été appelé : ce résultat valide le programme de contrôle sur ces cas, pas la fiabilité d’un fournisseur.
JSON valide, schéma conforme, donnée exacte
Ces contrôles répondent à des questions différentes.
| Contrôle |
Question posée |
Erreur qui peut encore passer |
| Lecture JSON |
Le texte peut-il être interprété ? |
Le montant est une chaîne au lieu d’un nombre |
| JSON Schema |
Les champs et types respectent-ils le contrat ? |
Le total ne correspond pas aux lignes |
| Règles métier |
Les valeurs sont-elles cohérentes et admissibles ? |
Une quantité fausse produit un total cohérent |
| Rapprochement à une référence |
La réponse correspond-elle à la source attendue ? |
La référence elle-même peut être mal annotée |
Dans JSON Schema, required impose la présence d’un champ. additionalProperties: false interdit les propriétés supplémentaires à l’endroit où cette règle est définie. Ces contraintes ne disent pas combien de claviers le demandeur a réellement commandés. Référence JSON Schema sur les objets.
Un champ obligatoire peut autoriser null. C’est utile pour représenter une information inconnue, à condition que l’application prévoie une revue. Remplacer cette inconnue par zéro changerait son sens : une quantité absente ne signifie pas une commande de zéro article. Cette politique doit apparaître dans le schéma et dans le traitement en aval.
Ce que les API permettent, et ce qui reste à traiter
La documentation OpenAI distingue JSON mode, qui vise un JSON valide, et Structured Outputs, qui vise le respect du schéma pris en charge. Elle précise que des erreurs de contenu restent possibles et prévoit des branches pour les refus et les réponses incomplètes. Il faut lire ces états avant de considérer le contenu comme un résultat exploitable. Guide OpenAI.
Claude documente également les arrêts refusal et max_tokens. Son sous-ensemble JSON Schema comporte des limites : toutes les contraintes numériques ou de longueur ne sont pas prises en charge. La documentation signale aussi une particularité de casse pour les valeurs enum et const. Une validation locale reste donc nécessaire ; toute normalisation de casse doit respecter le sens des codes métier. Guide Claude.
Gemini recommande explicitement de contrôler les valeurs dans l’application et de traiter les réponses conformes au schéma mais incorrectes sur le fond. Son guide présente aussi un sous-ensemble de JSON Schema. Guide Gemini.
Ces pages ont été vérifiées le 20 octobre 2026. La mise à jour documentaire Gemini du 13 octobre ne constitue pas, à elle seule, une annonce de lancement. Cet article est un guide de mise en œuvre.
Pour un branchement réel, vérifier le modèle, l’API, le SDK et les mots-clés de schéma supportés ensemble. Une validation réussie par une bibliothèque locale ne prouve pas que le fournisseur acceptera le même schéma. Et un schéma de réponse ne définit ni les connecteurs vers votre ERP, ni les permissions d’écriture, ni les règles de partage : ces éléments appartiennent à votre application.
Le cas concret : trois claviers deviennent quatre
Notre demande fictive DA-001 contient trois claviers CLAVIER-A à 12,50 euros l’unité, soit 37,50 euros. L’atelier représente les montants en centimes entiers : 1250 et 3750. Ce choix simplifie les calculs exacts de cet exercice en euros ; il ne constitue pas un modèle universel pour toutes les monnaies.
Le catalogue de contrôle autorise deux codes produits et la devise EUR. Les prix restent libres. Une annotation séparée, conservée dans reference.json, indique la quantité attendue. Elle n’est pas générée par le modèle.
Trois réponses montrent où placer les contrôles :
- Trois claviers, total 35 euros. Les types sont bons, mais le calcul échoue :
3 × 1250 ne vaut pas 3500. Rejet métier.
- Quatre claviers, total 50 euros. Le calcul et le catalogue passent. Le rapprochement à la référence détecte la mauvaise quantité. Rejet de fidélité.
- Quatre claviers, total 50 euros, sans référence disponible. Le programme demande une revue. Il ne transforme pas l’absence de preuve en validation.
La référence complète n’existera pas pour chaque nouveau document en production. Elle sert d’abord à évaluer un échantillon annoté. Ensuite, le processus doit prévoir une preuve disponible au moment du traitement : rapprochement à une commande existante, vérification humaine du passage source ou autre contrôle adapté. Demander au même modèle de confirmer sa propre réponse n’apporte pas une référence indépendante.
Remplacer une reprise aveugle par une décision explicite
Un traitement élémentaire peut envoyer un texte, essayer de lire le JSON et relancer jusqu’à obtenir un objet. Il mesure alors surtout sa capacité à récupérer une forme acceptable.
Le traitement proposé distingue cinq étapes : état de génération, lecture JSON, schéma, règles métier, fidélité. Il conserve le motif du premier blocage. L’intérêt est opérationnel : une erreur de syntaxe, un document tronqué et un désaccord avec la source n’appellent pas la même correction.
Dans l’atelier, une réponse déclarée incomplète reste écartée même si son corps contient un JSON parfaitement valide. Un adaptateur fournisseur réel doit extraire les états et les blocs documentés ; il ne doit pas convertir automatiquement tout HTTP 200 en succès métier. L’enveloppe state/body du téléchargement est uniquement un format pédagogique local.
Pour les reprises, définissez une limite d’essais, de coût et de durée avant lancement. Une troncature peut justifier un budget de sortie adapté ou un document découpé différemment. Une incohérence métier mérite un retour explicite sur la règle violée. Un refus doit suivre le traitement prévu par l’application. Aucun de ces chemins ne doit déclencher un achat pendant la correction.
Enfin, séparez admission des données et exécution d’une action. Une clé de requête stable et une vérification des opérations déjà enregistrées évitent qu’un rejeu crée deux commandes. L’atelier ne simule pas cette écriture : il s’arrête à un verdict.
Tutoriel : tester votre frontière d’admission
1. Préparer l’environnement
Téléchargez l’archive et décompressez-la. Prérequis : Python, un terminal et Internet pour l’installation. La recette a été exécutée avec Python 3.14.7 et jsonschema 4.26.0. Les dépendances résolues sont épinglées dans requirements-lock.txt.
Depuis le dossier atelier :
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-lock.txt
.venv/bin/python validate.py
Sous Windows, remplacez .venv/bin/python par .venv\Scripts\python.exe. Aucune clé API ni compte fournisseur n’est nécessaire. Après installation, la recette utilise uniquement les fichiers locaux.
2. Lire le contrat avant le code
Ouvrez demande-source.txt, puis reference.json et schema.json. La réponse attendue contient request_id, currency, lines et total_cents. Chaque ligne contient un produit, une quantité et un prix unitaire.
Les champs sont obligatoires, les propriétés supplémentaires interdites. Certains champs acceptent null pour représenter une extraction incertaine. Les règles de positivité, de catalogue et de calcul sont appliquées ensuite dans Python. Le schéma est un contrat local Draft 2020-12 ; il n’a pas été soumis à une API fournisseur.
La bibliothèque jsonschema fournit un validateur Draft 2020-12 et check_schema pour vérifier le schéma lui-même. Dans d’autres usages, attention au mot-clé format : sans contrôleur de format configuré, sa présence ne déclenche pas nécessairement une vérification de date ou d’adresse. Documentation de validation.
3. Contrôler les verdicts, pas seulement le nombre de succès
La dernière ligne attendue est :
19/19 cas conformes aux verdicts attendus
Le programme doit sortir avec le code 0. resultats.json détaille les verdicts attendus et obtenus. Vérifiez notamment :
| Cas |
Résultat attendu |
| Demande correcte |
validated |
| Réponse incomplète avec JSON lisible |
incomplete |
| Total faux |
reject_business |
| Quantité fausse, total cohérent |
reject_reference |
| Même erreur, référence indisponible |
review_reference |
validated signifie uniquement que l’entrée satisfait les contrôles de cet exercice. Le script n’autorise aucune dépense et n’écrit dans aucun ERP.
La recette couvre aussi les champs absents ou ajoutés, le mauvais type, les valeurs inconnues, les produits inconnus, la mauvaise devise, les lignes vides, les quantités négatives, les clés JSON dupliquées et les constantes non finies. Ce sont des cas déterministes de validation, pas un échantillon statistique de réponses de LLM.
4. Ajouter un échec propre à votre activité
Copiez un cas de cases.json, modifiez son entrée et définissez le verdict attendu avant d’adapter le contrôleur. Par exemple : un produit existant mais interdit pour ce service, ou un prix qui dépasse le plafond d’un contrat. Ajoutez la donnée de référence nécessaire et relancez.
La comparaison exacte à la référence inclut ici l’ordre des lignes. Pour des documents complexes, il faudra définir une clé de rapprochement et une politique de tolérance. Évitez de modifier les attentes uniquement pour faire passer le programme. Si votre référence est ambiguë, marquez l’ambiguïté au lieu de fabriquer une certitude.
Conservez les résultats utiles, puis supprimez seulement l’environnement .venv créé pour l’exercice si vous n’en avez plus besoin.
Deux autres applications pour une équipe data
Un catalogue produit alimenté depuis des fiches fournisseurs. Le schéma impose les champs et unités attendus. Le contrôle métier vérifie les unités autorisées et les associations produit/catégorie. Un échantillon annoté révèle les dimensions inventées malgré un format correct. Le critère utile est la part de fiches admises avec une valeur critique erronée, pas seulement la part de JSON lisibles.
Le classement de demandes internes. Une liste fermée impose des catégories admissibles. Elle ne prouve pas que la bonne catégorie a été choisie. Comparez à des exemples annotés, examinez les confusions entre catégories et réservez une issue « à revoir ». Notre guide du jeu de référence pour la classification détaille la construction de cette base d’évaluation.
Si les documents arrivent déjà dans un format déterministe exploitable, conservez ce parseur et ces contrôles. L’ajout d’un LLM se justifie par une difficulté d’interprétation réelle, pas par la seule possibilité de produire du JSON. Pour les factures et documents métiers, le guide Document AI Custom Extractor traite séparément l’extraction et son évaluation.
Mesurer le coût de la donnée admise
Le coût pertinent inclut les appels initiaux, les reprises, les vérifications et la revue humaine. Divisez ce total par le nombre de dossiers correctement admis, mesuré sur une référence contrôlée. Suivez aussi les rejets injustifiés et les dossiers restés sans décision.
Les tarifs API varient selon le modèle et les modalités de traitement ; consultez les grilles OpenAI, Claude et Gemini, vérifiées le 20 octobre. Il n’existe pas de prix unique pour « une sortie structurée ». Claude précise notamment que le prompt de format ajouté consomme des tokens. Notre exercice n’engendre aucun coût d’inférence ; les ressources locales restent à votre charge.
Avant un test API, utilisez des documents autorisés et minimisés, puis vérifiez les conditions de conservation et d’accès du service retenu. Le format JSON ne fournit aucune garantie de confidentialité. Pour le journal de contrôle, privilégiez identifiant, versions et motif de décision plutôt que la copie systématique des documents. Les indicateurs techniques peuvent rejoindre votre suivi de l’observabilité LLM.
Le premier livrable utile est une liste de sorties acceptables et inacceptables, accompagnée des preuves qui permettent de les distinguer. Le schéma en formalise une partie. Les règles métier et la référence couvrent le reste, dans les limites que vous avez effectivement testées.
