Política de PromptTokenLimit

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Descripción general

La política PromptTokenLimit protege los backends de modelos de lenguaje grandes (LLM) de los aumentos repentinos de tráfico limitando la cantidad de tokens en las instrucciones del usuario.

La política PromptTokenLimit es similar a la política SpikeArrest. Sin embargo, la política SpikeArrest limita la cantidad de solicitudes, mientras que la política PromptTokenLimit limita la cantidad de tokens dentro de esas solicitudes. Esta política está diseñada específicamente para las aplicaciones de LLM en las que el costo y el rendimiento se relacionan directamente con la cantidad de tokens procesados.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Diferencia entre PromptTokenLimit y LLMTokenQuota

La política PromptTokenLimit se usa para la administración operativa del tráfico y evitar incrementos repentinos en el uso de tokens. En cambio, la política de LLMTokenQuota se usa para aplicar límites de consumo en las apps cliente durante períodos más largos (como horas, días o meses) para administrar los costos y aplicar los acuerdos comerciales.

Elemento PromptTokenLimit

Define la política PromptTokenLimit.

Valor predeterminado Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio? Opcional
Tipo Objeto complejo
Elemento principal N/A
Elementos secundarios <Identifier>
<Rate> (obligatorio)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

Sintaxis

El elemento PromptTokenLimit usa la siguiente sintaxis:

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

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política de PromptTokenLimit a tu flujo en la 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 tiene los siguientes atributos que son comunes a todas las políticas:

Atributo Predeterminada (obligatorio) Descripción
name N/A Obligatorio

El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError falso Opcional Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta:
enabled true Opcional Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async   falso Obsoleta Este atributo dejó de estar disponible.

Ejemplos

En los siguientes ejemplos, se muestran algunas de las formas en las que puedes usar la política de PromptTokenLimit:

Ejemplo 1

Limitación de tokens de instrucciones dentro de una sola réplica.

En este ejemplo, el límite de tokens de la instrucción ocurre dentro de una sola réplica y no se distribuye entre varios procesadores de mensajes en una región. 

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

Ejemplo 2

Se limitó la distribución de tokens.

En este ejemplo, el límite de tokens de la instrucción se distribuye en varias réplicas de una región, y se emplea un algoritmo de límite de frecuencia de “ventana 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>

Ejemplo 3

Se limita la cantidad de tokens de tamaño de la ventana de contexto por solicitud.

En este ejemplo, la limitación de tokens de instrucciones ocurre dentro de una sola réplica y no se distribuye entre varios procesadores de mensajes en una región. Esta configuración específica se usa para limitar la cantidad de tokens por solicitud en función del tamaño de la ventana de contexto.

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

Ejemplo 4

Es la limitación de tokens distribuidos con valores predeterminados.

