policy LLMTokenQuota

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

Visualizza la documentazione di Apigee Edge.

Panoramica

La policy LLMTokenQuota è progettata per gestire e controllare il consumo di token per i workload AI/LLM. Poiché le interazioni con i modelli linguistici di grandi dimensioni (LLM) sono basate su token, una gestione efficace è fondamentale per il controllo dei costi, l'ottimizzazione delle prestazioni e la stabilità della piattaforma.

Una quota è una quantità di token LLM (input o output) che un proxy API può utilizzare in un periodo di tempo, ad esempio minuti, ore, giorni, settimane o mesi. I criteri LLMTokenQuota gestiscono i contatori che conteggiano il numero di token utilizzati dal proxy API. Questa funzionalità consente ai fornitori di API di applicare limiti al consumo di token da parte delle app in un intervallo di tempo.

Questa norma utilizza gli elementi <LLMTokenUsageSource> e <LLMModelSource> per estrarre il conteggio dei token dalla risposta dell'LLM e il nome del modello dalla richiesta o dalla risposta, consentendo l'applicazione precisa e in tempo reale della quota.

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.

Come funziona l'applicazione della quota di token LLM

Di seguito viene descritta la funzionalità del criterio LLMTokenQuota:

  • Conteggio dei token (<CountOnly>): La policy LLMTokenQuota gestisce i contatori che monitorano il numero di token consumati dalle risposte LLM che passano attraverso il proxy API.
  • Applicazione dei limiti (<EnforceOnly>): Questa funzionalità consente ai fornitori di API di impostare limiti rigorosi al numero di token utilizzati dalle applicazioni in un intervallo definito. Ad esempio, puoi limitare le applicazioni a 1000 token al minuto o 10.000.000 di token al mese.
  • Superamento della quota:quando un proxy API raggiunge il limite di quota di token definito, Apigee rifiuta le richieste successive che consumano token. Viene restituito un messaggio di errore finché il contatore LLMTokenQuota non viene reimpostato automaticamente al termine dell'intervallo di tempo specificato. Ad esempio, se una quota è impostata su 10.000 token al mese, la limitazione dei token inizia una volta conteggiato il 10.000° token, indipendentemente dal momento del mese in cui viene raggiunto il limite.

Come funziona LLMTokenQuota con i prodotti API

Di seguito viene descritto il funzionamento del criterio LLMTokenQuota con i prodotti API:

proxy flow for LLMTokenQuota
  1. Applica il criterio VerifyAPIKey o VerifyAccessToken insieme al criterio di applicazione LLMTokenQuota nella richiesta del proxy API (il proxy o il target non ha importanza).
  2. Applica il criterio di conteggio LLMTokenQuota in risposta al proxy API (il proxy o la destinazione non sono importanti).
  3. Il criterio VerifyAPIKey o VerifyAccessToken corrisponde alla chiave o al token con prodotto API, insieme di operazioni, sviluppatore e app. Espone le variabili di flusso per la quota LLM per tutti i modelli degli insiemi di operazioni LLM corrispondenti.
  4. All'interno delle norme di applicazione della quota, estraiamo il modello in base al modello di messaggio fornito.
  5. Vengono quindi abbinate le variabili di quota LLM per il modello. Se viene trovata una corrispondenza, i riferimenti vengono inseriti.
  6. Una volta inseriti i riferimenti, questi valori vengono utilizzati per eseguire le operazioni di quota.

Come funziona LLMTokenQuota con le risposte SSE

Per far funzionare LLMTokenQuota con le risposte SSE, aggiungi il criterio come parte del flusso di eventi come mostrato di seguito:

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

Durante l'elaborazione dello stream di eventi, il conteggio dei token viene eseguito solo quando i metadati sull'utilizzo dei token della risposta LLM vengono trovati nell'evento. Quando vengono rilevati i metadati sull'utilizzo dei token, questi vengono estratti e il criterio viene eseguito. Per tutti gli altri eventi, le norme comportano NO-OP.

Tipi di policy LLMTokenQuota

Il criterio LLMTokenQuota supporta diversi modi in cui il contatore della quota inizia e si azzera. Puoi definire quale utilizzare con l'attributo type nell'elemento <LLMTokenQuota>, come mostrato nell'esempio seguente:

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

I valori validi di type includono:

  • calendar: configura una quota in base a un orario di inizio esplicito. Il contatore LLMTokenQuota per ogni app viene aggiornato in base ai valori <StartTime>, <Interval> e <TimeUnit> che hai impostato.
  • rollingwindow: configura una quota che utilizza una finestra mobile per determinare l'utilizzo della quota. Con rollingwindow, determini le dimensioni della finestra con gli elementi <Interval> e <TimeUnit>, ad esempio 1 giorno. Quando arriva una richiesta, Apigee esamina l'ora esatta della richiesta (ad esempio le 17:01), conta il numero di token consumati tra quell'ora e le 17:01 del giorno precedente (1 giorno) e determina se la quota è stata superata durante quella finestra.
  • flexi: configura una quota che fa iniziare il conteggio quando viene ricevuto il primo messaggio di richiesta da un'app e si azzera in base ai valori <Interval> e <TimeUnit>.

La tabella seguente descrive quando viene reimpostata la quota per ogni tipo:

Unità di tempo Tipo
default (o null) calendar flexi
minuto Inizio del minuto successivo Un minuto dopo le ore <StartTime> Un minuto dopo la prima richiesta
ora Inizio dell'ora successiva Un'ora dopo <StartTime> Un'ora dopo la prima richiesta
giorno Mezzanotte GMT del giorno corrente 24 ore dopo <StartTime> 24 ore dopo la prima richiesta
settimana Mezzanotte GMT di domenica alla fine della settimana Una settimana dopo <StartTime> Una settimana dopo la prima richiesta
mese Mezzanotte GMT dell'ultimo giorno del mese Un mese (28 giorni) dopo <StartTime> Un mese (28 giorni) dopo la prima richiesta

Per type="calendar", devi specificare il valore di <StartTime>.

