Aller au contenu
English

Budgets, alertes et l'exécution coûteuse

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

Où nous en sommes

Dans les deux dernières leçons, nous avons attribué un coût à chaque exécution. Nous avons réparti le coût de la semaine par modèle, par segment et par étape. Nous savons pourquoi il a augmenté. Mais un rapport le lundi n'arrête pas une exécution qui dépense trop le dimanche. Dans cette leçon, nous définissons un budget et une alerte qui indique les exécutions responsables d'une hausse. Nous ajoutons aussi la limite dans le code qui arrête réellement les dépenses. Commençons par l'électricité à la maison.

Leçon 18 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditBudgets, alertes et l'exécution coûteuse
Aperçu du cours

Ce que vous saurez faire

Fixez un budget pour le coût du flux de travail. Recevez une alerte qui indique les exécutions responsables d’une hausse. Ajoutez ensuite une limite dans le code pour empêcher une exécution de trop dépenser. Aucun tableau de bord ne peut le faire.

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 laissé par la dernière leçon (l’instantané end-of-m05, 96 tests réussis), avec l’environnement virtuel actif.

Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont fournies, mais n’ont pas été exécutées. Les chiffres de Grafana proviennent de la semaine rejouée par l’équipe du cours à 1 000 fois sa vitesse réelle.

À la maison, trois choses servent à gérer le coût de l’électricité. La facture arrive chaque mois et indique vos dépenses. Un compteur intelligent peut envoyer un message : « Vous avez consommé 40 % de plus que d’habitude cette semaine. » Les deux vous informent après coup, et le courant continue de passer. Seul le fusible agit : quand le courant est trop élevé, il le coupe immédiatement, sans demander à personne.

Un bon message indique aussi où chercher : « le chauffe-eau, depuis mardi ». Sans cette indication, vous devez faire le tour de la maison et éteindre les appareils un par un.

Le problème : un rapport arrive trop tard, et une alerte sans exécutions en dit trop peu

Section intitulée « Le problème : un rapport arrive trop tard, et une alerte sans exécutions en dit trop peu »

Le rapport de coûts de Larkfield est le tableau de obs cost --by day, lu le lundi :

day runs resolved cost US$ per run per resolved success
Mon 12 52 33 0.0322 0.00062 0.00098 63.5%
Tue 13 52 36 0.0303 0.00058 0.00084 69.2%
Wed 14 52 33 0.1638 0.00315 0.00497 63.5%
Thu 15 52 38 0.1614 0.00310 0.00425 73.1%
Fri 16 52 35 0.1726 0.00332 0.00493 67.3%
Sat 17 28 12 0.0477 0.00170 0.00397 42.9%
Sun 18 28 16 0.0587 0.00210 0.00367 57.1%

Le coût par billet résolu a bondi le mercredi et est resté élevé. Une personne qui lit ce rapport le lundi l’apprend cinq jours trop tard. C’est la facture.

Une alerte est plus rapide. Mais si elle dit seulement « le coût est élevé », il faut chercher : quel modèle, quelle version, quelles exécutions? Ni la facture ni l’alerte n’arrête quoi que ce soit. Le mercredi après-midi, une exécution qui boucle sur un modèle payant continue ses appels jusqu’à ce que le code l’arrête.

L’idée : un budget, une alerte avec ses exécutions et une limite dans le code

Section intitulée « L’idée : un budget, une alerte avec ses exécutions et une limite dans le code »

Un budget est un montant que vous décidez de dépenser pour une unité de travail. Omar en a fixé un pour le flux de travail : 0,002 $ US par billet résolu. C’est une hypothèse, sa décision, pas un fait tiré des données. Un budget par billet résolu suit à la fois la qualité et le coût. Des coûts plus élevés pour les mêmes résultats le dépassent. Moins de résultats pour le même coût le dépassent aussi.

Une alerte de budget vérifie le budget sur une fenêtre, une portion du travail récent. La nôtre couvre les 45 dernières exécutions fermées, soit une journée chez Larkfield. Elle se déclenche quand le coût par billet résolu de la fenêtre dépasse le budget. Elle attend 20 exécutions pour que les premières exécutions d’une journée ne puissent pas la déclencher seules. L’alerte indique aussi les exécutions les plus coûteuses de sa fenêtre. Le premier clic mène donc à une trace, pas à une recherche.

