Policy PromptTokenLimit

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Panoramica

Il criterio 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 norma è pensata appositamente per le applicazioni LLM in cui il costo e il rendimento sono direttamente correlati al numero di token elaborati.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o 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, il criterio LLMTokenQuota viene utilizzato per applicare limiti di consumo alle app client per periodi più lunghi (ad esempio ore, giorni o mesi) per gestire i costi e applicare gli accordi 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>
      

Norme predefinite

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 del 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 su più elaboratori 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 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 su più processori di messaggi in una regione. Questa configurazione specifica viene utilizzata per il limite di token per richiesta della dimensione 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 del prompt si verifica all'interno di una singola replica e non viene distribuita su 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 la policy PromptTokenLimit possa essere applicata in base al client. Ad esempio, puoi raggruppare le richieste per ID sviluppatore, nel qual caso le richieste di ciascun sviluppatore verranno conteggiate ai fini della propria frequenza PromptTokenLimit e non tutte le richieste al proxy.

Se lasci vuoto l'elemento <Identifier>, viene applicato un limite di frequenza a tutte le richieste nel 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

L'esempio seguente 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 uniforme in fase di runtime accettando i valori dal client. Utilizza l'elemento <UseEffectiveCount> per impostare l'algoritmo di limitazione della 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 tasso validi (definiti come valore di variabile o nel corpo dell'elemento) devono rispettare il 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 velocità su cinque token al secondo:

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

Il criterio 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ò trattarsi di qualsiasi variabile di flusso, ad esempio un parametro di query HTTP, un'intestazione o il contenuto del corpo del messaggio oppure un valore come una KVM. Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso.

Puoi anche utilizzare variabili personalizzate utilizzando il criterio JavaScript o il criterio AssignMessage.

Se definisci sia ref che il corpo di questo elemento, il valore di ref viene applicato e 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 trasmette un'intestazione custom_rate, il cui valore è 10 ps, per tutti i client sul proxy, fino all'invio di una richiesta senza l'intestazione custom_rate.

Puoi utilizzare <Identifier> per raggruppare le richieste e 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 trasmette 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 un criterio è configurato 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 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 periodo all'inizio di un nuovo intervallo.

<UseEffectiveCount>

Questo elemento ti consente di scegliere tra diversi algoritmi PromptTokenLimit 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 (impostazione predefinita)

Se impostato su false (valore predefinito), il criterio 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 potenzialmente essere rifiutati.

Ad esempio, supponiamo che tu inserisca una velocità di 30 pm (30 token al minuto). Durante il test, potresti pensare di poter inviare 30 token in 1 secondo, purché vengano inviati entro un minuto. Tuttavia, non è così che la norma 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 uniformate in richieste complete consentite a 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 tariffe al secondo vengono uniformate in richieste complete consentite a intervalli di millisecondi.

    Ad esempio, 10ps vengono uniformati 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 ulteriori informazioni, consulta la sezione Riferimento alle 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 Indica se il criterio non è stato rispettato (true o false).
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 nelle norme.
ratelimit.POLICY_NAME.userPromptTokenCount Stringa Sola lettura Restituisce il conteggio dei token del prompt utente estratto.

Per ulteriori informazioni, consulta la sezione Riferimento alle variabili di flusso.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Potresti anche visualizzare Errori del criterio SpikeArrest. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione dei guasti.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice di errore Stato HTTP Errore Apigee Causa Correggi
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE Impossibile estrarre il prompt utente dalla richiesta API.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE Violazione di PromptTokenLimit.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 VERO I token non possono essere calcolati per il prompt utente.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Codice di errore Stato HTTP Errore Apigee Causa Correggi
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight non è supportato per il criterio PromptTokenLimit.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per saperne di più, consulta Cosa devi sapere sugli errori relativi alle norme.

Variabili Dove Esempio
ratelimit.policy_name.fault.name fault_name è il nome dell'errore, come elencato nella tabella degli errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di guasto. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Esempio di risposta di errore

Di seguito è riportato un esempio di risposta di errore:

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

Regola di errore di esempio

Di seguito è riportato un esempio di regola di errore per gestire un errore 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>

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

Schemi

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

Argomenti correlati