Política PromptTokenLimit

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 PromptTokenLimit protege os backends de grandes modelos de linguagem (GMLs) contra picos de tráfego, limitando o número de tokens nos comandos dos utilizadores.

A política PromptTokenLimit é semelhante à política SpikeArrest; no entanto, a política SpikeArrest limita o número de pedidos, enquanto a política PromptTokenLimit limita o número de tokens nesses pedidos. Esta política foi especificamente concebida para aplicações de MDIs em que o custo e o desempenho estão diretamente relacionados com o número de tokens processados.

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.

A diferença entre PromptTokenLimit e LLMTokenQuota

A política PromptTokenLimit é usada para a gestão do tráfego operacional para evitar picos súbitos na utilização de tokens. Por outro lado, a política LLMTokenQuota é usada para aplicar limites de consumo em apps de cliente durante períodos mais longos (como horas, dias ou meses) para gerir custos e aplicar acordos comerciais.

PromptTokenLimit elemento

Define a política PromptTokenLimit.

Valor predefinido	Consulte o separador Política predefinida abaixo
Obrigatório?	Opcional
Tipo	Objeto Complex
Elemento principal	N/A
Elementos subordinados	<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 predefinida

O exemplo seguinte mostra as predefinições quando adiciona uma política PromptTokenLimit ao seu fluxo na IU:

<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	Predefinição	Obrigatório?	Descrição
name	N/A	Obrigatório	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.
continueOnError	falso	Opcional	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: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
enabled	verdadeiro	Opcional	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 anexada a um fluxo.
async	falso	Descontinuado	Este atributo foi descontinuado.

Exemplos

Os exemplos seguintes mostram algumas das formas como pode usar a política PromptTokenLimit:

Exemplo 1

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

Neste exemplo, a limitação de tokens de comandos ocorre numa única réplica e não é distribuída por vários processadores de mensagens numa 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 comandos é distribuída por várias réplicas numa região, e é usado um algoritmo de limitação de taxa de "janela deslizante".

<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 tokens de tamanho da capacidade de resposta por pedido.

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

<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 tokens distribuídos com valores predefinidos.

Neste exemplo, a limitação de tokens de comandos ocorre numa única réplica e não é distribuída por vários processadores de mensagens numa região. É usado o valor predefinido da origem do comando do utilizador: {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 de elemento secundário

Esta secção descreve os elementos subordinados de <PromptTokenLimit>.

<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 e mais natural.

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

Valor predefinido	N/A
Obrigatório?	Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos subordinados	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 nem elementos subordinados.

<Identifier>

Permite-lhe escolher como agrupar os pedidos para que a política PromptTokenLimit possa ser aplicada com base no cliente. Por exemplo, pode agrupar pedidos por ID do programador, caso em que os pedidos de cada programador contam para a respetiva taxa PromptTokenLimit e não para todos os pedidos ao proxy.

Se deixar o elemento <Identifier> vazio, é aplicado um limite de taxa a todos os pedidos para esse proxy de API.

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

Sintaxe

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

Exemplo 1

O exemplo seguinte aplica a política PromptTokenLimit por ID de programador:

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

A tabela seguinte descreve os atributos de <Identifier>:

Atributo	Descrição	Predefinição	Presença
ref	Identifica a variável pela qual PromptTokenLimit agrupa os pedidos recebidos. Pode usar qualquer variável de fluxo para indicar um cliente único, como as disponíveis com a política VerifyAPIKey. Também pode definir variáveis personalizadas através da política de JavaScript ou da política AssignMessage.	N/A	Obrigatória

<Rate>

Especifica a taxa à qual limitar os picos (ou as rajadas) de tokens definindo o número de tokens permitidos em intervalos de minutos ou segundos. Pode usar este elemento em conjunto com <Identifier> para limitar o tráfego sem problemas no tempo de execução aceitando valores do cliente. Use o elemento <UseEffectiveCount> para definir o algoritmo de limitação de taxa usado pela política.

Nota: a utilização de <UseEffectiveCount> com um valor ou false não é suportada para nenhuma organização do Apigee nem para organizações híbridas do Apigee que executam cargas de trabalho de produção. Para mais informações, consulte <UseEffectiveCount>.

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

Sintaxe

Pode especificar tarifas de uma das seguintes formas:

• Uma taxa estática que especifica como o corpo do elemento <Rate>
• Um valor variável, que pode ser transmitido pelo cliente; identifique o nome da variável de fluxo através do 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 de variável ou no corpo do elemento) têm de estar em conformidade com o seguinte formato:

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

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

