Aller au contenu
English

Coût par exécution et par étape

  • Leçon 16
  • 35 min
  • Module 5 : Le coût

Où nous en sommes

Dans le dernier module, nous avons trouvé des défaillances dans les traces et examiné les métriques autour d'une exécution. Chaque span de modèle contient déjà les jetons de son appel, mais pas son coût. Dans cette leçon, nous convertissons les jetons en argent avec une table de prix datée. Nous lisons le coût de chaque exécution et de chaque étape, puis choisissons où le calculer. Nous commençons à la caisse d'une épicerie.

Leçon 16 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditCoût par exécution et par étape
Aperçu du cours

Ce que vous saurez faire

Attribuez un coût en dollars à chaque appel de modèle, étape et exécution, selon ses jetons et une table de prix datée. Vous pourrez alors répondre à cette question, maintenant et l’an prochain : « Combien cette exécution a-t-elle coûté, et quelle étape a engendré ce coût? »

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 35 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet dans l’état du dernier module : l’instantané end-of-m04, où python -m pytest -q termine par 93 passed, 1 skipped, 1 deselected (93 tests réussis, 1 ignoré, 1 désélectionné).
  • L’environnement virtuel actif et un terminal dans le dossier du projet, observable-workflow.

Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont écrites, mais n’ont pas été exécutées. La leçon n’appelle aucun modèle : chaque décision rejoue un enregistrement du cours Agents d’IA et orchestration des flux de travail. Chaque coût correspond donc aux jetons enregistrés multipliés par les prix du cours.

À l’épicerie, le reçu contient une ligne par article : 2 kg de pommes à 3,00 $ US le kilogramme, soit 6,00 $ US. La liste de prix du magasin fixe le prix de chaque article, et le reçu indique la date. La semaine suivante, les pommes coûtent 3,50 $ US. Votre ancien reçu indique toujours 6,00 $ US, car il a conservé le prix du jour.

Imaginez maintenant un reçu qui indique seulement « 2 kg de pommes ». Pour savoir ce que vous avez payé, vous consulteriez la liste de prix actuelle et obtiendriez 7,00 $ US. Ce montant serait faux pour la semaine dernière.

Le problème : la trace connaît les jetons, pas l’argent

Section intitulée « Le problème : la trace connaît les jetons, pas l’argent »

Notre flux de travail connaît déjà le coût d’une exécution. Exécutez le billet du double remboursement dans votre projet, dans l’état du dernier module :

Fenêtre de terminal
python -m resolver run T-90104 --variant agent_structured --model chat-strong

Les deux premières lignes de sa sortie sont :

Run T-90104-agent_structured-chat-strong-1 | single agent with one JSON step per call (for models without tool calling) | chat-strong
Outcome: resolve (rule W2) | 2 model call(s), 1 tool call(s) | 4586 tokens in, 265 out | US$0.01182

Le code du cours sur les agents additionne le coût de chaque appel pour sa limite de dépenses. Il affiche 0.01182 $ US. Lisez maintenant la même exécution dans sa télémétrie avec python -m obs trace T-90104 :

Run T-90104-agent_structured-chat-strong-1 | ticket T-90104 | chat-strong (agent_structured) | release 2.0.0 | language en
2 model call(s), 1 read(s), 0 write call(s), 4586 tokens in, 265 out, US$0.00000
Trace 1 c58e3444eabc8d5e2d40fa7232c2a4fc … 6.6 s
0.0 s |========================| 6.56 s invoke_agent support-resolver resolve rule W2
0.0 s |========= | 2.39 s chat chat-strong 2160 in / 47 out - stop
2.4 s | = | 0.00 s execute_tool get_order ok LK-793996
2.4 s | ================| 4.17 s chat chat-strong 2426 in / 218 out - stop
6.6 s | =| 0.00 s approval.request needs agent

Les jetons sont là. L’argent n’y est pas : un tiret sur chaque span de modèle et 0.00000 $ US pour l’exécution. Le reçu indique seulement « 2 kg de pommes ».

