Política PromptTokenLimit

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

Consulta la documentación de Apigee Edge.

Información general

La política PromptTokenLimit protege los back-ends de los modelos de lenguaje extensos (LLMs) frente a los picos de tráfico limitando el número de tokens de las peticiones de los usuarios.

La política PromptTokenLimit es similar a la política SpikeArrest. Sin embargo, la política SpikeArrest limita el número de solicitudes, mientras que la política PromptTokenLimit limita el número de tokens de esas solicitudes. Esta política se ha diseñado específicamente para aplicaciones de LLM en las que el coste y el rendimiento están directamente relacionados con el número de tokens procesados.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Diferencia entre PromptTokenLimit y LLMTokenQuota

La política PromptTokenLimit se usa para gestionar el tráfico operativo y evitar picos repentinos en el uso de tokens. Por el contrario, la política LLMTokenQuota se usa para aplicar límites de consumo en aplicaciones cliente durante periodos más largos (como horas, días o meses) para gestionar los costes y aplicar los acuerdos empresariales.

Elemento PromptTokenLimit

Define la política PromptTokenLimit.

Valor predeterminado Consulta la pestaña Política predeterminada que aparece más abajo.
¿Es obligatorio? Opcional
Tipo Objeto Complex
Elemento principal N/A
Elementos secundarios <Identifier>
<Rate> (obligatorio)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

Sintaxis

El elemento PromptTokenLimit utiliza 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 muestran los ajustes predeterminados al añadir una política PromptTokenLimit a tu flujo en la interfaz de usuario:

<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 Predeterminado ¿Es 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.

Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError falso Opcional Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también:
enabled true Opcional Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async   falso Obsoleto Este atributo está obsoleto.

Ejemplos

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

Ejemplo 1

Limitación de tokens de peticiones en una sola réplica.

En este ejemplo, el límite de tokens de petición se produce en una sola réplica y no se distribuye entre varios procesadores de mensajes de 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

Limitación de tokens distribuidos.

En este ejemplo, la limitación de tokens de peticiones se distribuye entre varias réplicas de una región y se emplea un algoritmo de limitación 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

Limitación de tokens por solicitud en el tamaño de la ventana de contexto.

En este ejemplo, la limitación de tokens de peticiones se produce en una sola réplica y no se distribuye entre varios procesadores de mensajes de una región. Esta configuración específica se usa para el tamaño de la ventana de contexto limitando los tokens por solicitud.

<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

Limitación de tokens distribuidos con valores predeterminados.

En este ejemplo, la limitación de tokens de peticiones se produce en una sola réplica y no se distribuye entre varios procesadores de mensajes de una región. Se usa el valor predeterminado de la fuente de la petició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 de elemento secundario

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

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

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

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

El elemento <DisplayName> utiliza 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 la política PromptTokenLimit se pueda aplicar en función del cliente. Por ejemplo, puedes agrupar las solicitudes por ID de desarrollador. En ese caso, las solicitudes de cada desarrollador se contabilizarán en su propia tarifa PromptTokenLimit y no en todas las solicitudes al proxy.

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Cadena
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 las que están disponibles con la política VerifyAPIKey. También puedes definir variables personalizadas con la política JavaScript o la política AssignMessage. N/A Obligatorio

<Rate>

Especifica la frecuencia con la que se limitan los picos (o ráfagas) de tokens. Para ello, se define el número de tokens que se permiten en intervalos por minuto o por segundo. Puedes usar este elemento junto con <Identifier> para limitar el tráfico de forma fluida en el tiempo de ejecución aceptando valores del cliente. Usa el elemento <UseEffectiveCount> para definir el algoritmo de limitación 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 las tarifas de una de las siguientes formas:

  • Un precio estático que especifiques como cuerpo del elemento <Rate>
  • Valor de una variable, que puede transferir el cliente. Identifica el nombre de la variable de flujo mediante 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 frecuencia válidos (definidos como valor de variable o en el cuerpo del elemento) deben ajustarse al siguiente formato:

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

El valor de int debe ser un número entero positivo distinto de 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 frecuencia a un token permitido cada 200 milisegundos (1000/5).

Ejemplo 2

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

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

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

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

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

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

Si defines tanto ref como el cuerpo de este elemento, se aplicará el valor de ref y tendrá prioridad cuando se defina la variable de flujo en la solicitud. (Ocurre lo contrario cuando la variable identificada en ref no se define en la solicitud).

Por ejemplo:

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

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

Puede usar <Identifier> para agrupar solicitudes y aplicar tarifas personalizadas a diferentes tipos de clientes.