Exemplo 1

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

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

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

Exemplo 2

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

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

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

A tabela seguinte descreve os atributos de <Rate>:

Atributo	Descrição	Presença	Predefinição
ref	Identifica uma variável de fluxo que especifica a taxa. Pode ser qualquer variável de fluxo, como um parâmetro de consulta HTTP, um cabeçalho ou o conteúdo do corpo de uma mensagem, ou um valor, como um KVM. Para mais informações, consulte o artigo Referência de variáveis de fluxo. Também pode usar variáveis personalizadas através da política de JavaScript ou da política AssignMessage. Se definir ref e o corpo deste elemento, o valor de ref é aplicado e tem prioridade quando a variável de fluxo é definida no pedido. (O inverso é verdadeiro quando a variável identificada em ref não está definida no pedido.) Por 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 da API é de 1 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é ser enviado um pedido sem o cabeçalho custom_rate. Pode usar <Identifier> para agrupar pedidos de forma a aplicar tarifas personalizadas a diferentes tipos de clientes. Se 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 gera um erro.	Opcional	N/A

A tabela seguinte descreve os atributos de Rate que definem o comportamento de limitação do tráfego:

Atributo	Descrição
messagesPerPeriod	Especifica o número de tokens permitidos num período definido. Por exemplo, se uma política estiver configurada para "10ps" (10 tokens por segundo), o valor de messagesPerPeriod seria 10.
periodInMicroseconds	Define o período, em microssegundos, durante o qual o elemento messagesPerPeriod é calculado. Para uma configuração de "10 ps", este 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 num curto período no início de um novo intervalo.

Nota: os valores e os cálculos destes atributos podem ser afetados pelo número de MPs e se a definição UseEffectiveCount está ativada. Por exemplo, se definir uma taxa de "10ps" com 10 MPs e UseEffectiveCount estiver ativado, a taxa efetiva para cada MP é de 1ps. Os atributos internos do PM individual são ajustados para refletir esta situação. Por exemplo, o atributo messagesPerPeriod pode ser definido como 1 e o atributo periodInMicroseconds como 1 000 000.

<UseEffectiveCount>

Este elemento permite-lhe escolher entre algoritmos PromptTokenLimit distintos ao definir o valor como true ou false, conforme explicado abaixo:

verdadeiro

Se estiver definido como true, o PromptTokenLimit é distribuído numa região. Isto significa que as contagens de pedidos são sincronizadas entre os processadores de mensagens (MPs) numa região. Além disso, é usado um algoritmo de limitação de taxa de "janela deslizante". Este algoritmo fornece um comportamento de limite de taxa consistente e não "suaviza" o número de pedidos recebidos que podem ser enviados para o back-end. Se for enviado um pico de pedidos num curto intervalo de tempo, estes são permitidos, 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 (predefinição)

Nota: embora o valor predefinido seja false, as organizações do Apigee devem definir este elemento como true.

A suavização de tarifas não é suportada para organizações do Apigee.

Se estiver definida como false (predefinição), a política PromptTokenLimit usa um algoritmo de "token bucket" que suaviza os picos de tokens dividindo o limite de taxa que especificar em intervalos mais pequenos. Uma desvantagem desta abordagem é que vários tokens legítimos recebidos num curto intervalo de tempo podem ser potencialmente recusados.

Por exemplo, suponhamos que introduz uma taxa de 30 pm (30 tokens por minuto). Nos testes, pode pensar que pode enviar 30 tokens num segundo, desde que sejam enviados no prazo de um minuto. No entanto, não é assim que a política aplica a definição. Se pensar bem, 30 tokens num período de 1 segundo podem ser considerados um mini aumento repentino em alguns ambientes.

