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 Se vuoi, utilizza l'elemento |
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 Ad esempio: <Rate ref="request.header.custom_rate">1pm</Rate> In questo esempio, se il client non passa un'intestazione Puoi utilizzare Se specifichi un valore per |
Facoltativo | N/D |
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
- Norma LLMTokenQuota: norma LLMTokenQuota, per limitare l'utilizzo della quota di token di risposta.
- Limitazione di frequenza per una panoramica della limitazione di frequenza
- Confronto tra criteri di limitazione di frequenza