Règle LLMTokenQuota

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Présentation

La règle LLMTokenQuota est conçue pour gérer et contrôler la consommation de jetons pour les charges de travail d'IA/LLM. Les interactions avec les grands modèles de langage (LLM) étant basées sur les jetons, une gestion efficace est essentielle pour contrôler les coûts, optimiser les performances et assurer la stabilité de la plate-forme.

Un quota est une attribution de jetons LLM (entrée ou sortie) qu'un proxy d'API est autorisé à consommer sur une période donnée (minute, heure, jour, semaine ou mois). La règle LLMTokenQuota gère les compteurs qui comptabilisent le nombre de jetons consommés par le proxy d'API. Cette fonctionnalité permet aux fournisseurs d'API d'appliquer des limites sur la consommation de jetons par les applications sur un intervalle de temps donné.

Cette règle utilise les éléments <LLMTokenUsageSource> et <LLMModelSource> pour extraire le nombre de jetons de la réponse du LLM et le nom du modèle de la requête ou de la réponse, ce qui permet d'appliquer le quota de manière précise et en temps réel.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Fonctionnement de l'application du quota de jetons LLM

Vous trouverez ci-dessous une description de la fonctionnalité de la règle LLMTokenQuota :

  • Comptage des jetons (<CountOnly>) : la règle LLMTokenQuota gère les compteurs qui suivent le nombre de jetons utilisés par les réponses LLM qui transitent par le proxy d'API.
  • Appliquer des limites (<EnforceOnly>) : cette fonctionnalité permet aux fournisseurs d'API de définir des limites strictes sur le nombre de jetons consommés par les applications au cours d'un intervalle défini. Par exemple, vous pouvez limiter les applications à 1 000 jetons par minute ou à 10 000 000 de jetons par mois.
  • Dépassement du quota : lorsqu'un proxy d'API atteint la limite de quota de jetons définie, Apigee refuse les requêtes suivantes consommant des jetons. Un message d'erreur s'affiche jusqu'à ce que le compteur LLMTokenQuota se réinitialise automatiquement à la fin de l'intervalle de temps spécifié. Par exemple, si un quota est défini sur 10 000 jetons par mois, la limitation des jetons commence une fois que le 10 000e jeton est comptabilisé, quelle que soit la date à laquelle cette limite est atteinte au cours du mois.

Fonctionnement de LLMTokenQuota avec les produits API

Vous trouverez ci-dessous une description du fonctionnement de la règle LLMTokenQuota avec les produits d'API :

Flux de proxy pour LLMTokenQuota
  1. Appliquez la règle VerifyAPIKey ou VerifyAccessToken avec la règle d'application LLMTokenQuota dans la requête du proxy d'API (le proxy ou la cible n'ont pas d'importance).
  2. Appliquez la règle de comptage LLMTokenQuota en réponse au proxy d'API (le proxy ou la cible n'ont pas d'importance).
  3. La règle VerifyAPIKey ou VerifyAccessToken associe la clé ou le jeton au produit d'API, à l'ensemble d'opérations, au développeur et à l'application. Elle expose les variables de flux pour le quota LLM pour tous les modèles des ensembles d'opérations LLM correspondants.
  4. Dans la règle d'application des quotas, nous extrayons le modèle en fonction du modèle de message fourni.
  5. Les variables de quota du LLM sont ensuite mises en correspondance pour le modèle. Si une correspondance est trouvée, les références sont injectées.
  6. Une fois les références injectées, ces valeurs sont utilisées pour effectuer les opérations de quota.

Fonctionnement de LLMTokenQuota avec les réponses SSE

Pour que LLMTokenQuota fonctionne avec les réponses SSE, ajoutez la règle au flux d'événements, comme indiqué ci-dessous :

<EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>LLM_TOKEN_QUOTA_COUNT_POLICY_NAME</Name>
      </Step>
    </Response>
  </EventFlow>

Lors du traitement du flux d'événements, le comptage des jetons n'est effectué que lorsque les métadonnées d'utilisation des jetons de la réponse du LLM sont trouvées dans l'événement. Lorsque les métadonnées d'utilisation du jeton sont détectées, elles sont extraites et la règle est exécutée. Pour tous les autres événements, la règle génère NO-OP.

Types de règles LLMTokenQuota

La règle LLMTokenQuota accepte plusieurs modes de démarrage et de réinitialisation du compteur de quota. Vous pouvez définir lequel utiliser avec l'attribut type sur l'élément <LLMTokenQuota>, comme le montre l'exemple suivant :

<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar">
  ...
</LLMTokenQuota>

Les valeurs valides pour type sont les suivantes :

  • calendar : configure un quota basé sur une heure de début explicite. Le compteur LLMTokenQuota de chaque application est actualisé en fonction des valeurs <StartTime>, <Interval> et <TimeUnit> que vous avez définies.
  • rollingwindow : configure un quota qui utilise une fenêtre glissante pour déterminer l'utilisation du quota. Avec rollingwindow, vous déterminez la taille de la fenêtre à l'aide des éléments <Interval> et <TimeUnit>, par exemple, 1 jour. Lorsqu'une requête arrive, Apigee examine l'heure exacte de la requête (par exemple, 17h01), comptabilise le nombre de jetons consommés entre 17h01 et 17h01 le jour précédent (un jour), et détermine si le quota a été dépassé pendant cette période.
  • flexi : configure un quota qui déclenche le démarrage du compteur lorsque le premier message de requête est reçu d'une application, et est réinitialisé en fonction des valeurs <Interval> et <TimeUnit>.

Le tableau suivant décrit la réinitialisation du quota pour chaque type :

Unité de temps Type
default (ou nul) calendar flexi
minute Début de la minute suivante Une minute après <StartTime> Une minute après la première requête
heure Haut de l'heure suivante Une heure après <StartTime> Une heure après la première requête
jour À minuit GMT du jour actuel 24 heures après <StartTime> 24 heures après la première requête
semaine À minuit GMT le dimanche à la fin de la semaine Une semaine après <StartTime> Une semaine après la première requête
mois À minuit GMT le dernier jour du mois Un mois (28 jours) après <StartTime> Un mois (28 jours) après la première requête

Pour type="calendar", vous devez spécifier la valeur de <StartTime>.

Le tableau ne décrit pas quand le nombre est réinitialisé pour le type rollingwindow. En effet, les quotas par fenêtre glissante fonctionnent différemment, en fonction d'une période d'analyse (par exemple, une heure ou un jour). Pour le type rollingwindow, le compteur n'est jamais réinitialisé, mais il est recalculé à chaque requête. Lorsqu'une nouvelle requête arrive, la règle détermine si le quota a été dépassé au cours de la dernière fenêtre.

