Política PromptTokenLimit

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 PromptTokenLimit protege os back-ends de modelos de linguagem grandes (LLMs) contra picos de tráfego, limitando o número de tokens nos comandos do usuário.

A política PromptTokenLimit é semelhante à política SpikeArrest. No entanto, a política SpikeArrest limita o número de solicitações, enquanto a política PromptTokenLimit limita o número de tokens nessas solicitações. Essa política é especificamente adaptada para aplicativos de LLM em que o custo e o desempenho estão diretamente relacionados ao número de tokens processados.

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.

A diferença entre PromptTokenLimit e LLMTokenQuota

A política PromptTokenLimit é usada para gerenciamento operacional de tráfego e evitar picos repentinos no uso de tokens. Por outro lado, a política LLMTokenQuota é usada para impor limites de consumo em apps de clientes por períodos mais longos (como horas, dias ou meses) para gerenciar custos e aplicar contratos comerciais.

Elemento PromptTokenLimit

Define a política PromptTokenLimit.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Opcional
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	<Identifier> <Rate> (obrigatório) <UseEffectiveCount> <UserPromptSource> <IgnoreUnresolvedVariables>

Sintaxe

O elemento PromptTokenLimit usa a seguinte sintaxe:

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política PromptTokenLimit ao fluxo na UI:

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	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.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a 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: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

Exemplos

Os exemplos a seguir mostram algumas maneiras de usar a política PromptTokenLimit:

Exemplo 1

Limitação de tokens de comandos em uma única réplica.

Neste exemplo, a limitação de tokens de solicitação ocorre em uma única réplica e não é distribuída entre vários processadores de mensagens em uma região.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Exemplo 2

Limitação de tokens distribuídos.

Neste exemplo, a limitação de tokens de solicitação é distribuída por várias réplicas em uma região, e um algoritmo de limitação de taxa de "janela deslizante" é usado.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

Exemplo 3

Limitação de token de tamanho da janela de contexto por solicitação.

Neste exemplo, a limitação de tokens de solicitação ocorre em uma única réplica e não é distribuída entre vários processadores de mensagens em uma região. Essa configuração específica é usada para limitar o tamanho da janela de contexto por solicitação.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Exemplo 4

Limitação de token distribuída com valores padrão.

Neste exemplo, a limitação de tokens de solicitação ocorre em uma única réplica e não é distribuída entre vários processadores de mensagens em uma região. O valor padrão da origem da solicitação do usuário é usado: {jsonPath('$.messages',request.content,true)}

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Referência a elementos filhos

Esta seção descreve os elementos filhos de <PromptTokenLimit>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo	String
Elemento pai	<PolicyElement>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

O elemento <DisplayName> não tem atributos ou elementos filhos.

<Identifier>

Permite escolher como agrupar as solicitações, para que a política PromptTokenLimit possa ser aplicada com base no cliente. Por exemplo, é possível agrupar solicitações por ID de desenvolvedor. Nesse caso, as solicitações de cada desenvolvedor serão consideradas na própria taxa de PromptTokenLimit e não todas as solicitações para o proxy.

Se você deixar o elemento <Identifier> vazio, um limite de taxa será aplicado a todas as solicitações nesse proxy de API.

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

Sintaxe

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

Exemplo 1

O exemplo a seguir aplica a política PromptTokenLimit por ID de desenvolvedor:

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>
      

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

Atributo	Descrição	Padrão	Presença
ref	Identifica a variável pela qual o PromptTokenLimit agrupa as solicitações recebidas. É possível usar qualquer variável de fluxo para indicar um cliente único, como aqueles disponíveis na política VerifyAPIKey. Também é possível definir variáveis personalizadas usando a política JavaScript ou a política AssignMessage.	N/A	Obrigatório

<Rate>

Especifica a taxa para limitar os picos (ou bursts) de tokens definindo o número de tokens permitidos em intervalos de minutos ou segundos. É possível usar esse elemento com <Identifier> para limitar facilmente o tráfego no ambiente de execução aceitando valores do cliente. Use o elemento <UseEffectiveCount> para definir o algoritmo de limitação de taxa usado pela política.

Observação:o uso de <UseEffectiveCount> com um valor ou false não é compatível com nenhuma organização da Apigee ou com organizações da Apigee híbrida que executam cargas de trabalho de produção. Para mais informações, consulte <UseEffectiveCount>.

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

Sintaxe

É possível especificar taxas de uma das seguintes maneiras:

• Uma taxa estática que você especifica como o corpo do elemento <Rate>
• Um valor variável, que pode ser transmitido pelo cliente; identifica o nome da variável de fluxo usando o atributo ref

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

