Política LLMTokenQuota

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Visão geral

A política LLMTokenQuota foi criada para gerenciar e controlar o consumo de tokens em cargas de trabalho de IA/LLM. Como as interações com modelos de linguagem grandes (LLMs) são baseadas em tokens, o gerenciamento eficaz é crucial para o controle de custos, a otimização de desempenho e a estabilidade da plataforma.

Uma cota é uma cota de tokens de LLM (entrada ou saída) que um proxy de API pode consumir durante um período, como minuto, hora, dia, semana ou mês. A política LLMTokenQuota mantém contadores que totalizam o número de tokens consumidos pelo proxy de API. Esse recurso permite que os provedores de API apliquem limites ao consumo de tokens por apps em um intervalo de tempo.

Essa política usa os elementos <LLMTokenUsageSource> e <LLMModelSource> para extrair a contagem de tokens da resposta do LLM e o nome do modelo da solicitação ou resposta, permitindo uma aplicação de cota precisa e em tempo real.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Como funciona a aplicação da LLMTokenQuota

Confira abaixo a funcionalidade da política LLMTokenQuota:

  • Contagem de tokens (<CountOnly>): a política LLMTokenQuota mantém contadores que rastreiam o número de tokens consumidos por respostas de LLM que passam pelo proxy de API.
  • Aplicação de limites (<EnforceOnly>):esse recurso permite que os provedores de API definam limites estritos para o número de tokens consumidos por aplicativos em um intervalo definido. Por exemplo, é possível limitar os aplicativos a 1.000 tokens por minuto ou 10.000.000 tokens por mês.
  • Exceder a cota:quando um proxy de API atinge o limite definido de cota de token, o Apigee rejeita as solicitações subsequentes que consomem tokens. Uma mensagem de erro é retornada até que o contador LLMTokenQuota seja redefinido automaticamente no final do intervalo de tempo especificado. Por exemplo, se uma cota for definida como 10.000 tokens por mês, a limitação de tokens começará assim que o 10.000º token for contado, independentemente de quando esse limite for atingido no mês.

Como o LLMTokenQuota funciona com produtos de API

A seguir, descrevemos como a política LLMTokenQuota funciona com produtos de API:

fluxo de proxy para LLMTokenQuota
  1. Aplique a política VerifyAPIKey ou VerifyAccessToken junto com a política de aplicação LLMTokenQuota na solicitação do proxy de API (não importa se é proxy ou destino).
  2. Aplique a política de contagem LLMTokenQuota em resposta ao proxy de API (proxy ou destino não importa).
  3. A política VerifyAPIKey ou VerifyAccessToken corresponde à chave ou ao token com o produto de API, o conjunto de operações, o desenvolvedor e o app. Ela expõe as variáveis de fluxo para a cota de LLM de todos os modelos dos conjuntos de operações de LLM correspondentes.
  4. Dentro da política de aplicação de cota, extraímos o modelo de acordo com o modelo de mensagem fornecido.
  5. Em seguida, as variáveis de cota de LLM são correspondidas para o modelo. Se a correspondência for encontrada, as referências serão injetadas.
  6. Depois que as referências são injetadas, esses valores são usados para realizar as operações de cota.

Como o LLMTokenQuota funciona com respostas de SSE

Para fazer com que LLMTokenQuota funcione com respostas de 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>

Ao processar o fluxo de eventos, a contagem de tokens é executada apenas quando os metadados de uso de tokens da resposta do LLM são encontrados no evento. Quando os metadados de uso do token são descobertos, eles 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 é compatível com várias maneiras de iniciar e redefinir o contador de cotas. É possível definir qual usar com o atributo type no elemento <LLMTokenQuota>, como no exemplo a seguir:

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

Os valores válidos de type incluem:

  • calendar: configura uma cota com base em um horário de início explícito. O contador LLMTokenQuota de cada app é atualizado com base nos valores de <StartTime>, <Interval> e <TimeUnit> que você definir.
  • rollingwindow: configura uma cota que usa uma janela de rolagem para determinar o uso da cota. Com rollingwindow, você determina o tamanho da janela com os elementos <Interval> e <TimeUnit>; por exemplo, um dia. Quando uma solicitação chega, o Apigee analisa o horário exato dela (por exemplo, 17h01), conta o número de tokens consumidos entre 17h01 do dia anterior (1 dia), e determina se a cota foi excedida durante essa janela.
  • flexi: configura uma cota que faz com que o contador comece quando a primeira mensagem de solicitação for recebida de um app e é redefinida com base nos valores <Interval> e <TimeUnit>.

A tabela a seguir descreve quando a cota é redefinida para cada tipo:

Unidade de tempo Tipo
default (ou nulo) calendar flexi
minuto Início do próximo minuto Um minuto depois de <StartTime> Um minuto após a primeira solicitação
hora Começo da próxima hora Uma hora depois de <StartTime> Uma hora após a primeira solicitação
dia Meia-noite GMT do dia atual 24 horas depois de <StartTime> 24 horas após a primeira solicitação
semana Meia-noite (GMT) no final da semana Uma semana depois de <StartTime> Uma semana depois da primeira solicitação
mês Meia-noite (GMT) do último dia do mês Um mês (28 dias) depois de <StartTime> Um mês (28 dias) após a primeira solicitação

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

