Measured Academy Measured Academy
English Pilote Progression 0

Module 3 · Leçon 2 sur 4

Ce que coûte le schéma

  1. 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é.
  2. 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.
  3. 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.
  4. 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.
Explorateur

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.jsonl
  • scripts/ch3_route_typed.py
  • runs/ch3-course-route-typed-2026-11-20.jsonl
Bascule

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_tokens et usage.output_tokens de 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.md chiffre à $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)
ValeurFichier dans les enregistrements du livreConditions
416BOOK.md
2,266BOOK.md
549runs/ch3-course-route-typed-2026-11-20.txt
2,919runs/ch3-course-route-typed-2026-11-20.txt
40BOOK.md
80BOOK.md
528runs/ch3-course-route-typed-2026-11-20.txt
120runs/ch3-course-route-typed-2026-11-20.txt
488BOOK.md
0BOOK.md
5.4xBOOK.md
39runs/ch3-router-typed-2026-10-14.jsonl
224runs/ch3-router-typed-2026-10-14.jsonl
45runs/ch3-router-typed-2026-10-14.jsonl
230runs/ch3-router-typed-2026-10-14.jsonl
185BOOK.md
237BOOK.md
4runs/ch3-router-typed-2026-10-14.jsonl
8runs/ch3-router-typed-2026-10-14.jsonl
20COST.md
21COST.md
2,682COST.md
120COST.md
$0.02COST.mdclaude-opus-4-6, tarifs Opus de COST.md
2,682COST.mdla reprise du 2026-10-14 sur Python 3.12.3
$0.03BOOK.mdclaude-opus-5, 2026-11-20, tarifs Opus de COST.md

Référence : Chapitre 3, « The concept » et « The tradeoff ».