Par exemple, vous définissez une fenêtre de deux heures qui autorise 1 000 jetons. Une nouvelle requête est envoyée à 16h45.La règle calcule le quota pour la dernière heure (soit le nombre de jetons consommés depuis 14h45). Si la limite de quota n'a pas été dépassée au cours de cet intervalle de deux heures, la requête est autorisée.

Une minute plus tard, à 16h46, une autre requête arrive. La règle calcule maintenant le quota depuis 14h46 pour déterminer si la limite a été dépassée.

Comprendre les compteurs de quotas

Lorsqu'une règle LLMTokenQuota s'exécute dans un flux de proxy d'API, un compteur de quota est incrémenté. Lorsque le compteur atteint sa limite, aucun autre appel d'API associé à ce compteur n'est autorisé. En fonction de la configuration que vous utilisez pour votre produit d'API, la règle LLMTokenQuota peut utiliser un seul compteur ou plusieurs compteurs indépendants. Il est important de comprendre les scénarios dans lesquels plusieurs compteurs seront utilisés et comment ils se comportent.

Configurer les paramètres de quota pour les produits d'API

Un produit d'API peut spécifier des paramètres de quota au niveau du produit ou au niveau des opérations individuelles, ou les deux. Si votre proxy d'API est inclus dans un produit d'API, vous pouvez configurer la règle LLMTokenQuota pour utiliser les paramètres de quota (nombre autorisé, unité de temps et intervalle) définis dans ce produit. Le moyen le plus simple de le faire est d'utiliser l'élément useQuotaConfigInAPIProduct. Vous pouvez également faire référence à ces paramètres dans la règle LLMTokenQuota à l'aide de références de variables individuelles.

Comment les quotas sont-ils comptabilisés ?

Par défaut, Apigee gère un compteur de quota distinct pour chaque opération définie dans un produit d'API, et les règles suivantes sont observées :

  • Si un quota est défini pour une opération, les paramètres de quota de l'opération ont priorité sur les paramètres de quota définis au niveau du produit.
  • Si aucun quota n'est défini pour une opération, les paramètres de quota au niveau du produit s'appliquent.
  • Si le produit d'API n'inclut aucun paramètre de quota, que ce soit au niveau du produit ou de l'opération, les paramètres de quota pour le nombre autorisé, l'unité de temps et l'intervalle spécifiés dans la règle LLMTokenQuota s'appliquent.

Dans tous les cas, Apigee gère un compteur de quota distinct pour chaque opération définie dans un produit d'API. Tous les appels d'API correspondant à une opération incrémentent son compteur.

Configurer des compteurs au niveau du proxy d'API

Il est possible de configurer un produit d'API pour gérer un compteur de quota au niveau du proxy d'API. Dans ce cas, la configuration de quota spécifiée au niveau du produit d'API est partagée par toutes les opérations qui ne disposent pas de leur propre quota. Cette configuration revient à créer un compteur au niveau du proxy d'API pour ce produit d'API.

Pour atteindre cette configuration, vous devez utiliser l'API Apigee /apiproducts pour créer ou mettre à jour le produit, puis définir l'attribut quotaCounterScope sur PROXY dans la requête de création ou de mise à jour. Avec la configuration PROXY, les requêtes correspondant à l'une des opérations définies pour le produit d'API et associées au même proxy qui n'ont pas leurs propres paramètres de quota partageront un compteur de quota commun pour ce proxy.

Dans la figure 1, les opérations 1 et 2 sont associées à Proxy1, et les opérations 4 et 5 sont associées à Proxy3. Étant donné que quotaCounterScope=PROXY est défini dans le produit d'API, chacune de ces opérations utilise le paramètre de quota au niveau du produit d'API. Les opérations 1 et 2, associées à Proxy1, utilisent un compteur partagé, tandis que les opérations 4 et 5, associées à Proxy3, utilisent un autre compteur partagé. L'opération 3 possède son propre paramètre de configuration de quota et utilise donc son propre compteur, quelle que soit la valeur de l'attribut quotaCounterScope.

Figure 1 : Utilisation de l'option quotaCounterScope

Comptage des quotas si aucun produit d'API n'est utilisé

Si aucun produit d'API n'est associé à un proxy d'API, une règle LLMTokenQuota ne gère qu'un seul compteur, quel que soit le nombre de références à ce compteur dans un proxy d'API. Le nom du compteur de quota est basé sur l'attribut name de la règle.

Par exemple, vous créez une règle LLMTokenQuota nommée MyLLMTokenQuotaPolicy avec une limite de 5 jetons et la placez sur plusieurs flux (Flux A, B et C) dans le proxy d'API. Même si elle est utilisée dans plusieurs flux, elle conserve un compteur unique mis à jour par toutes les instances de la règle. En supposant que la réponse du LLM ait utilisé un jeton à chaque fois :

  • Flux A exécuté -> la règle MyLLMTokenQuotaPolicy est exécutée et son compteur = 1
  • Flux B exécuté : MyLLMTokenQuotaPolicy est exécutée et son compteur est défini sur 2
  • Flux A exécuté -> la règle MyLLMTokenQuotaPolicy est exécutée et son compteur = 3
  • Flow C est exécuté → MyLLMTokenQuotaPolicy est exécuté et son compteur est défini sur 4
  • Flux A exécuté -> la règle MyLLMTokenQuotaPolicy est exécutée et son compteur = 5

La requête suivante vers l'un des trois flux est rejetée, car le compteur de quota a atteint sa limite.

L'utilisation de la même règle LLMTokenQuota à plusieurs endroits d'un flux de proxy d'API, qui peut entraîner une consommation de quota de jetons LLM plus rapide que prévu, est un anti-modèle décrit dans l'article Présentation des antimodèles.

Vous pouvez également définir plusieurs règles LLMTokenQuota dans votre proxy d'API et utiliser une règle différente dans chaque flux. Chaque règle LLMTokenQuota conserve son propre compteur, en fonction de son attribut name.

Créer plusieurs compteurs via une configuration de règle

Vous pouvez utiliser les éléments <Class> ou <Identifier> de la règle LLMTokenQuota pour définir plusieurs compteurs uniques dans une seule règle. En utilisant ces éléments, une seule règle peut gérer différents compteurs en fonction de l'application qui envoie la requête, du développeur de l'application qui effectue la requête, d'un ID client ou d'un autre identifiant client, etc. Consultez les exemples ci-dessus pour en savoir plus sur l'utilisation des éléments <Class> ou <Identifier>.

Notation de l'heure

Tous les quotas LLMTokenQuota sont définis sur le fuseau horaire UTC (Temps universel coordonné).

La notation de temps du quota de jetons LLM suit la notation de date standard internationale définie dans la norme internationale ISO 8601.

Les dates sont définies en année, mois et jour, au format suivant : YYYY-MM-DD. Par exemple, 2025-02-04 correspond au 4 février 2025.

