Aller au contenu
English

Quotas, budgets et limites de débit

  • Leçon 11
  • 40 min
  • Module 4 : La passerelle de modèles

Où nous en sommes

Dans la dernière leçon, nous avons fait passer chaque appel de modèle par une seule porte. Elle vérifie l'appelant et consigne le coût. Mais un enregistrement montre le coût seulement après la dépense. Un agent qui appelle un modèle en boucle continue jusqu'à ce que quelqu'un lise les enregistrements. Dans cette leçon, nous ajoutons les limites qui l'arrêtent. Nous rejouons un agent emballé pour voir où chaque limite l'arrête et combien il a dépensé jusque-là. Nous commençons avec la carte bancaire d'une famille.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Arrêtez un agent qui appelle un modèle sans cesse, avant qu’il coûte trop cher. Vous fixez des limites par agent, par exécution et par équipe. Un avertissement précède l’arrêt obligatoire, et la réponse indique à l’agent quoi faire.

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

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet tel que la dernière leçon l’a laissé (137 tests réussissent), avec le parc en marche : python -m estate up.
  • Un terminal suffit.

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.

Une famille partage un compte bancaire, et chaque personne a une carte. La banque n’attend pas le relevé mensuel pour protéger le compte. Chaque carte a une limite quotidienne au guichet automatique. Ainsi, une carte volée ne peut pas vider le compte en une journée. Le compte a un budget mensuel, et la banque envoie un message texte quand 80 % de ce budget est dépensé. Après quelques NIP incorrects en peu de temps, la carte cesse de fonctionner pendant un moment.

Chaque limite empêche un accident différent, à une vitesse différente. Le message texte est un avertissement : la carte fonctionne encore. Les limites imposent des arrêts obligatoires : la carte ne fonctionne plus jusqu’au lendemain, au mois suivant ou à la minute suivante.

Les agents tournent en boucle. Le cours Agents d’IA et orchestration des flux de travail en a enregistré une. Le petit modèle local gemma3:4b appelait sans cesse le même outil pour le billet de soutien T-64872. Son exécution a produit 4 appels de modèle, 9,209 jetons en entrée et 334 en sortie, en 13.5 secondes. Puis le propre garde-fou du flux de travail, repeated_call (appel répété), l’a arrêté. Sur un modèle local, la boucle ne coûtait rien. Les mêmes jetons sur strong-reasoning coûteraient 0.022 $ US.

Cette boucle était courte parce que l’application avait un garde-fou. Prenons maintenant une boucle qu’aucun garde-fou ne voit. Un mauvais déploiement du flux de travail renvoie sans cesse la première étape du billet T-90103, 600 fois par minute. La requête est réelle : le cours sur les agents l’a enregistrée sur chat-strong, avec 2 182 jetons en entrée et 55 en sortie. La boucle est construite : le cours l’a provoquée volontairement, avec le vrai code de la passerelle et une horloge rejouée. Sans limite, une heure donne 36,000 appels et 176.90 $ US. Personne ne lit le stockage d’utilisation à 2 h du matin.

L’idée : des limites que la passerelle vérifie avant chaque appel

Section intitulée « L’idée : des limites que la passerelle vérifie avant chaque appel »

Une limite est un nombre dans l’enregistrement de l’agent. La passerelle la vérifie au contrôle 8 de son parcours, avant que la requête atteigne un fournisseur. Ce cours utilise quatre types de limites :

  • Une limite de débit plafonne les requêtes par minute. Elle protège les fournisseurs et les autres agents contre une pointe de requêtes. Le flux de travail de Larkfield peut en envoyer 120 par minute.
  • Une limite d’étapes plafonne les appels de modèle par exécution (l’en-tête X-Run-Id). Une exécution qui ne finit jamais est la boucle classique. Le flux de travail peut faire 8 appels par exécution; ses exécutions réelles en font de 1 à 5.
  • Un quota plafonne les jetons par jour. Le flux de travail peut en utiliser 2 000 000.
  • Un budget plafonne l’argent par mois, pour l’agent (25 $ US pour le flux de travail) et son équipe (40 $ US pour l’équipe de service). Dès 80 % du budget de l’agent, chaque réponse porte un en-tête d’avertissement, x-gateway-budget-warning. À 100 %, la passerelle refuse.

Les compteurs se trouvent dans le stockage d’utilisation partagé, par agent et équipe, par minute, jour et mois. Chaque réplique de la passerelle lit donc le même compte. La dernière leçon de ce module ajoute deux répliques. Elles donnent toujours un seul budget à un agent, et non trois.

Exemple détaillé : quelle limite arrête la boucle, et quand?

