Política LLMTokenQuota

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Vista geral

A política LLMTokenQuota foi concebida para gerir e controlar o consumo de tokens para cargas de trabalho de IA/LLM. Uma vez que as interações com grandes modelos de linguagem (LLMs) se baseiam em tokens, a gestão eficaz é crucial para o controlo de custos, a otimização do desempenho e a estabilidade da plataforma.

Uma quota é uma atribuição de tokens de MDIs (entrada ou saída) que um proxy de API tem autorização para consumir durante um período, como um minuto, uma hora, um dia, uma semana ou um mês. A política LLMTokenQuota mantém contadores que registam o número de tokens consumidos pelo proxy da API. Esta capacidade permite que os fornecedores de APIs apliquem limites ao consumo de tokens por apps durante um intervalo de tempo.

Esta política usa os elementos <LLMTokenUsageSource> e <LLMModelSource> para extrair a contagem de tokens da resposta do MDG e o nome do modelo do pedido ou da resposta, o que permite uma aplicação precisa da quota em tempo real.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Como funciona a aplicação da LLMTokenQuota

Segue-se uma descrição da funcionalidade da política LLMTokenQuota:

  • Contagem de tokens (<CountOnly>): A política LLMTokenQuota mantém contadores que monitorizam o número de tokens consumidos pelas respostas do MDG que passam pelo proxy da API.
  • Aplicação de limites (<EnforceOnly>): esta capacidade permite aos fornecedores de APIs definir limites rigorosos para o número de tokens consumidos pelas aplicações durante um intervalo definido. Por exemplo, pode limitar as aplicações a 1000 tokens por minuto ou 10 000 000 de tokens por mês.
  • Exceder a quota: quando um proxy de API atinge o limite de quota de tokens definido, o Apigee rejeita os pedidos subsequentes que consomem tokens. É devolvida uma mensagem de erro até que o contador LLMTokenQuota seja reposto automaticamente no final do intervalo de tempo especificado. Por exemplo, se for definida uma quota de 10 000 tokens por mês, a limitação de tokens começa assim que o 10 000.º token for contabilizado, independentemente do momento do mês em que esse limite for atingido.

Como o LLMTokenQuota funciona com produtos de API

A descrição seguinte explica como a política LLMTokenQuota funciona com os produtos de API:

Fluxo de proxy para LLMTokenQuota
  1. Aplique a política VerifyAPIKey ou VerifyAccessToken juntamente com a política de aplicação LLMTokenQuota no pedido do proxy de API (o proxy ou o destino não são importantes).
  2. Aplique a política de contagem LLMTokenQuota em resposta ao proxy da API (o proxy ou o destino não são importantes).
  3. A política VerifyAPIKey ou VerifyAccessToken corresponde à chave ou ao token com o produto da API, o conjunto de operações, o programador e a app. Expõe as variáveis de fluxo para a quota de MDIs para todos os modelos dos conjuntos de operações de MDIs correspondentes.
  4. Na política de aplicação de quotas, extraímos o modelo de acordo com o modelo de mensagem fornecido.
  5. Em seguida, as variáveis de quota do MDG são associadas ao modelo. Se for encontrada uma correspondência, as referências são injetadas.
  6. Depois de as referências serem injetadas, esses valores são usados para realizar as operações de quota.

Como o LLMTokenQuota funciona com respostas SSE

Para fazer com que o LLMTokenQuota funcione com respostas SSE, adicione a política como parte do fluxo de eventos, conforme mostrado abaixo:

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

Durante o processamento da stream de eventos, a contagem de tokens só é executada quando os metadados de utilização de tokens da resposta do MDG são encontrados no evento. Quando os metadados de utilização de tokens são descobertos, são extraídos e a política é executada. Para todos os outros eventos, a política resulta em NO-OP.

Tipos de políticas LLMTokenQuota

A política LLMTokenQuota suporta várias formas diferentes de iniciar e repor o contador de quotas. Pode definir qual usar com o atributo type no elemento <LLMTokenQuota>, como mostra o exemplo seguinte:

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

Os valores válidos de type incluem:

  • calendar: configura uma quota com base numa hora de início explícita. O contador LLMTokenQuota de cada app é atualizado com base nos valores <StartTime>, <Interval> e <TimeUnit> que definir.
  • rollingwindow: configura uma quota que usa uma janela contínua para determinar a utilização da quota. Com rollingwindow, determina o tamanho da janela com os elementos <Interval> e <TimeUnit>; por exemplo, 1 dia. Quando chega um pedido, o Apigee analisa a hora exata do pedido (por exemplo, 17:01), conta o número de tokens consumidos entre esse momento e as 17:01 do dia anterior (1 dia) e determina se a quota foi excedida ou não durante esse período.
  • flexi: configura uma quota que faz com que o contador comece quando a primeira mensagem de pedido é recebida de uma app e é reposta com base nos valores <Interval> e <TimeUnit>.

A tabela seguinte descreve quando a quota é reposta para cada tipo:

Unidade de tempo Tipo
default (ou nulo) calendar flexi
minuto Início do minuto seguinte Um minuto depois de <StartTime> Um minuto após o primeiro pedido
hora Início da próxima hora Uma hora após <StartTime> Uma hora após o primeiro pedido
dia Meia-noite GMT do dia atual 24 horas após <StartTime> 24 horas após o primeiro pedido
semana Domingo à meia-noite GMT no final da semana Uma semana após <StartTime> Uma semana após o primeiro pedido
mês Meia-noite GMT do último dia do mês Um mês (28 dias) após <StartTime> Um mês (28 dias) após o primeiro pedido

Para type="calendar", tem de especificar o valor de <StartTime>.