La tabella non descrive quando viene reimpostato il conteggio per il tipo rollingwindow. Questo perché le quote della finestra mobile funzionano in modo leggermente diverso, in base a una finestra temporale, ad esempio un'ora o un giorno. Per il tipo rollingwindow, il contatore non viene mai reimpostato, ma viene ricalcolato a ogni richiesta. Quando arriva una nuova richiesta, la policy determina se la quota è stata superata nel periodo di tempo precedente.

Ad esempio, definisci una finestra di due ore che consente 1000 token. Una nuova richiesta arriva alle 16:45.Il criterio calcola il conteggio della quota per la finestra delle due ore precedenti, ovvero il numero di token consumati dalle 14:45. Se il limite di quota non è stato superato in questo intervallo di due ore, la richiesta è consentita.

Un minuto dopo, alle 16:46, arriva un'altra richiesta. Ora il criterio calcola il conteggio delle quote dalle ore 14:46 per determinare se il limite è stato superato.

Informazioni sui contatori delle quote

Quando un criterio LLMTokenQuota viene eseguito nel flusso di un proxy API, un contatore delle quote viene incrementato. Quando il contatore raggiunge il limite, non sono consentite ulteriori chiamate API associate a quel contatore. A seconda della configurazione utilizzata per il prodotto API, la policy LLMTokenQuota può utilizzare un singolo contatore o più contatori indipendenti. È importante comprendere gli scenari in cui verranno utilizzati più contatori e il loro comportamento.

Configurazione delle impostazioni di quota per i prodotti API

Un prodotto API può specificare le impostazioni di quota a livello di prodotto o a livello di singola operazione o entrambi. Se il proxy API è incluso in un prodotto API, puoi configurare i criteri LLMTokenQuota in modo da utilizzare le impostazioni di quota (conteggio consentito, unità di tempo e intervallo) definite in quel prodotto. Il modo più semplice per farlo è tramite l'elemento useQuotaConfigInAPIProduct. In alternativa, puoi fare riferimento a queste impostazioni nel criterio LLMTokenQuota tramite riferimenti a singole variabili.

Come vengono conteggiate le quote

Per impostazione predefinita, Apigee gestisce un contatore di quota separato per ogni operazione definita in un prodotto API e vengono rispettate le seguenti regole:

  • Se per un'operazione è definita una quota, le impostazioni della quota dell'operazione hanno la precedenza sulle impostazioni della quota definite a livello di prodotto.
  • Se per un'operazione non è definita una quota, vengono applicate le impostazioni della quota a livello di prodotto.
  • Se il prodotto API non include impostazioni di quota, né a livello di prodotto né di operazione, vengono applicate le impostazioni di quota per il conteggio consentito, l'unità di tempo e l'intervallo specificati nella policy LLMTokenQuota.

In tutti i casi, Apigee mantiene un contatore di quota separato per ogni operazione definita in un prodotto API. Tutte le chiamate API che corrispondono a un'operazione incrementano il relativo contatore.

Configurazione dei contatori a livello di proxy API

È possibile configurare un prodotto API per mantenere un conteggio della quota a livello di proxy API. In questo caso, la configurazione della quota specificata a livello di prodotto API viene condivisa da tutte le operazioni per le quali non è specificata una quota propria. L'effetto di questa configurazione è la creazione di un contatore a livello di proxy API per questo prodotto API.

Per ottenere questa configurazione, devi utilizzare l'API/apiproducts Apigee per creare o aggiornare il prodotto e impostare l'attributo quotaCounterScope su PROXY nella richiesta di creazione o aggiornamento. Con la configurazione PROXY, le richieste corrispondenti a una qualsiasi delle operazioni definite per il prodotto API associate allo stesso proxy e che non hanno impostazioni di quota proprie condivideranno un contatore di quota comune per quel proxy.

Nella Figura 1, le operazioni 1 e 2 sono associate a Proxy1, mentre le operazioni 4 e 5 sono associate a Proxy3. Poiché quotaCounterScope=PROXY è impostato nel prodotto API, ciascuna di queste operazioni utilizza l'impostazione della quota a livello di prodotto API. Le operazioni 1 e 2, associate a Proxy1, utilizzano un contatore condiviso, mentre le operazioni 4 e 5, associate a Proxy3, utilizzano un contatore condiviso separato. L'operazione 3 ha una propria impostazione di configurazione della quota e, per questo motivo, utilizza un proprio contatore, indipendentemente dal valore dell'attributo quotaCounterScope.

Figura 1: utilizzo del flag quotaCounterScope

Come vengono conteggiate le quote se non vengono utilizzati prodotti API

Se non è presente alcun prodotto API associato a un proxy API, un criterio LLMTokenQuota mantiene un singolo contatore, indipendentemente dal numero di volte in cui viene fatto riferimento in un proxy API. Il nome del contatore della quota si basa sull'attributo name del criterio.

Ad esempio, crei una policy LLMTokenQuota denominata MyLLMTokenQuotaPolicy con un limite di 5 token e la inserisci in più flussi (A, B e C) nel proxy API. Anche se viene utilizzato in più flussi, mantiene un unico contatore aggiornato da tutte le istanze del criterio. Supponendo che la risposta LLM abbia utilizzato 1 token ogni volta:

  • Il flusso A viene eseguito -> MyLLMTokenQuotaPolicy viene eseguito e il relativo contatore = 1
  • Il flusso B viene eseguito -> MyLLMTokenQuotaPolicy viene eseguito e il relativo contatore = 2
  • Il flusso A viene eseguito -> MyLLMTokenQuotaPolicy viene eseguito e il relativo contatore = 3
  • Viene eseguito il flusso C -> Viene eseguita MyLLMTokenQuotaPolicy e il relativo contatore = 4
  • Il flusso A viene eseguito -> MyLLMTokenQuotaPolicy viene eseguito e il suo contatore = 5

La richiesta successiva a uno dei tre flussi viene rifiutata perché il contatore della quota ha raggiunto il limite.

L'utilizzo della stessa policy LLMTokenQuota in più posizioni nel flusso di un proxy API, che può causare involontariamente l'esaurimento di LLMTokenQuota più rapidamente del previsto, è un anti-pattern descritto in Introduzione agli anti-pattern.