Kwame est responsable de la plateforme et de sa facture. Lundi, il pose deux questions à Amira : « Combien mercredi a-t-il coûté? » et « Quelle étape d’une exécution coûte le plus cher? » Avec seulement les jetons, Amira doit trouver une liste de prix et faire une multiplication. Quelle liste? Celle de mercredi dernier ou celle d’aujourd’hui? Si elle prend celle d’aujourd’hui et qu’un prix a changé, le coût de la semaine dernière change après coup.

L’idée : multiplier les jetons par une table de prix datée et inscrire le coût sur le span

Section intitulée « L’idée : multiplier les jetons par une table de prix datée et inscrire le coût sur le span »

Une table de prix indique, pour chaque modèle, le prix d’un million de jetons d’entrée et d’un million de jetons de sortie. Les fournisseurs facturent ces deux types de jetons à des prix différents. Le coût d’un appel de modèle est :

coût = jetons d’entrée × prix d’entrée ÷ 1 000 000 + jetons de sortie × prix de sortie ÷ 1 000 000

La table a besoin d’une version, et la version la plus simple est sa date. Quand les prix changent, vous créez une nouvelle table avec une nouvelle date. Vous ne modifiez jamais l’ancienne.

Vous inscrivez ensuite deux attributs sur chaque span de modèle, comme le reçu indique le prix et la date :

  • larkfield.cost.usd : le coût de cet appel, en dollars américains.
  • larkfield.price_table : la version de la table qui a produit ce montant.

Le span racine de l’exécution reçoit la somme de ses appels, avec la même version. Un compteur, larkfield.run.cost, ajoute le coût de chaque exécution à la fermeture du billet. Les tableaux de bord et les alertes lisent ce compteur.

La table de prix du cours est celle utilisée pour les enregistrements du cours sur les agents, dans resolver/usage.py :

Modèle Entrée, $ US par million de jetons Sortie, $ US par million de jetons Note
chat-small 0,10 0,50 gpt-6-luna sur Azure
chat-strong 2,00 10,00 gpt-6.1-sol sur Azure
gemma3:4b 0 0 local, avec Ollama : une hypothèse

Sa version est 2026-10-08. Traitez chaque prix ici comme une hypothèse avec sa date. Les prix changent : consultez donc la page des prix actuels de votre fournisseur avant de les utiliser. Le prix de 0 pour le modèle local est aussi une hypothèse : il exclut l’ordinateur qui l’exécute.

L’exécution du double remboursement a fait deux appels à chat-strong. Voici son reçu, avec une ligne par appel :

Appel Jetons d’entrée × 2,00 $ US ÷ 1 million Jetons de sortie × 10,00 $ US ÷ 1 million Coût
étape 1 2 160 → 0,004320 $ US 47 → 0,000470 $ US 0,004790 $ US
étape 2 2 426 → 0,004852 $ US 218 → 0,002180 $ US 0,007032 $ US
l’exécution 4 586 265 0,011822 $ US

L’exécution a donc coûté 0.01182 $ US, le montant affiché par le code du cours sur les agents. Deux choses ressortent déjà. Un jeton de sortie coûte cinq fois plus qu’un jeton d’entrée, pour les deux modèles. Le deuxième appel a coûté plus cher que le premier, car il a rédigé la proposition et la réponse. Il a produit 218 jetons de sortie plutôt que 47.

Python donne les mêmes nombres avec la fonction du projet :

Fenêtre de terminal
python -c "from resolver.usage import cost_usd; print(cost_usd('chat-strong', 2160, 47), cost_usd('chat-strong', 2426, 218))"
0.00479 0.007032

Une cascade des coûts représente chaque étape par une barre qui commence à la fin de la précédente. Vous voyez ainsi le total augmenter. Voici l’exécution la plus coûteuse de la semaine rejouée, R-1016-040 : le billet T-80009 sur chat-strong, après le changement d’Omar.

