Policy PromptTokenLimit

Policy estensibile

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

La policy PromptTokenLimit protegge i backend dei modelli linguistici di grandi dimensioni (LLM) dai picchi di traffico limitando il numero di token nei prompt degli utenti.

La policy PromptTokenLimit è simile alla policy SpikeArrest; tuttavia, la policy SpikeArrest limita il numero di richieste, mentre la policy PromptTokenLimit limita il numero di token all'interno di queste richieste. Questa policy è pensata specificamente per le applicazioni LLM in cui il costo e le prestazioni sono direttamente correlati al numero di token elaborati.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Differenza tra PromptTokenLimit e LLMTokenQuota

Il criterio PromptTokenLimit viene utilizzato per la gestione del traffico operativo per prevenire picchi improvvisi nell'utilizzo dei token. Al contrario, la policy LLMTokenQuota viene utilizzata per applicare limiti di consumo alle app client per periodi più lunghi (ad esempio ore, giorni o mesi) per gestire i costi e applicare i contratti commerciali.

Elemento PromptTokenLimit

Definisce la policy PromptTokenLimit.

Valore predefinito Consulta la scheda Policy predefinita di seguito
Obbligatorio? Facoltativo
Tipo Oggetto complesso
Elemento principale N/D
Elementi secondari <Identifier>
<Rate> (obbligatorio)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

Sintassi

L'elemento PromptTokenLimit utilizza la seguente sintassi:

<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>

Policy predefinita

L'esempio seguente mostra le impostazioni predefinite quando aggiungi una policy PromptTokenLimit al tuo flusso nella UI:

<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>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo Predefinito Obbligatorio? Descrizione
name N/D Obbligatorio

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
continueOnError falso Facoltativo Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:
enabled true Facoltativo Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.
async   falso Ritirato Questo attributo è stato ritirato.

Esempi

Gli esempi riportati di seguito mostrano alcuni modi in cui puoi utilizzare il criterio PromptTokenLimit:

Esempio 1

Limitazione dei token di prompt all'interno di una singola replica.

In questo esempio, la limitazione dei token del prompt si verifica all'interno di una singola replica e non viene distribuita tra più processori di messaggi in una regione. 

<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>

Esempio 2

Limitazione dei token distribuiti.

In questo esempio, la limitazione dei token dei prompt è distribuita su più repliche in una regione e viene utilizzato un algoritmo di limitazione di frequenza "a finestra scorrevole".

<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>

Esempio 3

Limitazione dei token per richiesta in base alle dimensioni della finestra contestuale.

In questo esempio, la limitazione dei token del prompt si verifica all'interno di una singola replica e non viene distribuita tra più processori di messaggi in una regione. Questa configurazione specifica viene utilizzata per limitare i token per richiesta in base alle dimensioni della finestra contestuale.

<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>

Esempio 4

Limitazione dei token distribuiti con valori predefiniti.

In questo esempio, la limitazione dei token dei prompt avviene all'interno di una singola replica e non è distribuita tra più processori di messaggi in una regione. Viene utilizzato il valore predefinito dell'origine del prompt dell'utente: {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>

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <PromptTokenLimit>.

<DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso e più naturale.

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito N/D
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

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

Esempio

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

L'elemento <DisplayName> non ha attributi o elementi secondari.

<Identifier>

Consente di scegliere come raggruppare le richieste in modo che il criterio PromptTokenLimit possa essere applicato in base al client. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, nel qual caso le richieste di ogni sviluppatore verranno conteggiate ai fini della propria frequenza PromptTokenLimit e non tutte le richieste al proxy.

Se lasci vuoto l'elemento <Identifier>, viene applicata una limitazione di frequenza per tutte le richieste a quel proxy API.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <PromptTokenLimit>
Elementi secondari Nessuno

Sintassi

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

Esempio 1

Il seguente esempio applica il criterio PromptTokenLimit per ID sviluppatore:

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

La tabella seguente descrive gli attributi di <Identifier>:

Attributo Descrizione Predefinito Presenza
ref Identifica la variabile in base alla quale PromptTokenLimit raggruppa le richieste in entrata. Puoi utilizzare qualsiasi variabile di flusso per indicare un client univoco, ad esempio quelle disponibili con la policy VerifyAPIKey. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage. N/D Obbligatorio

<Rate>

