Règle PromptTokenLimit

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

Consultez la documentation d'Apigee Edge.

Présentation

La règle PromptTokenLimit protège les backends de grands modèles de langage (LLM) contre les pics de trafic en limitant le nombre de jetons dans les requêtes utilisateur.

La règle PromptTokenLimit est semblable à la règle SpikeArrest. Toutefois, la règle SpikeArrest limite le nombre de requêtes, tandis que la règle PromptTokenLimit limite le nombre de jetons dans ces requêtes. Cette règle est spécifiquement conçue pour les applications LLM où le coût et les performances sont directement liés au nombre de jetons traités.

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.

Différence entre PromptTokenLimit et LLMTokenQuota

La règle PromptTokenLimit est utilisée pour la gestion du trafic opérationnel afin d'éviter les pics soudains d'utilisation de jetons. En revanche, la règle LLMTokenQuota est utilisée pour appliquer des limites de consommation aux applications clientes sur des périodes plus longues (heures, jours ou mois, par exemple) afin de gérer les coûts et d'appliquer les accords commerciaux.

Élément PromptTokenLimit

Définit la règle PromptTokenLimit.

Valeur par défaut Consultez l'onglet Règles par défaut ci-dessous.
Obligatoire ? Facultatif
Type Objet complexe
Élément parent ND
Éléments enfants <Identifier>
<Rate> (Obligatoire)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

Syntaxe

L'élément PromptTokenLimit utilise la syntaxe suivante :

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

Règle par défaut

L'exemple suivant présente les paramètres par défaut lorsque vous ajoutez une règle PromptTokenLimit à votre flux dans l'interface utilisateur :

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

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 avec un nom différent, en langage naturel.

continueOnError faux Facultatif 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 aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

Exemples

Les exemples suivants illustrent certaines des manières dont vous pouvez utiliser la règle PromptTokenLimit :

Exemple 1

Limitation des jetons de requête dans un seul réplica.

Dans cet exemple, la limitation des jetons d'invite se produit dans une seule réplique et n'est pas distribuée sur plusieurs processeurs de messages dans une région.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Exemple 2

Limitation des jetons distribués.

Dans cet exemple, la limitation des jetons d'invite est répartie sur plusieurs répliques dans une région, et un algorithme de limitation du débit "à fenêtre glissante" est utilisé.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

Exemple 3

Limitation de la taille de la fenêtre de contexte en jetons par requête.

Dans cet exemple, la limitation des jetons d'invite se produit dans une seule réplique et n'est pas répartie sur plusieurs processeurs de messages dans une région. Cette configuration spécifique est utilisée pour limiter le nombre de jetons de la taille de la fenêtre de contexte par requête.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Exemple 4

Limitation des jetons distribués avec des valeurs par défaut.

Dans cet exemple, la limitation des jetons d'invite se produit dans une seule réplique et n'est pas répartie sur plusieurs processeurs de messages dans une région. La valeur par défaut de la source d'invite utilisateur est utilisée : {jsonPath('$.messages',request.content,true)}

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Référence d'élément enfant

Cette section décrit les éléments enfants de <PromptTokenLimit>.

<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 et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut N/A
Obligatoire ? Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type Chaîne
Élément parent <PolicyElement>
Éléments enfants Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemple

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<Identifier>

Elle vous permet de choisir comment regrouper les requêtes afin de pouvoir appliquer la règle PromptTokenLimit en fonction du client. Par exemple, vous pouvez regrouper les requêtes par ID de développeur, auquel cas les requêtes de chaque développeur compteront pour leur propre débit PromptTokenLimit, et non toutes les requêtes adressées au proxy.

Si vous laissez l'élément <Identifier> vide, une limite de débit est appliquée à toutes les requêtes adressées à ce proxy d'API.

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

Syntaxe

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

Exemple 1

L'exemple suivant applique la règle PromptTokenLimit par ID de développeur :

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>
      

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

Attribut Description Par défaut Présence
ref Identifie la variable selon laquelle PromptTokenLimit regroupe les requêtes entrantes. Vous pouvez utiliser n'importe quelle variable de flux pour indiquer un client unique, telles que celle disponible dans la règle VerifyAPIKey. Vous pouvez également définir des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage. N/A Obligatoire

<Rate>