Section intitulée « Exemple détaillé : quelle limite arrête la boucle, et quand? »

Un appel de la boucle coûte 2 182 jetons × 2 $ US par million, plus 55 jetons × 10 $ US par million. Cela donne 0,004364 $ US + 0,00055 $ US = 0,004914 $ US. Il utilise 2 182 + 55 = 2 237 jetons. La boucle envoie 600 tentatives par minute. Prenons maintenant une limite à la fois.

  • Limite d’étapes seulement, même identifiant d’exécution : le 9e appel de l’exécution est refusé. 8 appels, 8 × 0,004914 $ US = 0,04 $ US.
  • Limite de débit seulement, nouvel identifiant d’exécution chaque fois : 120 appels par minute passent. En 60 minutes : 7 200 appels, 35,38 $ US. Elle ralentit la boucle. Elle ne l’arrête jamais.
  • Quota seulement : 2 000 000 ÷ 2 237 = 894,06. Après 894 appels, le compte quotidien atteint 1 999 878 jetons, encore sous le quota. Le 895e appel passe donc, puis la boucle s’arrête : 895 appels, 4,40 $ US, après 895 ÷ 600 = 1,5 minute.
  • Budget seulement (25 $ US) : 25 ÷ 0,004914 = 5 087,5. Donc 5 088 appels passent : 25,00 $ US, après 8,5 minutes.

La passerelle vérifie un compte avant l’appel et ajoute l’appel après. L’appel qui dépasse la limite passe donc encore. L’agent peut dépasser un peu la limite, d’au plus un appel.

L’équipe du cours a exécuté chaque variante avec le vrai code de la passerelle, pendant une heure rejouée. Chaque nombre ci-dessus provient de cette exécution :

Boucle simulée (600 tentatives par minute pendant une heure rejouée) d'une requête réelle enregistrée, avec le vrai code de la passerelle; prix du cours (chat-strong, 2 $ US et 10 $ US par million de jetons).
Description textuelle du graphique

Six barres, le coût d’une heure de boucle. Sans limite : 176.90 $ US pour 36,000 appels. Limite d’étapes seulement, même identifiant d’exécution : 0.04 $ US pour 8 appels. Limite de débit seulement : 35.38 $ US pour 7,200 appels. Quota quotidien seulement : 4.40 $ US pour 895 appels. Budget mensuel seulement : 25.00 $ US pour 5,088 appels. Toutes les limites, avec les réglages du cours : 4.40 $ US pour 895 appels. La limite de débit a ralenti la boucle dès la 13e seconde, et le quota l’a arrêtée à 7,1 minutes.

Chaque limite répond à une question différente. La limite d’étapes arrête la boucle au coût le plus faible, mais seulement si elle garde son identifiant d’exécution. Un bogue qui démarre une nouvelle exécution chaque fois y échappe. La limite de débit protège les autres, mais n’arrête jamais les dépenses. Le quota et le budget arrêtent les dépenses, à des niveaux différents. L’enregistrement fixe donc les quatre limites, et la première atteinte arrête la boucle.

Chaque limite répond HTTP 429, avec un code et un message qui expliquent ce qui s’est passé. Le code détermine ce que l’agent devrait faire ensuite :

Un flux. La passerelle répond 429. Quel code? rate_limited : attendez le délai retry-after, puis renvoyez la requête une fois; si la réponse est encore 429, arrêtez cette exécution et confiez la tâche à une personne; sinon, continuez l'exécution. run_step_limit : arrêtez cette exécution et confiez la tâche à une personne. quota_exhausted ou budget_exhausted : arrêtez, ne réessayez pas aujourd'hui ou ce mois-ci, et avisez le responsable. Séparément, une réponse 200 avec x-gateway-budget-warning : continuez et avertissez le responsable que 80 % du budget est utilisé.
Ce qu'un agent devrait faire avec chaque réponse des limites. Seule une limite de débit justifie une deuxième tentative.
Description textuelle du diagramme

Quand la passerelle répond 429, l’agent lit le code. Pour rate_limited, il attend le délai de l’en-tête retry-after et renvoie la requête une fois. Si elle est encore refusée, il arrête l’exécution et confie la tâche à une personne. Pour run_step_limit, il arrête l’exécution et confie la tâche à une personne : plus d’appels n’aideront pas. Pour quota_exhausted ou budget_exhausted, il s’arrête et ne réessaie pas aujourd’hui ou ce mois-ci, et le responsable est avisé. Une réponse 200 avec l’en-tête x-gateway-budget-warning signifie : continuez, mais avertissez le responsable que 80 % du budget est utilisé.