Une limite est le fusible. Elle se trouve dans le code qui dépense l’argent et agit avant l’appel suivant. Le flux de travail en possède une par exécution, vue dans le cours sur les agents : RESOLVER_MAX_COST_USD, soit 0,05 $ US par défaut.

Voici le moment où le budget a été dépassé. Après la 120e exécution fermée de la semaine, la fenêtre contenait 45 exécutions. Elles comptaient 31 billets résolus et un coût de 0,06698 $ US.

0,06698 $ US ÷ 31 billets résolus = 0,00216 $ US par billet résolu, au-dessus du budget de 0,002 $ US.

Trois de ces 45 exécutions utilisaient chat-strong. C’étaient les premiers billets difficiles après le changement à 9 h. Ensemble, elles coûtaient 0,04225 $ US : 63 % des dépenses de la fenêtre pour 3 de ses 45 exécutions. Les 42 autres exécutions coûtaient 0,02473 $ US.

  • la semaine rejouée
  • la semaine sans problème
  • budget de 0,002 $ US
Jetons rejoués × grille tarifaire du cours (version 2026-10-08), trafic construit. Chaque point représente la fenêtre après la fermeture d'une exécution (à partir de la 20e). Le budget de 0,002 $ US est une hypothèse : celle d'Omar.
Description textuelle du graphique

Deux courbes couvrent les 316 exécutions fermées de chaque semaine. Une ligne pointillée marque le budget de 0,002 $ US. La semaine sans problème utilise les mêmes billets, uniquement avec chat-small. Elle reste entre 0,00076 $ US et 0.00117 $ US : toujours sous le budget. La semaine rejouée est identique jusqu’au mercredi matin. À l’exécution fermée 120 (mercredi à 10:39), elle dépasse le budget à 0.00216 $ US. Elle reste au-dessus jusqu’à la fin de la semaine, avec un sommet de 0.00642 $ US.

La semaine sans problème ne franchit jamais la ligne : l’alerte resterait silencieuse, comme il se doit. La semaine rejouée la franchit 1 h 39 après le changement et ne redescend jamais en dessous.

  1. Demandez à obs quand la semaine a dépassé le budget, et pourquoi :

    Fenêtre de terminal
    python -m obs cost --budget 0.002 --data data/telemetry/week
    Budget: US$0.002 per resolved ticket over the last 45 closed runs (from 20 runs on)
    Over budget at Wed 14 Oct 10:39 (closed run 120, R-1014-016): US$0.00216 per resolved ticket (31 resolved, US$0.06698)
    The 5 runs that cost most in that window (67% of its cost):
    run ticket started outcome model tools appr cost US$ secs model flags
    R-1014-009 T-90201 Wed 09:15 resolved 3 2 1 0.01844 9.1 chat-strong -
    R-1014-016 T-80005 Wed 10:39 resolved 2 1 0 0.01197 6.3 chat-strong -
    R-1014-011 T-90203 Wed 09:29 resolved 2 1 1 0.01184 6.5 chat-strong -
    R-1014-004 T-65001 Wed 04:17 resolved 4 2 0 0.00124 6.8 chat-small -
    R-1014-010 T-65001 Wed 09:25 resolved 4 2 0 0.00124 6.8 chat-small -

    Les trois premières lignes donnent la réponse : trois exécutions sur chat-strong après 9 h. Les deux exécutions sur chat-small en dessous coûtent dix fois moins.

  2. Ouvrez la plus coûteuse : python -m obs trace R-1014-009 --data data/telemetry/week. C’est un billet difficile avec deux numéros de commande. Il compte trois appels de modèle, 0,01844 $ US et un remboursement approuvé par Sam après 9 minutes.

  3. Vérifiez la même règle sur la semaine sans problème :

    Fenêtre de terminal
    python -m obs cost --budget 0.002 --data data/telemetry/healthy-week
    Budget: US$0.002 per resolved ticket over the last 45 closed runs (from 20 runs on)
    Never over budget.
  4. Listez toutes les exécutions liées à cette cause ce jour-là : python -m obs runs --day wed --model chat-strong --data data/telemetry/week. La commande montre 11 exécutions, de 0,01148 $ US à 0,01844 $ US. Deux portent l’indicateur duplicate_write (écriture en double) : les remboursements en double du module 4, sur le même modèle.