A tabela não descreve quando a contagem é redefinida para o tipo rollingwindow. Isso porque as cotas de janela contínua funcionam de maneira um pouco diferente, com base em uma janela de lookback, como uma hora ou um dia. Para o tipo rollingwindow, o contador nunca é redefinido, mas é recalculado em cada solicitação. Quando uma nova solicitação chega, a política determina se a cota foi excedida na janela de tempo anterior.

Por exemplo, você define uma janela de duas horas que permite 1.000 tokens. Uma nova solicitação chega às 16h45.A política calcula a contagem de cotas para as duas últimas horas, o que significa o número de tokens consumidos desde as 14h45. Se o limite de cota não tiver sido excedido na janela de duas horas, a solicitação será permitida.

Um minuto depois, às 16h46, aparece outra solicitação. Agora, a política calcula a contagem de cotas desde 14h46, para determinar se o limite foi excedido.

Noções básicas sobre contadores de cota

Quando uma política LLMTokenQuota é executada em um fluxo de proxy de API, um contador de cota é incrementado. Quando o contador atinge o limite, não são permitidas outras chamadas de API associadas a ele. Dependendo da configuração usada para o produto de API, a política LLMTokenQuota pode usar um único contador ou vários contadores independentes. É importante entender os cenários em que vários contadores serão usados e como eles se comportam.

Configurar as configurações de cota para produtos de API

Um produto de API pode especificar configurações de cota no nível do produto ou no nível da operação individual, ou em ambos. Se o proxy de API estiver incluído em um produto de API, será possível configurar a política LLMTokenQuota para usar as configurações de cota (contagem permitida, unidade de tempo e intervalo) definidas nesse produto. A maneira mais fácil de fazer isso é usando o elemento useQuotaConfigInAPIProduct. Como alternativa, você pode referenciar essas configurações na política "LLMTokenQuota" usando referências de variáveis individuais.

Como as cotas são contabilizadas

Por padrão, a Apigee mantém um contador de cotas separado para cada operação definida em um produto de API, e as seguintes regras são observadas:

  • Se uma operação tiver uma cota definida, as configurações de cota da operação terão precedência sobre as configurações definidas no nível do produto.
  • Se uma operação não tiver uma cota definida, as configurações de cota no nível do produto serão aplicadas.
  • Se o produto da API não incluir nenhuma configuração de cota (nem no nível do produto nem da operação), as configurações de cota para contagem permitida, unidade de tempo e intervalo, conforme especificado na política LLMTokenQuota, serão aplicadas.

Em todos os casos, o Apigee mantém um contador de cotas separado para cada operação definida em um produto de API. Qualquer chamada de API que corresponda a uma operação vai incrementar o contador dela.

Como configurar contadores no nível do proxy de API

É possível configurar um produto de API para manter uma contagem de cotas no escopo do proxy da API. Nesse caso, a configuração de cota especificada no nível do produto de API é compartilhada por todas as operações que não têm a própria cota especificada. O efeito dessa configuração é criar um contador no nível do proxy de API para esse produto de API.

Para isso, use o API/apiproducts da Apigee para criar ou atualizar o produto e definir o quotaCounterScope atributo aPROXY na solicitação de criação ou atualização. Com a configuração do PROXY, as solicitações que corresponderem a qualquer uma das operações definidas para o produto da API associadas ao mesmo proxy e que não têm configurações de cota próprias vão compartilhar um contador de cota comum para esse proxy.

Na Figura 1, a Operação 1 e 2 está associada ao Proxy 1, e as Operações 4 e 5 estão associadas ao Proxy 3. Como quotaCounterScope=PROXY é definido no produto da API, cada uma dessas operações usa a configuração de cota no nível do produto da API. As operações 1 e 2, associadas ao Proxy1, usam um contador compartilhado, e as operações 4 e 5, associadas ao Proxy3, usam um contador compartilhado separado. A operação 3 tem a própria configuração de cota e, por isso, usa o próprio contador, independente do valor do atributo quotaCounterScope.

Figura 1: uso da sinalização cotaCounterScope

Como as cotas são contadas se nenhum produto de API estiver em uso

Se não houver um produto de API associado a um proxy de API, uma política LLMTokenQuota vai manter um único contador, independentemente de quantas vezes você fizer referência a ele em um proxy de API. O nome do contador de cotas é baseado no atributo name da política.

Por exemplo, crie uma política LLMTokenQuota chamada MyLLMTokenQuotaPolicy com um limite de cinco tokens e coloque-a em vários fluxos (Fluxo A, B e C) no proxy de API. Mesmo sendo usado em vários fluxos, ele mantém um único contador atualizado por todas as instâncias da política. Supondo que a resposta do LLM tenha usado um token a cada vez:

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