Une nouvelle tentative convient seulement pour une courte attente. Un agent qui réessaie immédiatement après un quota atteint, en boucle, est un deuxième agent emballé. Chaque refus compte encore comme une requête dans la minute.

  1. Copiez les fichiers de la leçon : l’outil d’emballement et les tests de la passerelle.

    Fenêtre de terminal
    S=../nextia-learning-labs/C32/snapshots/end-of-m04
    cp $S/apps/runaway.py apps/
    cp $S/tests/test_gateway.py tests/
  2. Exécutez les tests : python -m pytest -q. La dernière ligne indique 153 passed, 1 deselected (153 réussis, 1 non sélectionné). Un nouveau test, test_the_budget_is_a_hard_stop_with_a_warning_before, fixe le budget du juge à 0,01 $ US. Il vérifie l’en-tête d’avertissement avant l’arrêt.

  3. Lisez les limites du flux de travail dans son enregistrement :

    Fenêtre de terminal
    grep -n -e budget_usd_month -e limits registrations/support-workflow.yaml
    24:budget_usd_month: 25
    25:limits: {requests_per_minute: 120, tokens_per_day: 2000000, max_calls_per_run: 8}

    Les budgets des équipes sont dans config/teams.yaml : l’équipe de service a 40 $ US par mois.

  4. Lancez une boucle qui ne termine jamais son exécution. Elle envoie 300 tentatives avec un seul identifiant d’exécution :

    Fenêtre de terminal
    python -m apps.runaway support-workflow --attempts 300 --same-run

    L’outil attend d’abord le début de la prochaine minute, car la limite de débit compte par minute civile. Ensuite, il prend moins d’une seconde. La sortie, une boucle construite d’une requête rejouée :

    support-workflow: 300 attempts of T-90103 step 1 (strong-reasoning) through the gateway, one run ID for every call
    Waiting 23 s for the next minute to start (--now starts at once)
    answered 8 | cost US$0.0393 | 0.2 s
    refused run_step_limit 112, rate_limited 180
    first run_step_limit: after 8 answers and US$0.0393 (0.1 s): 429 Run runaway-1792718460 has made 8 model calls: the limit is 8. Stop the run and hand the task to a person.
    first rate_limited: after 8 answers and US$0.0393 (0.1 s): 429 support-workflow may send 120 requests a minute. (retry-after: 60 s)

    Votre attente et votre identifiant d’exécution diffèrent. La limite d’étapes a arrêté l’exécution après 8 réponses. La boucle a continué ses demandes : 112 refus de plus, puis la minute était pleine. Les refus comptent comme des requêtes. Les 180 dernières tentatives ont donc reçu rate_limited (débit limité) à la place.

  5. Maintenant, le bogue plus difficile : un nouvel identifiant d’exécution pour chaque appel.

    Fenêtre de terminal
    python -m apps.runaway support-workflow --attempts 300
    support-workflow: 300 attempts of T-90103 step 1 (strong-reasoning) through the gateway, a new run ID for every call
    Waiting 60 s for the next minute to start (--now starts at once)
    answered 120 | cost US$0.5897 | 0.4 s
    refused rate_limited 180
    first rate_limited: after 120 answers and US$0.5897 (0.3 s): 429 support-workflow may send 120 requests a minute. (retry-after: 60 s)

    La limite d’étapes ne peut pas voir cette boucle. La limite de débit laisse passer 120 appels, soit 120 × 0,004914 $ US = 0,5897 $ US. Elle en laisserait passer 120 autres chaque minute. Dans l’heure rejouée, le quota l’a arrêtée à 7,1 minutes.

Exécutez immédiatement le vrai flux de travail sur un nouveau billet, dans la même minute que la dernière boucle :

Fenêtre de terminal
RESOLVER_PROVIDER=gateway python -m resolver run T-90104 --variant agent_structured --model strong-reasoning
Run T-90104-agent_structured-strong-reasoning-1 | single agent with one JSON step per call (for models without tool calling) | strong-reasoning
Stopped: provider_error. No proposal: the ticket goes to a person.
Last error: HTTP 429: rate limited.

Le cours sur les agents a construit le flux de travail pour arrêter à toute erreur du fournisseur. Il confie alors le billet à une personne. C’est sûr, mais peu nuancé : pour une limite de débit, une attente de retry-after (délai avant une nouvelle tentative) secondes aurait suffi. Si la minute a déjà changé au moment de l’exécution, celle-ci fonctionne. Attendez alors le prochain emballement et réessayez. python -m estate usage --last 1 montre le refus avec check_name rate_limit (contrôle de limite de débit). Il montre aussi le run_id (identifiant d’exécution) de l’exécution, T-90104-agent_structured-strong-reasoning-1.