Si especifica un valor para ref, pero no define la tarifa en el cuerpo del elemento <Rate> y el cliente no transfiere ningún valor, la política PromptTokenLimit genera un error.

 Opcional N/A
En la siguiente tabla se describen los atributos de Rate que definen el comportamiento de limitación del tráfico:
Atributo Descripción
messagesPerPeriod Especifica el número de tokens permitidos en un periodo definido. Por ejemplo, si una política se configura con el valor "10ps" (10 tokens por segundo), el valor de messagesPerPeriod sería 10.
periodInMicroseconds Define el periodo, en microsegundos, durante el cual se calcula messagesPerPeriod. En una configuración de 10 ps, este valor sería 1.000.000, lo que equivale a un segundo.
maxBurstMessageCount Representa el número máximo de tokens que se pueden permitir al instante o en un breve periodo al principio de un nuevo intervalo.

<UseEffectiveCount>

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

true

Si se define como true, PromptTokenLimit se distribuye en una región. Esto significa que los recuentos de solicitudes se sincronizan entre los procesadores de mensajes (MPs) de una región. Además, se emplea un algoritmo de limitación de frecuencia de "ventana deslizante". Este algoritmo proporciona un comportamiento de limitación de frecuencia coherente y no "suaviza" el número de solicitudes entrantes que se pueden enviar al backend. Si se envía una ráfaga de solicitudes en un intervalo de tiempo breve, se permiten siempre que no superen el límite de frecuencia configurado, tal como se define en el elemento <Rate>. Por ejemplo:

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

false (valor predeterminado)

Si se define como false (el valor predeterminado), la política PromptTokenLimit utiliza un algoritmo de "cubo de tokens" que suaviza los picos de tokens dividiendo el límite de frecuencia que especifiques en intervalos más pequeños. Un inconveniente de este enfoque es que se pueden denegar varios tokens legítimos que lleguen en un intervalo de tiempo breve.

Por ejemplo, supongamos que introduces una tarifa de 30 pm (30 tokens por minuto). En las pruebas, puede que pienses que puedes enviar 30 tokens en 1 segundo, siempre que se envíen en un minuto. Sin embargo, no es así como la política aplica el ajuste. Si lo piensas, 30 tokens en un periodo de 1 segundo podrían considerarse un minipico en algunos entornos.

  • Las tarifas por minuto se suavizan en solicitudes completas permitidas en intervalos de segundos.

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

  • Las frecuencias por segundo se suavizan en solicitudes completas permitidas en intervalos de milisegundos.

    Por ejemplo, 10ps se suaviza de la siguiente manera:
    1000 milisegundos (1 segundo) / 10ps = intervalos de 100 milisegundos, o 1 token permitido cada 100 milisegundos. Si se envía un segundo token en un plazo de 100 ms, se producirá un error. Además, si se envía un undécimo token en un segundo, se producirá un error.

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 consulta HTTP, un encabezado o el contenido del cuerpo de un mensaje. Para obtener más información, consulta la referencia de variables de flujo. También puede definir variables personalizadas con la política JavaScript o la política AssignMessage. N/A Opcional

<UserPromptSource>

Proporciona la fuente para obtener el texto de la petición del usuario. Usa una plantilla de mensaje.

La plantilla de mensaje debe proporcionar un único valor del texto de la petición del usuario.

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

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Cadena
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.

Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento. De lo contrario, asigna el valor 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 PromptTokenLimit, se rellenan las siguientes variables de flujo:

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

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

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que se definen cuando esta política activa un error. También puede ver errores de la política SpikeArrest. Es importante conocer esta información si vas a desarrollar reglas de errores para gestionar los errores. Para obtener más información, consulta los artículos Qué debes saber sobre los errores de las políticas y Gestionar fallos.

Errores de tiempo de ejecución

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

Código de fallo Estado de HTTP Error de Apigee Causa Solucionar
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSO No se ha podido extraer la petición del usuario de la solicitud de la API.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSO PromptTokenLimit violation.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE No se pueden calcular los tokens de la petición del usuario.

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

Código de fallo Estado de HTTP Error de Apigee Causa Solucionar
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSO MessageWeight no se admite en la política PromptTokenLimit.

Variables de error

Estas variables se definen cuando se produce un error de tiempo de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de las políticas.

Variables Dónde Ejemplo
ratelimit.policy_name.fault.name fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name es el nombre de la política especificado por el usuario que ha provocado el error. 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}"
   }
}

Regla de fallo de ejemplo

A continuación se muestra un ejemplo de regla de error para gestionar un error 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 LLMTokenQuota o PromptTokenLimit es 429 (Demasiadas solicitudes).

Esquemas

Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Temas relacionados