Os valores de taxa válidos (definidos como um valor variável ou no corpo do elemento) precisam estar em conformidade com o seguinte formato:

• intps (número de tokens por segundo, simplificados em intervalos de milissegundos)
• intpm (número de tokens por minuto, simplificados em intervalos de segundos)

O valor de int precisa ser um número inteiro positivo diferente de zero.

Exemplo 1

O exemplo a seguir define a taxa como cinco tokens por segundo:

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

A política simplifica a taxa para um token permitido a cada 200 milissegundos (1000/5).

Exemplo 2

O exemplo a seguir define a taxa como 12 tokens por minuto:

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

Essa política de exemplo simplifica a taxa para um token permitido a cada cinco segundos (60/12).

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

Atributo	Descrição	Presença	Padrão
ref	Identifica uma variável de fluxo que especifica a taxa. Ele pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, cabeçalho ou conteúdo do corpo da mensagem, ou um valor como um KVM. Para mais informações, consulte a Referência de variáveis de fluxo. Também é possível usar variáveis personalizadas usando a política JavaScript ou a política AssignMessage. Se você definir ref e o corpo desse elemento, o valor de ref será aplicado e terá precedência quando a variável de fluxo for definida na solicitação. O inverso é verdadeiro quando a variável identificada em ref não é definida na solicitação. Exemplo: <Rate ref="request.header.custom_rate">1pm</Rate> Neste exemplo, se o cliente não transmitir um cabeçalho custom_rate, a taxa do proxy de APII será de um token por minuto para todos os clientes. Se o cliente transmitir um cabeçalho custom_rate, cujo valor é 10ps, para todos os clientes no proxy, até que uma solicitação sem o cabeçalho custom_rate seja enviada. Use <Identifier> para agrupar solicitações que impõem taxas personalizadas a diferentes tipos de clientes. Se você especificar um valor para ref, mas não definir a taxa no corpo do elemento <Rate> e o cliente não transmitir um valor, a política PromptTokenLimit gerará um erro.	Opcional	N/A

A tabela a seguir descreve os atributos de Rate que definem o comportamento da limitação de tráfego:

Atributo	Descrição
messagesPerPeriod	Especifica o número de tokens permitidos em um período definido. Por exemplo, se uma política for configurada para "10ps" (10 tokens por segundo), o valor de messagesPerPeriod será 10.
periodInMicroseconds	Define o período, em microssegundos, em que o messagesPerPeriod é calculado. Para uma configuração "10ps", esse valor seria 1.000.000, o que equivale a um segundo.
maxBurstMessageCount	Representa o número máximo de tokens que podem ser permitidos instantaneamente ou em um curto período no início de um novo intervalo.

Observação:os valores e cálculos desses atributos podem ser afetados pelo número de MPs e se a configuração UseEffectiveCount está ativada. Por exemplo, se você definir uma taxa de "10ps" com 10 MPs e UseEffectiveCount estiver ativado, a taxa efetiva para cada MP será de 1ps. Os atributos internos do MP individual são ajustados para refletir isso. Por exemplo, o atributo messagesPerPeriod pode ser definido como 1 e periodInMicroseconds como 1.000.000.

<UseEffectiveCount>

Esse elemento permite escolher entre algoritmos distintos de PromptTokenLimit definindo o valor como true ou false, conforme explicado abaixo:

verdadeiro

Se definida como true, a PromptTokenLimit será distribuída em uma região. Isso significa que as contagens de solicitações são sincronizadas entre os processadores de mensagens (MPs) em uma região. Além disso, um algoritmo de limitação de taxa de "janela deslizante" é empregado. Esse algoritmo fornece um comportamento de limite de taxa consistente e não "nivela" o número de solicitações recebidas que podem ser enviadas para o back-end. Se uma explosão de solicitações for enviada em um curto intervalo de tempo, elas serão permitidas, desde que não excedam o limite de taxa configurado, conforme definido no elemento <Rate> , Por exemplo:

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false (padrão)

Observação:embora o valor padrão seja false, as organizações da Apigee precisam definir esse elemento como true.

O ajuste de taxa não é compatível com organizações do Apigee.

Se definida como false (padrão), a política PromptTokenLimit usará um algoritmo de intervalo de token que suaviza os picos de token dividindo o limite de taxa especificado em intervalos menores. Uma desvantagem dessa abordagem é que vários tokens legítimos recebidos em um curto período podem ser negados.