A próxima solicitação para qualquer um dos três fluxos é rejeitada porque o contador de cotas atingiu o limite.

Usar a mesma política LLMTokenQuota em mais de um local em um fluxo de proxy de API, o que pode fazer com que a LLMTokenQuota acabe antes do esperado, é um antipadrão descrito em Introdução aos antipadrões.

Se preferir, defina várias políticas LLMTokenQuota no proxy de API e use uma política diferente em cada fluxo. Cada política de LLMTokenQuota mantém seu próprio contador, com base no atributo name da política.

Como criar vários contadores por meio da configuração de políticas

É possível usar os elementos <Class> ou <Identifier> na política LLMTokenQuota para definir vários contadores exclusivos em uma única política. Ao usar esses elementos, uma única política pode manter diferentes contadores com base no aplicativo que faz a solicitação, no desenvolvedor do aplicativo que fez a solicitação, um ID do cliente ou outro identificador de cliente e muito mais. Veja os exemplos acima para mais informações sobre como usar os elementos <Class> ou <Identifier>.

Notação de tempo

Todos os horários de LLMTokenQuota são definidos com o fuso horário Tempo Universal Coordenado (UTC).

A notação de tempo de cota de token de LLM segue a notação de data padrão internacional definida no padrão 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 o tempo um segundo antes da meia-noite.

Observe que duas notações, 00:00:00 e 24:00:00, estão disponíveis para distinguir as duas meias-noites que podem ser associadas a uma data. Portanto, 2025-02-04 24:00:00 tem a mesma data e hora que 2025-02-05 00:00:00. O último geralmente é a notação preferida.

Como conseguir configurações de cota da configuração do produto da API

Você pode definir limites de cota em configurações de produtos de API. Esses limites não impõem a cota automaticamente. Em vez disso, é possível fazer referência às configurações de cota do produto em uma política LLMTokenQuota. Confira algumas vantagens de definir uma cota no produto para políticas LLMTokenQuota:

  • As políticas LLMTokenQuota podem usar uma configuração uniforme em todos os proxies de API no produto de API.
  • Você pode fazer mudanças no ambiente de execução na configuração de cota de um produto da API, e as políticas LLMTokenQuota que fazem referência ao valor têm valores de cota atualizados automaticamente.

Para saber como usar as configurações de cota de um produto da API, consulte o exemplo de cota dinâmica.

Para informações sobre como configurar produtos de API com limites de cota, consulte Gerenciar produtos de API.

Como configurar contadores de cotas compartilhados

No caso simples, a política LLMTokenQuota incrementa o contador uma vez para cada token enviado a um proxy de API durante o processamento inicial da solicitação. Em alguns casos, talvez seja necessário verificar se a cota foi excedida no processamento inicial da solicitação recebida, mas incrementar o contador apenas durante o processamento da resposta.

Três elementos da política LLMTokenQuota (<SharedName>, <CountOnly> e <EnforceOnly>) permitem personalizar a política LLMTokenQuota para aplicar a cota em solicitações recebidas, mas só incrementam o contador no fluxo de resposta.

Por exemplo, suponha que você tenha um proxy de API que usa um LLM como destino e queira aplicar uma cota de 100.000 tokens por hora. As respostas do LLM fornecem um valor totalTokenCount. Para fazer isso, siga estas etapas:

  • Anexe uma política LLMTokenQuota ao fluxo de solicitação 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 buscar a contagem de tokens.

Para ver um exemplo de como usar contadores compartilhados, consulte Contadores compartilhados na seção Amostras.

Amostras

Estes exemplos de códigos de política ilustram como iniciar e encerrar períodos de cota:

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 cotas dinâmicas permitem que você configure uma única política LLMTokenQuota que impõe diferentes configurações de cota com base nas informações transmitidas para essa política. Outro termo para as configurações de LLMTokenQuota neste contexto é plano de serviço. A cota dinâmica de LLMTokenQuota verifica o plano de serviços dos apps e aplica essas configurações.

Por exemplo, ao criar um produto de API, você tem a opção de definir o limite de cota, a unidade de tempo e o intervalo permitidos. No entanto, definir esses valores no produto de API não impõe o uso em um proxy de API. Você também precisa adicionar uma política LLMTokenQuota ao proxy de API que lê esses valores. Consulte Criar produtos de API para saber mais.

No exemplo acima, o proxy de API que contém a política LLMTokenQuota usa uma política VerifyAPIKey chamada verify-api-key para validar a chave de API transmitida em uma solicitação. A política LLMTokenQuota acessa as variáveis de fluxo da política VerifyAPIKey para ler os valores de cota definidos no produto de API.