In alternativa, puoi definire più criteri LLMTokenQuota nel proxy API e utilizzare un criterio diverso in ogni flusso. Ogni criterio LLMTokenQuota mantiene il proprio contatore, in base all'attributo name del criterio.

Creazione di più contatori tramite la configurazione dei criteri

Puoi utilizzare gli elementi <Class> o <Identifier> nel criterio LLMTokenQuota per definire più contatori unici in un unico criterio. Utilizzando questi elementi, una singola norma può mantenere contatori diversi in base all'app che effettua la richiesta, al suo sviluppatore, a un ID client o a un altro identificatore client e altro ancora. Per ulteriori informazioni sull'utilizzo degli elementi <Class> o <Identifier>, consulta gli esempi riportati sopra.

Notazione temporale

Tutti gli orari di LLMTokenQuota sono impostati sul fuso orario Coordinated Universal Time (UTC).

La notazione temporale LLMTokenQuota segue la notazione temporale standard internazionale definita nello standard internazionale ISO 8601.

Le date sono definite come anno, mese e giorno, nel seguente formato: YYYY-MM-DD. Ad esempio, 2025-02-04 rappresenta il 4 febbraio 2025.

L'ora del giorno è definita come ore, minuti e secondi nel seguente formato: hours:minutes:seconds. Ad esempio, 23:59:59 rappresenta l'ora un secondo prima di mezzanotte.

Tieni presente che sono disponibili due notazioni, 00:00:00 e 24:00:00, per distinguere le due mezzanotte che possono essere associate a una data. Pertanto, 2025-02-04 24:00:00 corrisponde alla stessa data e ora di 2025-02-05 00:00:00. Quest'ultima è di solito la notazione preferita.

Recupero delle impostazioni di quota dalla configurazione del prodotto API

Puoi impostare limiti di quota nelle configurazioni dei prodotti API. Questi limiti non applicano automaticamente la quota. In alternativa, puoi fare riferimento alle impostazioni delle quote di prodotto in una norma LLMTokenQuota. Ecco alcuni vantaggi dell'impostazione di una quota sul prodotto a cui fare riferimento per le norme LLMTokenQuota:

  • I criteri LLMTokenQuota possono utilizzare un'impostazione uniforme in tutti i proxy API nel prodotto API.
  • Puoi apportare modifiche in fase di runtime all'impostazione della quota di un prodotto API e i criteri LLMTokenQuota che fanno riferimento al valore hanno automaticamente valori di quota aggiornati.

Per ulteriori informazioni sull'utilizzo delle impostazioni di quota di un prodotto API, consulta l'esempio di quota dinamica.

Per informazioni sulla configurazione dei prodotti API con limiti di quota, vedi Gestione dei prodotti API.

Configurazione dei contatori delle quote condivise

Nel caso semplice, il criterio LLMTokenQuota incrementa il contatore una volta per ogni token inviato a un proxy API durante l'elaborazione della richiesta iniziale. In alcuni casi, potresti voler verificare se la quota viene superata durante la gestione iniziale della richiesta in entrata, ma incrementare il contatore solo durante la gestione della risposta.

Tre elementi della policy LLMTokenQuota, <SharedName>, <CountOnly> e <EnforceOnly>, se utilizzati insieme, ti consentono di personalizzare la policy LLMTokenQuota per applicare la quota alle richieste in entrata, ma solo incrementare il contatore nel flusso di risposta.

Ad esempio, supponi di avere un proxy API che utilizza un LLM come target e di voler applicare una quota di 100.000 token all'ora. Le risposte del LLM forniscono un valore totalTokenCount. Per farlo:

  • Collega un criterio LLMTokenQuota al flusso di richiesta ProxyEndpoint con l'elemento <SharedName> impostato con un valore di nome e l'elemento <EnforceOnly> impostato su true.
  • Utilizza l'elemento <LLMTokenUsageSource> nel criterio LLMTokenQuota per recuperare il conteggio dei token

Per un esempio che mostra come utilizzare i contatori condivisi, consulta Contatori condivisi nella sezione Esempi.

Esempi

Questi esempi di codice delle norme mostrano come iniziare e terminare i periodi di quota:

Più Dynamic LLMTokenQuota

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

Le quote dinamiche ti consentono di configurare un singolo criterio LLMTokenQuota che applica impostazioni di quota diverse in base alle informazioni trasmesse al criterio LLMTokenQuota. Un altro termine per le impostazioni di LLMTokenQuota in questo contesto è piano di servizio. LLMTokenQuota dinamico controlla il piano di servizio delle app e poi applica queste impostazioni.

Ad esempio, quando crei un prodotto API, puoi impostare facoltativamente il limite di quota consentito, l'unità di tempo e l'intervallo. Tuttavia, l'impostazione di questi valori nel prodotto API non ne impone l'utilizzo in un proxy API. Devi anche aggiungere una policy LLMTokenQuota al proxy API che legge questi valori. Per saperne di più, consulta Crea prodotti API.

Nell'esempio precedente, il proxy API contenente la policy LLMTokenQuota utilizza una policy VerifyAPIKey, denominata verify-api-key, per convalidare la chiave API trasmessa in una richiesta. Il criterio LLMTokenQuota accede quindi alle variabili di flusso dal criterio VerifyAPIKey per leggere i valori di quota impostati sul prodotto API.

Un'altra opzione è impostare attributi personalizzati per singoli sviluppatori o app, quindi leggere questi valori nel criterio LLMTokenQuota. Ad esempio, per impostare valori di quota diversi per sviluppatore, imposta attributi personalizzati per lo sviluppatore contenenti il limite, l'unità di tempo e l'intervallo. Fai riferimento a questi valori nel criterio LLMTokenQuota come mostrato di seguito:

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

Questo esempio utilizza anche le variabili di flusso VerifyAPIKey per fare riferimento agli attributi personalizzati impostati sullo sviluppatore.

Puoi utilizzare qualsiasi variabile per impostare i parametri del criterio LLMTokenQuota. Queste variabili possono provenire da:

  • Variabili di flusso
  • Proprietà del prodotto API, dell'app o dello sviluppatore
  • Una mappa di coppie chiave-valore (KVM)
  • Un'intestazione, un parametro di query, un parametro del modulo e altri