C’est le coût d’une limite par agent. La boucle et le vrai travail partagent un agent. Les dépenses de la boucle bloquent donc aussi les vrais billets. Dans le mois rejoué, le cours a rejoué la même boucle le 22 septembre, avec ses limites, en plus d’une journée normale. Elle a fait 837 appels et coûté 4,09 $ US avant que le quota l’arrête. Le vrai travail de la journée avait déjà utilisé une partie du quota. Ensuite, 19 appels normaux du flux de travail ont été refusés pour le reste de la journée. Ces tâches ont été confiées à des personnes.

Un budget d’équipe couvre tous ses agents. Fixez de petits budgets pour deux équipes, prédisez où chaque boucle s’arrête et voyez qui d’autre est arrêté.

  1. Lisez ce que chaque équipe a dépensé ce mois-ci :

    Fenêtre de terminal
    python -m estate usage --by team

    Si vous avez exécuté chaque commande de ce module une fois, l’équipe de service a dépensé environ 0,68 $ US. L’équipe d’évaluation a dépensé environ 0,0122 $ US. Vos nombres diffèrent si vous avez exécuté plus de commandes.

  2. Ouvrez config/teams.yaml et fixez deux budgets : service à 1.00 et evaluation à 0.05. Enregistrez le fichier.

  3. Publiez la configuration : python -m estate config publish --note "practice: small team budgets".

  4. Prédisez : combien d’appels de la boucle du flux de travail passent avant que le budget de l’équipe de service l’arrête? Un appel coûte 0,004914 $ US. Notez votre nombre.

  5. Exécutez la boucle du flux de travail, puis une boucle du juge de mise en production, et un billet de triage :

    Fenêtre de terminal
    python -m apps.runaway support-workflow --attempts 300
    python -m apps.runaway release-judge --attempts 30 --now
    python -m apps.replay ticket-triage --units 1 --via gateway
  6. Remettez les budgets à 40 et 10, puis publiez de nouveau avec --note "the teams' budgets again".

Vérifiez votre prédiction

L’exécution du cours :

support-workflow: 300 attempts of T-90103 step 1 (strong-reasoning) through the gateway, a new run ID for every call
Waiting 59 s for the next minute to start (--now starts at once)
answered 66 | cost US$0.3243 | 0.4 s
refused budget_exhausted 54, rate_limited 180
first budget_exhausted: after 66 answers and US$0.3243 (0.2 s): 429 The service team has spent its US$1.00 for this month.
first rate_limited: after 66 answers and US$0.3243 (0.2 s): 429 support-workflow may send 120 requests a minute. (retry-after: 60 s)
release-judge: 30 attempts of T-64707 step 1 (strong-reasoning) through the gateway, a new run ID for every call
answered 10 | cost US$0.0409 | 0.1 s
refused budget_exhausted 20
first budget_exhausted: after 10 answers and US$0.0409 (0.1 s): 429 The evaluation team has spent its US$0.05 for this month.
ticket-triage: 2 requests through the gateway | status {429: 2}
refused or failed: budget_exhausted x2
tokens: 0 in, 0 out | cost: US$0.0000

Il restait à l’équipe de service 1,00 $ US − 0,6802 $ US = 0,3198 $ US. 0,3198 ÷ 0,004914 = 65,1. Le 66e appel a donc passé et dépassé la limite : 66 appels, 0,3243 $ US. Il restait 0,0378 $ US à l’équipe d’évaluation. Un appel du juge coûte environ 0,0041 $ US, donc 10 appels ont passé. Regardez la dernière ligne : le service de triage n’a rien fait de mal, mais il est arrêté lui aussi. Il fait partie de l’équipe de service. Un budget d’équipe protège l’argent de l’équipe. Il permet aussi à la boucle d’un agent d’arrêter ses voisins. Voilà pourquoi le flux de travail a aussi son propre budget. Une limite d’étapes ou un quota devrait arrêter une boucle bien avant le budget d’équipe. Après la nouvelle publication des budgets, le billet de triage passe.

Erreur courante

Une limite d'étapes qui n'arrête jamais une boucle

Symptôme : l’enregistrement du flux de travail contient max_calls_per_run: 8, mais python -m apps.runaway support-workflow --attempts 300 répond à 120 appels, pas 8 :

answered 120 | cost US$0.5897 | 0.4 s
refused rate_limited 180

Cause : la limite d’étapes compte les appels par identifiant d’exécution. Cette boucle envoie un nouvel identifiant d’exécution à chaque appel. Un vrai bogue a le même aspect : un agent démarre une nouvelle exécution après chaque erreur. La limite d’étapes ne peut pas le voir.