Outra opção é definir atributos personalizados em desenvolvedores ou apps individuais e ler esses valores na política LLMTokenQuota. Por exemplo, para definir valores de cota diferentes por desenvolvedor, defina atributos personalizados no desenvolvedor que contêm o limite, a unidade de tempo e o intervalo. Em seguida, faça referência a esses 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 desenvolvedor.

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

  • Variáveis de fluxo
  • Propriedades sobre o produto, aplicativo ou desenvolvedor de API
  • Um mapa de chave-valor (KVM)
  • Um cabeçalho, parâmetro de consulta ou parâmetro de formulário, entre outros

Para cada proxy de API, é possível adicionar uma política LLMTokenQuota que referencie a mesma variável de todas as outras políticas LLMTokenQuota em todos os outros proxies ou a política LLMTokenQuota pode referenciar variáveis exclusivas para essa política e proxy.

Horário 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 uma LLMTokenQuota com type definido como calendar, defina um valor <StartTime> explícito. O valor de hora é o horário GMT, não horário local. Se você não fornecer um valor <StartTime> para uma política do tipo calendar, a Apigee emitirá um erro.

O contador LLMTokenQuota de cada app é atualizado com base nos valores de <StartTime>, <Interval> e <TimeUnit>. Para este exemplo, a LLMTokenQuota começa a contar às 10h30 GMT em 18 de fevereiro de 2025 e é atualizada a cada cinco horas. Portanto, a próxima atualização é às 15h30 GMT, em 18 de fevereiro de 2025.

Contador de acessos

<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. Acesse essas variáveis de fluxo no proxy da API para executar o processamento condicional, monitorar a política conforme ela se aproxima do limite da cota, retornar o contador de cotas atual para um app ou por outras razões.

Como o acesso das variáveis de fluxo para a política é baseado no atributo name das políticas, para a política acima chamada <LLMTokenQuota>, você acessa as variáveis do fluxo no formulário:

  • ratelimit.LLMTokenQuotaPolicy.allowed.count: contagem permitida.
  • ratelimit.LLMTokenQuotaPolicy.used.count: valor do contador atual.
  • ratelimit.LLMTokenQuotaPolicy.expiry.time: horário UTC quando o contador é redefinido.

Há muitas outras variáveis de fluxo que você pode acessar, conforme descrito abaixo.

Por exemplo, use a seguinte política AssignMessage para retornar os valores das variáveis do 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 compartilhados

O exemplo a seguir ilustra como configurar um contador compartilhado para um proxy de API, em que o contador de cotas também é incrementado quando a resposta de destino é o status HTTP 200. Como as duas políticas LLMTokenQuota usam o mesmo valor <SharedName>, ambas compartilham o mesmo contador de cotas. Para mais informações, consulte Como configurar contadores de cota compartilhados.

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

Exemplo da primeira 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 de 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>

Primeira solicitação

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

Use este exemplo de código para aplicar uma cota de 10.000 tokens por hora. A política redefine o contador de cotas na parte superior de cada hora. Se o contador atingir a cota de 10.000 tokens antes do fim da hora, as chamadas de API que consomem tokens além de 10.000 serão rejeitadas.

Por exemplo, se o contador começar em 2025-07-08 07:00:00, ele será redefinido para 0 às 2025-07-08 08:00:00 (1 hora a partir do horário de início). Se a primeira solicitação for recebida em 2025-07-08 07:35:28 e a contagem de tokens alcançar 10.000 antes de 2025-07-08 08:00:00, as solicitações que consomem tokens além dessa contagem serão rejeitadas até que a contagem seja redefinida no topo da hora.

O tempo de redefinição de contador é baseado na combinação de <Interval> e <TimeUnit>. Por exemplo, se você definir <Interval> como 12 para uma <TimeUnit> de hora, o contador será redefinido a cada 12 horas. Você pode definir <TimeUnit> como minuto, hora, dia, semana ou mês.

Você pode referenciar essa política em vários lugares no proxy da API. Por exemplo, você pode colocá-lo no pré-fluxo de proxy para que ele seja executado em todas as solicitações. Também é possível colocá-lo em vários fluxos no proxy da API. Se você usar essa política em vários lugares no proxy, ela manterá um único contador atualizado por todas as instâncias da política.

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

Definir 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 padrão, uma política LLMTokenQuota define um único contador para o proxy de API, independente da origem de uma solicitação. Como alternativa, é possível usar o atributo <Identifier> com uma política LLMTokenQuota para manter contadores separados com base no valor do atributo <Identifier>.

Por exemplo, use a tag <Identifier> para definir contadores separados para cada ID do cliente. Em uma solicitação ao seu proxy, o app cliente transmite um cabeçalho contendo clientID, conforme mostrado no exemplo acima.

É possível especificar qualquer variável de fluxo para o atributo <Identifier>. Por exemplo, é possível especificar que um parâmetro de consulta chamado id contenha o identificador exclusivo:

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

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

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

Cada valor client_id exclusivo agora define seu próprio contador na política LLMTokenQuota (link em inglês).

Turma

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

Você pode definir limites de LLMTokenQuota dinamicamente usando uma contagem de LLMTokenQuota baseada em classe. Neste exemplo, o limite de cota é determinado pelo valor do cabeçalho developer_segment transmitido com cada solicitação. Essa variável pode ter um valor de platinum ou silver. Se o cabeçalho tiver um valor inválido, a política retornará um erro de violação de cota.

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