Per ogni proxy API, puoi aggiungere un criterio LLMTokenQuota che fa riferimento alla stessa variabile di tutti gli altri criteri LLMTokenQuota in tutti gli altri proxy oppure può fare riferimento a variabili univoche per quel criterio e proxy.

Ora di inizio

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

Per un LLMTokenQuota con type impostato su calendar, devi definire un valore <StartTime> esplicito. Il valore temporale è l'ora GMT, non l'ora locale. Se non fornisci un valore <StartTime> per un criterio di tipo calendar, Apigee genera un errore.

Il contatore LLMTokenQuota per ogni app viene aggiornato in base ai valori <StartTime>, <Interval> e <TimeUnit>. Per questo esempio, la quota di token LLM inizia a essere conteggiata alle 10:30 GMT del 18 febbraio 2025 e viene aggiornata ogni 5 ore. Pertanto, il prossimo aggiornamento è alle 15:30 GMT del 18 febbraio 2025.

Contatore accessi

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

Un proxy API ha accesso alle variabili di flusso impostate dal criterio LLMTokenQuota. Puoi accedere a queste variabili di flusso nel proxy API per eseguire l'elaborazione condizionale, monitorare la policy quando si avvicina al limite di quota, restituire il contatore della quota corrente a un'app o per altri motivi.

Poiché l'accesso alle variabili di flusso per la policy si basa sull'attributo name, per la policy precedente denominata <LLMTokenQuota> accedi alle relative variabili di flusso nel formato:

  • ratelimit.LLMTokenQuotaPolicy.allowed.count: conteggio consentito.
  • ratelimit.LLMTokenQuotaPolicy.used.count: valore attuale del contatore.
  • ratelimit.LLMTokenQuotaPolicy.expiry.time: l'ora UTC in cui il contatore viene reimpostato.

Come descritto di seguito, puoi accedere a molte altre variabili di flusso.

Ad esempio, puoi utilizzare la seguente policy AssignMessage per restituire i valori delle variabili di flusso LLMTokenQuota come intestazioni di risposta:

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

Contatori condivisi

L'esempio seguente mostra come configurare un contatore condiviso per un proxy API, in cui il contatore della quota viene incrementato anche quando la risposta di destinazione è lo stato HTTP 200. Poiché entrambi i criteri LLMTokenQuota utilizzano lo stesso valore <SharedName>, entrambi i criteri LLMTokenQuota condivideranno lo stesso contatore di quote. Per saperne di più, consulta Configurazione dei contatori delle quote condivise.

Esempio di configurazione di 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>

Primo esempio di criterio 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>

Secondo esempio di criterio 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>

Prima richiesta

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

Utilizza questo codice campione per applicare una quota di 10.000 token all'ora. Le norme reimpostano il contatore della quota all'inizio di ogni ora. Se il contatore raggiunge la quota di 10.000 token prima della fine dell'ora, le chiamate API che consumano token oltre 10.000 vengono rifiutate.