L'heure de la journée se définit en heures, minutes et secondes au format suivant : hours:minutes:seconds. Par exemple, 23:59:59 représente l'heure une seconde avant minuit.

Notez que deux notations, 00:00:00 et 24:00:00, sont disponibles pour distinguer les deux représentations de minuit qui peuvent être associées à une date. Par conséquent, 2025-02-04 24:00:00 est la même date et la même heure que 2025-02-05 00:00:00. Ce dernier format est généralement la notation préférée.

Obtenir des paramètres de quota à partir de la configuration du produit d'API

Vous pouvez définir des limites de quota dans les configurations de produit de l'API. Ces limites ne s'appliquent pas automatiquement au quota. À la place, vous pouvez référencer des paramètres de quota du produit dans une règle LLMTokenQuota. Voici quelques avantages liés à la définition d'un quota sur le produit pour que les règles LLMTokenQuota puissent le référencer :

  • Les règles LLMTokenQuota peuvent utiliser un paramètre uniforme pour tous les proxys d'API du produit d'API.
  • Vous pouvez modifier l'environnement d'exécution du paramètre de quota d'un produit d'API, et les règles LLMTokenQuota qui font référence à la valeur ont automatiquement des valeurs de quota mises à jour.

Pour en savoir plus sur l'utilisation des paramètres de quota d'un produit d'API, consultez l'exemple Quotas dynamiques.

Pour en savoir plus sur la configuration des produits d'API avec des limites de quota, consultez la page Gérer les produits API.

Configurer des compteurs de quotas partagés

Dans le cas simple, la règle LLMTokenQuota incrémente son compteur une fois pour chaque jeton envoyé à un proxy d'API lors du traitement initial de la requête. Dans certains cas, vous pouvez vérifier si le quota est dépassé lors du traitement initial de la requête entrante, mais incrémenter le compteur uniquement lors du traitement de la réponse.

Trois éléments de la règle LLMTokenQuota (<SharedName>, <CountOnly> et <EnforceOnly>) utilisés conjointement vous permettent de personnaliser la règle LLMTokenQuota pour appliquer le quota aux requêtes entrantes, mais uniquement d'incrémenter le compteur dans le flux de réponse.

Par exemple, supposons que vous disposiez d'un proxy d'API qui utilise un LLM comme cible et que vous souhaitiez appliquer un quota de 100 000 jetons par heure. Les réponses du LLM fournissent une valeur totalTokenCount. Pour ce faire, procédez comme suit :

  • Associez une règle LLMTokenQuota au flux de requête ProxyEndpoint avec l'élément <SharedName> défini avec une valeur de nom et l'élément <EnforceOnly> défini sur true.
  • Utilisez l'élément <LLMTokenUsageSource> dans la règle LLMTokenQuota pour récupérer le nombre de jetons.

Pour obtenir un exemple illustrant l'utilisation de compteurs partagés, consultez Compteurs partagés dans la section Exemples.

Exemples

Ces exemples de codes de règles montrent comment définir le début et la fin d'une période de quota :

Quotas de jetons LLM plus dynamiques

<LLMTokenQuota name="CheckLLMTokenQuota">
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmquota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmquota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmquota.limit"/>
</LLMTokenQuota>

Les quotas dynamiques vous permettent de configurer une seule règle LLMTokenQuota appliquant différents paramètres de quota en fonction des informations transmises à la règle LLMTokenQuota. Dans ce contexte, un autre terme applicable aux paramètres LLMTokenQuota est forfait. Le quota dynamique LLMTokenQuota vérifie le forfait des applications, puis applique ces paramètres.

Par exemple, lorsque vous créez un produit d'API, vous pouvez éventuellement définir la limite de quota, l'unité de temps et l'intervalle autorisés. Toutefois, définir ces valeurs sur le produit d'API n'impose pas leur utilisation dans un proxy d'API. Vous devez également ajouter une règle LLMTokenQuota au proxy d'API qui lit ces valeurs. Voir Créer des produits API pour plus d'informations.

Dans l'exemple ci-dessus, le proxy d'API contenant la règle LLMTokenQuota utilise une règle VerifyAPIKey, nommée verify-api-key, pour valider la clé API transmise dans une requête. La règle LLMTokenQuota accède ensuite aux variables de flux à partir de la règle VerifyAPIKey pour lire les valeurs de quota définies sur le produit d'API.

Vous pouvez également définir des attributs personnalisés pour des développeurs ou applications spécifiques, puis lire ces valeurs dans la règle LLMTokenQuota. Par exemple, pour définir différentes valeurs de quota par développeur, vous définissez des attributs personnalisés pour le développeur contenant la limite, l'unité de temps et l'intervalle. Vous référencez ensuite ces valeurs dans la règle LLMTokenQuota comme indiqué ci-dessous :

<LLMTokenQuota name="DeveloperLLMTokenQuota">
  <Identifier ref="verifyapikey.verify-api-key.client_id"/>
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/>
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/>
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/>
</LLMTokenQuota>

Cet exemple utilise également les variables de flux VerifyAPIKey pour référencer les attributs personnalisés définis sur le développeur.

Vous pouvez utiliser n'importe quelle variable pour définir les paramètres de la règle LLMTokenQuota. Ces variables peuvent provenir des éléments suivants :

  • Variables de flux
  • Propriétés du produit d'API, de l'application ou du développeur
  • Mappage clé-valeur (KVM)
  • En-tête, paramètre de requête, paramètre de formulaire, etc.

Pour chaque proxy d'API, vous pouvez ajouter une règle LLMTokenQuota faisant référence à la même variable que toutes les autres règles LLMTokenQuota de tous les autres proxys. La règle LLMTokenQuota peut faire référence à des variables uniques pour cette règle et ce proxy.

Heure de début

<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar">
  <StartTime>2025-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

Pour un LLMTokenQuota dont la valeur type est définie sur calendar, vous devez définir une valeur <StartTime> explicite. La valeur horaire correspond à l'heure GMT, et non à l'heure locale. Si vous ne fournissez pas de valeur <StartTime> pour une règle de type calendar, Apigee affiche une erreur.

Le compteur LLMTokenQuota pour chaque application est actualisé en fonction des valeurs <StartTime>, <Interval> et <TimeUnit>. Dans cet exemple, le quota LLMTokenQuota commence à être comptabilisé à 10h30 GMT le 18 février 2025 et s'actualise toutes les 5 heures. Par conséquent, la prochaine actualisation est fixée à 15h30 GMT le 18 février 2025.

Compteur d'accès

<LLMTokenQuota name="LLMTokenQuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