A tabela não descreve quando a contagem é reposta para o tipo rollingwindow. Isto deve-se ao facto de as quotas de período contínuo funcionarem de forma ligeiramente diferente, com base num período de análise, como uma hora ou um dia. Para o tipo rollingwindow, o contador nunca é reposto, mas é recalculado em cada pedido. Quando chega um novo pedido, a política determina se a quota foi excedida no período anterior.

Por exemplo, define um período de duas horas que permite 1000 tokens. Um novo pedido é recebido às 16:45.A política calcula a contagem da quota para o período de duas horas anterior, o que significa o número de tokens consumidos desde as 14:45. Se o limite de quota não tiver sido excedido nesse período de duas horas, o pedido é permitido.

Um minuto depois, às 16:46, chega outro pedido. Agora, a política calcula a contagem de quotas desde as 14:46 para determinar se o limite foi excedido.

Compreender os contadores de quotas

Quando uma política LLMTokenQuota é executada num fluxo de proxy de API, um contador de quotas é incrementado. Quando o contador atinge o limite, não são permitidas mais chamadas API associadas a esse contador. Consoante a configuração que usa para o seu produto da API, a política LLMTokenQuota pode usar um único contador ou vários contadores independentes. É importante compreender os cenários em que são usados vários contadores e como se comportam.

Configurar definições de quota para produtos de API

Um produto de API pode especificar definições de quota ao nível do produto ou ao nível da operação individual, ou ambos. Se o seu proxy de API estiver incluído num produto de API, pode configurar a política LLMTokenQuota para usar as definições de quota (contagem permitida, unidade de tempo e intervalo) definidas nesse produto. A forma mais fácil de o fazer é através do elemento useQuotaConfigInAPIProduct. Em alternativa, pode fazer referência a estas definições na política LLMTokenQuota através de referências de variáveis individuais.

Como são contabilizadas as quotas

Por predefinição, o Apigee mantém um contador de quota separado para cada operação definida num produto da API e são observadas as seguintes regras:

  • Se uma operação tiver uma quota definida, as definições de quota da operação têm precedência sobre as definições de quota definidas ao nível do produto.
  • Se uma operação não tiver uma quota definida, aplicam-se as definições de quota ao nível do produto.
  • Se o produto API não incluir definições de quota, nem ao nível do produto nem da operação, aplicam-se as definições de quota para a contagem permitida, a unidade de tempo e o intervalo, conforme especificado na política LLMTokenQuota.

Em todos os casos, o Apigee mantém um contador de quotas separado para cada operação definida num produto de API. Todas as chamadas API que correspondam a uma operação incrementam o respetivo contador.

Configurar contadores ao nível do proxy da API

É possível configurar um produto de API para manter uma contagem de quotas ao nível do proxy de API. Neste caso, a configuração de quota especificada ao nível do produto API é partilhada por todas as operações que não têm a sua própria quota especificada. O efeito desta configuração é criar um contador ao nível do proxy de API para este produto de API.

Para alcançar esta configuração, tem de usar a API Apigee/apiproducts para criar ou atualizar o produto e definir o atributo quotaCounterScope como PROXY no pedido de criação ou atualização. Com a configuração PROXY, os pedidos que correspondam a qualquer uma das operações definidas para o produto da API que estejam associados ao mesmo proxy e não tenham as suas próprias definições de quota, partilham um contador de quota comum para esse proxy.

Na Figura 1, as operações 1 e 2 estão associadas ao Proxy1, e as operações 4 e 5 estão associadas ao Proxy3. Uma vez que quotaCounterScope=PROXY está definido no produto API, cada uma destas operações usa a definição de quota ao nível do produto API. As operações 1 e 2, associadas a Proxy1, usam um contador partilhado, e as operações 4 e 5, associadas a Proxy3, usam um contador partilhado separado. A operação 3 tem a sua própria definição de configuração de quota e, por esse motivo, usa o seu próprio contador, independentemente do valor do atributo quotaCounterScope.

Figura 1: utilização da flag quotaCounterScope

Como são contabilizadas as quotas se não estiverem a ser usados produtos da API

Se não existir nenhum produto API associado a um proxy API, uma política LLMTokenQuota mantém um único contador, independentemente do número de vezes que o referencie num proxy API. O nome do contador de quotas baseia-se no atributo name da política.

Por exemplo, cria uma política LLMTokenQuota denominada MyLLMTokenQuotaPolicy com um limite de 5 tokens e coloca-a em vários fluxos (fluxo A, B e C) no proxy da API. Embora seja usada em vários fluxos, mantém um único contador que é atualizado por todas as instâncias da política. Partindo do princípio de que a resposta do GML usou 1 token de cada vez:

  • O fluxo A é executado -> MyLLMTokenQuotaPolicy é executado e o respetivo contador = 1
  • O fluxo B é executado -> MyLLMTokenQuotaPolicy é executado e o respetivo contador = 2
  • O fluxo A é executado -> MyLLMTokenQuotaPolicy é executado e o respetivo contador = 3
  • O fluxo C é executado -> MyLLMTokenQuotaPolicy é executado e o respetivo contador = 4
  • O fluxo A é executado -> MyLLMTokenQuotaPolicy é executado e o respetivo contador = 5

O pedido seguinte a qualquer um dos três fluxos é rejeitado porque o contador de quotas atingiu o limite.

A utilização da mesma política LLMTokenQuota em mais do que um local num fluxo de proxy de API, que pode causar involuntariamente o esgotamento da LLMTokenQuota mais rapidamente do que o esperado, é um antipadrão descrito na Introdução aos antipadrões.

Em alternativa, pode definir várias políticas LLMTokenQuota no seu proxy de API e usar uma política diferente em cada fluxo. Cada política LLMTokenQuota mantém o seu próprio contador, com base no atributo name da política.

Criar vários contadores através da configuração de políticas