Dans Grafana, la même règle est une requête sur les deux compteurs. Le module 7 la transforme en fichier de règle d’alerte :

sum(increase(larkfield_run_cost_total[90s])) / sum(increase(larkfield_runs_total{larkfield_outcome="resolved"}[90s])) > 0.002

L’équipe du cours a exécuté la semaine dans Grafana à 1 000 fois sa vitesse réelle. Cette alerte s’est déclenchée le mercredi à 16 h 41 dans le temps de l’exercice, plus tard que l’indique obs. La fenêtre de Grafana couvre 90 secondes de la relecture accélérée, soit environ une journée de l’exercice. Grafana vérifie la règle toutes les 10 secondes, soit environ toutes les 2,8 heures de l’exercice. Une relecture accélérée manque donc de précision; les exécutions enregistrées donnent le moment exact.

Pour que l’alerte Grafana indique ses exécutions, ajoutez un lien vers Tempo dans son message. Utilisez la requête TraceQL pour les exécutions coûteuses dans la fiche du cours, grafana/traceql.md :

{ span.gen_ai.operation.name =~ "invoke_agent|invoke_workflow" && span.larkfield.cost.usd > 0.01 }

Dans la même exécution de Grafana, cette requête a trouvé 23 exécutions de plus de 1 cent. La semaine enregistrée compte 39 exécutions de ce type, toutes sur chat-strong. Tempo ne contient que les traces conservées par l’échantillonnage en fin de trace du Collector. Utilisez donc le lien pour trouver des exemples, et obs cost ou le compteur pour obtenir les totaux. Une personne qui ouvre l’alerte voit la cause en un clic.

Regardez encore l’ordre des événements. Le modèle répond, le fournisseur compte les jetons, et l’argent est dépensé. Ensuite, le span (une unité de travail enregistrée) le consigne et le compteur l’ajoute. Quelques exécutions plus tard, l’alerte informe une personne. Chaque élément de télémétrie arrive après la dépense. Il peut vous informer rapidement, avec des preuves, mais il ne peut pas arrêter un appel.

Un flux part du haut. Le prochain appel de modèle arrive à une première question dans le code de l'exécution : le coût cumulé dépasse-t-il RESOLVER_MAX_COST_USD? Oui : arrêter l'exécution, motif d'arrêt cost, la confier à une personne (boîte verte). Non : une deuxième question à la passerelle : les dépenses mensuelles de l'agent dépassent-elles budget_usd_month? Oui : refuser l'appel, HTTP 429 budget_exhausted (boîte verte). Non : le fournisseur répond et l'argent est dépensé. Ensuite, dans des boîtes orange en pointillés : la télémétrie le consigne (span, métrique, coût). Une alerte de budget informe une personne et indique les exécutions responsables. Une flèche pointillée : une personne décide plus tard de changer le modèle, la requête ou la limite.
Ce qui arrête les dépenses et ce qui les rapporte seulement : les limites agissent avant un appel (vert). La télémétrie et les alertes agissent après la dépense (orange, pointillés).
Description textuelle du diagramme

Deux vérifications précèdent l’appel au fournisseur. Dans le code de l’exécution, la limite du cours sur les agents arrête une exécution dont le coût cumulé dépasse RESOLVER_MAX_COST_USD. Le billet est confié à une personne. À la passerelle du cours sur la gouvernance des agents, chaque agent enregistré possède un budget mensuel. Quand ce budget est dépensé, la passerelle refuse l’appel avec HTTP 429 budget_exhausted. Si aucune vérification n’arrête l’appel, le fournisseur répond et l’argent est dépensé. La télémétrie le consigne seulement ensuite. Une alerte de budget informe une personne, qui décide plus tard.