En este ejemplo, la limitación de tokens de instrucciones ocurre dentro de una sola réplica y no se distribuye entre varios procesadores de mensajes en una región. Se usa el valor predeterminado de la fuente de la instrucción del usuario: {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>

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <PromptTokenLimit>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado N/A
¿Es obligatorio? Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo String
Elemento principal <PolicyElement>
Elementos secundarios Ninguno

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Identifier>

Te permite elegir cómo agrupar las solicitudes para que se pueda aplicar la política de PromptTokenLimit según el cliente. Por ejemplo, puedes agrupar solicitudes por ID de desarrollador, en cuyo caso las solicitudes de cada desarrollador se contarán en su propia frecuencia de PromptTokenLimit y no todas las solicitudes al proxy.

Si dejas el elemento <Identifier> vacío, se aplica un límite de frecuencia para todas las solicitudes a ese proxy de API.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo String
Elemento principal <PromptTokenLimit>
Elementos secundarios Ninguno

Sintaxis

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

Ejemplo 1

En el siguiente ejemplo, se aplica la política PromptTokenLimit por ID de desarrollador:

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

En la siguiente tabla, se describen los atributos de <Identifier>:

Atributo Descripción Predeterminado Presencia
ref Identifica la variable por la que PromptTokenLimit agrupa las solicitudes entrantes. Puedes usar cualquier variable de flujo para indicar un cliente único, como los disponibles con la política VerifyAPIKey. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage. N/A Obligatorio

<Rate>

Especifica la frecuencia a la que se deben limitar los aumentos repentinos de tokens (o aumentos de actividad) configurando la cantidad de tokens permitidos en intervalos por minuto o por segundo. Puedes usar este elemento junto con <Identifier> para limitar el tráfico en el entorno de ejecución con facilidad. Para ello, debes aceptar valores del cliente. Usa el elemento <UseEffectiveCount> para establecer el algoritmo de límite de frecuencia que usa la política.

Valor predeterminado N/A
¿Es obligatorio? Obligatorio
Tipo Entero
Elemento principal <PromptTokenLimit>
Elementos secundarios Ninguno

Sintaxis

Puedes especificar tasas de una de las siguientes maneras:

  • Una tasa estática que especificas como cuerpo del elemento <Rate>
  • Un valor variable, que el cliente puede pasar. Identificar el nombre de la variable de flujo con el atributo ref.
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

Los valores de las tarifas válidas (definidas como valores de variables o en el cuerpo del elemento) deben cumplir con el siguiente formato:

  • intps (cantidad de tokens por segundo, se suman en intervalos de milisegundos)
  • intpm (cantidad de tokens por minuto, se suman en intervalos de segundos)

El valor de int debe ser un número entero positivo que no sea cero.

Ejemplo 1

En el siguiente ejemplo, se establece la frecuencia en cinco tokens por segundo:

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

La política suaviza la tasa a un token permitido cada 200 milisegundos (1,000/5).

Ejemplo 2

En el siguiente ejemplo, se establece la frecuencia en 12 tokens por minuto:

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

Esta política de ejemplo mitiga la frecuencia a un token permitido cada cinco segundos (60/12).

En la siguiente tabla, se describen los atributos de <Rate>:

Atributo Description Presencia Predeterminado
ref Identifica una variable de flujo que especifica la frecuencia. Puede ser cualquier variable de flujo, como un parámetro de búsqueda HTTP, un encabezado o contenido del cuerpo del mensaje, o un valor, como una KVM. Para obtener más información, consulta Referencia de variables de flujo.

También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage.

Si defines ref y el cuerpo de este elemento, se aplicará el valor de ref y tendrá prioridad cuando la variable de flujo se establezca en la solicitud. (La inversa es verdadera cuando la variable identificada en ref no se establece en la solicitud).

Por ejemplo:

<Rate ref="request.header.custom_rate">1pm</Rate>

En este ejemplo, si el cliente no transmite un encabezado custom_rate, la frecuencia del proxy de API es de 1 token por minuto para todos los clientes. Si el cliente pasa un encabezado custom_rate, cuyo valor es 10 ps, para todos los clientes del proxy, hasta que se envía una solicitud sin el encabezado custom_rate.

Puedes usar <Identifier> para agrupar solicitudes a fin de aplicar frecuecias personalizadas para diferentes tipos de clientes.

Si especificas un valor para ref, pero no estableces la velocidad en el cuerpo del elemento <Rate> y el cliente no pasa un valor, la política de PromptTokenLimit muestra un error.

 Opcional N/A
En la siguiente tabla, se describen los atributos de Rate que definen el comportamiento de la limitación del tráfico:
Atributo Descripción
messagesPerPeriod Especifica la cantidad de tokens permitidos dentro de un período definido. Por ejemplo, si una política se configura para "10 ps" (10 tokens por segundo), el valor de messagesPerPeriod sería 10.
periodInMicroseconds Define el período, en microsegundos, durante el cual se calcula el messagesPerPeriod. Para una configuración de "10 ps", este valor sería 1,000,000, lo que equivale a un segundo.
maxBurstMessageCount Representa la cantidad máxima de tokens que se pueden permitir de forma instantánea o en una ráfaga corta al comienzo de un intervalo nuevo.

<UseEffectiveCount>

Este elemento te permite elegir entre algoritmos de PromptTokenLimit distintos. Para ello, establece el valor en true o false, como se explica a continuación:

verdadero

Si se configura como true, PromptTokenLimit se distribuye en una región. Eso significa que los recuentos de solicitudes se sincronizan entre los procesadores de mensajes (MP) de una región. Además, se emplea un algoritmo de límite de frecuencia de “ventana deslizante”. Este algoritmo proporciona un comportamiento de límite de frecuencia coherente y no “suaviza” la cantidad de solicitudes entrantes que se pueden enviar al backend. Si se envía un pico de actividad de solicitudes en un intervalo de tiempo corto, se permitirán siempre que no excedan el límite de frecuencia configurado, como se establece en el elemento <Rate>. Por ejemplo:

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

false (predeterminado)

Si se configura como false (la opción predeterminada), la política PromptTokenLimit usa un algoritmo de "bucket de tokens" que disminuye los aumentos de tokens dividiendo el límite de frecuencia que especifiques en intervalos más pequeños. Una desventaja de este enfoque es que posiblemente se rechacen varios tokens legítimos que ingresen en un intervalo de tiempo corto.

Por ejemplo, supongamos que ingresas una frecuencia de 30 pm (30 tokens por minuto). En las pruebas, podrías pensar que podrías enviar 30 tokens en 1 segundo, siempre que estén dentro de un minuto. Pero esa no es la forma en que la política aplica la configuración. Si lo piensas, 30 tokens en un período de 1 segundo se podrían considerar un pequeño aumento en algunos entornos.

  • Las tarifas por minuto se suman a las solicitudes completas permitidas en intervalos de segundos.

    Por ejemplo, 30 pm se mitigan de la siguiente manera:
    60 segundos (1 minuto) / 30 pm = intervalos de 2 segundos o 1 token permitido cada 2 segundos. Si se envía un segundo token en un plazo de 2 segundos, se producirá un error. Además, fallará el token número 31 en un minuto.

  • Las tarifas por segundo se suman a las solicitudes completas permitidas en intervalos de milisegundos.

    Por ejemplo, 10 ps se suavizan de la siguiente manera:
    1, 000 milisegundos (1 segundo) / 10 ps = intervalos de 100 milisegundos o 1 token permitido cada 100 milisegundos. Una segunda solicitud dentro de los 100 ms fallará. Además, fallará el token número 11 en un segundo.

Valor predeterminado Falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <PromptTokenLimit>
Elementos secundarios Ninguno

En la siguiente tabla, se describen los atributos del elemento <UseEffectiveCount>:

Atributo Descripción Predeterminado Presencia
ref Identifica la variable que contiene el valor de <UseEffectiveCount>. Puede ser cualquier variable de flujo, como un parámetro de búsqueda HTTP, un encabezado o contenido del cuerpo del mensaje. Para obtener más información, consulta Referencia de variables de flujo. También puedes usar variables personalizadas mediante la política de JavaScript o la Política de AssignMessage. N/A Opcional

<UserPromptSource>

Proporciona la fuente para recuperar el texto de la instrucción del usuario. Usar una plantilla de mensaje

La plantilla de mensaje debe proporcionar un solo valor del texto de la instrucción del usuario.

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo String
Elemento principal <PromptTokenLimit>
Elementos secundarios Ninguno

Sintaxis

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

Ejemplo 1

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

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver.

Configúralo como true para ignorar las variables sin resolver y continuar con el procesamiento, de lo contrario, false. El valor predeterminado es false.

Valor predeterminado Falso
¿Es obligatorio? Opcional
Tipo Booleano
Elemento principal <PromptTokenLimit>
Elementos secundarios Ninguno

Sintaxis

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

Ejemplo

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

Variables de flujo

Cuando se ejecuta una política de PromptTokenLimit, se propagan las siguientes variables de flujo:

Variable Tipo Permiso Descripción
ratelimit.POLICY_NAME.failed Booleano Solo lectura Indica si la política falló o no (true o false).
ratelimit.POLICY_NAME.resolvedUserPrompt String Solo lectura Devuelve la instrucción del usuario extraída.
ratelimit.POLICY_NAME.userPromptSource String Solo lectura Devuelve la plantilla de mensaje para la instrucción del usuario especificada en la política.
ratelimit.POLICY_NAME.userPromptTokenCount String Solo lectura Devuelve el recuento de tokens del mensaje del usuario extraído.

Para obtener más información, consulta Referencia de variables de flujo.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, así como las variables de falla que establece Apigee cuando esta política activa un error. También es posible que veas errores de la política de SpikeArrest. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla Estado de HTTP Falla de Apigee Causa Corregir
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSO No se pudo extraer la instrucción del usuario de la solicitud de la API.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSO Es un incumplimiento de PromptTokenLimit.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE No se pueden calcular los tokens para la instrucción del usuario.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Código de falla Estado de HTTP Falla de Apigee Causa Corregir
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSO MessageWeight no se admite para la política PromptTokenLimit.

Variables con fallas

Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables Donde Ejemplo
ratelimit.policy_name.fault.name fault_name es el nombre de la falla, como se indica en la tabla Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

Ejemplo de respuesta de error

A continuación, se muestra un ejemplo de respuesta de error:

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

Ejemplo de regla de falla

A continuación, se muestra un ejemplo de regla de falla para manejar una falla de 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>

El código de estado HTTP actual para superar un límite de frecuencia establecido por una política de LLMTokenQuota o PromptTokenLimit es 429 (Demasiadas solicitudes).

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Temas relacionados