Pode usar os elementos <Class> ou <Identifier> na política LLMTokenQuota para definir vários contadores únicos numa única política. Ao usar estes elementos, uma única política pode manter diferentes contadores com base na app que faz o pedido, no programador da app que faz o pedido, num ID de cliente ou noutro identificador de cliente, entre outros. Consulte os exemplos acima para ver mais informações sobre a utilização dos elementos <Class> ou <Identifier>.

Notação de tempo

Todas as horas de LLMTokenQuota estão definidas para o fuso horário do Tempo Universal Coordenado (UTC).

A notação de tempo LLMTokenQuota segue a notação de data padrão internacional definida na norma internacional ISO 8601.

As datas são definidas como ano, mês e dia, no seguinte formato: YYYY-MM-DD. Por exemplo, 2025-02-04 representa 4 de fevereiro de 2025.

A hora do dia é definida como horas, minutos e segundos no seguinte formato: hours:minutes:seconds. Por exemplo, 23:59:59 representa a hora um segundo antes da meia-noite.

Tenha em atenção que estão disponíveis duas notações, 00:00:00 e 24:00:00, para distinguir as duas meias-noites que podem ser associadas a uma data. Por conseguinte, 2025-02-04 24:00:00 é a mesma data e hora que 2025-02-05 00:00:00. Normalmente, a última é a notação preferida.

Obter definições de quota da configuração do produto API

Pode definir limites de quota nas configurações de produtos de API. Esses limites não aplicam automaticamente a quota. Em alternativa, pode fazer referência às definições de quota de produtos numa política LLMTokenQuota. Seguem-se algumas vantagens de definir uma quota no produto para que as políticas LLMTokenQuota possam ser usadas como referência:

  • As políticas LLMTokenQuota podem usar uma definição uniforme em todos os proxies de API no produto API.
  • Pode fazer alterações em tempo de execução à definição de quota num produto API e as políticas LLMTokenQuota que referenciam o valor têm automaticamente valores de quota atualizados.

Para mais informações sobre a utilização das definições de quota de um produto de API, consulte o exemplo de quota dinâmica.

Para informações sobre a configuração de produtos de API com limites de quota, consulte o artigo Gerir produtos de API.

Configurar contadores de quota partilhada

No caso simples, a política LLMTokenQuota incrementa o respetivo contador uma vez para cada token enviado para um proxy de API, durante o processamento do pedido inicial. Em alguns casos, pode querer verificar se a quota foi excedida no processamento inicial do pedido recebido, mas incrementar o contador apenas durante o processamento da resposta.

Os três elementos da política LLMTokenQuota (<SharedName>, <CountOnly> e <EnforceOnly>), quando usados em conjunto, permitem-lhe personalizar a política LLMTokenQuota para aplicar a quota aos pedidos recebidos, mas apenas incrementam o contador no fluxo de resposta.

Por exemplo, suponha que tem um proxy de API que usa um MDG como destino e quer aplicar uma quota de 100 000 tokens por hora. As respostas do MDG fornecem um valor totalTokenCount. Para o fazer, siga estes passos:

  • Anexe uma política LLMTokenQuota ao fluxo de pedidos ProxyEndpoint com o elemento <SharedName> definido com um valor de nome e o elemento <EnforceOnly> definido como true.
  • Use o elemento <LLMTokenUsageSource> na política LLMTokenQuota para obter a contagem de tokens

Para ver um exemplo que mostra como usar contadores partilhados, consulte Contadores partilhados na secção Exemplos.

Amostras

Estes exemplos de código de políticas ilustram como iniciar e terminar períodos de quota:

Mais DynamicLLMTokenQuota

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

As quotas dinâmicas permitem-lhe configurar uma única política LLMTokenQuota que aplica diferentes definições de quota com base nas informações transmitidas à política LLMTokenQuota. Outro termo para as definições de LLMTokenQuota neste contexto é plano de serviço. O LLMTokenQuota dinâmico verifica o plano de serviço das apps e, em seguida, aplica essas definições.

Por exemplo, quando cria um produto API, pode definir opcionalmente o limite de quota permitido, a unidade de tempo e o intervalo. No entanto, a definição destes valores no produto API não impõe a respetiva utilização num proxy de API. Também tem de adicionar uma política LLMTokenQuota ao proxy da API que lê estes valores. Consulte o artigo Crie produtos da API para mais informações.

No exemplo acima, o proxy de API que contém a política LLMTokenQuota usa uma política VerifyAPIKey, denominada verify-api-key, para validar a chave API transmitida num pedido. A política LLMTokenQuota acede então às variáveis de fluxo da política VerifyAPIKey para ler os valores de quota definidos no produto API.

Outra opção é definir atributos personalizados em programadores ou apps individuais e, em seguida, ler esses valores na política LLMTokenQuota. Por exemplo, para definir valores de quota diferentes por programador, defina atributos personalizados no programador que contenham o limite, a unidade de tempo e o intervalo. Em seguida, faz referência a estes valores na política LLMTokenQuota, conforme mostrado abaixo:

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

Este exemplo também usa as variáveis de fluxo VerifyAPIKey para fazer referência aos atributos personalizados definidos no programador.

Pode usar qualquer variável para definir os parâmetros da política LLMTokenQuota. Essas variáveis podem ser provenientes de:

  • Variáveis de fluxo
  • Propriedades no produto da API, na app ou no programador
  • Um mapa de chaves-valores (KVM)
  • Um cabeçalho, um parâmetro de consulta, um parâmetro de formulário e outros

Para cada proxy de API, pode adicionar uma política LLMTokenQuota que faça referência à mesma variável que todas as outras políticas LLMTokenQuota em todos os outros proxies, ou a política LLMTokenQuota pode fazer referência a variáveis únicas para essa política e proxy.

Hora de início

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