Un proxy d'API a accès aux variables de flux définies par la règle LLMTokenQuota. Vous pouvez accéder à ces variables de flux dans le proxy d'API pour effectuer un traitement conditionnel, surveiller la règle lorsqu'elle se rapproche de la limite de quota, renvoyer le compteur de quota actuel à une application, ou pour d'autres raisons.

Comme l'accès aux variables de flux de la règle est basé sur l'attribut name des règles, pour la règle ci-dessus nommée <LLMTokenQuota>, vous accédez à ses variables de flux sous la forme suivante :

  • ratelimit.LLMTokenQuotaPolicy.allowed.count : nombre autorisé.
  • ratelimit.LLMTokenQuotaPolicy.used.count : valeur de compteur actuelle.
  • ratelimit.LLMTokenQuotaPolicy.expiry.time : heure UTC lorsque le compteur est réinitialisé.

Vous pouvez accéder à de nombreuses autres variables de flux, comme décrit ci-dessous.

Par exemple, vous pouvez utiliser la règle AssignMessage suivante pour renvoyer les valeurs des variables de flux LLMTokenQuota en tant qu'en-têtes de réponse :

<AssignMessage continueOnError="false" enabled="true" name="ReturnQuotaVars">
  <AssignTo createNew="false" type="response"/>
  <Set>
    <Headers>
      <Header name="LLMTokenQuotaLimit">{ratelimit.LLMTokenQuotaPolicy.allowed.count}</Header>
      <Header name="LLMTokenQuotaUsed">{ratelimit.LLMTokenQuotaPolicy.used.count}</Header>
      <Header name="LLMTokenQuotaResetUTC">{ratelimit.LLMTokenQuotaPolicy.expiry.time}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Compteurs partagés

L'exemple suivant montre comment configurer un compteur partagé pour un proxy d'API, où le compteur de quota est également incrémenté lorsque la réponse cible correspond à l'état HTTP 200. Étant donné que les deux règles LLMTokenQuota utilisent la même valeur <SharedName>, elles partagent le même compteur de quota. Pour en savoir plus, consultez la page Configurer des compteurs de quotas partagés.

Exemple de configuration de ProxyEndpoint : 

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LLMTokenQuota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>LLMTokenQuota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

Premier exemple de règle LLMTokenQuota :

<LLMTokenQuota name="LLMTokenQuota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</LLMTokenQuota>

Deuxième exemple de règle LLMTokenQuota :