Une cascade des coûts pour l'exécution R-1016-040, billet T-80009 sur chat-strong. Étape 1 : 2 163 jetons d'entrée et 48 de sortie, ajout de 0,00481 $ US. Puis get_order échoue avec invalid_arguments (arguments invalides) et coûte 0 $ US. Étape 2 : 2 253 en entrée, 48 en sortie, ajout de 0,00499 $ US. get_customer_orders, ok (réussite), 0 $ US. Étape 3 : 2 367 en entrée, 49 en sortie, ajout de 0,00522 $ US. get_order, ok, 0 $ US. Étape 4 : 2 681 en entrée, 181 en sortie, ajout de 0,00717 $ US. send_reply, ok, 0 $ US. Toute l'exécution : quatre appels de modèle, quatre appels d'outils, 0,02219 $ US.
Jetons rejoués × table de prix du cours (version 2026-10-08) : l'exécution la plus coûteuse de la semaine, étape par étape. Les appels d'outils ne coûtent aucun jeton; chaque appel de modèle renvoie toute la conversation.
Description textuelle du diagramme

Lisez de haut en bas. Chaque appel de modèle ajoute une barre après la précédente, et chaque appel d’outil n’ajoute rien. Les jetons d’entrée augmentent à chaque étape, de 2 163 à 2 681, car chaque appel envoie toute la conversation jusque-là. L’étape 4 est la plus coûteuse : le plus de jetons d’entrée, et la réponse en sortie. La première étape a rapporté peu : le modèle a demandé la commande LK-55190, avec un chiffre manquant. Le service de commandes l’a refusée. Les étapes 2 et 3 ont trouvé la vraie commande, LK-551906. L’exécution a coûté 0,02219 $ US.

Lisez la cascade comme une histoire de décisions. Le premier appel du modèle a demandé un numéro de commande avec un chiffre manquant. Les deux appels suivants ont payé pour corriger cela. Le coût d’une étape ne se limite pas à ses propres jetons. Il comprend aussi chaque étape précédente que l’appel renvoie.

Le changement du projet est petit. Dans resolver/observe.py, chaque span de modèle reçoit son coût et la version de la table dès le retour de l’appel. Le span de l’exécution reçoit la somme de l’exécution. Dans resolver/live.py, la fermeture du billet ajoute le coût de l’exécution au compteur larkfield.run.cost. Il utilise les mêmes étiquettes que le compteur d’exécutions.

  1. Copiez les fichiers de ce module depuis l’instantané end-of-m05 :

    Fenêtre de terminal
    S=../nextia-learning-labs/C31/snapshots/end-of-m05
    cp $S/resolver/observe.py $S/resolver/live.py resolver/
    cp $S/obs/__main__.py $S/obs/gateway.py obs/
    cp $S/tests/test_stage_m05.py $S/tests/test_obs_cli.py $S/tests/test_telemetry.py tests/
    cp $S/README.md .
  2. Exécutez les tests : python -m pytest -q. La dernière ligne indique 96 passed, 1 skipped, 1 deselected (96 tests réussis, 1 ignoré, 1 désélectionné). Votre projet correspond maintenant à l’instantané end-of-m05. Le nouveau test exécute un billet. Il vérifie que chaque span de modèle contient la version de la table et que les coûts totalisent celui de l’exécution.

  3. Ouvrez resolver/observe.py et cherchez PRICE_TABLE. Trouvez les deux endroits : le span de modèle et le span de l’exécution.

  4. Supprimez le dossier work, puis exécutez de nouveau le billet : python -m resolver run T-90104 --variant agent_structured --model chat-strong. Dans PowerShell, supprimez le dossier avec Remove-Item -Recurse work.

  5. Lisez sa trace : python -m obs trace T-90104. Chaque span de modèle affiche maintenant son coût :

    2 model call(s), 1 read(s), 0 write call(s), 4586 tokens in, 265 out, US$0.01182
    …
    0.0 s |========= | 2.39 s chat chat-strong 2160 in / 47 out US$0.00479 stop
    2.4 s | = | 0.00 s execute_tool get_order ok LK-793996
    2.4 s | ================| 4.17 s chat chat-strong 2426 in / 218 out US$0.00703 stop
  6. Lisez les deux attributs sur vos propres spans avec le lecteur du projet :

    Fenêtre de terminal
    python -c "from obs.model import Telemetry; r = next(iter(Telemetry('work/telemetry').runs.values())); print([(s.name, s.get('larkfield.cost.usd'), s.get('larkfield.price_table')) for s in r.model_spans])"
    [('chat chat-strong', 0.00479, '2026-10-08'), ('chat chat-strong', 0.007032, '2026-10-08')]
  7. Répartissez le coût de la semaine enregistrée par modèle et par étape : python -m obs cost --by step --data data/telemetry/week. Les lignes pour chat-strong sont :

    model step calls tokens in out cost US$
    chat-strong 1 40 86447 2108 0.1940
    chat-strong 2 39 95057 6391 0.2540
    chat-strong 3 8 20244 1250 0.0530
    chat-strong 4 2 5362 362 0.0143