Para um LLMTokenQuota com type definido como calendar, tem de definir um valor <StartTime> explícito. O valor de tempo é a hora GMT e não a hora local. Se não fornecer um valor <StartTime> para uma política do tipo calendar, o Apigee emite um erro.

O contador LLMTokenQuota para cada app é atualizado com base nos valores <StartTime>, <Interval> e <TimeUnit>. Para este exemplo, a LLMTokenQuota começa a ser contabilizada às 10:30 GMT a 18 de fevereiro de 2025 e é atualizada a cada 5 horas. Por isso, a próxima atualização é às 15:30 GMT a 18 de fevereiro de 2025.

Contador de acesso

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

Um proxy de API tem acesso às variáveis de fluxo definidas pela política LLMTokenQuota. Pode aceder a estas variáveis de fluxo no proxy da API para realizar o processamento condicional, monitorizar a política à medida que se aproxima do limite de quota, devolver o contador de quotas atual a uma app ou por outros motivos.

Uma vez que o acesso às variáveis de fluxo da política se baseia no atributo name, para a política acima denominada <LLMTokenQuota>, acede às respetivas variáveis de fluxo no formato:

  • ratelimit.LLMTokenQuotaPolicy.allowed.count: contagem permitida.
  • ratelimit.LLMTokenQuotaPolicy.used.count: valor atual do contador.
  • ratelimit.LLMTokenQuotaPolicy.expiry.time: hora UTC em que o contador é reposto.

Existem muitas outras variáveis de fluxo às quais pode aceder, conforme descrito abaixo.

Por exemplo, pode usar a seguinte política AssignMessage para devolver os valores das variáveis de fluxo LLMTokenQuota como cabeçalhos de resposta:

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

Contadores partilhados

O exemplo seguinte ilustra como configurar um contador partilhado para um proxy de API, em que o contador de quota também é incrementado quando a resposta de destino é o estado HTTP 200. Uma vez que ambas as políticas LLMTokenQuota usam o mesmo valor <SharedName>, ambas as políticas LLMTokenQuota partilham o mesmo contador de quota. Para mais informações, consulte o artigo Configurar contadores de quota partilhada.

Exemplo de configuração de 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>

Primeiro exemplo de política 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>

Segundo exemplo da política 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>

Primeiro pedido

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

Use este exemplo de código para aplicar uma quota de 10 000 tokens por hora. A política repõe o contador de quotas no início de cada hora. Se o contador atingir a quota de 10 000 tokens antes do final da hora, as chamadas da API que consumam tokens além dos 10 000 são rejeitadas.

Por exemplo, se o contador começar em 2025-07-08 07:00:00, é reposto para 0 às 2025-07-08 08:00:00 (1 hora após a hora de início). Se o primeiro pedido for recebido às 2025-07-08 07:35:28 e a contagem de tokens atingir 10 000 antes das 2025-07-08 08:00:00, os pedidos que consumam tokens além dessa contagem são rejeitados até que a contagem seja reposta no início da hora.

A hora de reposição do contador baseia-se na combinação de <Interval> e <TimeUnit>. Por exemplo, se definir <Interval> como 12 para um <TimeUnit> de horas, o contador é reposto a cada doze horas. Pode definir <TimeUnit> para minuto, hora, dia, semana ou mês.

Pode fazer referência a esta política em vários locais no seu proxy de API. Por exemplo, pode colocá-la no Proxy PreFlow para que seja executada em todos os pedidos. Em alternativa, pode colocá-lo em vários fluxos no proxy de API. Se usar esta política em vários locais no proxy, mantém um único contador que é atualizado por todas as instâncias da política.

Em alternativa, pode definir várias políticas LLMTokenQuota no seu proxy de API. Cada política LLMTokenQuota mantém o seu próprio contador, com base no atributo name da política.

Defina o identificador

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

Por predefinição, uma política LLMTokenQuota define um único contador para o proxy de API, independentemente da origem de um pedido. Em alternativa, pode usar o atributo <Identifier> com uma política LLMTokenQuota para manter contadores separados com base no valor do atributo <Identifier>.

Por exemplo, use a etiqueta <Identifier> para definir contadores separados para cada ID do cliente. Num pedido ao seu proxy, a app cliente passa então um cabeçalho que contém o clientID, conforme mostrado no exemplo acima.

Pode especificar qualquer variável de fluxo para o atributo <Identifier>. Por exemplo, pode especificar que um parâmetro de consulta denominado id contém o identificador exclusivo:

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

Se usar a política VerifyAPIKey para validar a chave da API ou as políticas OAuthV2 com tokens OAuth, pode usar informações na chave da API ou no token para definir contadores individuais para a mesma política LLMTokenQuota. Por exemplo, o elemento <Identifier> usa a variável de fluxo client_id de uma política VerifyAPIKey denominada verify-api-key:

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

Cada valor client_id único define agora o seu próprio contador na política 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>

Pode definir limites de LLMTokenQuota dinamicamente através de uma contagem de LLMTokenQuota baseada em classes. Neste exemplo, o limite da quota é determinado pelo valor do cabeçalho developer_segment transmitido com cada pedido. Essa variável pode ter um valor de platinum ou silver. Se o cabeçalho tiver um valor inválido, a política devolve um erro de violação de quota.

Os exemplos seguintes ilustram várias configurações da política de LLMTokenQuota.

Calcular tokens

Este exemplo mostra como calcular os tokens.

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

Contagem de variáveis dinâmicas de quota através do produto de API, do programador e da app

Este exemplo mostra como contabilizar variáveis dinâmicas de quota através do produto da API, do programador e da 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>

Aplique a quota sem o produto API

Este exemplo mostra como aplicar a quota sem um produto 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>

Aplique a quota com o produto de API, o programador e a app

Este exemplo mostra como aplicar a quota com o produto API, o programador e a 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>