Notre système possède deux fusibles. La limite d’exécution se trouve dans resolver/loop.py. Avant chaque appel de modèle, elle compare le coût cumulé de l’exécution à RESOLVER_MAX_COST_USD. La limite de la passerelle se trouve dans l’enregistrement de support-workflow : budget_usd_month: 25. La passerelle refuse tout appel une fois ce budget dépensé. Dès 80 % du budget, elle ajoute un en-tête d’avertissement à ses réponses. Votre compte chez le fournisseur peut aussi avoir sa propre limite de dépenses; vérifiez ses paramètres.

L’exécution la plus coûteuse de la semaine, T-80009 sur chat-strong, a fait quatre appels pour 0,02219 $ US. Exécutez-la de nouveau avec une limite de 0,01 $ US :

  1. Supprimez le dossier work. Exécutez ensuite le billet une fois sans limite, pour comparer :

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

    La deuxième ligne se termine par 4 model call(s), 3 tool call(s) | 9464 tokens in, 326 out | US$0.02219 (4 appels de modèle, 3 appels d’outils, 9 464 jetons en entrée, 326 en sortie, coût de 0,02219 $ US).

  2. Exécutez-le avec la limite :

    Fenêtre de terminal
    RESOLVER_MAX_COST_USD=0.01 python -m resolver run T-80009 --variant agent_structured --model chat-strong
    Run T-80009-agent_structured-chat-strong-2 | single agent with one JSON step per call (for models without tool calling) | chat-strong
    Stopped: cost. No proposal: the ticket goes to a person.
  3. Lisez l’exécution arrêtée : python -m obs trace T-80009-agent_structured-chat-strong-2.

    3 model call(s), 3 read(s), 0 write call(s), 6783 tokens in, 145 out, US$0.01502
    …
    0.0 s |========================| 5.60 s invoke_agent support-resolver cost
    0.0 s |========== | 2.35 s chat chat-strong 2163 in / 48 out US$0.00481 stop
    2.4 s | = | 0.00 s execute_tool get_order ERROR invalid_arguments LK-55190
    2.4 s | ======= | 1.66 s chat chat-strong 2253 in / 48 out US$0.00499 stop
    4.0 s | = | 0.00 s execute_tool get_customer_orders ok
    4.0 s | =======| 1.59 s chat chat-strong 2367 in / 49 out US$0.00522 stop
    5.6 s | =| 0.00 s execute_tool get_order ok LK-551906
    Outcome: handed_to_person | stopped: cost
  4. Comparez les deux exécutions : python -m obs cost --by outcome.

    outcome runs resolved cost US$ per run per resolved success
    handed_to_person 1 0 0.0150 0.01502 - 0.0%
    resolved 1 1 0.0222 0.02219 0.02219 100.0%
    total 2 1 0.0372 0.01860 0.03720 50.0%

Le fusible a fonctionné : le quatrième appel n’a jamais eu lieu. Mais lisez les chiffres. L’exécution a dépensé 0,01502 $ US avec une limite de 0,01 $ US. Après deux appels, elle avait dépensé 0,00979 $ US, sous la limite. Elle a donc fait un troisième appel. La vérification précède l’appel et ne peut pas savoir combien il coûtera.

Et l’exécution arrêtée n’a rien obtenu. Elle a coûté les deux tiers d’une exécution complète, sans résoudre de billet, et a confié le billet à une personne. En l’incluant, le coût par billet résolu de ces deux exécutions est de 0,03720 $ US plutôt que 0,02219 $ US. Une limite trop basse augmente le coût par billet résolu au lieu de le réduire.

La limite d’une exécution vise les exécutions incontrôlées, pas les billets difficiles ordinaires. Fixez-la à partir de vos propres exécutions. Dans la semaine rejouée, l’exécution la plus coûteuse a coûté 0,02219 $ US. La valeur par défaut de 0,05 $ US laisse donc plus du double de ce montant avant un arrêt. Une boucle sur un modèle payant l’atteint en quelques appels, puis s’arrête. Les trois boucles de la semaine utilisaient le modèle local, au prix de 0. Cette limite monétaire ne les aurait pas détectées. Voilà pourquoi les limites d’étapes et de temps du cours sur les agents comptent aussi.