Calcular tokens

Este exemplo mostra como calcular 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>

Contar variáveis dinâmicas de cota usando produto de API, desenvolvedor e app

Este exemplo mostra como contar variáveis dinâmicas de cota usando produto de API, desenvolvedor 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>

Aplicar cota sem produto de API

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

Aplicar cota com produto de API, desenvolvedor e app

Este exemplo mostra como aplicar a cota com produto de API, desenvolvedor 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>

Com fluxo de SSE

Este exemplo mostra como usar LLMTokenQuota com um fluxo SSE.

Política de contagem de cota 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>

Elemento <LLMTokenQuota>

Veja a seguir os atributos e elementos filho de <LLMTokenQuota>. Observe que algumas combinações de elementos são mutuamente exclusivas ou não obrigatórias. Consulte as amostras para uso específico.

As variáveis verifyapikey.my-verify-key-policy.apiproduct.* abaixo estão disponíveis por padrão quando uma política VerifyAPIKey chamada my-verify-key-policy é usada para verificar a chave de API do app na solicitação. Os valores das variáveis vêm das configurações de cota no produto da API a que a chave está associada, conforme descrito em Como conseguir configurações de cota 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 atributos a seguir são específicos dessa política:

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

Define o tipo de política LLMTokenQuota, que determina quando e como o contador de cotas verifica o uso da cota, além de como ela é redefinida.

Se você não definir type, o contador começará no início do minuto, da hora, do dia, da semana ou do mês.

Valores válidos:

  • calendar
  • rollingwindow
  • flexi

Para ver uma descrição completa de cada tipo, consulte Tipos de políticas de cota de token de LLM.

 N/A Opcional

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo Descrição Padrão Presence
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

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

 N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

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

 false Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

 true Opcional
async

Esse atributo está obsoleto.

 false Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence 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 esse valor de limite, as chamadas de API subsequentes serão rejeitadas até que o contador seja redefinido.

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

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo inteiro ou complexo
Elemento pai <LLMTokenQuota>
Elemento filho <Class>

Veja abaixo três maneiras 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 você especificar count e countRef, countRef terá a prioridade. Se countRef não for resolvido no ambiente de execução, o valor de count será usado.

Também é possível especificar um elemento <Class> como filho de <Allow> para determinar a contagem permitida da política com base em uma variável de fluxo. A Apigee combina o valor da variável de fluxo com o elemento class da tag <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 a seguir lista os atributos de <Allow>:

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

Use para especificar uma contagem de tokens para a cota.

Por exemplo, um valor de atributo count de 100, Interval de 1 e TimeUnit do mês especifica uma cota 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 cota. countRef tem precedência sobre o atributo count.

 nenhum Opcional

<Class>

Permite que você condicione o valor do elemento <Allow> com base no valor de uma variável de fluxo. Para cada tag filha <Allow> diferente de <Class>, a política mantém um contador diferente.

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento pai <Allow>
Elemento filho <Allow> (Filho de <Class>)

Para usar o elemento <Class>, especifique uma variável de fluxo usando o atributo ref para a elemento <Class>. Em seguida, a Apigee usa o valor da variável de fluxo para selecionar um dos elementos filhos <Allow> e determinar a contagem permitida da política. A Apigee combina o valor da variável de fluxo com o elemento class da tag <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 cotas atual é determinado pelo valor do parâmetro de consulta time_variable transmitido com cada solicitação. 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 retornará um erro de violação de cota.

A tabela a seguir lista os atributos de <Class>:

Atributo Descrição Padrão Presença
ref Use para especificar uma variável de fluxo contendo a classe de cota para uma cota. nenhum Obrigatório

<Allow> (filho de <Class>)

Especifica o limite de um contador de cotas definido pelo elemento <Class>. Para cada tag filha <Allow> diferente de <Class>, a política mantém um contador diferente.

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento pai <Class>
Elemento filho Nenhum

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 cota chamados peak_time e off_peak_time. Dependendo disso, você usará o parâmetro de consulta transmitido, como mostrado no exemplo de <Class>.

A tabela a seguir lista os atributos de <Allow>:

Atributo Descrição Padrão Presença
class Define o nome do contador de cotas. nenhum Obrigatório
count Especifica o limite de cota para o contador. nenhum Obrigatório

<IgnoreUnresolvedVariables>

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

Valor padrão falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false. O valor padrão é false.

Se <IgnoreUnresolvedVariables> estiver definido como true e a variável especificada em um atributo ref não puder ser resolvida, a Apigee vai ignorar o atributo ref. Se o elemento que contém o atributo ref também tiver um valor, como <Allow count="2000"/>, a Apigee usará esse valor. Se não houver um valor, a Apigee vai tratar o valor do elemento como nulo e substituir o valor padrão, se houver um, ou uma string vazia.

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

<Interval>

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