Ad esempio, se il contatore inizia da 2025-07-08 07:00:00, si azzera a 0 alle 2025-07-08 08:00:00 (1 ora dall'ora di inizio). Se la prima richiesta viene ricevuta alle ore 2025-07-08 07:35:28 e il conteggio dei token raggiunge 10.000 prima delle ore 2025-07-08 08:00:00, le richieste che consumano token oltre questo conteggio vengono rifiutate fino al reset del conteggio all'inizio dell'ora.

Il tempo di ripristino del contatore si basa sulla combinazione di <Interval> e <TimeUnit>. Ad esempio, se imposti <Interval> su 12 per un <TimeUnit> di ora, il contatore viene reimpostato ogni 12 ore. Puoi impostare <TimeUnit> su minuti, ore, giorni, settimane o mesi.

Puoi fare riferimento a questo criterio in più punti del proxy API. Ad esempio, puoi inserirlo nel Proxy PreFlow in modo che venga eseguito a ogni richiesta. In alternativa, puoi posizionarlo in più flussi nel proxy API. Se utilizzi questo criterio in più posizioni nel proxy, viene mantenuto un unico contatore aggiornato da tutte le istanze del criterio.

In alternativa, puoi definire più criteri LLMTokenQuota nel proxy API. Ogni criterio LLMTokenQuota mantiene il proprio contatore, in base all'attributo name del criterio.

Imposta identificatore

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

Per impostazione predefinita, una policy LLMTokenQuota definisce un singolo contatore per il proxy API, indipendentemente dall'origine di una richiesta. In alternativa, puoi utilizzare l'attributo <Identifier> con un criterio LLMTokenQuota per mantenere contatori separati in base al valore dell'attributo <Identifier>.

Ad esempio, utilizza il tag <Identifier> per definire contatori separati per ogni ID client. In una richiesta al proxy, l'app client passa quindi un'intestazione contenente clientID, come mostrato nell'esempio precedente.

Puoi specificare qualsiasi variabile di flusso per l'attributo <Identifier>. Ad esempio, potresti specificare che un parametro di query denominato id contiene l'identificatore univoco:

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

Se utilizzi il criterio VerifyAPIKey per convalidare la chiave API o i criteri OAuthV2 con token OAuth, puoi utilizzare le informazioni nella chiave API o nel token per definire singoli contatori per lo stesso criterio LLMTokenQuota. Ad esempio, il seguente elemento <Identifier> utilizza la variabile di flusso client_id di una norma VerifyAPIKey denominata verify-api-key:

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

Ogni valore univoco di client_id ora definisce un proprio contatore nel criterio 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>

Puoi impostare i limiti di LLMTokenQuota in modo dinamico utilizzando un conteggio LLMTokenQuota basato sulla classe. In questo esempio, il limite di quota è determinato dal valore dell'intestazione developer_segment trasmessa con ogni richiesta. Questa variabile può avere un valore di platinum o silver. Se l'intestazione ha un valore non valido, il criterio restituisce un errore di violazione della quota.

I seguenti esempi illustrano varie configurazioni della policy LLMTokenQuota.

Calcola token

Questo esempio mostra come calcolare i token.

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

Variabili dinamiche della quota di conteggio utilizzando prodotto API, sviluppatore e app

Questo esempio mostra come conteggiare le variabili dinamiche delle quote utilizzando prodotto API, sviluppatore e app.

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

Applica la quota senza prodotto API

Questo esempio mostra come applicare la quota senza un prodotto 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>

Applicare la quota con prodotto API, sviluppatore e app

Questo esempio mostra come applicare la quota con prodotto API, sviluppatore e app.

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

Con stream SSE

Questo esempio mostra come utilizzare LLMTokenQuota con un flusso SSE.

Policy di conteggio della quota di token:

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

Flusso di eventi:

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

Elemento <LLMTokenQuota>

Di seguito sono riportati gli attributi e gli elementi secondari di <LLMTokenQuota>. Tieni presente che alcune combinazioni di elementi sono reciprocamente esclusive o non obbligatorie. Consulta gli esempi per un utilizzo specifico.

Le variabili verifyapikey.my-verify-key-policy.apiproduct.* di seguito sono disponibili per impostazione predefinita quando viene utilizzata una norma VerifyAPIKey chiamata my-verify-key-policy per controllare la chiave API dell'app nella richiesta. I valori delle variabili provengono dalle impostazioni di quota del prodotto API a cui è associata la chiave, come descritto in Recuperare le impostazioni di quota dalla configurazione del prodotto 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>

I seguenti attributi sono specifici di queste norme:

Attributo Descrizione Predefinito Presenza
type

Imposta il tipo di criterio LLMTokenQuota, che determina quando e come il contatore delle quote controlla l'utilizzo delle quote e come viene reimpostato.

Se non imposti type, il contatore inizia all'inizio del minuto/ora/giorno/settimana/mese.

I valori validi includono:

  • calendar
  • rollingwindow
  • flexi

Per una descrizione completa di ogni tipo, consulta Tipi di policy LLMTokenQuota.

 N/D Facoltativo

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presence
name

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.

 N/D Obbligatorio
continueOnError

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:

 falso Facoltativo
enabled

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.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Deprecato

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence Facoltativo
Tipo Stringa

<Allow>

Specifica il numero totale di token consentiti per l'intervallo di tempo specificato. Se il contatore del criterio raggiunge questo valore limite, le chiamate API successive vengono rifiutate finché il contatore non viene reimpostato.

Può contenere anche un elemento <Class> che condiziona l'elemento <Allow> in base a una variabile di flusso.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Tipo intero o complesso
Elemento principale <LLMTokenQuota>
Elementi secondari <Class>

Di seguito sono riportati tre modi per impostare l'elemento <Allow>:

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

Se specifichi sia count che countRef, countRef ha la priorità. Se countRef non viene risolto in fase di runtime, viene utilizzato il valore di count.

Puoi anche specificare un elemento <Class> come elemento secondario di <Allow> per determinare il conteggio consentito del criterio in base a una variabile di flusso. Apigee associa il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

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

La tabella seguente elenca gli attributi di <Allow>:

Attributo Descrizione Predefinito Presenza
count

Utilizza questo campo per specificare un conteggio dei token per la quota.

Ad esempio, un valore dell'attributo count pari a 100, un valore dell'attributo Interval pari a 1 e un valore dell'attributo TimeUnit pari a mese specificano una quota di 100 token al mese.

 2000 Facoltativo
countRef

Utilizza questo attributo per specificare una variabile di flusso contenente il conteggio dei token per una quota. countRef ha la precedenza sull'attributo count.

 nessuno Facoltativo

<Class>

Consente di condizionare il valore dell'elemento <Allow> in base al valore di una variabile di flusso. Per ogni tag figlio <Allow> diverso di <Class>, i criteri mantengono un contatore diverso.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <Allow>
Elementi secondari <Allow> (figlio di <Class>)

Per utilizzare l'elemento <Class>, specifica una variabile di flusso utilizzando l'attributo ref dell'elemento <Class>. Apigee utilizza quindi il valore della variabile di flusso per selezionare uno degli elementi secondari <Allow> per determinare il conteggio consentito del criterio. Apigee associa il valore della variabile di flusso all'attributo class dell'elemento <Allow>, come mostrato di seguito:

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

In questo esempio, il contatore della quota corrente è determinato dal valore del parametro di query time_variable passato con ogni richiesta. Questa variabile può avere un valore di peak_time o off_peak_time. Se il parametro di query contiene un valore non valido, il criterio restituisce un errore di violazione della quota.

La tabella seguente elenca gli attributi di <Class>:

Attributo Descrizione Predefinito Presenza
ref Utilizza questa opzione per specificare una variabile di flusso contenente la classe di quota per una quota. nessuno Obbligatorio

<Allow> (figlio di <Class>)

Specifica il limite per un contatore di quota definito dall'elemento <Class>. Per ogni tag figlio <Allow> diverso di <Class>, i criteri mantengono un contatore diverso.

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

Ad esempio:

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

In questo esempio, il criterio LLMTokenQuota gestisce due contatori di quota denominati peak_time e off_peak_time. L'utilizzo di uno o dell'altro dipende dal parametro di query passato, come mostrato nell'esempio <Class>.

La tabella seguente elenca gli attributi di <Allow>:

Attributo Descrizione Predefinito Presenza
class Definisce il nome del contatore della quota. nessuno Obbligatorio
count Specifica il limite di quota per il contatore. nessuno Obbligatorio

<IgnoreUnresolvedVariables>

Determina se l'elaborazione della policy LLMTokenQuota si interrompe se Apigee non riesce a risolvere una variabile a cui fa riferimento l'attributo ref nella policy.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

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

Se <IgnoreUnresolvedVariables> è impostato su true e la variabile specificata in un attributo ref non può essere risolta, Apigee ignora l'attributo ref. Se l'elemento contenente l'attributo ref contiene anche un valore, ad esempio <Allow count="2000"/>, Apigee utilizza questo valore. Se non è presente alcun valore, Apigee considera il valore dell'elemento come null e sostituisce il valore predefinito, se presente, o una stringa vuota.

Se <IgnoreUnresolvedVariables> è false e la variabile specificata in un attributo ref non può essere risolta, Apigee restituisce un errore.

<Interval>

Specifica il numero di periodi di tempo in cui vengono calcolate le quote.

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

Utilizza questo campo per specificare un numero intero (ad esempio 1, 2, 5, 60 e così via) che verrà abbinato all'elemento <TimeUnit> specificato (minuto, ora, giorno, settimana o mese) per determinare un periodo di tempo durante il quale Apigee calcola l'utilizzo della quota.

Ad esempio, un intervallo di 24 con un <TimeUnit> di hour significa che la quota verrà calcolata nell'arco di 24 ore.

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

La tabella seguente elenca gli attributi di <Interval>:

Attributo Descrizione Predefinito Presenza
ref

Utilizza questa opzione per specificare una variabile di flusso contenente l'intervallo per una quota. ref ha la precedenza su un valore di intervallo esplicito. Se vengono specificati sia il riferimento che il valore, il riferimento ha la priorità. Se ref non viene risolto in fase di runtime, viene utilizzato il valore.

 nessuno Facoltativo

<TimeUnit>

Specifica l'unità di tempo applicabile alla quota.

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

Scegli tra minute, hour, day, week, month o year.

Ad esempio, un Interval di 24 con un TimeUnit di hour significa che la quota verrà calcolata nell'arco di 24 ore.

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

La tabella seguente elenca gli attributi di <TimeUnit>:

Attributo Descrizione Predefinito Presenza
ref Specifica una variabile di flusso contenente l'unità di tempo per una quota. ref ha la precedenza su un valore di intervallo esplicito. Se ref non viene risolto in fase di runtime, viene utilizzato il valore dell'intervallo. nessuno Facoltativo

<StartTime>

Quando type è impostato su calendar, specifica la data e l'ora in cui inizia il conteggio del contatore della quota, indipendentemente dal fatto che siano state ricevute richieste da qualsiasi app.

Valore predefinito N/D
Obbligatorio? (Facoltativo, obbligatorio se type è impostato su calendar)
Tipo Stringa nel formato data e ora ISO 8601
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

Ad esempio:

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

<Distributed>

Determina se Apigee utilizza uno o più nodi per elaborare le richieste.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

Imposta true per specificare che il criterio deve mantenere un contatore centrale e sincronizzarlo continuamente su tutti i nodi. I nodi possono trovarsi in zone di disponibilità e/o regioni diverse.

Se utilizzi il valore predefinito di false, potresti superare la quota perché il conteggio per ogni nodo non è condiviso:

<Distributed>false</Distributed>

Per garantire che i contatori siano sincronizzati e aggiornati a ogni richiesta, imposta <Distributed> e <Synchronous> su true:

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

<Synchronous>

Determina se aggiornare in modo sincrono un contatore di quota distribuita.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

Imposta su true per aggiornare in modo sincrono un contatore di quota distribuita. Ciò significa che gli aggiornamenti ai contatori vengono eseguiti contemporaneamente alla verifica della quota in una richiesta all'API. Imposta true se è essenziale non consentire chiamate API oltre la quota.

Imposta false per aggiornare il contatore della quota in modo asincrono. Ciò significa che è possibile che alcune chiamate API che superano la quota vengano eseguite, a seconda di quando viene aggiornato in modo asincrono il contatore delle quote nel repository centrale. Tuttavia, non dovrai affrontare i potenziali impatti sulle prestazioni associati agli aggiornamenti sincroni.

L'intervallo di aggiornamento asincrono predefinito è di 10 secondi. Utilizza l'elemento <AsynchronousConfiguration> per configurare questo comportamento asincrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura l'intervallo di sincronizzazione tra i contatori delle quote distribuite quando l'elemento di configurazione del criterio <Synchronous> non è presente o è presente e impostato su false. Apigee ignora questo elemento quando <Synchronous> è impostato su true.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <LLMTokenQuota>
Elementi secondari <SyncIntervalInSeconds>
<SyncMessageCount>

Puoi specificare il comportamento di sincronizzazione utilizzando gli elementi secondari <SyncIntervalInSeconds> o <SyncMessageCount>. Utilizza uno o entrambi gli elementi. Ad esempio,

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

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Quando è presente solo <SyncIntervalInSeconds>, la quota si sincronizza ogni N secondi, dove N è il valore specificato nell'elemento, indipendentemente dal numero di messaggi gestiti.
  • Quando è presente solo <SyncMessageCount>, la quota si sincronizza ogni M messaggi, dove M è il valore specificato nell'elemento o ogni 10 secondi, a seconda dell'evento che si verifica per primo.
  • Quando sono presenti entrambi gli elementi, la quota viene sincronizzata ogni M messaggi o ogni N secondi, a seconda dell'evento che si verifica per primo.
  • Quando <AsynchronousConfiguration> non è presente o non è presente alcun elemento secondario, la quota viene sincronizzata ogni 10 secondi, indipendentemente dal numero di messaggi gestiti.

<SyncIntervalInSeconds>

Esegue l'override del comportamento predefinito in cui gli aggiornamenti asincroni vengono eseguiti dopo un intervallo di 10 secondi.

Valore predefinito 10 secondi
Obbligatorio? Facoltativo
Tipo Numero intero
Elemento principale <AsynchronousConfiguration>
Elementi secondari Nessuno
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

L'intervallo di sincronizzazione deve essere >= 10 secondi, come descritto in Limiti.

<SyncMessageCount>

Specifica il numero di richieste da elaborare prima di sincronizzare il contatore della quota.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Numero intero
Elemento principale <AsynchronousConfiguration>
Elementi secondari Nessuno
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Utilizzando la configurazione in questo esempio, su ogni nodo il conteggio delle quote verrà sincronizzato dopo ogni 5 richieste o ogni 10 secondi, a seconda dell'evento che si verifica per primo.

<LLMTokenUsageSource>

Fornisce l'origine dell'utilizzo dei token dalla risposta LLM. Deve essere un modello di messaggio che si risolve in un singolo valore di utilizzo dei token. Se la norma non fa parte di un flusso di eventi e non è possibile estrarre il conteggio dei token dall'origine specificata, viene generato un errore di runtime policies.ratelimit.FailedToResolveTokenUsageCount.

Valore predefinito {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

L'esempio seguente mostra come specificare l'origine dell'utilizzo dei token:

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

<LLMModelSource>

Fornisce l'origine del nome del modello dalla risposta o dalla richiesta LLM. Deve essere un modello di messaggio che fornisce un singolo valore del nome del modello.

Valore predefinito
Obbligatorio? Facoltativo
Tipo Stringa
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

L'esempio seguente mostra come specificare l'origine del modello dalla richiesta:

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

<Identifier>

Configura il criterio per creare contatori unici in base a una variabile di flusso.

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

Tramite l'elemento Identificatore, puoi assegnare conteggi di token a bucket distinti definiti dal valore di una variabile di flusso. Ad esempio, puoi utilizzare la variabile developer.id, che viene compilata dopo una policy VerifyAPIKey, per applicare un limite di quota a tutte le istanze di tutte le app create da ogni sviluppatore specifico oppure puoi utilizzare client_id per applicare un limite di quota a ogni app specifica. La configurazione per quest'ultima è la seguente:

<Identifier ref="client_id"/>

Puoi fare riferimento a una variabile personalizzata che potresti impostare con il criterio AssignMessage o il criterio JavaScript oppure a una variabile impostata implicitamente, ad esempio quelle impostate dal criterio VerifyAPIKey o dal criterio VerifyJWT. Per saperne di più sulle variabili, consulta Utilizzo delle variabili di flusso. Per un elenco delle variabili note definite da Apigee, consulta il riferimento alle variabili di flusso.

Se non utilizzi questo elemento, il criterio assegna tutti i conteggi dei token a un unico contatore per il criterio LLMTokenQuota specifico.

La tabella seguente descrive gli attributi di <Identifier>:

Attributo Descrizione Predefinito Presenza
ref

Specifica una variabile di flusso che identifica il contatore da utilizzare per la richiesta. La variabile può fare riferimento a un'intestazione HTTP, a un parametro di query, a un parametro del modulo o a un elemento del contenuto del messaggio oppure a un altro valore per identificare come assegnare i conteggi dei token.

client_id viene comunemente utilizzato come variabile. client_id è nota anche come chiave API o chiave consumer e viene generata per un'app quando viene registrata in un'organizzazione su Apigee. Puoi utilizzare questo identificatore se hai abilitato le norme di autorizzazione OAuth o della chiave API per la tua API.

 N/D Facoltativo

<UseQuotaConfigInAPIProduct>

Definisce le impostazioni di quota per un prodotto API, ad esempio le unità di tempo, l'intervallo e il massimo consentito.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <LLMTokenQuota>
Elementi secondari <DefaultConfig>

Se aggiungi l'elemento <UseQuotaConfigInAPIProduct> alla policy LLMTokenQuota, Apigee ignora gli elementi secondari <Allow>, <Interval> e <TimeUnit> di LLMTokenQuotaPolicy.

L'elemento <UseQuotaConfigInAPIProduct> è semplicemente un contenitore per le impostazioni predefinite che definisci utilizzando l'elemento <DefaultConfig>, come mostrato nell'esempio seguente:

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

Puoi utilizzare l'attributo stepName per fare riferimento a un'operazione di criterio VerifyAPIKey o a un'operazione di criterio ValidateToken del criterio OAuthv2 nel flusso.

La tabella seguente descrive gli attributi di <UseQuotaConfigInAPIProduct>:

Attributo Descrizione Predefinito Presenza
stepName Identifica il nome della policy di autenticazione nel flusso. Il target può essere un criterio VerifyAPIKey o un criterio OAuthv2. N/D Obbligatorio

Per ulteriori informazioni, consulta le seguenti risorse:

<DefaultConfig>

Contiene i valori predefiniti per la quota di un prodotto API. Quando definisci un <DefaultConfig>, tutti e tre gli elementi secondari sono obbligatori.

Valore predefinito N/D
Obbligatorio? Facoltativo
Tipo Tipo complesso
Elemento principale <UseQuotaConfigInAPIProduct>
Elementi secondari <Allow>
<Interval>
<TimeUnit>

È possibile definire questi valori sia nell'operazione del prodotto API (tramite la UI o l'API API products) sia nel criterio LLMTokenQuota. Se lo fai, tuttavia, le impostazioni del prodotto API hanno la precedenza e le impostazioni della norma LLMTokenQuota vengono ignorate.

La sintassi di questo elemento è la seguente:

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

L'esempio seguente specifica una quota di 10.000 ogni settimana:

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

Per ulteriori informazioni, consulta le seguenti risorse:

<SharedName>

Identifica questo criterio LLMTokenQuota come condiviso. Tutti i criteri LLMTokenQuota in un proxy API con lo stesso valore <SharedName> condividono lo stesso contatore di quote sottostante.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori di quota condivisi.

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

<CountOnly>

Inserisci una policy LLMTokenQuota con questo elemento impostato su true in un passaggio del flusso di risposta ProxyEndpoint per monitorare il numero di token senza inviare un errore al client quando il limite di quota di token viene superato. Se questo elemento è presente, deve essere presente anche l'elemento <SharedName> e non deve essere presente l'elemento <EnforceOnly>.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori delle quote condivise.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

<EnforceOnly>

Inserisci una policy LLMTokenQuota con questo elemento impostato su true nel flusso di richiesta di un proxy API per applicare un limite di token senza incrementare il contatore della quota. Se questo elemento è presente, deve essere presente anche <SharedName> e l'elemento <CountOnly> non deve essere presente.

Per ulteriori informazioni ed esempi, consulta Configurazione dei contatori delle quote condivise.

Valore predefinito falso
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <LLMTokenQuota>
Elementi secondari Nessuno

Variabili di flusso

Le seguenti variabili di flusso predefinite vengono compilate automaticamente quando viene eseguita una policy LLMTokenQuota. Per ulteriori informazioni, consulta Riferimento alle variabili di flusso.

Variabili Tipo Autorizzazioni Descrizione
ratelimit.{policy_name}.allowed.count Lungo Sola lettura Restituisce il conteggio della quota consentita.
ratelimit.{policy_name}.used.count Lungo Sola lettura Restituisce la quota attuale utilizzata all'interno di un intervallo di quota.
ratelimit.{policy_name}.available.count Lungo Sola lettura Restituisce il conteggio della quota disponibile nell'intervallo di quota.
ratelimit.{policy_name}.exceed.count Lungo Sola lettura Restituisce 1 dopo il superamento della quota.
ratelimit.{policy_name}.total.exceed.count Lungo Sola lettura Restituisce 1 dopo il superamento della quota.
ratelimit.{policy_name}.expiry.time Lungo Sola lettura

Restituisce l'ora UTC (in millisecondi), che determina la scadenza della quota e l'inizio del nuovo intervallo di quota.

Quando il tipo del criterio LLMTokenQuota è rollingwindow, questo valore non è valido perché l'intervallo di quota non scade mai.

ratelimit.{policy_name}.identifier Stringa Sola lettura Restituisce il riferimento all'identificatore (client) allegato alle norme.
ratelimit.{policy_name}.class Stringa Sola lettura Restituisce la classe associata all'identificatore client
ratelimit.{policy_name}.class.allowed.count Lungo Sola lettura Restituisce il conteggio della quota consentita definita nella classe
ratelimit.{policy_name}.class.used.count Lungo Sola lettura Restituisce la quota utilizzata all'interno di un corso
ratelimit.{policy_name}.class.available.count Lungo Sola lettura Restituisce il conteggio delle quote disponibili nella classe
ratelimit.{policy_name}.class.exceed.count Lungo Sola lettura Restituisce il conteggio dei token che superano il limite nella classe nell'intervallo di quota corrente
ratelimit.{policy_name}.class.total.exceed.count Lungo Sola lettura Restituisce il conteggio totale dei token che superano il limite nella classe in tutti gli intervalli di quota, quindi è la somma di class.exceed.count per tutti gli intervalli di quota.
ratelimit.{policy_name}.failed Booleano Sola lettura

Indica se il criterio non è stato rispettato (true o false).
llmtokenquota.{policy_name}.model Stringa Sola lettura Restituisce il modello estratto.

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 genera un errore. 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 Causa Correggi
policies.llmtokenquota.FailedToResolveModelName 400 Impossibile risolvere il nome del modello. N/D
policies.llmtokenquota.FailedToResolveTokenUsageCount 500 Impossibile risolvere il conteggio dell'utilizzo dei token. N/D
policies.llmtokenquota.MessageTemplateExtractionFailed 400 L'estrazione del modello di messaggio non è riuscita. N/D
policies.llmtokenquota.LLMTokenQuotaViolation 429 Il limite di quota token LLM è stato superato. N/D
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Si verifica se l'elemento <Interval> non è definito all'interno della policy LLMTokenQuota. Questo elemento è obbligatorio e viene utilizzato per specificare l'intervallo di tempo applicabile alla quota di token LLM. L'intervallo di tempo può essere minuti, ore, giorni, settimane o mesi, come definito con l'elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Si verifica se l'elemento <TimeUnit> non è definito all'interno della policy LLMTokenQuota. Questo elemento è obbligatorio e viene utilizzato per specificare l'unità di tempo applicabile alla quota di token LLM. L'intervallo di tempo può essere espresso in minuti, ore, giorni, settimane o mesi.

Errori di deployment

Nome dell'errore Causa Correggi
policies.llmtokenquota.MessageWeightNotSupported Errore quando viene utilizzato l'elemento "MessageWeight", in quanto non è supportato. N/D
policies.llmtokenquota.InvalidConfiguration Esattamente uno dei valori <CountOnly> o <EnforceOnly> deve essere impostato su true. N/D
InvalidQuotaInterval Se l'intervallo della quota di token LLM specificato nell'elemento <Interval> non è un numero intero, il deployment del proxy API non va a buon fine. Ad esempio, se l'intervallo di quota specificato è 0,1 nell'elemento <Interval>, il deployment del proxy API non va a buon fine.
InvalidQuotaTimeUnit Se l'unità di tempo specificata nell'elemento <TimeUnit> non è supportata, il deployment del proxy API non va a buon fine. Le unità di tempo supportate sono minute, hour, day, week e month.
InvalidQuotaType Se il tipo di quota di token LLM specificato dall'attributo type nell'elemento <LLMTokenQuota> non è valido, il deployment del proxy API non riesce. I tipi di quota supportati sono default, calendar, flexi e rollingwindow.
InvalidStartTime Se il formato dell'ora specificata nell'elemento <StartTime> non è valido, il deployment del proxy API non va a buon fine. Il formato valido è yyyy-MM-dd HH:mm:ss, che è il formato data e ora ISO 8601. Ad esempio, se l'ora specificata nell'elemento <StartTime> è 7-16-2017 12:00:00, il deployment del proxy API non va a buon fine.
StartTimeNotSupported Se viene specificato l'elemento <StartTime> il cui tipo di quota non è calendar, il deployment del proxy API non va a buon fine. L'elemento <StartTime> è supportato solo per il tipo di quota calendar. Ad esempio, se l'attributo type è impostato su flexi o rolling window nell'elemento <LLMTokenQuota>, il deployment del proxy API non va a buon fine.
InvalidSynchronizeIntervalForAsyncConfiguration Se il valore specificato per l'elemento <SyncIntervalInSeconds> all'interno dell'elemento <AsynchronousConfiguration> in un criterio LLMTokenQuota è inferiore a zero, il deployment del proxy API non riesce.
InvalidAsynchronizeConfigurationForSynchronousQuota Se il valore dell'elemento <AsynchronousConfiguration> è impostato su true in un criterio LLMTokenQuota, che ha anche una configurazione asincrona definita utilizzando l'elemento <AsynchronousConfiguration>, il deployment del proxy API non va a buon fine.

Variabili di errore

Queste variabili vengono impostate quando questo criterio genera un errore. Per saperne di più, consulta Cosa devi sapere sugli errori relativi alle norme.

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

Esempio di risposta di errore

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

 Identifier : _default"
   }
}

Regola di errore di esempio

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

Schemi

Argomenti correlati

PromptTokenLimit policy