La dernière commande lit chaque span de modèle des 316 exécutions et additionne les coûts par modèle et par étape. Voici la partie du modèle fort sous forme de graphique :

Jetons rejoués × table de prix du cours (version 2026-10-08) : le coût de chaque appel à chat-strong durant la semaine rejouée, selon l'étape de l'exécution qui l'a effectué.
Description textuelle du graphique

Quatre barres. Étape 1 : 40 appels, 0.1940 $ US. Étape 2 : 39 appels, 0.2540 $ US, la plus élevée. Étape 3 : 8 appels, 0.0530 $ US. Étape 4 : 2 appels, 0.0143 $ US. La plupart des exécutions se terminent après deux étapes; les étapes 1 et 2 concentrent donc la majorité du coût. Pour chat-small, les étapes 1 et 2 coûtent 0.0600 $ US et 0.0667 $ US, pour 260 et 225 appels.

La deuxième question de Kwame a donc une réponse. L’étape 2 est la plus coûteuse de la semaine, car la plupart des exécutions y rédigent leur proposition. Les étapes 1 et 2 de chat-strong coûtent ensemble 0,448 $ US. C’est plus que les 260 exécutions de chat-small (0,1513 $ US).

Vous pouvez convertir les jetons en argent à trois endroits. Chacun voit des données différentes.

Un flux de gauche à droite. Un appel de modèle avec 2 160 jetons d'entrée et 47 de sortie mène à « Dans l'application : jetons multipliés par la table de prix 2026-10-08, soit 0,00479 $ US sur le span ». De là partent deux flèches. L'une mène à « Le span conserve larkfield.cost.usd = 0.00479 et larkfield.price_table = 2026-10-08 », puis à « Le Collector pourrait multiplier ici, mais l'échantillonnage en fin de trace élimine 159 traces sur 434 » (cadre rouge pointillé), puis à « Au moment de la requête, multiplier les jetons par les prix actuels change les nombres de la semaine dernière » (cadre rouge pointillé). L'autre flèche mène à « La métrique larkfield.run.cost compte chaque exécution, échantillonnée ou non », puis aussi au cadre de la requête.
Trois endroits où calculer le coût. Le cours le calcule dans l'application et conserve la version de la table sur le span; le Collector et la requête lisent le résultat.
Description textuelle du diagramme

Au moment de l’appel, l’application connaît le modèle, les jetons et la table de prix. Elle inscrit donc le coût sur le span et l’ajoute à un compteur. Le Collector pourrait aussi multiplier, mais son échantillonnage en fin de trace ne conserve que certaines traces. Une somme sur les traces échantillonnées omet de l’argent. Une requête à la lecture peut aussi multiplier les jetons par les prix. Mais avec les prix actuels, elle change les nombres de la semaine dernière.

Dans l’application (le choix du cours). Le code connaît le modèle qui a répondu, les jetons exacts et la table en vigueur. Il peut aussi gérer un cas particulier. Le flux de travail peut appeler la passerelle du cours Gouverner les agents d’IA : passerelles, registres et contrôles. Il peut demander une capacité comme strong-reasoning (raisonnement avancé). L’application n’a pas de prix pour ce nom. Elle calcule donc le coût du modèle nommé par la passerelle dans son en-tête de réponse, et inscrit larkfield.priced_as. Le coût : chaque application a besoin de la table, et un nouveau prix exige une nouvelle mise en production.

Dans le Collector. Un processeur transform (transformation) pourrait multiplier deux attributs par un prix dans la configuration du Collector. Une seule table sert toutes les applications. Mais le Collector ne voit que ce que disent les spans : un nom de capacité, aucun en-tête de réponse, aucun prix. Regardez aussi le Collector du module 2 : son échantillonnage en fin de trace a conservé 275 traces sur 434. Le coût additionné à partir des traces arrivées dans Tempo omettrait celles éliminées. Si vous le calculez dans le Collector, faites-le avant l’échantillonnage et lisez les totaux dans les métriques.