Valor padrão N/A
Obrigatório? Obrigatório
Tipo Número inteiro
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

Use para especificar um número inteiro (por exemplo, 1, 2, 5, 60 e assim por diante) que será pareado com o elemento <TimeUnit> especificado (minuto, hora, dia, semana ou mês) para determinar um período em que o Apigee calcula o uso da cota.

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

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

A tabela a seguir lista os atributos de <Interval>:

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

Use para especificar uma variável de fluxo contendo o intervalo de uma cota. ref tem precedência sobre um valor de intervalo explícito. Se a referência e o valor forem especificados, a referência terá a prioridade. Se ref não for resolvido no ambiente de execução, o valor será usado.

 nenhum Opcional

<TimeUnit>

Especifica a unidade de tempo aplicável à cota.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

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

Por exemplo, uma Interval de 24 com TimeUnit de hour significa que a cota será calculada ao longo de 24 horas.

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

A tabela a seguir lista os atributos de <TimeUnit>:

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

<StartTime>

Quando type for definido como calendar, especifica a data e a hora em que o contador de cotas começa a contagem, independentemente de as solicitações terem sido recebidas de qualquer aplicativo.

Valor padrão N/A
Obrigatório? Opcional (obrigatório quando type estiver definido como calendar)
Tipo String no formato de data e hora ISO 8601
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

Exemplo:

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

<Distributed>

Determina se a Apigee usa um ou mais nós para processar solicitações.

Valor padrão falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

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

Se você usar o valor padrão false, poderá exceder sua cota porque a contagem de cada nó não é compartilhada:

<Distributed>false</Distributed>

Para garantir que os contadores sejam sincronizados e atualizados em cada solicitação, defina <Distributed> e <Synchronous> para true:

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

<Synchronous>

Determina se um contador de cota distribuída precisa ser atualizado de forma síncrona.

Valor padrão falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

Defina como true para atualizar um contador de cotas distribuídas de forma síncrona. Isso significa que as atualizações nos contadores são feitas ao mesmo tempo, que a cota é verificada em uma solicitação à API. Defina como true se for essencial que você não permita chamadas de API acima da cota.

Defina como false para atualizar o contador de cotas de forma assíncrona. Isso significa que é possível que algumas chamadas de API que excedam a cota passem, dependendo de quando o contador de cotas no repositório central for atualizado de forma assíncrona. No entanto, você não enfrentará os possíveis impactos de desempenho associados a atualizações síncronas.

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

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

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

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento pai <LLMTokenQuota>
Elemento filho <SyncIntervalInSeconds>
<SyncMessageCount>

É possível especificar o comportamento da sincronização usando os elementos filhos <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> estiver presente, a cota será sincronizada a cada N segundos, em que N é o valor especificado no elemento, independentemente do número de mensagens processadas.
  • Quando apenas <SyncMessageCount> está presente, a cota sincroniza a cada M mensagens, em que M é o valor especificado no elemento ou a cada 10 segundos, o que ocorrer primeiro.
  • Quando ambos os elementos estiverem presentes, a cota sincroniza a cada M mensagens ou a cada N segundos, o que ocorrer primeiro.
  • Quando <AsynchronousConfiguration> não estiver presente ou nenhum elemento filho estiver presente, a cota é sincronizada a cada 10 segundos, independente do número de mensagens processadas.

<SyncIntervalInSeconds>

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

Valor padrão 10 segundos
Obrigatório? Opcional
Tipo Número inteiro
Elemento pai <AsynchronousConfiguration>
Elemento filho Nenhum
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

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

<SyncMessageCount>

Especifica o número de solicitações a serem processadas antes de sincronizar o contador de cotas.

Valor padrão N/A
Obrigatório? Opcional
Tipo Número inteiro
Elemento pai <AsynchronousConfiguration>
Elemento filho Nenhum
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Usando a configuração deste exemplo, em cada nó, a contagem de cota será sincronizada a cada 5 solicitações ou a cada 10 segundos, o que ocorrer primeiro.

<LLMTokenUsageSource>

Fornece a origem do uso de tokens da resposta do LLM. Precisa ser um modelo de mensagem que seja resolvido como um único valor de uso de token. Se a política não fizer parte de um fluxo de eventos e não puder extrair a contagem de tokens da fonte especificada, ela vai gerar um erro de tempo de execução policies.ratelimit.FailedToResolveTokenUsageCount.