Com stream SSE

Este exemplo mostra como usar LLMTokenQuota com um fluxo SSE.

Política de contagem de quotas de tokens:

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

Fluxo de eventos:

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

<LLMTokenQuota> elemento

Seguem-se os atributos e os elementos secundários de <LLMTokenQuota>. Tenha em atenção que algumas combinações de elementos são mutuamente exclusivas ou não são obrigatórias. Consulte os exemplos para ver a utilização específica.

As variáveis verifyapikey.my-verify-key-policy.apiproduct.* abaixo estão disponíveis por predefinição quando é usada uma política VerifyAPIKey denominada my-verify-key-policy para verificar a chave da API da app no pedido. Os valores das variáveis provêm das definições de quota no produto da API ao qual a chave está associada, conforme descrito em Obter definições de quota da configuração do produto da 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>

Os seguintes atributos são específicos desta política:

Atributo Descrição Predefinição Presença
type

Define o tipo de política LLMTokenQuota, que determina quando e como o contador de quotas verifica a utilização de quotas, bem como a forma como é reposto.

Se não definir type, o contador começa no início do minuto/hora/dia/semana/mês.

Os valores válidos incluem:

  • calendar
  • rollingwindow
  • flexi

Para uma descrição completa de cada tipo, consulte os tipos de políticas LLMTokenQuota.

 N/A Opcional

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo Descrição Predefinição Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

 N/A Obrigatória
continueOnError

Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas.

Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:

 falso Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.

 verdadeiro Opcional
async

Este atributo foi descontinuado.

 falso Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>
Predefinição

N/A

Se omitir este elemento, é usado o valor do atributo name da política.
Presença Opcional
Tipo String

<Allow>

Especifica o número total de tokens permitidos para o intervalo de tempo especificado. Se o contador da política atingir este valor limite, as chamadas API subsequentes são rejeitadas até o contador ser reposto.

Também pode conter um elemento <Class> que condicione o elemento <Allow> com base numa variável de fluxo.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo inteiro ou complexo
Elemento principal <LLMTokenQuota>
Elementos subordinados <Class>

Abaixo, são apresentadas três formas de definir o elemento <Allow>:

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

Se especificar count e countRef, countRef tem prioridade. Se countRef não for resolvido no tempo de execução, é usado o valor de count.

Também pode especificar um elemento <Class> como filho de <Allow> para determinar a quantidade permitida da política com base numa variável de fluxo. O Apigee faz corresponder o valor da variável de fluxo ao atributo class do elemento <Allow>, conforme mostrado abaixo:

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

A tabela seguinte indica os atributos de <Allow>:

Atributo Descrição Predefinição Presença
count

Use para especificar uma contagem de tokens para a quota.

Por exemplo, um valor do atributo count de 100, um valor do atributo Interval de 1 e um valor do atributo TimeUnit de mês especificam uma quota de 100 tokens por mês.

 2000 Opcional
countRef

Use para especificar uma variável de fluxo que contenha a contagem de tokens para uma quota. countRef tem precedência sobre o atributo count.

 nenhum Opcional

<Class>

Permite condicionar o valor do elemento <Allow> com base no valor de uma variável de fluxo. Para cada <Allow> etiqueta secundária diferente de <Class>, a política mantém um contador diferente.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento principal <Allow>
Elementos subordinados <Allow> (filho de <Class>)

Para usar o elemento <Class>, especifique uma variável de fluxo através do atributo ref no elemento <Class>. Em seguida, o Apigee usa o valor da variável de fluxo <Allow> para selecionar um dos elementos secundários <Allow> para determinar a contagem permitida da política. O Apigee faz corresponder o valor da variável de fluxo ao atributo class do elemento <Allow>, conforme mostrado abaixo:

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

Neste exemplo, o contador de quota atual é determinado pelo valor do parâmetro de consulta time_variable transmitido com cada pedido. Essa variável pode ter um valor de peak_time ou off_peak_time. Se o parâmetro de consulta contiver um valor inválido, a política devolve um erro de violação de quota.

A tabela seguinte indica os atributos de <Class>:

Atributo Descrição Predefinição Presença
ref Use para especificar uma variável de fluxo que contenha a classe de quota para uma quota. nenhum Obrigatória

<Allow> (filho de <Class>)

Especifica o limite de um contador de quota definido pelo elemento <Class>. Para cada etiqueta de criança <Allow> diferente de <Class>, a política mantém um contador diferente.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento principal <Class>
Elementos subordinados Nenhum

Por exemplo:

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

Neste exemplo, a política LLMTokenQuota mantém dois contadores de quotas denominados peak_time e off_peak_time. A opção usada depende do parâmetro de consulta transmitido, conforme mostrado no exemplo <Class>.

A tabela seguinte indica os atributos de <Allow>:

Atributo Descrição Predefinição Presença
class Define o nome do contador de quota. nenhum Obrigatória
count Especifica o limite da quota para o contador. nenhum Obrigatória

<IgnoreUnresolvedVariables>

Determina se o processamento da política LLMTokenQuota é interrompido se o Apigee não conseguir resolver uma variável referenciada pelo atributo ref na política.

Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Definido como true para ignorar as variáveis não resolvidas e continuar o processamento; caso contrário, false. O valor predefinido é false.

Se <IgnoreUnresolvedVariables> estiver definido como true e a variável especificada num atributo ref não puder ser resolvida, o Apigee ignora o atributo ref. Se o elemento que contém o atributo ref também contiver um valor, como <Allow count="2000"/>, o Apigee usa esse valor. Se não existir nenhum valor, o Apigee trata o valor do elemento como nulo e substitui o valor predefinido, se existir, ou uma string vazia.

Se <IgnoreUnresolvedVariables> for false e a variável especificada num atributo ref não puder ser resolvida, o Apigee devolve um erro.

