Module 3 · Leçon 3 sur 4
Trois façons dont un appel typé tourne mal
- Ce qui s’est passéUn appel typé coupé en cours de route a levé une erreur de validation et n’a rien renvoyé, une réponse de la mauvaise forme a aussi levé une exception, et une réponse sans bloc de texte a renvoyé None sans rien lever.
- Pourquoi ça a changéLe SDK valide le texte de la réponse par rapport à votre type après l’appel ; un JSON brisé ou non conforme échoue donc bruyamment, mais quand il n’y a aucun texte à valider, il n’a rien à rejeter et renvoie None.
- Comment on le mesureUn vrai appel est forcé à se tronquer avec un minuscule max_tokens et son exception est capturée, la même requête est envoyée sans type pour voir les octets bruts, et l’analyseur est piloté localement avec des réponses fabriquées à la main.
- Comment l’améliorerAttraper l’erreur de validation et vérifier None dans deux branches séparées, dimensionner max_tokens pour la réponse entière, et écrire chaque issue, y compris une exception, dans le fichier d’exécution.
Où aboutit chaque réponse
Essayez. Choisissez l’une des six réponses enregistrées, y compris celle du modèle actuel qui a été coupée, et voyez laquelle des trois sorties elle prend et quelle protection l’attraperait.
D’où viennent ces données · 2026-10-14, 2026-11-20 et 2026-09-02
Lu dans les enregistrements du livre. Rien ici n’est simulé. Les requêtes, les billets, les réponses des modèles et les messages d’erreur restent en anglais, tels qu’ils ont été envoyés et reçus.
runs/ch3-router-typed-2026-10-14.txt section Cruns/ch3-course-route-typed-2026-11-20.jsonlruns/ch7-parse-output-format-2026-09-02.txt sections C3 and C4
La même réponse coupée, typée et non typée
Essayez. Passez de ce que votre code reçoit à ce que le modèle a écrit, pour la même requête coupée envoyée avec et sans type.
D’où viennent ces données · claude-opus-5 · 2026-09-02
Lu dans les enregistrements du livre. Rien ici n’est simulé. Les requêtes, les billets, les réponses des modèles et les messages d’erreur restent en anglais, tels qu’ils ont été envoyés et reçus.
runs/ch7-parse-output-format-2026-09-02.txt sections C1 and C1b
Ce qui s’est passé
La garantie de la leçon 1 était « l’une de quatre valeurs, ou une exception ». Cette leçon met volontairement à l’épreuve la deuxième moitié, et trouve une troisième issue que le slogan passe sous silence.
Coupée : elle a levé une exception. Le routeur typé a été appelé une fois avec max_tokens=3, trop peu pour terminer le JSON. Rien n’a été renvoyé. L’appel a levé une ValidationError de Pydantic avec ce message (runs/ch3-router-typed-2026-10-14.txt, section C) :
Invalid JSON: EOF while parsing a string at line 1 column 10
La réponse s’était rendue jusqu’à {"queue":" et s’était arrêtée. Dans l’exécution du cours sur claude-opus-5, le même appel a été coupé encore plus tôt et a levé la même classe d’exception, avec Invalid JSON: EOF while parsing a string at line 1 column 5 sur le fragment {"que (runs/ch3-course-route-typed-2026-11-20.txt). Cette fois, l’issue est une ligne du fichier d’exécution.
Mauvaise forme : elle a levé une exception. Piloter l’analyseur localement avec un JSON valide qui utilisait le mauvais nom de champ a aussi levé une exception, signalant 2 erreurs de validation, une pour chaque champ obligatoire manquant. Une réponse qui était une simple phrase a aussi levé une exception (runs/ch7-parse-output-format-2026-09-02.txt, section C3).
Aucun texte du tout : elle a renvoyé None. Piloter l’analyseur avec une réponse sans aucun bloc de contenu n’a produit aucune exception. La ligne enregistrée est parsed_output = None -- no raise (même fichier, section C4).
| Réponse | Issue | Attrapée par except ValidationError |
Attrapée par une vérification de None |
|---|---|---|---|
| Complète et valide | votre type | inutile | inutile |
| Coupée au milieu du JSON | exception | oui | non |
| JSON valide, mauvaise forme | exception | oui | non |
| Pas du JSON | exception | oui | non |
| Aucun bloc de texte | None, sans erreur |
non | oui |
Pourquoi ça a changé
La vérification a lieu après l’appel, sur votre machine. Le SDK prend le texte de la réponse et demande à Pydantic de construire votre type à partir de lui. On ne peut rien construire avec la moitié d’un objet JSON ; Pydantic refuse donc. Il refuse aussi un JSON aux mauvais champs.
Le troisième cas passe entre les mailles pour une raison banale : sans bloc de texte, il n’y a aucun texte à valider. Rien n’est mal formé. Le SDK renvoie le message avec son champ analysé vide.
Comparez maintenant la même réponse coupée à travers un appel typé et un appel non typé, avec la deuxième comparaison ci-dessus. Sur un schéma de facture avec max_tokens=16, l’appel typé a levé Invalid JSON: EOF while parsing a value at line 1 column 30. La même requête envoyée sans type est revenue comme une réponse ordinaire : raison d’arrêt max_tokens, 16 jetons de sortie, et une chaîne contenant le début d’un objet JSON (runs/ch7-parse-output-format-2026-09-02.txt, sections C1 et C1b, claude-opus-5). C’étaient deux appels avec le même petit budget, et les deux réponses se sont arrêtées au milieu de l’objet. Un seul chemin a laissé son fragment atteindre votre code avec l’apparence d’un résultat.
Ça rejoint le module 1. Là, un modèle qui réfléchit avant de répondre a dépensé un petit budget entièrement à réfléchir, et 20 sur 20 réponses sont revenues sans texte (BOOK.md, constats mesurés). Une réponse sans texte est exactement l’entrée qui produit None dans la sonde locale. Dans la seule exécution du cours faite jusqu’ici, un appel typé sur le modèle qui réfléchit, avec trois jetons de budget, a levé une exception au lieu de renvoyer None. Un seul appel ne fait pas une règle ; c’est pourquoi le test pratique vous demande de prédire et de consigner ce que fait le vôtre.
Comment on le mesure
- Forcez l’échec. Un vrai appel avec un budget trop petit pour terminer. La classe de l’exception, son message et le fragment sont capturés à partir de la console.
- Regardez les octets. La même requête par le chemin non typé montre ce que le chemin typé a refusé.
- Pilotez l’analyseur directement. Quatre réponses fabriquées à la main et une réponse vide sont passées à la fonction d’analyse du SDK, sans aucun réseau. Ce sont des faits locaux sur la version du SDK nommée dans le fichier, SDK 1.2.0, pas des observations d’un modèle.
- Remarquez ce qui n’a pas été enregistré. Le résultat de la troncature n’existe que dans la capture de la console. L’appel a levé une exception avant que le banc d’essai atteigne le code qui enregistre la consommation et écrit le fichier ; le JSONL de l’exécution n’a donc aucune ligne pour lui. Le chapitre qualifie ça de défaut de l’instrument et le laisse au dossier.
Comment l’améliorer
- Deux protections, pas une. Enveloppez l’appel dans
except ValidationError, et vérifiez séparément que le résultat analysé n’est pasNoneavant de l’utiliser. - Décidez ce que chacun veut dire. Une exception due à une troncature mérite peut-être une nouvelle tentative avec un plus grand budget. Un
Nonemérite d’abord un coup d’œil à la raison d’arrêt. - Dimensionnez
max_tokenspour la réponse entière, et, sur un modèle qui réfléchit, pour la réflexion aussi. - Consignez l’échec là où vivent les données. Écrivez l’issue de chaque appel dans le fichier d’exécution à l’intérieur de la branche
except, pour qu’une exception laisse une ligne. Le test pratique le vérifie. - N’assouplissez jamais l’analyseur pour faire disparaître une erreur. Un analyseur qui accepte la moitié d’un objet, c’est comme ça qu’une clé tronquée aboutit dans une base de données.
Les cas limites sont présentés au chapitre 3 du livre, « Edge cases ». Suite : typé ne veut pas dire juste.
Chaque nombre de cette leçon et le fichier d’où il vient (7)
| Valeur | Fichier dans les enregistrements du livre | Conditions |
|---|---|---|
| Invalid JSON: EOF while parsing a string at line 1 column 10 | runs/ch3-router-typed-2026-10-14.txt | claude-opus-4-6, max_tokens=3, un appel |
| Invalid JSON: EOF while parsing a string at line 1 column 5 | runs/ch3-course-route-typed-2026-11-20.txt | claude-opus-5, max_tokens=3, un appel |
| 2 | runs/ch7-parse-output-format-2026-09-02.txt | |
| parsed_output = None -- no raise | runs/ch7-parse-output-format-2026-09-02.txt | |
| Invalid JSON: EOF while parsing a value at line 1 column 30 | runs/ch7-parse-output-format-2026-09-02.txt | claude-opus-5, max_tokens=16, 2026-09-02, un appel |
| 16 | runs/ch7-parse-output-format-2026-09-02.txt | |
| 20 sur 20 | BOOK.md | claude-opus-5, max_tokens 100, 2026-11-08 |
Référence : Chapitre 3, « Edge cases » et la description du diagramme d’architecture.