Valor padrão {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
Obrigatório? Opcional
Tipo String
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

O exemplo a seguir mostra como especificar a origem do uso do token:

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

<LLMModelSource>

Fornece a origem do nome do modelo da resposta ou solicitação do LLM. Precisa ser um modelo de mensagem que forneça um único valor de nome do modelo.

Valor padrão
Obrigatório? Opcional
Tipo String
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

O exemplo a seguir mostra como especificar a origem do modelo na solicitação:

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

<Identifier>

Configura a política para criar contadores exclusivos com base em uma variável de fluxo.

Valor padrão N/A
Obrigatório? Opcional
Tipo String
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

Usando o elemento identificador, você pode alocar contagens de token a buckets diferentes definidos pelo valor em uma variável de fluxo. Por exemplo, é possível usar a variável developer.id, que é preenchida após uma política VerifyAPIKey, para aplicar um limite de cota a todas as instâncias de todos os apps criados por cada desenvolvedor específico . Você também pode usar o client_id para aplicar um limite de cota a cada app. A configuração do último é semelhante a esta:

<Identifier ref="client_id"/>

Você pode consultar uma variável personalizada que pode ser definida com aPolítica de "AssignMessage" ou aPolítica do JavaScript ou uma variável definida implicitamente, como as definidas peloPolítica VerifyAPIKey ou aVerificar política JWT de dados. Para mais informações sobre variáveis, consulte Como usar variáveis de fluxo. Para ver uma lista de variáveis conhecidas definidas pela Apigee, consulte a Referência de variáveis de fluxo.

Se você não usar esse elemento, a política alocará todas as contagens de tokens em um único contador para a política LLMTokenQuota específica.

A tabela a seguir descreve os atributos de <Identifier>:

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

Especifica uma variável de fluxo que identifica o contador a usar para a solicitação. A variável pode se referir 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 alocar contagens de tokens.

Geralmente, o client_id é usado como variável. O client_id também é conhecido como a chave de API ou chave do cliente e é gerado para um app quando ele é registrado em uma organização na Apigee. Você pode usar esse identificador se tiver ativado as chaves de autorização da API ou do OAuth na API.

 N/A Opcional

<UseQuotaConfigInAPIProduct>

Define configurações de cota para um produto da API, como unidades de tempo, intervalo e máximo permitido.

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento pai <LLMTokenQuota>
Elemento filho <DefaultConfig>

Se você adicionar o elemento <UseQuotaConfigInAPIProduct> à política LLMTokenQuota, a Apigee vai ignorar os elementos filhos <Allow>, <Interval> e <TimeUnit> de LLMTokenQuotaPolicy.

O elemento <UseQuotaConfigInAPIProduct> é simplesmente um contêiner das configurações padrão definidas usando o elemento <DefaultConfig>, como no exemplo a seguir:

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

É possível usar o atributo stepName para referenciar uma política VerifyAPIKey ou uma operação ValidateToken da política OAuthv2 no fluxo.

A tabela a seguir descreve os atributos de <UseQuotaConfigInAPIProduct>:

Atributo Descrição Padrã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ório

Para ver mais informações, consulte os seguintes tópicos:

<DefaultConfig>

Contém valores padrão para a cota de um produto da API. Quando você define um <DefaultConfig>, os três elementos filhos são obrigatórios.

Valor padrão N/A
Obrigatório? Opcional
Tipo Tipo complexo
Elemento pai <UseQuotaConfigInAPIProduct>
Elemento filho <Allow>
<Interval>
<TimeUnit>

É possível definir esses valores na operação do produto da API, seja com a UI ou com a API de produtos de API, e na política LLMTokenQuota. No entanto, se as configurações no produto da API tiverem precedência e as configurações na política LLMTokenQuota forem ignoradas.

A sintaxe para esse 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 a seguir especifica uma cota de 10.000 todas as semanas:

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

Para ver mais informações, consulte os seguintes tópicos:

<SharedName>

Identifica esta política LLMTokenQuota como compartilhada. Todas as políticas LLMTokenQuota em um proxy de API com o mesmo valor <SharedName> compartilham o mesmo contador de cotas subjacente.

Para mais informações e exemplos, consulte Como configurar contadores de cotas compartilhados.

Valor padrão N/A
Obrigatório? Opcional
Tipo String
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

<CountOnly>

Coloque uma política LLMTokenQuota com esse elemento definido como true em uma etapa no fluxo de resposta ProxyEndpoint para rastrear o número de tokens sem enviar um erro de volta ao cliente quando o limite de cota de token é excedido. Se esse elemento estiver presente, o elemento <SharedName> também precisará estar presente, e o elemento <EnforceOnly> não poderá estar presente.

Para mais informações e exemplos, consulte Como configurar contadores de cota compartilhados.

Valor padrão falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <LLMTokenQuota>
Elemento filho Nenhum

<EnforceOnly>

Coloque uma política LLMTokenQuota com esse elemento definido como true no fluxo de solicitação de um proxy de API para aplicar um limite de token sem incrementar o contador de cotas. Se esse elemento estiver presente, o <SharedName> também precisará estar presente e o elemento <CountOnly> não poderá estar presente.

Para mais informações e exemplos, consulte Como configurar contadores de cota compartilhados.

Valor padrão falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <LLMTokenQuota>
Elemento filho 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 Permissões Descrição
ratelimit.{policy_name}.allowed.count Longo Somente leitura Retorna a contagem de cotas permitida
ratelimit.{policy_name}.used.count Longo Somente leitura Retorna a cota atual usada dentro de um intervalo de cotas.
ratelimit.{policy_name}.available.count Longo Somente leitura Retorna a contagem de cotas disponíveis no intervalo de cotas.
ratelimit.{policy_name}.exceed.count Longo Somente leitura Retorna 1 após a cota ser excedida.
ratelimit.{policy_name}.total.exceed.count Longo Somente leitura Retorna 1 após a cota ser excedida.
ratelimit.{policy_name}.expiry.time Longo Somente leitura

Retorna o horário UTC (em milissegundos), que determina quando a cota expira e quando o novo intervalo de cota é iniciado.

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

ratelimit.{policy_name}.identifier String Somente leitura Retorna a referência do identificador (cliente) anexada à política
ratelimit.{policy_name}.class String Somente leitura Retorna a classe associada ao identificador do cliente
ratelimit.{policy_name}.class.allowed.count Longo Somente leitura Retorna a contagem de cotas permitidas definida na classe
ratelimit.{policy_name}.class.used.count Longo Somente leitura Retorna a cota usada dentro de uma classe
ratelimit.{policy_name}.class.available.count Longo Somente leitura Retorna a contagem de cotas disponíveis na classe
ratelimit.{policy_name}.class.exceed.count Longo Somente leitura Retorna a contagem de tokens que excede o limite da classe no intervalo de cota atual.
ratelimit.{policy_name}.class.total.exceed.count Longo Somente leitura Retorna a contagem total de tokens que excedem o limite na classe em todos os intervalos de cota. Portanto, é a soma de class.exceed.count para todos os intervalos de cota.
ratelimit.{policy_name}.failed Booleano Somente leitura

Indica se a política falhou (verdadeiro ou falso).
llmtokenquota.{policy_name}.model String Somente leitura Retorna o modelo extraído.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Código de falha Status 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 uso do token. N/A
policies.llmtokenquota.MessageTemplateExtractionFailed 400 A extração do modelo de mensagem falhou. N/A
policies.llmtokenquota.LLMTokenQuotaViolation 429 O limite de cota de tokens do LLM foi excedido. N/A
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Ocorre se o elemento <Interval> não estiver definido na política LLMTokenQuota. Esse elemento é obrigatório e usado para especificar o intervalo de tempo aplicável à cota 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. Esse elemento é obrigatório e usado para especificar a unidade de tempo aplicável à cota de tokens do LLM. O intervalo de tempo pode ser de minutos, horas, dias, semanas ou meses.

Erros de implantação

Nome do erro Causa Corrigir
policies.llmtokenquota.MessageWeightNotSupported Erro quando o elemento "MessageWeight" é usado, já que não é compatível. N/A
policies.llmtokenquota.InvalidConfiguration É necessário definir exatamente um de <CountOnly> ou <EnforceOnly> como verdadeiro. N/A
InvalidQuotaInterval Se o intervalo de cota de token do LLM especificado no elemento <Interval> não for um número inteiro, a implantação do proxy de API vai falhar. Por exemplo, se o intervalo de cota especificado for 0.1 no elemento <Interval>, a implantação do proxy de API falhará.
InvalidQuotaTimeUnit Se a unidade de tempo especificada no elemento <TimeUnit> não for compatível, a implantação do proxy de API falhará. As unidades de tempo compatíveis são minute, hour, day, week e month.
InvalidQuotaType Se o tipo da cota de token do LLM especificado pelo atributo type no elemento <LLMTokenQuota> for inválido, a implantação do proxy de API vai falhar. Os tipos de cota compatíveis são default, calendar, flexi e rollingwindow.
InvalidStartTime Se o formato do tempo especificado no elemento <StartTime> for inválido, a implantação do proxy de API falhará. O formato válido é yyyy-MM-dd HH:mm:ss, que é o formato de data e hora ISO 8601. Por exemplo, se o tempo especificado no elemento <StartTime> for 7-16-2017 12:00:00, a implantação do proxy da API falhará.
StartTimeNotSupported Se o elemento <StartTime> for especificado e tem um tipo de cota que não é calendar, a implantação do proxy da API falhará. O elemento <StartTime> é compatível apenas com o tipo de cota calendar. Por exemplo, se o atributo type estiver definido como flexi ou rolling window no elemento <LLMTokenQuota>, a implantação do proxy da API falhará.
InvalidSynchronizeIntervalForAsyncConfiguration Se o valor especificado para o elemento <SyncIntervalInSeconds> dentro do elemento <AsynchronousConfiguration> em uma política LLMTokenQuota for menor que zero, a implantação do proxy de API falhará.
InvalidAsynchronizeConfigurationForSynchronousQuota Se o valor do elemento <AsynchronousConfiguration> estiver definido como true em uma política LLMTokenQuota, que também tem uma configuração assíncrona definida usando o elemento <AsynchronousConfiguration>, a implantação do proxy de API falhará.

Variáveis de falha

Essas variáveis são definidas quando esta política aciona um erro. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente 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 usuário da política que causou 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

Temas relacionados

Política PromptTokenLimit