Module 3 · Leçon 2 sur 4
Ce que coûte le schéma
- Ce qui s’est passéTyper le routeur a multiplié plusieurs fois les jetons d’entrée pour la même décision d’un seul mot, alors que les jetons de sortie ont beaucoup moins bougé.
- Pourquoi ça a changéLe SDK transforme le type en schéma JSON et l’envoie avec chaque appel ; chaque appel typé transporte donc un bloc fixe d’entrée supplémentaire, et la réponse revient sous forme d’un petit objet JSON au lieu d’un mot nu.
- Comment on le mesureLes jetons d’entrée et de sortie sont journalisés pour chaque appel à partir du champ usage de la réponse, puis comparés appel par appel entre les versions non typée et typée du même billet.
- Comment l’améliorerJournaliser la consommation par appel avant et après le typage, garder les schémas petits, se passer de schéma quand c’est une personne qui lit la sortie, et chiffrer le surcoût à votre propre volume au lieu de citer un ratio.
Le même billet, avec et sans schéma
Essayez. Choisissez un billet et passez des jetons d’entrée aux jetons de sortie pour voir ce que le typage de l’appel a ajouté.
D’où viennent ces données · claude-opus-4-6, 2026-10-14; claude-opus-5, 2026-11-20
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.jsonlscripts/ch3_route_typed.pyruns/ch3-course-route-typed-2026-11-20.jsonl
Ce qui transite sur le réseau
Essayez. Choisissez le genre de type que vous passeriez, puis passez du schéma que Pydantic construit au schéma qui a été envoyé.
D’où viennent ces données · anthropic 1.2.0, pydantic 2.13.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 section A
Ce qui s’est passé
Le routeur typé a pris la même décision pour chaque billet. Il n’a pas coûté la même chose.
| Sur dix appels | Non typé, exécution du livre | Typé, exécution du livre | Non typé, exécution du cours | Typé, exécution du cours |
|---|---|---|---|---|
| Modèle | claude-opus-4-6 |
claude-opus-4-6 |
claude-opus-5 |
claude-opus-5 |
| Jetons d’entrée | 416 | 2,266 | 549 | 2,919 |
| Jetons de sortie | 40 | 80 | 528 | 120 |
| Dont réflexion | non enregistré | non enregistré | 488 | 0 pour chaque appel |
Sources : BOOK.md, constats mesurés, à partir de runs/ch3-router-typed-2026-10-14.jsonl pour l’exécution du livre ; runs/ch3-course-route-typed-2026-11-20.txt et sa ligne dans BOOK.md pour l’exécution du cours. BOOK.md donne le ratio d’entrée de l’exécution du livre comme 5.4x.
Regardez un seul billet et la cause saute aux yeux. Pour le premier billet, l’appel non typé a journalisé 39 jetons d’entrée et l’appel typé 224. Pour le dernier, 45 et 230. Les billets diffèrent en longueur de quelques jetons. L’écart entre les deux versions, lui, ne bouge pas.
Pourquoi ça a changé
Quand vous passez un type à messages.parse, le SDK fait trois choses : il construit un schéma JSON à partir du type, envoie ce schéma avec votre requête, et construit un objet de votre type à partir de ce qui revient. C’est l’étape du milieu qui coûte. Le schéma voyage avec chaque appel, que le billet fasse une ligne ou vingt.
BOOK.md évalue le surcoût à environ 185 jetons d’entrée supplémentaires par appel pour ce schéma dans l’exécution du livre, et à environ 237 dans l’exécution du cours. C’est un bloc fixe, pas un pourcentage, et c’est pourquoi le ratio paraît si grand ici : la requête non typée était minuscule au départ. Le bloc a un peu grossi sur le modèle récent ; le schéma, lui, n’a pas changé.
La sortie a grossi pour une raison plus simple. L’appel non typé répondait par un mot nu, journalisé comme 4 jetons de sortie pour le premier billet. L’appel typé répondait par un petit objet JSON contenant ce mot, journalisé comme 8.
| Appel non typé | Appel typé | |
|---|---|---|
| Envoyé | la requête | la requête plus le schéma |
| Renvoyé | un mot | un objet JSON avec un seul champ |
| Grossit avec | le billet | le billet, plus une constante pour le schéma |
Sur le modèle actuel, le côté sortie s’est inversé. Les appels non typés réfléchissaient avant de répondre, et la plus grande partie de leur sortie était de la réflexion. Les appels typés n’ont déclaré aucune réflexion et ont écrit le même petit objet chaque fois. Dans cette exécution, la version typée a donc dépensé plus en entrée et moins en sortie que la version non typée. C’est une seule exécution de dix billets ; c’est une raison de mesurer vos propres appels, pas une règle voulant que les appels typés ne réfléchissent pas.
Servez-vous du premier explorateur ci-dessus pour le vérifier vous-même, billet par billet, sur l’une ou l’autre exécution. Le second montre ce que le SDK envoie réellement pour chaque genre de type qu’il accepte.
Comment on le mesure
- La consommation par appel, tirée de la réponse. Les champs
usage.input_tokensetusage.output_tokensde chaque appel entrent dans le fichier d’exécution avec une étiquette. Rien n’est estimé à partir de la longueur des chaînes. - Apparié par billet. La comparaison porte sur le même billet à travers les deux versions ; la seule différence est donc le schéma et la consigne qu’il remplace.
- Les totaux à partir des enregistrements. L’exécution du livre a journalisé la consommation de 20 des 21 appels faits : 2,682 jetons d’entrée et 120 jetons de sortie, que
COST.mdchiffre à $0.02. La reprise du 2026-10-14 a journalisé les mêmes 2,682 jetons d’entrée. L’exécution du cours sur le modèle actuel a coûté $0.03 pour les mêmes vingt appels avec consommation (BOOK.md, constats mesurés).
L’appel manquant est la troncature volontaire de la leçon 3. Quand un appel lève une exception, il n’y a aucune réponse où lire la consommation, dans l’une ou l’autre exécution. Le banc d’essai du cours lui donne quand même une ligne, avec sa consommation laissée vide plutôt que devinée.
Une mise en garde sur le ratio : il vient d’une seule exécution de dix billets avec une requête très courte. Avec une longue requête, le même surcoût fixe représenterait une part bien plus petite. Citez le surcoût par appel avec son schéma, pas le ratio.
Comment l’améliorer
- Journalisez la consommation avant de typer quoi que ce soit, pour avoir une base de comparaison.
- Gardez le schéma petit. Chaque champ, chaque description et chaque modèle imbriqué est de l’entrée à chaque appel.
- Ne typez pas ce qu’une personne lit. Un résumé ou une réponse de clavardage gagne une étape de validation et l’équivalent d’un schéma en jetons, pour rien.
- Un unique champ de texte libre n’apporte rien. Le chapitre note qu’un simple type chaîne envoie un schéma qui dit seulement « string ».
- Chiffrez-le à votre volume. Le surcoût est petit par appel et constant. Savoir s’il compte est une question de nombre d’appels, que le module 13 aborde.
Les types acceptés et le raisonnement derrière la recommandation se trouvent au chapitre 3 du livre, « The concept » et « The tradeoff ». Suite : trois façons dont un appel typé tourne mal.
Chaque nombre de cette leçon et le fichier d’où il vient (26)
| Valeur | Fichier dans les enregistrements du livre | Conditions |
|---|---|---|
| 416 | BOOK.md | |
| 2,266 | BOOK.md | |
| 549 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 2,919 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 40 | BOOK.md | |
| 80 | BOOK.md | |
| 528 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 120 | runs/ch3-course-route-typed-2026-11-20.txt | |
| 488 | BOOK.md | |
| 0 | BOOK.md | |
| 5.4x | BOOK.md | |
| 39 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 224 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 45 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 230 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 185 | BOOK.md | |
| 237 | BOOK.md | |
| 4 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 8 | runs/ch3-router-typed-2026-10-14.jsonl | |
| 20 | COST.md | |
| 21 | COST.md | |
| 2,682 | COST.md | |
| 120 | COST.md | |
| $0.02 | COST.md | claude-opus-4-6, tarifs Opus de COST.md |
| 2,682 | COST.md | la reprise du 2026-10-14 sur Python 3.12.3 |
| $0.03 | BOOK.md | claude-opus-5, 2026-11-20, tarifs Opus de COST.md |
Référence : Chapitre 3, « The concept » et « The tradeoff ».