Indique le débit limite des pics de jetons (ou d'utilisation intensive) en définissant le nombre de jetons autorisés par minute ou par seconde. Vous pouvez utiliser cet élément conjointement avec <Identifier> afin de limiter de manière fluide le trafic au moment de l'exécution en acceptant les valeurs du client. Utilisez l'élément <UseEffectiveCount> pour définir l'algorithme de limitation du débit utilisé par la règle.

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

Syntaxe

Vous pouvez spécifier les débits de l'une des manières suivantes :

  • Un débit statique que vous spécifiez comme corps de l'élément <Rate>
  • Une valeur variable qui peut être transmise par le client ; identifiez le nom de la variable de flux à l'aide de l'attribut ref
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

Les valeurs de débit valides (définies en tant que valeur variable ou dans le corps de l'élément) doivent respecter le format suivant :

  • intps (nombre de jetons par seconde, lissé sur des intervalles de quelques millisecondes)
  • intpm (nombre de jetons par minute, lissé sur des intervalles de quelques secondes)

La valeur de int doit être un entier positif non nul.

Exemple 1

Dans l'exemple suivant, le débit est défini sur cinq jetons par seconde :

<PromptTokenLimit name="PTL-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>
        

La règle lisse le débit pour obtenir un jeton autorisé toutes les 200 millisecondes (1 000/5).

Exemple 2

Dans l'exemple suivant, le débit est défini sur 12 jetons par minute :

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Cet exemple de règle lisse le débit pour obtenir un jeton autorisé toutes les cinq secondes (60/12).

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

Attribut Description Présence Par défaut
ref Identifie une variable de flux qui spécifie le débit. Il peut s'agir de n'importe quelle variable de flux, telle qu'un paramètre de requête HTTP, un en-tête, le contenu du corps d'un message ou une valeur telle qu'une KVM. Pour en savoir plus, consultez la documentation de référence sur les variables de flux.

Vous pouvez également utiliser des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage.

Si vous définissez à la fois ref et le corps de cet élément, la valeur de ref est appliquée et est prioritaire lorsque la variable de flux est définie dans la requête. (L'inverse est vrai lorsque la variable identifiée dans ref n'est pas définie dans la requête.)

Exemple :

<Rate ref="request.header.custom_rate">1pm</Rate>

Dans cet exemple, si le client ne transmet pas d'en-tête custom_rate, le taux du proxy d'API est d'un jeton par minute pour tous les clients. Si le client transmet un en-tête custom_rate dont la valeur est 10ps, pour tous les clients sur le proxy, jusqu'à ce qu'une requête sans en-tête custom_rate soit envoyée.

Vous pouvez utiliser <Identifier> pour regrouper les requêtes afin d'appliquer des taux personnalisés à différents types de clients.

Si vous spécifiez une valeur pour ref, mais que vous ne définissez pas le débit dans le corps de l'élément <Rate> et que le client ne transmet pas de valeur, la règle PromptTokenLimit génère une erreur.

Facultatif N/A
Le tableau suivant décrit les attributs de Rate qui définissent le comportement de limitation du trafic :
Attribut Description
messagesPerPeriod Spécifie le nombre de jetons autorisés au cours d'une période définie. Par exemple, si une règle est configurée sur "10ps" (10 jetons par seconde), la valeur messagesPerPeriod sera de 10.
periodInMicroseconds Définit la période, en microsecondes, sur laquelle messagesPerPeriod est calculé. Pour une configuration "10 ps", cette valeur serait de 1 000 000, ce qui équivaut à une seconde.
maxBurstMessageCount Représente le nombre maximal de jetons pouvant être autorisés instantanément ou en rafale au début d'un nouvel intervalle.

<UseEffectiveCount>

Cet élément vous permet de choisir entre des algorithmes PromptTokenLimit distincts en définissant la valeur sur true ou false, comme expliqué ci-dessous :

vrai

Si la valeur est true, PromptTokenLimit est distribué dans une région. Cela signifie que le décompte des requêtes est synchronisé entre les processeurs de messages (MP) d'une même région. En outre, un algorithme de limitation du débit "à fenêtre glissante" est utilisé. Cet algorithme fournit un comportement de limitation de débit cohérent et ne "lisse" pas le nombre de requêtes entrantes pouvant être envoyées au backend. Si une rafale de requêtes est envoyée sur une courte période, elles sont autorisées tant qu'elles ne dépassent pas la limitation de débit configurée, telle que définie dans l'élément <Rate>. Exemple :

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false (valeur par défaut)

Si la valeur est false (valeur par défaut), la règle PromptTokenLimit utilise un algorithme "token bucket" qui lisse les pics de jetons en divisant la limite de débit que vous définissez en intervalles plus courts. L'inconvénient de cette approche est que plusieurs jetons légitimes qui arrivent sur une courte période peuvent être refusés.

Par exemple, supposons que vous saisissiez un débit de 30 pm (30 jetons par minute). Lors des tests, on pourrait imaginer envoyer 30 jetons en une seconde, à condition qu'ils arrivent dans la minute qui suit. Mais ce n'est pas ainsi que la règle s'applique. À bien y réfléchir, 30 jetons en une seconde pourraient être considérés comme un mini pic dans certains environnements.

  • Les débits par minute sont lissés pour obtenir un nombre de requêtes complètes autorisées par intervalles exprimés en secondes.

    Par exemple, un taux de 30 pm est lissé de la manière suivante :
    60 secondes (une minute) / 30 = 2 secondes, soit un jeton autorisé toutes les deux secondes. Une seconde requête dans un intervalle de deux secondes échouera. Une 31e requête de jeton dans un intervalle d'une minute échouera également.

  • Les débits par seconde sont lissés pour obtenir un nombre de requêtes complètes autorisées par intervalles exprimés en millisecondes.

    Par exemple, un débit de 10 ps est lissé comme suit :
    1 000 millisecondes (1 seconde) / 10 ps = 100 millisecondes d'intervalles ou un jeton autorisé toutes les 100 millisecondes. Un deuxième jeton dans un intervalle de 100 ms échouera. En outre, un 11e jeton dans un intervalle d'une seconde échouera.

Valeur par défaut Faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <PromptTokenLimit>
Éléments enfants Aucun

Le tableau suivant décrit les attributs de l'élément <UseEffectiveCount> :

Attribut Description Par défaut Présence
ref Identifie la variable contenant la valeur de <UseEffectiveCount>. Il peut s'agir de n'importe quelle variable de flux, telle qu'un paramètre de requête HTTP, un en-tête ou le contenu du corps du message. Pour en savoir plus, consultez la documentation de référence sur les variables de flux. Vous pouvez également définir des variables personnalisées à l'aide de la règle JavaScript ou de la règle AssignMessage. N/A Facultatif

<UserPromptSource>

Indique la source permettant de récupérer le texte de l'invite utilisateur. Utilisez un modèle de message.

Le modèle de message doit fournir une seule valeur pour le texte de la requête utilisateur.

Par exemple, {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}.

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

Syntaxe

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

Exemple 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

<IgnoreUnresolvedVariables>

Détermine si le traitement s'arrête lorsqu'une variable non résolue est rencontrée.

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.

Valeur par défaut Faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <PromptTokenLimit>
Éléments enfants Aucun

Syntaxe

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Exemple

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Variables de flux

Lorsqu'une règle PromptTokenLimit est exécutée, les variables de flux suivantes sont renseignées :

Variable Type Autorisation Description
ratelimit.POLICY_NAME.failed Booléen En lecture seule Indique si la règle a échoué (true ou false).
ratelimit.POLICY_NAME.resolvedUserPrompt Chaîne En lecture seule Renvoie la requête utilisateur extraite.
ratelimit.POLICY_NAME.userPromptSource Chaîne En lecture seule Renvoie le modèle de message pour la requête utilisateur spécifiée dans la règle.
ratelimit.POLICY_NAME.userPromptTokenCount Chaîne En lecture seule Renvoie le nombre de jetons de l'invite utilisateur extraite.

Pour en savoir plus, consultez la documentation de référence sur les variables de flux.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Vous pouvez également voir des erreurs liées à la règle SpikeArrest. 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 Erreur Apigee Cause Corriger
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE Impossible d'extraire la requête utilisateur de la requête API.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE Non-respect de la limite de jetons des requêtes.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE Les jetons ne peuvent pas être calculés pour la requête utilisateur.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Code d'erreur État HTTP Erreur Apigee Cause Corriger
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight n'est pas compatible avec la règle PromptTokenLimit.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez Ce que vous devez savoir sur les erreurs liées aux règles.

Variables Lieu Exemple
ratelimit.policy_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 "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Exemple de réponse d'erreur

Vous trouverez ci-dessous un exemple de réponse d'erreur :

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.prompttokenlimit.PromptTokenLimitViolation"
      },
      "faultstring":"Prompt Token Limit Violation. Allowed rate : MessageRate{capacity=10, period=Minutes}"
   }
}

Exemple de règle de défaillance

Vous trouverez ci-dessous un exemple de règle d'erreur pour gérer une erreur PromptTokenLimitViolation :

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "PromptTokenLimitViolation") </Condition>
        </Step>
        <Condition>ratelimit.PTL-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Le code d'état HTTP actuel pour le dépassement d'une limite de débit définie par une règle LLMTokenQuota ou PromptTokenLimit est "429" (trop de requêtes).

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Articles associés