<LLMTokenQuota name="LLMTokenQuota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first LLMTokenQuota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>
    {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
  </LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource>
</LLMTokenQuota>

Première requête

<LLMTokenQuota name="MyLLMTokenQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</LLMTokenQuota>

Utilisez cet exemple de code pour appliquer un quota de 10 000 jetons par heure. La règle réinitialise le compteur de quota en haut de chaque heure. Si le compteur atteint le quota de 10 000 jetons avant la fin de l'heure, les appels d'API consommant des jetons au-delà de 10 000 sont rejetés.

Par exemple, si le compteur commence à 2025-07-08 07:00:00, il est réinitialisé à 0 à 2025-07-08 08:00:00 (1 heure à partir de l'heure de début). Si la première requête est reçue à 2025-07-08 07:35:28 et que le nombre de jetons atteint 10 000 avant 2025-07-08 08:00:00, les requêtes consommant des jetons au-delà de ce nombre sont refusées jusqu'à ce que le décompte soit réinitialisé à l'heure pile.

Le délai de réinitialisation du compteur est basé sur la combinaison des options <Interval> et <TimeUnit>. Par exemple, si vous définissez <Interval> sur 12 pour une <TimeUnit> en heures, le compteur est réinitialisé toutes les 12 heures. Vous pouvez définir le paramètre <TimeUnit> en minutes, heures, jours, semaines ou mois.

Vous pouvez référencer cette règle à plusieurs endroits de votre proxy d'API. Par exemple, vous pouvez la placer dans le PreFlow du proxy afin qu'il soit exécuté à chaque requête. Vous pouvez également la placer sur plusieurs flux dans le proxy d'API. Si vous utilisez cette règle à plusieurs endroits du proxy, elle conserve un compteur unique mis à jour par toutes les instances de la règle.

Vous pouvez également définir plusieurs règles LLMTokenQuota dans votre proxy d'API. Chaque règle LLMTokenQuota conserve son propre compteur, en fonction de son attribut name.

Définir un identifiant

<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2025-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

Par défaut, une règle LLMTokenQuota définit un seul compteur pour le proxy d'API, quelle que soit l'origine d'une requête. Vous pouvez également utiliser l'attribut <Identifier> avec une règle LLMTokenQuota pour gérer des compteurs distincts en fonction de la valeur de l'attribut <Identifier>.

Par exemple, utilisez le tag <Identifier> pour définir des compteurs distincts pour chaque ID client. En cas de requête envoyée à votre proxy, l'application cliente transmet un en-tête contenant clientID, comme illustré dans l'exemple ci-dessus.

Vous pouvez spécifier n'importe quelle variable de flux pour l'attribut <Identifier>. Par exemple, vous pouvez spécifier qu'un paramètre de requête nommé id contient l'identifiant unique :

<Identifier ref="request.queryparam.id"/>

Si vous appliquez la règle VerifyAPIKey pour valider la clé API ou les règles OAuthV2 avec des jetons OAuth, vous pouvez utiliser les informations de la clé API ou du jeton pour définir des compteurs individuels pour la même règle LLMTokenQuota. Par exemple, l'élément <Identifier> suivant utilise la variable de flux client_id d'une règle VerifyAPIKey nommée verify-api-key :

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

Chaque valeur client_id unique définit désormais son propre compteur dans la règle LLMTokenQuota.

Classe

<LLMTokenQuota name="LLMTokenQuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</LLMTokenQuota>

Vous pouvez définir les limites de LLMTokenQuota de manière dynamique en utilisant un nombre de LLMTokenQuota basé sur une classe. Dans cet exemple, la limite de quota est déterminée par la valeur de l'en-tête developer_segment transmise avec chaque requête. Cette variable peut avoir la valeur platinum ou silver. Si l'en-tête comporte une valeur non valide, la règle renvoie une erreur d'erreur de quota.

Les exemples suivants illustrent différentes configurations de la règle LLMTokenQuota.

Calculer les jetons

Cet exemple montre comment calculer les jetons.

<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>
    {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
  </LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource>
</LLMTokenQuota>

Variables dynamiques de quota de nombre utilisant le produit d'API, le développeur et l'application

Cet exemple montre comment compter les variables dynamiques de quota à l'aide des produits d'API, des développeurs et des applications.

<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <CountOnly>true</CountOnly>
<Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.limit"/>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>
    {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
  </LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource>
</LLMTokenQuota>

Appliquer un quota sans produit d'API

Cet exemple montre comment appliquer un quota sans produit d'API.

<LLMTokenQuota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</LLMTokenQuota>

Appliquer un quota avec un produit d'API, un développeur et une application

Cet exemple montre comment appliquer un quota avec un produit d'API, un développeur et une application.

<LLMTokenQuota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
<Interval ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.llmQuota.limit"/>
  <Distributed>true</Distributed>
</LLMTokenQuota>

Avec le flux SSE

Cet exemple montre comment utiliser LLMTokenQuota avec un flux SSE.

Règles de décompte du quota de jetons :

<LLMTokenQuota name="LTQ-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <LLMTokenUsageSource>
    {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
  </LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource>
</LLMTokenQuota>

Flux d'événements :

<EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>LTQ-Count-Only</Name>
      </Step>
    </Response>
  </EventFlow>

Élément <LLMTokenQuota>

Voici les attributs et les éléments enfants de <LLMTokenQuota>. Notez que certaines combinaisons d'éléments s'excluent mutuellement ou ne sont pas obligatoires. Consultez les exemples pour une utilisation spécifique.

Les variables verifyapikey.my-verify-key-policy.apiproduct.* ci-dessous sont disponibles par défaut lorsqu'une règle VerifyAPIKey appelée my-verify-key-policy est utilisée pour vérifier la clé API de l'application dans la requête. Les valeurs des variables proviennent des paramètres de quota du produit d'API auquel la clé est associée, comme décrit dans Obtenir des paramètres de quota à partir de la configuration du produit d'API.

<LLMTokenQuota continueOnError="false" enabled="true" name="LTQ-TokenQuota-1" type="calendar">
  <DisplayName>Quota 3</DisplayName>
  <LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}</LLMTokenUsageSource>
  <LLMModelSource>{jsonPath('$.model',response.content,true)}</LLMModelSource>
  <Allow count="UPPER_REQUEST_LIMIT"
      countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.limit"/>
  <Allow>
    <Class ref="request.queryparam.time_variable">
      <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
      <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
    </Class>
  </Allow>
  <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.interval">
    1
  </Interval>
  <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.timeunit">
    month
  </TimeUnit>
  <StartTime>2025-7-16 12:00:00</StartTime>
  <Distributed>false</Distributed>
  <Synchronous>false</Synchronous>
  <AsynchronousConfiguration>
    <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
    <SyncMessageCount>5</SyncMessageCount>
  </AsynchronousConfiguration>
  <Identifier/>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UseQuotaConfigInAPIProduct>
    <DefaultConfig>
      <Allow>
        <Class ref="request.queryparam.time_variable">
          <Allow class="peak_time" count="5000"/>
          <Allow class="off_peak_time" count="1000"/>
        </Class>
      </Allow>
      <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.interval">
        1
      </Interval>
      <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.llmquota.timeunit">
        month
      </TimeUnit>
    </DefaultConfig>
  </UseQuotaConfigInAPIProduct>
  <SharedName/>
  <EnforceOnly>true</EnforceOnly>
</LLMTokenQuota>

Les attributs suivants sont spécifiques à cette règle :

Attribut Description Par défaut Présence
type

Définit le type de règle LLMTokenQuota, qui détermine quand et comment le compteur de quota vérifie l'utilisation du quota, ainsi que le processus de réinitialisation.

Si vous ne définissez pas type, le compteur démarre au début de la minute/heure/jour/semaine/mois.

Les valeurs valides sont les suivantes :

  • calendar
  • rollingwindow
  • flexi

Pour obtenir une description complète de chaque type, consultez la section Types de règles LLMTokenQuota.

 N/A Facultatif

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut Description Par défaut Presence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

 N/A Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir également :

 false Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

 true Facultatif
async

Cet attribut est obsolète.

 false Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Presence Facultatif
Type Chaîne

<Allow>

Spécifie le nombre total de jetons autorisés pour l'intervalle de temps spécifié. Si le compteur de la règle atteint cette limite, les appels d'API suivants sont rejetés jusqu'à la réinitialisation du compteur.

Peut également contenir un élément <Class> qui conditionne l'élément <Allow> en fonction d'une variable de flux.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type entier ou complexe
Élément parent <LLMTokenQuota>
Éléments enfants <Class>

Voici trois façons de définir l'élément <Allow> :

<Allow count="2000"/>
 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>
 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>

Si vous spécifiez à la fois count et countRef, countRef obtient la priorité. Si countRef n'est pas renvoyé au moment de l'exécution, la valeur de count est utilisée.

Vous pouvez également spécifier un élément <Class> en tant qu'enfant de <Allow> pour déterminer le décompte autorisé de la règle en fonction d'une variable de flux. Apigee met en correspondance la valeur de la variable de flux avec l'attribut class de l'élément <Allow>, comme indiqué ci-dessous :

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Le tableau suivant répertorie les attributs de <Allow> :

Attribut Description Par défaut Présence
count

Permet de spécifier le nombre de jetons pour le quota.

Par exemple, une valeur d'attribut count de 100, Interval de 1, et une valeur TimeUnit en mois spécifie un quota de 100 jetons par mois.

 2000 Facultatif
countRef

Permet de spécifier une variable de flux contenant le nombre de jetons d'un quota. countRef est prioritaire sur l'attribut count.

 aucun Facultatif

<Class>

Permet de conditionner la valeur de l'élément <Allow> en fonction de la valeur d'une variable de flux. Pour chaque tag enfant <Allow> différent de <Class>, la règle conserve un compteur différent.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Allow>
Éléments enfants <Allow> (enfant de <Class>)

Pour utiliser l'élément <Class>, spécifiez une variable de flux avec l'attribut ref de l'élément <Class>. Apigee utilise ensuite la valeur de la variable de flux pour sélectionner l'un des éléments enfants <Allow> afin de déterminer le décomtpe autorisé de la règle. Apigee met en correspondance la valeur de la variable de flux avec l'attribut class de l'élément <Allow>, comme indiqué ci-dessous :

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Dans cet exemple, le compteur de quota actuel est déterminé par la valeur du paramètre de requête time_variable transmis avec chaque requête. Cette variable peut avoir la valeur peak_time ou off_peak_time. Si le paramètre de requête contient une valeur non valide, la règle renvoie une erreur de non-respect du quota.

Le tableau suivant répertorie les attributs de <Class> :

Attribut Description Par défaut Présence
ref Permet de spécifier une variable de flux contenant la classe de quota pour un quota. aucun Obligatoire

<Allow> (enfant de <Class>)

Spécifie la limite d'un compteur de quota défini par l'élément <Class>. Pour chaque balise enfant <Allow> différente de <Class>, la règle conserve un compteur différent.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <Class>
Éléments enfants Aucune

Exemple :

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
    </Allow>

Dans cet exemple, la règle LLMTokenQuota gère deux compteurs de quota nommés peak_time et off_peak_time. Celui qui est utilisé dépend du paramètre de requête transmis, comme illustré dans l'exemple <Class>.

Le tableau suivant répertorie les attributs de <Allow> :

Attribut Description Par défaut Présence
class Définit le nom du compteur de quota. aucun Obligatoire
count Spécifie la limite de quota pour le compteur. aucun Obligatoire

<IgnoreUnresolvedVariables>

Détermine si le traitement de la règle LLMTokenQuota s'arrête si Apigee ne peut pas résoudre une variable référencée par l'attribut ref dans la règle.

Valeur par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Définissez la valeur sur true pour ignorer les variables non résolues et poursuivre le traitement, sinon false. La valeur par défaut est false.

Si <IgnoreUnresolvedVariables> est défini sur true et que la variable spécifiée dans un attribut ref ne peut pas être résolue, Apigee ignore l'attribut ref. Si l'élément contenant l'attribut ref contient également une valeur, telle que <Allow count="2000"/>, Apigee utilise cette valeur. S'il n'y a pas de valeur, Apigee considère que la valeur de l'élément est nulle et la remplace par la valeur par défaut, s'il y en a une, ou par une chaîne vide.

Si <IgnoreUnresolvedVariables> est défini sur false et que la variable spécifiée dans un attribut ref ne peut pas être résolue, Apigee renvoie une erreur.

<Interval>

Indique le nombre de périodes de calcul des quotas.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Entier
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Permet de spécifier un entier (par exemple, 1, 2, 5, 60, etc.) qui sera associé à l'élément <TimeUnit> que vous spécifiez (minute, heure, jour, semaine ou mois) pour déterminer une période pendant laquelle Apigee calcule l'utilisation du quota.

Par exemple, un intervalle de 24 avec une <TimeUnit> de hour signifie que le quota est calculé sur une période de 24 heures.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.interval">1</Interval>

Le tableau suivant répertorie les attributs de <Interval> :

Attribut Description Par défaut Présence
ref

Permet de spécifier une variable de flux contenant l'intervalle pour un quota. ref est prioritaire sur une valeur d'intervalle explicite. Si une référence et une valeur sont spécifiées, la valeur obtient la priorité. Si ref n'est pas renvoyé au moment de l'exécution, la valeur est utilisée.

 aucun Facultatif

<TimeUnit>

Spécifie l'unité de temps applicable au quota.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Sélectionnez minute, hour, day, week, month ou year.

Par exemple, un Interval de 24 avec une TimeUnit en hour signifie que le quota est calculé sur une période de 24 heures.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.timeunit">month</TimeUnit>

Le tableau suivant répertorie les attributs de <TimeUnit> :

Attribut Description Par défaut Présence
ref Spécifie une variable de flux contenant l'unité de temps d'un quota. ref a priorité sur une valeur d'intervalle explicite. Si ref n'est pas renvoyé au moment de l'exécution, la valeur d'intervalle est utilisée. aucun Facultatif

<StartTime>

Lorsque type est défini sur calendar, date et heure auxquelles le compteur de quota commence à comptabiliser, même si des requêtes ont été reçues à partir d'applications.

Valeur par défaut N/A
Obligatoire ? Facultatif (obligatoire lorsque type est défini sur calendar)
Type Chaîne de date et heure, au format ISO 8601
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Exemple :

<StartTime>2025-7-16 12:00:00</StartTime>

<Distributed>

Détermine si Apigee utilise un ou plusieurs nœuds pour traiter les requêtes.

Valeur par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Définissez la valeur sur true pour spécifier que la règle doit conserver un compteur central et le synchroniser en continu sur tous les nœuds. Les nœuds peuvent se trouver dans plusieurs zones et/ou régions de disponibilité.

Si vous utilisez la valeur par défaut false, vous risquez de dépasser votre quota, car le décompte de chaque nœud n'est pas partagé :

<Distributed>false</Distributed>

Pour garantir la synchronisation et la mise à jour des compteurs à chaque requête, définissez <Distributed> et <Synchronous> sur true :

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

Détermine si un compteur de quota distribué doit être mis à jour de manière synchrone.

Valeur par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Définissez la valeur sur true pour mettre à jour un compteur de quota distribué de manière synchrone. Cela signifie que les mises à jour des compteurs sont effectuées en même temps que le quota est vérifié pour une requête adressée à l'API. Définissez la valeur sur true s'il est essentiel de ne pas autoriser les appels d'API au-delà du quota.

Définissez la valeur sur false pour mettre à jour le compteur de quota de manière asynchrone. Cela signifie que certains appels d'API dépassant le quota peuvent passer, selon la fréquence de mise à jour asynchrone du compteur de quotas dans le répertoire central. Toutefois, vous ne serez pas affecté par les répercussions potentielles sur les performances associées aux mises à jour synchrones.

L'intervalle de mise à jour asynchrone par défaut est de 10 secondes. Utilisez l'élément <AsynchronousConfiguration> pour configurer ce comportement asynchrone.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configure l'intervalle de synchronisation entre les compteurs de quotas distribués lorsque l'élément de configuration de règle <Synchronous> n'est pas présent, ou présent et défini sur false. Apigee ignore cet élément lorsque <Synchronous> est défini sur true.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <LLMTokenQuota>
Éléments enfants <SyncIntervalInSeconds>
<SyncMessageCount>

Vous pouvez spécifier le comportement de synchronisation à l'aide des éléments enfants <SyncIntervalInSeconds> ou <SyncMessageCount>. Utilisez l'un ou l'autre de ces éléments, ou les deux. Exemple :

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

ou

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Lorsque seul <SyncIntervalInSeconds> est présent, le quota se synchronise toutes les N secondes, où N est la valeur spécifiée dans l'élément, quel que soit le nombre de messages traités.
  • Lorsque seul <SyncMessageCount> est présent, le quota se synchronise tous les M messages, où M est la valeur spécifiée dans l'élément, ou toutes les 10 secondes, selon la première occurrence.
  • Lorsque les deux éléments sont présents, le quota se synchronise tous les M messages ou toutes les N secondes, selon la première occurrence.
  • Lorsque <AsynchronousConfiguration> ou aucun élément enfant n'est présent, le quota se synchronise toutes les 10 secondes, quel que soit le nombre de messages traités.

<SyncIntervalInSeconds>

Remplace le comportement par défaut selon lequel les mises à jour asynchrones sont effectuées à un intervalle de 10 secondes.

Valeur par défaut 10 secondes
Obligatoire ? Facultatif
Type Entier
Élément parent <AsynchronousConfiguration>
Éléments enfants Aucune
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

L'intervalle de synchronisation doit être supérieur ou égal à 10 secondes, comme décrit dans la section Limites.

<SyncMessageCount>

Spécifie le nombre de requêtes à traiter avant de synchroniser le compteur de quotas.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Entier
Élément parent <AsynchronousConfiguration>
Éléments enfants Aucune
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

En utilisant la configuration de cet exemple, sur chaque nœud, le décompte de quota se synchronise toutes les cinq requêtes ou toutes les 10 secondes, selon la première échéance atteinte.

<LLMTokenUsageSource>

Fournit la source de l'utilisation du jeton à partir de la réponse du LLM. Il doit s'agir d'un modèle de message qui correspond à une seule valeur d'utilisation de jetons. Si la règle ne fait pas partie d'un flux d'événements et ne peut pas extraire le nombre de jetons de la source spécifiée, elle génère une erreur d'exécution policies.ratelimit.FailedToResolveTokenUsageCount.

Valeur par défaut {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
Obligatoire ? Facultatif
Type Chaîne
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

L'exemple suivant montre comment spécifier la source d'utilisation du jeton :

<LLMTokenUsageSource>{jsonPath('$.usageMetadata.candidatesTokenCount', response.content, true)}</LLMTokenUsageSource>

<LLMModelSource>

Fournit la source du nom du modèle à partir de la réponse du LLM ou de la requête du LLM. Il doit s'agir d'un modèle de message qui fournit une seule valeur de nom de modèle.

Valeur par défaut
Obligatoire ? Facultatif
Type Chaîne
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

L'exemple suivant montre comment spécifier la source du modèle à partir de la requête :

<LLMModelSource>{jsonPath('$.model', request.content, true)}</LLMModelSource>

<Identifier>

Configure la règle pour créer des compteurs uniques en fonction d'une variable de flux.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Via l'élément identificateur, vous pouvez attribuer des décomptes de jetons à des buckets distincts définis par la valeur d'une variable de flux. Par exemple, vous pouvez utiliser la variable developer.id, qui est renseignée après une règle VerifyAPIKey, pour appliquer une limite de quota à toutes les instances de toutes les applications créées par chaque développeur spécifique. Vous pouvez également utiliser le client_id pour appliquer une limite de quota à chaque application. La configuration de la dernière option ressemble à ceci :

<Identifier ref="client_id"/>

Vous pouvez faire référence à une variable personnalisée que vous pouvez définir dans la règle AssignMessage ou la règle JavaScript, ou une variable définie implicitement, comme les variables définies par la règle VerifyAPIKey ou la règle VerifyJWT. Pour en savoir plus sur les variables, consultez la section Utiliser des variables de flux. Pour obtenir la liste des variables connues définies par Apigee, consultez la documentation de référence sur les variables.

Si vous n'utilisez pas cet élément, la règle attribue tous les décomptes de jetons à un seul compteur pour la règle LLMTokenQuota spécifique.

Le tableau suivant décrit les attributs de <Identifier> :

Attribut Description Par défaut Présence
ref

Spécifie une variable de flux qui identifie le compteur à utiliser pour la requête. La variable peut faire référence à un en-tête HTTP, à un paramètre de requête, un paramètre de formulaire ou un élément du contenu du message, ou à une autre valeur permettant d'identifier la manière d'attribuer les décomptes de jetons.

client_id est couramment utilisé comme variable. client_id est également appelé clé API ou clé client, et est généré pour une application lorsqu'elle est enregistrée dans une organisation sur Apigee. Vous pouvez utiliser cet identifiant si vous avez activé une clé API ou des règles d'autorisation OAuth pour votre API.

 N/A Facultatif

<UseQuotaConfigInAPIProduct>

Définit les paramètres de quota pour un produit d'API, tels que les unités de temps, l'intervalle et le maximum autorisé.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <LLMTokenQuota>
Éléments enfants <DefaultConfig>

Si vous ajoutez l'élément <UseQuotaConfigInAPIProduct> à la règle LLMTokenQuota, Apigee ignore les éléments enfants <Allow>, <Interval> et <TimeUnit> de LLMTokenQuotaPolicy.

L'élément <UseQuotaConfigInAPIProduct> est simplement un conteneur pour les paramètres par défaut que vous définissez à l'aide de l'élément <DefaultConfig>, comme le montre l'exemple suivant :

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Vous pouvez utiliser l'attribut stepName pour faire référence à une règle VerifyAPIKey ou à une opération de règle ValidateToken de la règle OAuthv2 dans le flux.

Le tableau suivant décrit les attributs de <UseQuotaConfigInAPIProduct> :

Attribut Description Par défaut Présence
stepName Identifie le nom de la règle d'authentification dans le flux. La cible peut être une règle VerifyAPIKey ou une règle OAuthv2. N/A Obligatoire

Pour en savoir plus, consultez les ressources suivantes :

<DefaultConfig>

Contient les valeurs par défaut pour le quota d'un produit d'API. Lorsque vous définissez <DefaultConfig>, les trois éléments enfants sont requis.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Type complexe
Élément parent <UseQuotaConfigInAPIProduct>
Éléments enfants <Allow>
<Interval>
<TimeUnit>

Il est possible de définir ces valeurs sur l'opération du produit d'API (à l'aide de l'interface utilisateur ou de l'API des produits d'API) et dans la règle LLMTokenQuota. Toutefois, si vous le faites, les paramètres du produit d'API ont la priorité et les paramètres de la règle LLMTokenQuota sont ignorés.

La syntaxe de cet élément est la suivante :

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

L'exemple suivant spécifie un quota de 10 000 par semaine :

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Pour en savoir plus, consultez les ressources suivantes :

<SharedName>

Identifie cette règle LLMTokenQuota comme étant partagée. Toutes les règles LLMTokenQuota d'un proxy d'API ayant la même valeur <SharedName> partagent le même compteur de quota sous-jacent.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

Valeur par défaut N/A
Obligatoire ? Facultatif
Type Chaîne
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

<CountOnly>

Placez une règle LLMTokenQuota avec cet élément défini sur true dans une étape du flux de réponse ProxyEndpoint pour suivre le nombre de jetons sans renvoyer d'erreur au client lorsque la limite de quota de jetons est dépassée. Si cet élément est présent, l'élément <SharedName> doit également être présent et l'élément <EnforceOnly> ne doit pas l'être.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

Valeur par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

<EnforceOnly>

Placez une règle LLMTokenQuota avec cet élément défini sur true dans le flux de requête d'un proxy d'API pour appliquer une limite de jetons sans incrémenter le compteur de quota. Si cet élément est présent, l'élément <SharedName> doit également être présent et l'élément <CountOnly> ne doit pas l'être.

Pour en savoir plus et obtenir des exemples, consultez Configurer des compteurs de quota partagés.

Valeur par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <LLMTokenQuota>
Éléments enfants Aucune

Variables de flux

Les variables de flux prédéfinies suivantes sont automatiquement renseignées lorsqu'une règle LLMTokenQuota est exécutée. Pour en savoir plus, consultez la documentation de référence sur les variables de flux.

Variables Type Autorisations Description
ratelimit.{policy_name}.allowed.count Long En lecture seule Renvoie le décompte de quota autorisé.
ratelimit.{policy_name}.used.count Long En lecture seule Renvoie le quota actuel utilisé dans un intervalle de quota.
ratelimit.{policy_name}.available.count Long En lecture seule Renvoie le décompte de quota disponible dans l'intervalle de quota.
ratelimit.{policy_name}.exceed.count Long En lecture seule Renvoie 1 une fois le quota dépassé
ratelimit.{policy_name}.total.exceed.count Long En lecture seule Renvoie 1 une fois le quota dépassé
ratelimit.{policy_name}.expiry.time Long En lecture seule

Renvoie le temps UTC (en millisecondes) qui détermine la date d'expiration du quota et le début d'un nouvel intervalle.

Lorsque le type de règle LLMTokenQuota est rollingwindow, cette valeur n'est pas valide, car l'intervalle de quota n'expire jamais.

ratelimit.{policy_name}.identifier Chaîne En lecture seule Renvoie la référence de l'identifiant (client) associée à la règle.
ratelimit.{policy_name}.class Chaîne En lecture seule Renvoie la classe associée à l'identifiant client
ratelimit.{policy_name}.class.allowed.count Long En lecture seule Renvoie le nombre de quotas autorisés défini dans la classe
ratelimit.{policy_name}.class.used.count Long En lecture seule Renvoie le quota utilisé dans une classe
ratelimit.{policy_name}.class.available.count Long En lecture seule Renvoie le nombre de quotas disponibles dans la classe
ratelimit.{policy_name}.class.exceed.count Long En lecture seule Renvoie le nombre de jetons qui dépassent la limite définie dans la classe dans l'intervalle de quota actuel
ratelimit.{policy_name}.class.total.exceed.count Long En lecture seule Renvoie le nombre total de jetons qui dépassent la limite définie pour la classe parmi tous les intervalles de quotas. Il correspond donc à la somme de class.exceed.count pour tous les intervalles de quota.
ratelimit.{policy_name}.failed Booléen En lecture seule

Indique si la règle a échoué (vrai ou faux)
llmtokenquota.{policy_name}.model Chaîne En lecture seule Renvoie le modèle extrait.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause Corriger
policies.llmtokenquota.FailedToResolveModelName 400 Impossible de résoudre le nom du modèle. N/A
policies.llmtokenquota.FailedToResolveTokenUsageCount 500 Impossible de résoudre le nombre d'utilisations de jetons. N/A
policies.llmtokenquota.MessageTemplateExtractionFailed 400 Échec de l'extraction du modèle de message. N/A
policies.llmtokenquota.LLMTokenQuotaViolation 429 La limite de quota de jetons LLM a été dépassée. N/A
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Cette erreur se produit si l'élément <Interval> n'est pas défini dans la règle LLMTokenQuota. Cet élément est obligatoire et permet de spécifier l'intervalle de temps applicable au quota de jetons du LLM. L'intervalle de temps peut être exprimé en minutes, en heures, en jours, en semaines ou en mois, comme défini dans l'élément <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Cette erreur se produit si l'élément <TimeUnit> n'est pas défini dans la règle LLMTokenQuota. Cet élément est obligatoire et permet de spécifier l'unité de temps applicable au quota de jetons du LLM. L'intervalle de temps peut être exprimé en minutes, en heures, en jours, en semaines ou en mois.

Erreurs de déploiement

Nom de l'erreur Cause Corriger
policies.llmtokenquota.MessageWeightNotSupported Erreur lorsque l'élément "MessageWeight" est utilisé, car il n'est pas pris en charge. N/A
policies.llmtokenquota.InvalidConfiguration Une seule des options <CountOnly> ou <EnforceOnly> doit être définie sur "true". N/A
InvalidQuotaInterval Si l'intervalle de quota de jetons LLM spécifié dans l'élément <Interval> n'est pas un entier, le déploiement du proxy d'API échoue. Par exemple, si l'intervalle de quota spécifié est de 0,1 dans l'élément <Interval>, le déploiement du proxy d'API échoue.
InvalidQuotaTimeUnit Si l'unité de temps spécifiée dans l'élément <TimeUnit> n'est pas acceptée, le déploiement du proxy d'API échoue. Les unités de temps acceptées sont minute, hour, day, week et month.
InvalidQuotaType Si le type de quota de jetons LLM spécifié par l'attribut type dans l'élément <LLMTokenQuota> n'est pas valide, le déploiement du proxy d'API échoue. Les types de quotas acceptés sont default, calendar, flexi et rollingwindow.
InvalidStartTime Si le format de l'heure spécifiée dans l'élément <StartTime> n'est pas valide, le déploiement du proxy d'API échoue. Le format valide est yyyy-MM-dd HH:mm:ss. Il correspond au format de date et d'heure ISO 8601. Par exemple, si l'heure spécifiée dans l'élément <StartTime> est 7-16-2017 12:00:00, le déploiement du proxy d'API échoue.
StartTimeNotSupported Si l'élément <StartTime> est spécifié et que le type de quota n'est pas calendar, le déploiement du proxy d'API échoue. L'élément <StartTime> n'est disponible que pour le type de quota calendar. Par exemple, si l'attribut type est défini sur flexi ou rolling window dans l'élément <LLMTokenQuota>, le déploiement du proxy d'API échoue.
InvalidSynchronizeIntervalForAsyncConfiguration Si la valeur spécifiée pour l'élément <SyncIntervalInSeconds> au sein de l'élément <AsynchronousConfiguration> d'une règle LLMTokenQuota est inférieure à zéro, le déploiement du proxy d'API échoue.
InvalidAsynchronizeConfigurationForSynchronousQuota Si la valeur de l'élément <AsynchronousConfiguration> est définie sur true dans une règle LLMTokenQuota, dont la configuration asynchrone est définie à l'aide de l'élément <AsynchronousConfiguration>, le déploiement du proxy d'API échoue.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Variables Lieu Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "LLMTokenQuotaViolation"
ratelimit.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. ratelimit.QT-LLMTokenQuotaPolicy.failed = true

Exemple de réponse d'erreur

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.llmtokenquota.LLMTokenQuotaViolation"
      },
      "faultstring":"Rate limit LLM Token quota violation. Quota limit exceeded.

 Identifier : _default"
   }
}

Exemple de règle de défaillance

<FaultRules>
    <FaultRule name="LLMTokenQuota Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "LLMTokenQuotaViolation") </Condition>
        </Step>
        <Condition>ratelimit.LLMTokenQuota-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Schémas

Articles associés

Règle PromptTokenLimit