Specifica la velocità con cui limitare i picchi (o i burst) di token impostando il numero di token consentiti a intervalli di minuti o secondi. Puoi utilizzare questo elemento insieme a <Identifier> per limitare il traffico in modo fluido in fase di runtime accettando i valori dal client. Utilizza l'elemento <UseEffectiveCount> per impostare l'algoritmo di limitazione di frequenza utilizzato dalla policy.

Valore predefinito N/D
Obbligatorio? Obbligatorio
Tipo Numero intero
Elemento principale <PromptTokenLimit>
Elementi secondari Nessuno

Sintassi

Puoi specificare le tariffe in uno dei seguenti modi:

  • Una tariffa statica che specifichi come corpo dell'elemento <Rate>
  • Un valore variabile, che può essere passato dal client; identifica il nome della variabile di flusso utilizzando l'attributo ref
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

I valori di tariffa validi (definiti come valore di una variabile o nel corpo dell'elemento) devono essere conformi al seguente formato:

  • intps (numero di token al secondo, suddivisi in intervalli di millisecondi)
  • intpm (numero di token al minuto, suddivisi in intervalli di secondi)

Il valore di int deve essere un numero intero positivo diverso da zero.

Esempio 1

L'esempio seguente imposta la frequenza su cinque token al secondo:

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

La policy uniforma la frequenza a un token consentito ogni 200 millisecondi (1000/5).

Esempio 2

L'esempio seguente imposta la velocità su 12 token al minuto:

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

Questa policy di esempio uniforma la frequenza a un token consentito ogni cinque secondi (60/12).

La tabella seguente descrive gli attributi di <Rate>:

Attributo Descrizione Presenza Predefinito
ref Identifica una variabile di flusso che specifica la tariffa. Può essere qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o un contenuto del corpo del messaggio, oppure un valore come un KVM. Per ulteriori informazioni, consulta Riferimento alle variabili di flusso.

Puoi anche utilizzare variabili personalizzate utilizzando la policy JavaScript o la policy AssignMessage.

Se definisci sia ref sia il corpo di questo elemento, viene applicato il valore di ref, che ha la precedenza quando la variabile di flusso viene impostata nella richiesta. (Il contrario è vero quando la variabile identificata in ref non è impostata nella richiesta.)

Ad esempio:

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

In questo esempio, se il client non passa un'intestazione custom_rate, la velocità per il proxy API è di 1 token al minuto per tutti i client. Se il client passa un'intestazione custom_rate, il cui valore è 10ps, per tutti i client sul proxy, finché non viene inviata una richiesta senza l'intestazione custom_rate.

Puoi utilizzare <Identifier> per raggruppare le richieste in modo da applicare tariffe personalizzate per diversi tipi di client.

Se specifichi un valore per ref, ma non imposti la tariffa nel corpo dell'elemento <Rate> e il client non passa un valore, il criterio PromptTokenLimit genera un errore.

 Facoltativo N/D
La tabella seguente descrive gli attributi di Rate che definiscono il comportamento di limitazione del traffico:
Attributo Descrizione
messagesPerPeriod Specifica il numero di token consentiti in un periodo definito. Ad esempio, se una policy è configurata per "10ps" (10 token al secondo), il valore di messagesPerPeriod sarà 10.
periodInMicroseconds Definisce il periodo di tempo, in microsecondi, durante il quale viene calcolato il valore messagesPerPeriod. Per una configurazione "10ps", questo valore sarebbe 1.000.000, che equivale a un secondo.
maxBurstMessageCount Rappresenta il numero massimo di token che possono essere consentiti istantaneamente o in un breve burst all'inizio di un nuovo intervallo.

<UseEffectiveCount>

Questo elemento ti consente di scegliere tra algoritmi PromptTokenLimit distinti impostando il valore su true o false, come spiegato di seguito:

true

Se impostato su true, PromptTokenLimit viene distribuito in una regione. Ciò significa che i conteggi delle richieste vengono sincronizzati tra i processori di messaggi (MP) in una regione. Inoltre, viene utilizzato un algoritmo di limitazione di frequenza "a finestra scorrevole". Questo algoritmo fornisce un comportamento coerente del limite di frequenza e non "uniforma" il numero di richieste in entrata che possono essere inviate al backend. Se viene inviato un burst di richieste in un breve intervallo di tempo, queste sono consentite a condizione che non superino il limite di frequenza configurato, come impostato nell'elemento <Rate>. Ad esempio:

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

false (predefinito)

Se impostata su false (valore predefinito), la policy PromptTokenLimit utilizza un algoritmo "token bucket" che attenua i picchi di token dividendo il limite di frequenza specificato in intervalli più piccoli. Uno svantaggio di questo approccio è che più token legittimi in arrivo in un breve intervallo di tempo possono essere potenzialmente rifiutati.

Ad esempio, supponiamo che tu inserisca una frequenza di 30pm (30 token al minuto). Durante i test, potresti pensare di poter inviare 30 token in 1 secondo, purché arrivino entro un minuto. Tuttavia, non è così che la policy applica l'impostazione. Se ci pensi, 30 token in un periodo di 1 secondo potrebbero essere considerati un mini picco in alcuni ambienti.

  • Le tariffe al minuto vengono distribuite in richieste complete consentite in intervalli di secondi.

    Ad esempio, 30pm viene uniformato in questo modo:
    60 secondi (1 minuto)/30pm = intervalli di 2 secondi o 1 token consentito ogni 2 secondi. Un secondo token entro 2 secondi non andrà a buon fine. Inoltre, un 31° token entro un minuto non andrà a buon fine.

  • Le frequenze al secondo vengono distribuite in richieste complete consentite in intervalli di millisecondi.

    Ad esempio, 10ps viene uniformato in questo modo:
    1000 millisecondi (1 secondo) / 10ps = intervalli di 100 millisecondi o 1 token consentito ogni 100 millisecondi. Un secondo token entro 100 ms non andrà a buon fine. Inoltre, un undicesimo token entro un secondo non andrà a buon fine.

Valore predefinito Falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <PromptTokenLimit>
Elementi secondari Nessuno

La tabella seguente descrive gli attributi dell'elemento <UseEffectiveCount>:

Attributo Descrizione Predefinito Presenza
ref Identifica la variabile che contiene il valore di <UseEffectiveCount>. Può essere qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio. Per saperne di più, consulta il riferimento per le variabili di flusso. Puoi anche impostare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage. N/D Facoltativo

<UserPromptSource>

Fornisce l'origine per il recupero del testo del prompt dell'utente. Utilizza un modello di messaggio.

Il modello di messaggio deve fornire un singolo valore del testo del prompt utente.

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

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <PromptTokenLimit>
Elementi secondari Nessuno

Sintassi

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

Esempio 1

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

<IgnoreUnresolvedVariables>

Determina se l'elaborazione si interrompe quando viene rilevata una variabile non risolta.

Imposta su true per ignorare le variabili non risolte e continuare l'elaborazione; altrimenti false. Il valore predefinito è false.

Valore predefinito Falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <PromptTokenLimit>
Elementi secondari Nessuno

Sintassi

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

Esempio

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

Variabili di flusso

Quando viene eseguita una norma PromptTokenLimit, vengono compilate le seguenti variabili di flusso:

Variabile Tipo Autorizzazione Descrizione
ratelimit.POLICY_NAME.failed Booleano Sola lettura Questa variabile è true se la policy ha riscontrato un errore di esecuzione interno. Questa variabile non deve essere utilizzata per verificare se è stato superato un limite di frequenza. Potrebbe essere impostato su true in caso di carico elevato a causa della progettazione "fail-open" della policy.
ratelimit.POLICY_NAME.resolvedUserPrompt Stringa Sola lettura Restituisce il prompt dell'utente estratto.
ratelimit.POLICY_NAME.userPromptSource Stringa Sola lettura Restituisce il modello di messaggio per il prompt dell'utente specificato nel criterio.
ratelimit.POLICY_NAME.userPromptTokenCount Stringa Sola lettura Restituisce il conteggio dei token del prompt utente estratto.

Per ulteriori informazioni, consulta il Riferimento per le variabili di flusso.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. You may also see SpikeArrest policy errors. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Apigee fault Cause Fix
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE Unable to extract the user prompt from the API request.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE PromptTokenLimit violation.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE Tokens cannot be calculated for the user prompt.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault code HTTP status Apigee fault Cause Fix
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight is not supported for the PromptTokenLimit policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
ratelimit.policy_name.fault.name fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Example error response

Shown below is an example error response:

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

Example fault rule

Shown below is an example fault rule to handle a PromptTokenLimitViolation fault:

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>Assign-Message-1</Name>
        </Step>
        <Condition>(fault.name Matches "PromptTokenLimitViolation")</Condition>
    </FaultRule>
</FaultRules>

Il codice di stato HTTP attuale per il superamento di un limite di frequenza impostato da una policy LLMTokenQuota o PromptTokenLimit è 429 (Troppe richieste).

Schemi

Ogni tipo di norma è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle norme sono disponibili su GitHub.

Argomenti correlati