Diagnostic : python -m estate usage --by outcome montre plus de refused:rate_limit (refus pour limite de débit) et aucun nouveau refused:step_limit (refus pour limite d’étapes). Les identifiants d’exécution dans python -m estate usage --last 3 sont tous différents.

Rétablissement : gardez la limite d’étapes pour les exécutions qui ne finissent jamais. Comptez sur le quota et les budgets pour les boucles qui redémarrent. Fixez le quota près de l’utilisation quotidienne réelle de l’agent, avec une marge. Les 45 exécutions quotidiennes du flux de travail (une hypothèse) utilisent beaucoup moins de 2 000 000 jetons. Pour modifier une limite, modifiez l’enregistrement, enregistrez-le de nouveau et révisez-le. Une nouvelle version d’un agent à risque élevé attend une révision, comme dans Le cycle de vie d’un agent.

Vérifiez votre compréhension

Une équipe demande seulement une limite de débit, car un budget « arrêterait notre agent en production ». Que révèle l'emballement rejoué sur ce choix?

Afficher la réponse

Une limite de débit ralentit une boucle, mais ne l’arrête jamais. Avec 120 requêtes par minute, l’heure rejouée a encore produit 7 200 appels et coûté 35,38 $ US. Un budget ou un quota quotidien arrête les dépenses : 25,00 $ US et 4,40 $ US dans la même heure. L’inquiétude de l’équipe est légitime. Fixez donc le quota et le budget au-dessus de l’utilisation réelle de l’agent. L’avertissement à 80 % donne du temps au responsable. Gardez aussi la limite de débit.

Vérifiez votre compréhension

Le flux de travail reçoit 429 run_step_limit, puis plus tard 429 rate_limited. Que devrait-il faire dans chaque cas, et pourquoi les réponses diffèrent-elles?

Afficher la réponse

run_step_limit : arrêtez cette exécution et confiez la tâche à une personne. L’exécution a fait plus d’appels que toute exécution réelle n’en a besoin, donc plus d’appels n’aideront pas. rate_limited : attendez le délai retry-after et réessayez une fois, car la limite se réinitialise chaque minute. Si la deuxième tentative est aussi refusée, arrêtez et confiez la tâche à une personne. Un agent qui réessaie immédiatement, en boucle, aggrave le problème, car chaque refus compte comme une requête.

Vérifiez votre compréhension

Vérification pratique : fixez le budget de l'équipe d'évaluation à 0,05 $ US au-dessus de ses dépenses, publiez et exécutez python -m apps.runaway release-judge --attempts 30 --now. Combien d'appels passent, combien ont-ils coûté et quel message arrête les autres?

Afficher la réponse

Un appel du juge coûte environ 0,0041 $ US, donc environ 13 appels passent : 0,05 $ US ÷ 0,0041 = 12,2. L’appel qui dépasse la limite passe aussi. Ils coûtent un peu plus de 0,05 $ US. Les autres reçoivent 429 budget_exhausted avec « The evaluation team has spent its US$… for this month. » (l’équipe d’évaluation a dépensé ses … $ US pour ce mois). Lisez les nombres dans votre propre sortie. La première ligne de refus donne le nombre de réponses et leur coût avant ce refus. Remettez ensuite le budget à sa valeur initiale et publiez de nouveau.

Récapitulatif

  • La passerelle vérifie quatre limites avant chaque appel : requêtes par minute, appels par exécution, jetons par jour et $ US par mois. Chaque réplique lit les mêmes compteurs partagés.
  • Chaque limite arrête une boucle différente. L’heure rejouée a coûté 176,90 $ US sans limite. Elle a coûté 0,04 $ US avec la limite d’étapes, 35,38 $ US avec la limite de débit, 4,40 $ US avec le quota et 25,00 $ US avec le budget.
  • Un en-tête d’avertissement apparaît dès 80 % du budget de l’agent; l’arrêt à 100 % est une réponse 429 avec un code. Réessayez seulement pour rate_limited, une fois, après retry-after.
  • Les limites par agent et par équipe ont un coût. Une boucle utilise le même quota et budget que le vrai travail de l’agent et les autres agents de son équipe.

Votre projet maintenant : apps/runaway.py, les tests de la passerelle et 153 tests qui réussissent. La passerelle arrête maintenant un agent qui dépense trop. Mais elle transmet encore tout le contenu de la requête. Cela comprend même un numéro de carte ou une clé qui ne doit pas atteindre un fournisseur. Ensuite, vous ajoutez des garde-fous à la passerelle et mesurez leur coût.

Leçon suivante : Les garde-fous à la passerelle