Plafonds de dépense et grand livre

Un point d’accès /v1 pour tous les fournisseurs. Pointez votre client OpenAI vers une autre URL et une clé, avec vos clés et 0 % de majoration.

Chaque requête passe par votre propre clé de fournisseur : ce qu’il faut maîtriser, c’est la part de votre facture fournisseur qu’une clé, un client, un agent ou une politique peut engager. Quatre types de plafond s’en chargent, chacun vérifié avant qu’une requête n’atteigne un fournisseur, et chaque requête laisse un enregistrement chiffré que vous pouvez auditer ensuite.

Quatre types de plafond

Par clé : une application ou un environnement. PATCH /v1/keys/:hash avec limit, limit_reset et limit_mode, ou la page Clés.
Par garde-fou : un budget sur une politique, pour chaque clé ou membre auquel elle est attribuée (limit_usd, reset_interval).
Par espace de travail : un client, sur l’ensemble de ses clés, un budget par période.
Par agent : un agent nommé dans X-Autonomous-Relay-Agent, sur toutes les clés qu’il utilise, sans toucher aux autres agents de la même clé.

Les périodes sont daily, weekly, monthly ou lifetime. Chaque niveau est vérifié séparément et jamais additionné à un autre : un budget d’espace de travail de 100 $ et un plafond de clé de 50 $ ne font pas 150 $, et le premier atteint refuse la requête. Les plafonds de clé, les budgets d’agent et ceux du premier espace de travail fonctionnent sur tous les forfaits ; les budgets de garde-fou, les canaux d’alerte et l’export CSV viennent avec le forfait Team.

Ce que compte un plafond

Ce que coûte chaque requête au prix catalogue du fournisseur — ce que votre fournisseur vous facture —, sur la période en cours du plafond. Un plafond mensuel de 50 $ arrête la clé à 50 $ de ces dépenses. C’est le comportement par défaut pour tous les plafonds ; mettez include_byok_in_limit (ou include_byok_in_budgets, include_byok) à false pour ne compter que les dépenses sur la capacité de la plateforme, qui n’en a aucune aujourd’hui. Une requête qui n’a rien produit n’est pas comptée.

Strict ou souple

Un plafond strict, par défaut, refuse la requête avec 403 budget_exceeded avant tout contact avec un fournisseur, et le refus est consigné : Activité montre ce qui a été arrêté et pourquoi. Un plafond souple sert la requête et ajoute un en-tête x-autonomous-relay-limit-warning portant la même phrase : pour une limite dont vous voulez être averti plutôt que l’appliquer.

Pourquoi des requêtes parallèles ne peuvent pas dépasser

Avant l’envoi, chaque requête réserve son coût maximal possible, au prix catalogue, sur chaque plafond applicable ; au règlement, la réservation devient le coût réel et le reste est libéré. Une rafale de requêtes est donc refusée au plafond, pas après : vingt requêtes chacune sous la limite ne peuvent pas la dépasser ensemble. GET /v1/keys indique l’usage et limit_remaining de chaque clé, y compris les réservations des requêtes en cours, exactement comme le plafond est appliqué. Le basculement ne contourne pas non plus un plafond : la vérification a lieu une fois, avant la première tentative.

Un exemple complet

Un robot de support sur une clé : 50 $ par mois au plus, son agent plafonné à 10 $ par jour, et un message Slack à 80 % et 100 %.

curl

# La clé : un plafond strict de 50 $ par mois.
curl -X PATCH https://autonomousrelay.com/v1/keys/$KEY_HASH \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY" \
  -H 'content-type: application/json' \
  -d '{"limit": 50, "limit_reset": "monthly", "limit_mode": "hard"}'

# L'agent : 10 $ par jour, d'où que viennent ses requêtes.
curl -X PUT https://autonomousrelay.com/v1/agents/support-bot/budgets/daily \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY" \
  -H 'content-type: application/json' \
  -d '{"limit_usd": 10}'

Ajoutez ensuite, sur Team, un canal Slack, webhook ou courriel sous Alertes : une clé plafonnée est signalée quand elle franchit 50 %, 80 % et 100 %, ou les seuils de votre choix, une fois par seuil et par période.

Dépenses emballées, sans plafond

Une clé ou un agent dont les 15 dernières minutes ont coûté au moins trois fois leur habitude (et au moins 5 $) est signalé sur vos canaux d’alerte comme spend.runaway. Mettez runaway_action à pause et la clé est aussi suspendue jusqu’à ce que vous la réactiviez. Voir Limites et crédits pour les seuils.

Auditer les dépenses ensuite

Chaque requête est découpée en lignes chiffrées — entrée, sortie, raisonnement, cache, etc. —, chacune portant le prix unitaire auquel elle a été facturée : une ancienne charge se recalcule à l’identique après un changement de prix. GET /v1/generation?id=:id montre les lignes d’une requête et le point d’accès qui l’a servie ; GET /v1/activity/upstream montre chaque tentative ; et GET /v1/activity/export.csv fournit un mois de requêtes, pour l’organisation ou un client, avec list_price_usd, le montant que mesurent les plafonds. Voir Facturation et grand livre.