<Interval>

Especifica o número de períodos em que as quotas são calculadas.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo Número inteiro
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Use para especificar um número inteiro (por exemplo, 1, 2, 5, 60, etc.) que vai ser associado ao elemento <TimeUnit> que especificar (minuto, hora, dia, semana ou mês) para determinar um período durante o qual o Apigee calcula a utilização da quota.

Por exemplo, um intervalo de 24 com um <TimeUnit> de hour significa que a quota vai ser calculada ao longo de 24 horas.

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

A tabela seguinte indica os atributos de <Interval>:

Atributo Descrição Predefinição Presença
ref

Use para especificar uma variável de fluxo que contenha o intervalo para uma quota. ref tem precedência sobre um valor de intervalo explícito. Se forem especificados a referência e o valor, a referência tem prioridade. Se ref não for resolvido no momento da execução, é usado o valor.

 nenhum Opcional

<TimeUnit>

Especifica a unidade de tempo aplicável à quota.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Selecione entre minute, hour, day, week, month ou year.

Por exemplo, um Interval de 24 com um TimeUnit de hour significa que a quota vai ser calculada ao longo de 24 horas.

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

A tabela seguinte indica os atributos de <TimeUnit>:

Atributo Descrição Predefinição Presença
ref Especifica uma variável de fluxo que contém a unidade de tempo para uma quota. ref tem precedência sobre um valor de intervalo explícito. Se ref não for resolvido no momento da execução, é usado o valor do intervalo. nenhum Opcional

<StartTime>

Quando type está definido como calendar, especifica a data e a hora em que o contador de quota começa a contar, independentemente de terem sido recebidos pedidos de quaisquer apps.

Valor predefinido N/A
Obrigatório? Opcional (obrigatório quando type está definido como calendar)
Tipo String no formato de data e hora ISO 8601
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Por exemplo:

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

<Distributed>

Determina se o Apigee usa um ou mais nós para processar pedidos.

Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Defina como true para especificar que a política deve manter um contador central e sincronizá-lo continuamente em todos os nós. Os nós podem estar em várias zonas de disponibilidade e/ou regiões.

Se usar o valor predefinido de false, pode exceder a sua quota porque a contagem de cada nó não é partilhada:

<Distributed>false</Distributed>

Para garantir que os contadores são sincronizados e atualizados em cada pedido, defina <Distributed> e <Synchronous> como true:

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

<Synchronous>

Determina se deve atualizar um contador de quotas distribuídas de forma síncrona.

Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Defina como true para atualizar um contador de quotas distribuídas de forma síncrona. Isto significa que as atualizações dos contadores são feitas ao mesmo tempo que a quota é verificada num pedido à API. Defina como true se for essencial que não permita chamadas API acima da quota.

Definido como false para atualizar o contador de quotas de forma assíncrona. Isto significa que é possível que algumas chamadas API que excedam a quota sejam processadas, consoante o momento em que o contador de quotas no repositório central é atualizado de forma assíncrona. No entanto, não vai enfrentar os potenciais impactos no desempenho associados às atualizações síncronas.

O intervalo de atualização assíncrono predefinido é de 10 segundos. Use o elemento <AsynchronousConfiguration> para configurar este comportamento assíncrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura o intervalo de sincronização entre contadores de quotas distribuídos quando o elemento de configuração da política <Synchronous> não está presente ou está presente e definido como false. O Apigee ignora este elemento quando <Synchronous> está definido como true.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento principal <LLMTokenQuota>
Elementos subordinados <SyncIntervalInSeconds>
<SyncMessageCount>

Pode especificar o comportamento de sincronização através dos elementos secundários <SyncIntervalInSeconds> ou <SyncMessageCount>. Use um ou ambos os elementos. Por exemplo,

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

ou

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Quando apenas <SyncIntervalInSeconds> está presente, a quota é sincronizada a cada N segundos, onde N é o valor especificado no elemento, independentemente do número de mensagens processadas.
  • Quando apenas <SyncMessageCount> está presente, a quota é sincronizada a cada M mensagens, em que M é o valor especificado no elemento, ou a cada 10 segundos, consoante o que ocorrer primeiro.
  • Quando ambos os elementos estão presentes, a quota é sincronizada a cada M mensagens ou a cada N segundos, consoante o que ocorrer primeiro.
  • Quando <AsynchronousConfiguration> não está presente ou nenhum dos elementos secundários está presente, a quota é sincronizada a cada 10 segundos, independentemente do número de mensagens processadas.

<SyncIntervalInSeconds>

Substitui o comportamento predefinido em que as atualizações assíncronas são realizadas após um intervalo de 10 segundos.

Valor predefinido 10 segundos
Obrigatório? Opcional
Tipo Número inteiro
Elemento principal <AsynchronousConfiguration>
Elementos subordinados Nenhum
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

O intervalo de sincronização tem de ser >= 10 segundos, conforme descrito nos Limites.

<SyncMessageCount>

Especifica o número de pedidos a processar antes de sincronizar o contador de quota.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Número inteiro
Elemento principal <AsynchronousConfiguration>
Elementos subordinados Nenhum
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Usando a configuração neste exemplo, em cada nó, a contagem de quotas é sincronizada após cada 5 pedidos ou a cada 10 segundos, consoante o que ocorrer primeiro.

<LLMTokenUsageSource>

Fornece a origem da utilização de tokens da resposta do GML. Tem de ser um modelo de mensagem que seja resolvido para um único valor de utilização de tokens. Se a política não fizer parte de um fluxo de eventos e não conseguir extrair a contagem de tokens da origem especificada, gera um erro de tempo de execução.policies.ratelimit.FailedToResolveTokenUsageCount