Au moment de la requête. Grafana peut multiplier les compteurs de jetons par les prix dans PromQL. Cela se modifie rapidement et n’exige aucune mise en production. Mais la requête utilise les prix qu’elle connaît aujourd’hui pour chaque semaine qu’elle lit.

Essayez un changement inventé pour comprendre pourquoi. Supposons que les prix de chat-strong baissent de moitié le mois prochain. Ce changement est construit pour l’exemple : il n’a pas eu lieu.

  • Avec une requête à la lecture, le coût de chat-strong de mercredi dernier passe de 0,1409 $ US à environ 0,0705 $ US. Le total de mercredi baisse de 0,1638 $ US à environ 0,0934 $ US. Personne n’a dépensé moins : le rapport a changé.
  • Avec le coût sur le span, mercredi reste à 0,1638 $ US, et chaque span indique larkfield.price_table = 2026-10-08. Pour comparer, vous recalculez volontairement la semaine avec la nouvelle table. Vous l’étiquetez : « la même semaine aux nouveaux prix ».

La version explique aussi une différence. Si deux rapports divergent, vérifiez d’abord leurs tables. Au module 8, Langfuse reçoit les mêmes spans et ne calcule aucun coût : il ne connaît pas les noms chat-small et gpt-6-luna. Un outil a besoin de ses propres définitions de prix. Notre table est la nôtre, avec sa date.

Calculez le coût dans l’application quand elle appelle les modèles directement et connaît les jetons : c’est le cas de la plupart des agents. Utilisez les enregistrements de la passerelle comme deuxième compte indépendant, comme dans la prochaine leçon. Ne calculez pas le coût à partir des seules traces échantillonnées.

Le coût est faible. Deux attributs sur chaque span de modèle, un sur le span de l’exécution, un compteur. Les données de trace augmentent de quelques octets par span. Le vrai travail concerne la table : quelqu’un doit en être responsable et vérifier les prix du fournisseur. Cette personne doit créer une nouvelle version quand ils changent. Chez Larkfield, c’est Kwame.

Erreur courante

Le coût affiche un tiret, ou le total est trop bas

Symptôme : obs trace affiche - (tiret) plutôt qu’un coût sur un span de modèle. obs cost donne un total inférieur à la facture du fournisseur.

Cause : la table de prix n’a aucun prix pour le nom du modèle. La fonction renvoie volontairement None (aucune valeur), et non 0 : un prix inconnu ne signifie pas un appel gratuit. Les noms qui causent habituellement ce problème sont un nouveau modèle, un nom de déploiement plutôt qu’un nom de modèle, ou une capacité de passerelle :

Fenêtre de terminal
python -c "from resolver.usage import cost_usd; print(cost_usd('strong-reasoning', 2160, 47))"
None

Diagnostic : listez les noms de modèles sur les spans avec un tiret : python -m obs runs affiche le modèle de chaque exécution. Comparez-les aux noms dans resolver/usage.py.

Correction : ajoutez le modèle à la table et donnez-lui une nouvelle version pour que les nouveaux montants indiquent leur origine. Pour une capacité de passerelle, calculez le coût du modèle nommé par la passerelle dans sa réponse, comme le fait le projet. Ne remplacez jamais un prix manquant par 0.

L’étape 4 de la cascade compte 2 681 jetons d’entrée et 181 jetons de sortie, sur chat-strong.

  1. Calculez son coût à la main avec la table. Vérifiez ensuite avec cost_usd('chat-strong', 2681, 181).
  2. Prédisez le coût des mêmes jetons sur chat-small. C’est un scénario hypothétique : le petit modèle lirait et écrirait d’autres jetons.
  3. Exécutez python -m obs trace R-1016-040 --data data/telemetry/week et comparez votre étape 4 à la trace.

La réponse se trouve dans la première vérification des connaissances.

Vérifiez votre compréhension

À vous : combien coûte l'étape 4 de R-1016-040 (2 681 jetons d'entrée, 181 de sortie, chat-strong)? Et sur chat-small?

Afficher la réponse