Utilisez l’alerte de budget pour la tendance quotidienne et la limite d’exécution pour une exécution incontrôlée. Utilisez le budget mensuel de la passerelle pour l’agent entier. Chaque mesure a un coût. Une alerte exige qu’une personne agisse. Une limite arrête certaines exécutions qui auraient réussi. Un budget de passerelle peut arrêter toute une équipe le dernier jour du mois.

Erreur courante

L'exécution a dépensé plus que sa limite

Symptôme : avec RESOLVER_MAX_COST_USD=0.01, une exécution se termine par Stopped: cost (arrêtée pour cause de coût). Mais obs trace montre 0,01502 $ US.

Cause : la limite est vérifiée avant chaque appel de modèle, par rapport au coût cumulé. L’exécution était sous la limite après deux appels (0,00979 $ US). Le troisième appel a donc été envoyé et l’a fait dépasser. Une limite ne peut pas refuser un appel dont elle ne connaît pas encore le coût.

Diagnostic : lisez la trace. Le dernier appel de modèle avant l’arrêt est celui qui a franchi la limite. Son coût est le dépassement.

Correction : traitez la limite comme « le maximum qu’une exécution peut dépenser, moins un appel ». Pour chat-strong, un appel de la semaine a coûté jusqu’à 0,00816 $ US. Ou estimez le prochain appel avant de l’envoyer. Il envoie au moins les jetons d’entrée du dernier appel. Son coût est donc au moins égal à ces jetons multipliés par le prix d’entrée.

À vous de jouer : trouver ce qui a fait augmenter le coût de la semaine dernière

Section intitulée « À vous de jouer : trouver ce qui a fait augmenter le coût de la semaine dernière »

Kwame vous demande le lundi : « La semaine dernière a coûté plus de trois fois la semaine sans problème. Pourquoi? » Répondez avec des commandes, pas des suppositions, et notez le sens de chaque sortie.

  1. Comparez les deux semaines : python -m obs cost --by model --data data/telemetry/healthy-week, puis la même commande pour data/telemetry/week.
  2. Trouvez quand la hausse a commencé : --by day, puis --by release.
  3. Trouvez qui a dépensé : --by design --day wed, puis python -m obs runs --day wed --model chat-strong --data data/telemetry/week.
  4. Départagez les deux causes : plus de billets, ou des billets plus coûteux.

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

Vérifiez votre compréhension

À vous de jouer : pourquoi le coût a-t-il augmenté la semaine dernière? Donnez les chiffres qui le prouvent.

Afficher la réponse

Ce n’est pas le nombre de billets : les deux semaines comptaient 316 exécutions, 52 chaque jour de semaine, et 203 billets résolus. La semaine normale a coûté 0,1850 $ US (0,00091 $ US par billet résolu). La semaine rejouée a coûté 0,6667 $ US (0,00328 $ US), soit 3,6 fois plus. Par jour, la hausse commence mercredi (0,00497 $ US par billet résolu, contre 0,00084 $ US mardi). Par version, elle commence avec 2.1.0 mercredi à 9 h 00 (0,00476 $ US) et continue avec 2.1.1 (0,00426 $ US), contre 2.0.0 (0,00094 $ US). Mercredi, les 11 exécutions agent_structured sur chat-strong ont coûté 0,1409 $ US sur les 0,1638 $ US de la journée. La cause est donc le changement d’Omar : les billets difficiles utilisent maintenant un modèle dont les jetons coûtent 20 fois plus.

Vérifiez votre compréhension

Tomás dit : « Nous avons maintenant l'alerte de budget, donc nous ne pouvons pas dépasser le budget. » Pourquoi est-ce faux, et qu'est-ce qui arrête les dépenses?

Afficher la réponse

Une alerte arrive après la dépense. Le fournisseur répond, le span (segment de trace) enregistre le coût, puis l’alerte lit le compteur quelques exécutions plus tard. Elle avertit une personne et lui montre les exécutions concernées, mais cette personne décide ensuite. Une limite dans le code qui fait l’appel arrête les dépenses, avant l’appel. La première est la limite de l’exécution, RESOLVER_MAX_COST_USD, vérifiée avant chaque appel de modèle : T-80009 s’est arrêtée après trois appels. L’autre est le budget mensuel de la passerelle par agent, budget_usd_month: 25, suivi d’une réponse HTTP 429. Même la limite de l’exécution est dépassée d’un appel : 0,01502 $ US contre 0,01 $ US.