Por exemplo, digamos que você insira uma taxa de 30pm (30 tokens por minuto). Durante os testes, talvez você ache que possa enviar 30 tokens em um segundo, desde que tenham ocorrido em um minuto. Mas não é assim que a política aplica a configuração. Se você pensar nisso, 30 tokens dentro de um período de um segundo podem ser considerados um pequeno pico em alguns ambientes.

• As taxas por minuto são simplificadas em solicitações completas permitidas em intervalos de segundos.

  Por exemplo, 30pm fica mais tranquilo assim:
  60 segundos (1 minuto) / 30pm = intervalos de 2 segundos, ou 1 token permitido a cada 2 segundos. Um segundo token dentro de 2 segundos vai falhar. Além disso, um 31º token em um minuto vai falhar.

• As taxas por segundo são simplificadas em solicitações completas permitidas em intervalos de milissegundos.

  Por exemplo, 10 ps são simplificados desta maneira:
  1.000 milissegundos (1 segundo) / 10 ps = intervalos de 100 milissegundos ou 1 token permitido a cada 100 milissegundos. Um segundo token em 100 ms vai falhar. Além disso, um 11º token em um segundo vai falhar.

Observação:na simplificação de taxa, o número de tokens é sempre um número inteiro maior que zero. A simplificação nunca envolve o cálculo de frações de tokens.

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

A tabela a seguir descreve os atributos do elemento <UseEffectiveCount>:

Atributo	Descrição	Padrão	Presença
ref	Identifica a variável que contém o valor de <UseEffectiveCount>. Pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, cabeçalho ou conteúdo do corpo da mensagem. Para mais informações, consulte a Referência de variáveis de fluxo. Também é possível definir variáveis personalizadas usando a política JavaScript ou a política AssignMessage.	N/A	Opcional

<UserPromptSource>

Fornece a origem para recuperar o texto do comando do usuário. Use um modelo de mensagem.

O modelo de mensagem precisa fornecer um único valor do texto do comando do usuário.

Por exemplo, {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}

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

Sintaxe

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

Exemplo 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

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

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

Sintaxe

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Exemplo

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

Variáveis de fluxo

Quando uma política PromptTokenLimit é executada, as seguintes variáveis de fluxo são preenchidas:

Variável	Tipo	Permissão	Descrição
ratelimit.POLICY_NAME.failed	Booleano	Somente leitura	Indica se a política falhou (true ou false).
ratelimit.POLICY_NAME.resolvedUserPrompt	String	Somente leitura	Retorna o comando do usuário extraído.
ratelimit.POLICY_NAME.userPromptSource	String	Somente leitura	Retorna o modelo de mensagem para o comando do usuário especificado na política.
ratelimit.POLICY_NAME.userPromptTokenCount	String	Somente leitura	Retorna a contagem de tokens do comando do usuário extraído.

Para mais informações, consulte a Referência de variáveis de fluxo.

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. Também é possível encontrar erros na política SpikeArrest. 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.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Código de falha	Status HTTP	Falha da Apigee	Causa	Corrigir
policies.prompttokenlimit.FailedToExtractUserPrompt	400	FALSO	Não foi possível extrair o comando do usuário da solicitação de API.
policies.prompttokenlimit.PromptTokenLimitViolation	429	FALSO	Violação de PromptTokenLimit.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens	500	TRUE	Não é possível calcular os tokens para o comando do usuário.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para informações detalhadas sobre a solução de problemas.

Código de falha	Status HTTP	Falha da Apigee	Causa	Correção
policies.prompttokenlimit.MessageWeightNotSupported	500	FALSO	MessageWeight não é compatível com a política PromptTokenLimit.

Variáveis de falha

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

Variáveis	Onde	Exemplo
ratelimit.policy_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 "PromptTokenLimitViolation"
ratelimit.policy_name.failed	policy_name é o nome da política especificada pelo usuário que gerou a falha.	ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Exemplo de resposta de erro

Veja abaixo um exemplo de resposta de erro:

Observação:para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque ele pode mudar.

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

Exemplo de regra de falha

Veja abaixo um exemplo de regra de falha para lidar com uma falha PromptTokenLimitViolation:

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "PromptTokenLimitViolation") </Condition>
        </Step>
        <Condition>ratelimit.PTL-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

O código de status HTTP atual para exceder um limite de taxa definido por uma política de LLMTokenQuota ou PromptTokenLimit é 429 (muitas solicitações).

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

Temas relacionados

• Política LLMTokenQuota: política LLMTokenQuota para limitar o uso da cota de tokens de resposta.
• Limitação de taxa para uma visão geral da limitação de taxa
• Como comparar políticas de limitação de taxa