Valor predefinido {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
Obrigatório? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

O exemplo seguinte mostra como especificar a origem da utilização de tokens:

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

<LLMModelSource>

Indica a origem do nome do modelo a partir da resposta ou do pedido do MDI/CE. Tem de ser um modelo de mensagem que forneça um único valor de nome do modelo.

Valor predefinido
Obrigatório? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

O exemplo seguinte mostra como especificar a origem do modelo a partir do pedido:

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

<Identifier>

Configura a política para criar contadores únicos com base numa variável de fluxo.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Através do elemento Identifier, pode atribuir contagens de tokens a contentores distintos definidos pelo valor numa variável de fluxo. Por exemplo, pode usar a variável developer.id, que é preenchida após uma política VerifyAPIKey, para aplicar um limite de quota a todas as instâncias de todas as apps criadas por cada programador específico, ou pode usar a variável client_id para aplicar um limite de quota a cada app específica. A configuração para a última opção tem o seguinte aspeto:

<Identifier ref="client_id"/>

Pode referir-se a uma variável personalizada que pode definir com a política AssignMessage ou a política JavaScript, ou a uma variável que é definida implicitamente, como as definidas pela política VerifyAPIKey ou a política VerifyJWT. Para mais informações sobre as variáveis, consulte o artigo Usar variáveis de fluxo e, para ver uma lista de variáveis conhecidas definidas pelo Apigee, consulte a referência de variáveis de fluxo.

Se não usar este elemento, a política atribui todas as contagens de tokens a um único contador para a política LLMTokenQuota específica.

A tabela seguinte descreve os atributos de <Identifier>:

Atributo Descrição Predefinição Presença
ref

Especifica uma variável de fluxo que identifica o contador a usar para o pedido. A variável pode referir-se a um cabeçalho HTTP, um parâmetro de consulta, um parâmetro de formulário ou um elemento do conteúdo da mensagem ou algum outro valor para identificar como atribuir contagens de tokens.

O client_id é usado frequentemente como variável. O client_id também é conhecido como chave da API ou chave de consumidor e é gerado para uma app quando esta é registada numa organização no Apigee. Pode usar este identificador se tiver ativado as políticas de autorização de OAuth ou de chave de API para a sua API.

 N/A Opcional

<UseQuotaConfigInAPIProduct>

Define as definições de quota para um produto API, como as unidades de tempo, o intervalo e o máximo permitido.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento principal <LLMTokenQuota>
Elementos subordinados <DefaultConfig>

Se adicionar o elemento <UseQuotaConfigInAPIProduct> à política LLMTokenQuota, o Apigee ignora todos os elementos filhos <Allow>, <Interval> e <TimeUnit> de LLMTokenQuotaPolicy.

O elemento <UseQuotaConfigInAPIProduct> é simplesmente um contentor para as predefinições que define através do elemento <DefaultConfig>, como mostra o exemplo seguinte:

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

Pode usar o atributo stepName para fazer referência a uma política VerifyAPIKey ou a uma operação de política ValidateToken da política OAuthv2 no fluxo.

A tabela seguinte descreve os atributos de <UseQuotaConfigInAPIProduct>:

Atributo Descrição Predefinição Presença
stepName Identifica o nome da política de autenticação no fluxo. O destino pode ser uma política VerifyAPIKey ou uma política OAuthv2. N/A Obrigatória

Para mais informações, consulte o seguinte:

<DefaultConfig>

Contém os valores predefinidos da quota de um produto API. Quando define um <DefaultConfig>, todos os três elementos secundários são obrigatórios.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento principal <UseQuotaConfigInAPIProduct>
Elementos subordinados <Allow>
<Interval>
<TimeUnit>

É possível definir estes valores na operação do produto de API (com a IU ou a API Products API) e na política LLMTokenQuota. No entanto, se o fizer, as definições no produto API têm precedência e as definições na política LLMTokenQuota são ignoradas.

A sintaxe deste elemento é a seguinte:

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

O exemplo seguinte especifica uma quota de 10 000 todas as semanas:

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

Para mais informações, consulte o seguinte:

<SharedName>

Identifica esta política LLMTokenQuota como partilhada. Todas as políticas LLMTokenQuota num proxy de API com o mesmo valor <SharedName> partilham o mesmo contador de quota subjacente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

<CountOnly>

Coloque uma política LLMTokenQuota com este elemento definido como true num passo no fluxo de resposta do ProxyEndpoint para acompanhar o número de tokens sem enviar um erro de volta ao cliente quando o limite de quota de tokens for excedido. Se este elemento estiver presente, o elemento <SharedName> também tem de estar presente e o elemento <EnforceOnly> não pode estar presente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

<EnforceOnly>

Coloque uma política LLMTokenQuota com este elemento definido como true no fluxo de pedidos de um proxy de API para aplicar um limite de tokens sem incrementar o contador de quotas. Se este elemento estiver presente, o elemento <SharedName> também tem de estar presente e o elemento <CountOnly> não pode estar presente.

Para mais informações e exemplos, consulte o artigo Configurar contadores de quota partilhados.

Valor predefinido falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <LLMTokenQuota>
Elementos subordinados Nenhum

Variáveis de fluxo

As seguintes variáveis de fluxo predefinidas são preenchidas automaticamente quando uma política LLMTokenQuota é executada. Para mais informações, consulte a Referência de variáveis de fluxo.

Variáveis Tipo Autorizações Descrição
ratelimit.{policy_name}.allowed.count Longo Só de leitura Devolve a contagem da quota permitida.
ratelimit.{policy_name}.used.count Longo Só de leitura Devolve a quota atual usada num intervalo de quota.
ratelimit.{policy_name}.available.count Longo Só de leitura Devolve a contagem de quota disponível no intervalo de quota.
ratelimit.{policy_name}.exceed.count Longo Só de leitura Devolve 1 após a quota ser excedida.
ratelimit.{policy_name}.total.exceed.count Longo Só de leitura Devolve 1 após a quota ser excedida.
ratelimit.{policy_name}.expiry.time Longo Só de leitura

Devolve a hora UTC (em milissegundos), que determina quando a quota expira e quando o novo intervalo de quota começa.

Quando o tipo da política LLMTokenQuota é rollingwindow, este valor não é válido porque o intervalo de quota nunca expira.

ratelimit.{policy_name}.identifier String Só de leitura Devolve a referência do identificador (cliente) anexada à política
ratelimit.{policy_name}.class String Só de leitura Devolve a classe associada ao identificador do cliente
ratelimit.{policy_name}.class.allowed.count Longo Só de leitura Devolve a contagem da quota permitida definida na classe
ratelimit.{policy_name}.class.used.count Longo Só de leitura Devolve a quota usada numa classe
ratelimit.{policy_name}.class.available.count Longo Só de leitura Devolve a contagem de quota disponível na classe
ratelimit.{policy_name}.class.exceed.count Longo Só de leitura Devolve a contagem de tokens que excede o limite na classe no intervalo de quota atual
ratelimit.{policy_name}.class.total.exceed.count Longo Só de leitura Devolve a contagem total de tokens que excede o limite na classe em todos os intervalos de quotas, pelo que é a soma de class.exceed.count para todos os intervalos de quotas.
ratelimit.{policy_name}.failed Booleano Só de leitura

Indica se a política falhou ou não (verdadeiro ou falso).
llmtokenquota.{policy_name}.model String Só de leitura Devolve o modelo extraído.

Referência de erro

Esta secção descreve os códigos de falhas e as mensagens de erro devolvidas, bem como as variáveis de falhas definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes se estiver a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha Estado de HTTP Causa Corrigir
policies.llmtokenquota.FailedToResolveModelName 400 Não foi possível resolver o nome do modelo. N/A
policies.llmtokenquota.FailedToResolveTokenUsageCount 500 Não foi possível resolver a contagem de utilização de tokens. N/A
policies.llmtokenquota.MessageTemplateExtractionFailed 400 A extração do modelo de mensagem falhou. N/A
policies.llmtokenquota.LLMTokenQuotaViolation 429 O limite da quota de tokens do MDG foi excedido. N/A
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Ocorre se o elemento <Interval> não estiver definido na política LLMTokenQuota. Este elemento é obrigatório e usado para especificar o intervalo de tempo aplicável à quota de tokens do LLM. O intervalo de tempo pode ser minutos, horas, dias, semanas ou meses, conforme definido com o elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Ocorre se o elemento <TimeUnit> não estiver definido na política LLMTokenQuota. Este elemento é obrigatório e usado para especificar a unidade de tempo aplicável à quota de tokens do MDG. O intervalo de tempo pode ser em minutos, horas, dias, semanas ou meses.

Erros de implementação

Nome do erro Causa Corrigir
policies.llmtokenquota.MessageWeightNotSupported Erro quando o elemento "MessageWeight" é usado, uma vez que não é suportado. N/A
policies.llmtokenquota.InvalidConfiguration Tem de definir exatamente um dos elementos <CountOnly> ou <EnforceOnly> como verdadeiro. N/A
InvalidQuotaInterval Se o intervalo da quota de tokens do MDI/CE especificado no elemento <Interval> não for um número inteiro, a implementação do proxy da API falha. Por exemplo, se o intervalo de quota especificado for 0,1 no elemento <Interval>, a implementação do proxy de API falha.
InvalidQuotaTimeUnit Se a unidade de tempo especificada no elemento <TimeUnit> não for suportada, a implementação do proxy de API falha. As unidades de tempo suportadas são minute, hour, day, week e month.
InvalidQuotaType Se o tipo de quota de tokens do MDG especificado pelo atributo type no elemento <LLMTokenQuota> for inválido, a implementação do proxy da API falha. Os tipos de quotas suportados são default, calendar, flexi e rollingwindow.
InvalidStartTime Se o formato da hora especificada no elemento <StartTime> for inválido, a implementação do proxy da API falha. O formato válido é yyyy-MM-dd HH:mm:ss, que é o formato de data e hora ISO 8601. Por exemplo, se a hora especificada no elemento <StartTime> for 7-16-2017 12:00:00, a implementação do proxy da API falha.
StartTimeNotSupported Se for especificado o elemento <StartTime> cujo tipo de quota não seja do tipo calendar, a implementação do proxy de API falha. O elemento <StartTime> só é compatível com o tipo de quota calendar. Por exemplo, se o atributo type estiver definido como flexi ou rolling window no elemento <LLMTokenQuota>, a implementação do proxy da API falha.
InvalidSynchronizeIntervalForAsyncConfiguration Se o valor especificado para o elemento <SyncIntervalInSeconds> no elemento <AsynchronousConfiguration> numa política LLMTokenQuota for inferior a zero, a implementação do proxy de API falha.
InvalidAsynchronizeConfigurationForSynchronousQuota Se o valor do elemento <AsynchronousConfiguration> estiver definido como true numa política LLMTokenQuota, que também tenha uma configuração assíncrona definida através do elemento <AsynchronousConfiguration>, a implementação do proxy de API falha.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela Erros de tempo de execução acima. O nome da falha é a última parte do código de falha. fault.name Matches "LLMTokenQuotaViolation"
ratelimit.policy_name.failed policy_name é o nome especificado pelo utilizador da política que gerou a falha. ratelimit.QT-LLMTokenQuotaPolicy.failed = true

Exemplo de resposta de erro

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

 Identifier : _default"
   }
}

Exemplo de regra de falha

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

Esquemas

Tópicos relacionados

Política de PromptTokenLimit