Sur chat-strong : 2 681 × 2,00 $ US ÷ 1 000 000 = 0,005362 $ US, plus 181 × 10,00 $ US ÷ 1 000 000 = 0,001810 $ US, soit 0,007172 $ US. La trace indique 0,00717 $ US. Sur chat-small, les mêmes jetons coûtent 2 681 × 0,10 $ US ÷ 1 million = 0,000268 $ US, plus 181 × 0,50 $ US ÷ 1 million = 0,000091 $ US, soit environ 0,00036 $ US : 20 fois moins. C’est un scénario hypothétique avec les mêmes jetons, basé sur une hypothèse datée selon la table. Une vraie exécution sur chat-small lit et écrit d’autres jetons, et elle ne résout pas nécessairement le billet.

Vérifiez votre compréhension

Tomás dit : « Gardez seulement les jetons. On peut multiplier par les prix dans Grafana quand on veut connaître le coût. » Quel problème cela pose-t-il? Que fait le cours à la place?

Afficher la réponse

Une requête utilise les prix qu’elle connaît au moment de son exécution. Quand un prix change, toutes les semaines passées changent aussi, même si personne n’a dépensé moins ou plus. La requête a aussi besoin d’un prix pour chaque nom de modèle, y compris les noms de capacités qu’elle ne peut pas connaître. Le cours calcule le coût dans l’application, au moment de l’appel. Il inscrit le coût et la version de la table (larkfield.price_table = 2026-10-08) dans chaque span de modèle. Il ajoute aussi le coût de l’exécution à un compteur. Un nouveau prix signifie une nouvelle table avec une nouvelle version. Pour comparer les prix, recalculez volontairement la semaine et indiquez qu’il s’agit d’un nouveau calcul.

Vérifiez votre compréhension

Dans R-1016-040, chaque étape coûte plus que la précédente, même si le modèle écrit presque la même courte réponse aux étapes 1 à 3. Pourquoi? Et pourquoi est-ce une erreur d'additionner les coûts des traces conservées par le Collector?

Afficher la réponse

Chaque appel de modèle envoie toute la conversation jusqu’à ce point : les instructions, le billet et chaque résultat d’outil précédent. Les jetons d’entrée augmentent donc à chaque étape, de 2 163 à 2 681, et le coût augmente avec eux. Vous payez de nouveau une étape inutile à chaque appel suivant. L’échantillonnage en fin de trace du Collector ne conserve que certaines traces : 275 sur 434 dans l’exécution du module 2. La somme des traces conservées exclut le coût des exécutions écartées. Lisez les totaux dans le compteur larkfield.run.cost, qui compte chaque exécution, et utilisez les traces pour expliquer une exécution.

Récapitulatif

  • Le coût d’un appel correspond aux jetons d’entrée × prix d’entrée plus les jetons de sortie × prix de sortie, par million de jetons. Pour nos modèles, un jeton de sortie coûte cinq fois plus qu’un jeton d’entrée.
  • La table de prix a une version : sa date. Chaque span de modèle contient larkfield.cost.usd et larkfield.price_table; le span d’exécution contient la somme; le compteur larkfield.run.cost ajoute chaque exécution.
  • Chaque prix présenté ici est une hypothèse datée. Les prix changent : consultez la page de votre fournisseur. Un modèle inconnu n’a pas de prix, jamais un prix de 0.
  • Un graphique en cascade des coûts montre comment le coût d’une exécution augmente à chaque étape. Chaque appel renvoie la conversation, donc vous payez de nouveau une étape inutile dans les appels suivants.
  • Calculez le coût dans l’application, avant tout échantillonnage; lisez les totaux dans le compteur, pas dans les traces échantillonnées.
  • Votre projet correspond maintenant à l’instantané end-of-m05 : 96 tests réussissent.

Vous pouvez maintenant dire combien coûtent chaque exécution et chaque étape. Mais la facture de Kwame est par équipe. La question d’Omar porte sur le coût par billet résolu, pas par appel. Ensuite, vous répartirez le coût par modèle, par segment et par client sans faire exploser le nombre de métriques. Vous comparerez aussi vos totaux à ceux de la passerelle.

Leçon suivante : Coût par client, par agent, par locataire et par modèle