Vérifiez votre compréhension

Vérification de fin de module : Omar demande s'il doit garder chat-strong pour les billets difficiles ou annuler ce changement. Recommandez une option, avec les coûts et les preuves de réussite des jours de semaine avant et après le changement.

Afficher la réponse

Une bonne réponse compare les coûts et les résultats, et précise ses hypothèses. Coût : le coût par billet résolu est passé de 0,00094 $ US à 0,00478 $ US (5,1 fois plus). Il dépasse le budget d’Omar de 0,002 $ US depuis mercredi à 10 h 39. La hausse vient entièrement des billets difficiles : 0,00080 $ US par billet difficile résolu sur chat-small avant, contre 0,01333 $ US sur chat-strong après. Les autres billets n’ont pas changé. Résultats : pour les billets difficiles, le résultat correct selon les étiquettes du cours est passé de 18 exécutions sur 26 (69,2 %) à 31 sur 33 (93,9 %). Le taux de résolution est passé de 73,1 % à 97,0 %. Pour toutes les exécutions des jours de semaine, le taux de résultats corrects est passé de 84,8 % à 90,5 %. Cela correspond aux enregistrements : chat-small a réussi 11 tâches difficiles sur 15, et chat-strong, 15 sur 15. Le prix du gain : un billet difficile coûte 0,01234 $ US de plus par exécution pour 24,7 points de plus de réponses correctes. Cela représente environ 0,05 $ US par réponse correcte supplémentaire. Recommandation : gardez le changement. Une mauvaise réponse concernant une livraison en retard coûte plus de 5 cents en temps humain. Il peut s’agir d’un remboursement ou d’une réexpédition accordés ou refusés à tort. Mais changez le budget, pas le modèle : les 0,002 $ US étaient prévus pour un ensemble de billets traité par chat-small. Donnez aux billets difficiles leur propre budget, environ 0,015 $ US par billet résolu. Gardez 0,002 $ US pour les autres, et créez une alerte pour chaque budget. Annulez le changement seulement si le montant est une limite fixe. Attendez-vous alors à environ 25 mauvaises réponses de plus pour 100 billets difficiles. Limites : le trafic de la semaine est construit, les étiquettes remplacent un réviseur, et les prix sont des hypothèses datées.

Récapitulatif

  • Un budget est une décision : les 0,002 $ US d’Omar par billet résolu sont une hypothèse. Un budget par billet résolu suit les coûts et les résultats ensemble.
  • Une alerte de budget vérifie une fenêtre (les 45 dernières exécutions terminées, après 20 exécutions). Elle indique les exécutions les plus coûteuses de cette fenêtre. Le budget a été dépassé mercredi à 10 h 39, à l’exécution 120, avec 0,00216 $ US. Trois exécutions chat-strong représentaient 63 % du coût de la fenêtre. La semaine normale est restée sous le budget.
  • Dans Grafana, la même règle est un rapport PromQL entre deux compteurs. Un lien TraceQL mène aux exécutions coûteuses.
  • L’observabilité rapporte les dépenses après coup. Les limites dans le code les arrêtent avant un appel : RESOLVER_MAX_COST_USD pour l’exécution et le budget mensuel de la passerelle. Une limite est dépassée d’un appel, et une exécution arrêtée ne résout rien.
  • Le changement d’Omar coûte environ 5 cents par réponse correcte supplémentaire sur un billet difficile. Gardez-le, et donnez aux billets difficiles leur propre budget.

Vous pouvez maintenant expliquer le coût du flux de travail, ses causes et ce qui l’empêche de trop dépenser. Mais le coût n’est qu’une des questions de Grace et des auditeurs. « Qui a approuvé le deuxième remboursement de T-90104, et sur quelles preuves? » en est une autre. Une trace qui peut être échantillonnée ne peut pas y répondre. Ensuite, dans le module 6, vous verrez pourquoi une piste d’audit n’est pas un journal.

Leçon suivante : Une piste d'audit n'est pas un journal