• As taxas por minuto são suavizadas em pedidos completos permitidos em intervalos de segundos.

  Por exemplo, 30 pm é suavizado da seguinte forma:
  60 segundos (1 minuto) / 30 pm = intervalos de 2 segundos ou 1 token permitido a cada 2 segundos. Um segundo token dentro de 2 segundos falha. Além disso, um 31.º token num minuto falha.

• As taxas por segundo são suavizadas em pedidos completos permitidos em intervalos de milissegundos.

  Por exemplo, 10ps é suavizado da seguinte forma:
  1000 milissegundos (1 segundo) / 10ps = intervalos de 100 milissegundos ou 1 token permitido a cada 100 milissegundos. Um segundo token dentro de 100 ms vai falhar. Além disso, um 11.º token num segundo vai falhar.

Nota: na suavização da taxa, o número de tokens é sempre um número inteiro superior a zero. A suavização nunca envolve o cálculo de frações de tokens.

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

A tabela seguinte descreve os atributos do elemento <UseEffectiveCount>:

Atributo	Descrição	Predefiniçã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, um cabeçalho ou o conteúdo do corpo de uma mensagem. Para mais informações, consulte a referência de variáveis de fluxo. Também pode definir variáveis personalizadas através da política de JavaScript ou da política AssignMessage.	N/A	Opcional

<UserPromptSource>

Fornece a origem para obter o texto do comando do utilizador. Use um modelo de mensagem.

O modelo de mensagem deve fornecer um único valor do texto do comando do utilizador.

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

Valor predefinido	N/A
Obrigatório?	Opcional
Tipo	String
Elemento principal	<PromptTokenLimit>
Elementos subordinados	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 é encontrada uma variável não resolvida.

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

Valor predefinido	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento principal	<PromptTokenLimit>
Elementos subordinados	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	Autorização	Descrição
ratelimit.POLICY_NAME.failed	Booleano	Só de leitura	Indica se a política falhou ou não (true ou false).
ratelimit.POLICY_NAME.resolvedUserPrompt	String	Só de leitura	Devolve o comando do utilizador extraído.
ratelimit.POLICY_NAME.userPromptSource	String	Só de leitura	Devolve o modelo de mensagem para o comando do utilizador especificado na política.
ratelimit.POLICY_NAME.userPromptTokenCount	String	Só de leitura	Devolve a contagem de tokens do comando do utilizador extraído.

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

Referência de erro

Esta secção descreve os códigos de falhas e as mensagens de erro devolvidas e as variáveis de falhas definidas pelo Apigee quando esta política aciona um erro. Também pode ver Erros da política SpikeArrest. É importante conhecer estas informações se estiver a desenvolver regras de falhas para processar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Processar falhas.

Erros de tempo de execução

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

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Código de falha	Estado de HTTP	Falha do Apigee	Causa	Corrigir
policies.prompttokenlimit.FailedToExtractUserPrompt	400	FALSE	Não é possível extrair o comando do utilizador do pedido da API.
policies.prompttokenlimit.PromptTokenLimitViolation	429	FALSE	Violação de PromptTokenLimit.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens	500	TRUE	Não é possível calcular os tokens para o comando do utilizador.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

Código de falha	Estado de HTTP	Falha do Apigee	Causa	Corrigir
policies.prompttokenlimit.MessageWeightNotSupported	500	FALSE	MessageWeight não é compatível com a política PromptTokenLimit.

Variáveis de falha

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

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

Exemplo de resposta de erro

Segue-se um exemplo de uma resposta de erro:

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque 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

Segue-se um exemplo de uma regra de falha para processar 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 estado HTTP atual para exceder um limite de taxa definido por uma política LLMTokenQuota ou PromptTokenLimit é 429 (Demasiados pedidos).

Esquemas

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

Tópicos relacionados

• LLMTokenQuota policy: política LLMTokenQuota para limitar a utilização da quota de tokens de resposta.
• Limitação de velocidade para uma vista geral da limitação de velocidade
• Comparar políticas de limitação de taxa