Política LLMTokenQuota

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 LLMTokenQuota está diseñada para administrar y controlar el consumo de tokens para las cargas de trabajo de IA/LLM. Dado que las interacciones con los modelos de lenguaje grandes (LLM) se basan en tokens, la administración eficaz es fundamental para el control de costos, la optimización del rendimiento y la estabilidad de la plataforma.

Una cuota es una asignación de tokens de LLM (entrada o salida) que un proxy de API puede consumir durante un período, como un minuto, una hora, un día, una semana o un mes. La política de LLMTokenQuota mantiene contadores que registran la cantidad de tokens consumidos por el proxy de API. Esta capacidad permite que los proveedores de API apliquen límites al consumo de tokens por parte de las apps en un intervalo de tiempo.

Esta política usa los elementos <LLMTokenUsageSource> y <LLMModelSource> para extraer el recuento de tokens de la respuesta del LLM y el nombre del modelo de la solicitud o la respuesta, lo que permite una aplicación precisa de la cuota en tiempo real.

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.

Cómo funciona la aplicación de la cuota de LLMToken

A continuación, se describe la funcionalidad de la política LLMTokenQuota:

  • Recuento de tokens (<CountOnly>): La política de LLMTokenQuota mantiene contadores que registran la cantidad de tokens consumidos por las respuestas de LLM que pasan por el proxy de API.
  • Aplicación de límites (<EnforceOnly>): Esta capacidad permite que los proveedores de API establezcan límites estrictos en la cantidad de tokens que consumen las aplicaciones durante un intervalo definido. Por ejemplo, puedes limitar las aplicaciones a 1,000 tokens por minuto o 10,000,000 tokens por mes.
  • Exceso de cuota: Cuando un proxy de API alcanza el límite de cuota de tokens definido, Apigee rechaza las solicitudes posteriores que consumen tokens. Se devuelve un mensaje de error hasta que el contador LLMTokenQuota se restablece automáticamente al final del intervalo de tiempo especificado. Por ejemplo, si se establece una cuota de 10,000 tokens por mes, el límite de tokens comienza una vez que se cuenta el token número 10,000, independientemente del momento del mes en que se alcance ese límite.

Cómo funciona LLMTokenQuota con los productos de API

A continuación, se describe cómo funciona la política de LLMTokenQuota con los productos de API:

Flujo de proxy para LLMTokenQuota
  1. Aplica la política VerifyAPIKey o VerifyAccessToken junto con la política de aplicación LLMTokenQuota en la solicitud del proxy de API (no importa si es Proxy o Target).
  2. Aplica la política de recuento de LLMTokenQuota en respuesta al proxy de API (no importa si es un proxy o un destino).
  3. La política VerifyAPIKey o VerifyAccessToken hace coincidir la clave o el token con el producto de API, el conjunto de operaciones, el desarrollador y la app. Expone las variables de flujo para la cuota de LLM para todos los modelos de los conjuntos de operaciones de LLM coincidentes.
  4. Dentro de la política de aplicación de la cuota, extraemos el modelo según la plantilla de mensaje proporcionada.
  5. Luego, se correlacionan las variables de cuota del LLM para el modelo. Si se encuentra la coincidencia, se insertan las referencias.
  6. Una vez que se insertan las referencias, esos valores se usan para llevar a cabo las operaciones de cuota.

Cómo funciona LLMTokenQuota con las respuestas de SSE

Para que LLMTokenQuota funcione con las respuestas de SSE, agrega la política como parte del flujo de eventos, como se muestra a continuación:

<EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>LLM_TOKEN_QUOTA_COUNT_POLICY_NAME</Name>
      </Step>
    </Response>
  </EventFlow>

Mientras se procesa el flujo de eventos, el recuento de tokens solo se ejecuta cuando se encuentran en el evento los metadatos de uso de tokens de la respuesta del LLM. Cuando se descubren los metadatos de uso del token, se extraen y se ejecuta la política. Para todos los demás eventos, la política genera un NO-OP.

Tipos de políticas de LLMTokenQuota

La política de LLMTokenQuota admite varias formas diferentes en las que el contador de cuotas se inicia y se restablece. Puedes definir cuál usar con el atributo type en el elemento <LLMTokenQuota>, como se muestra en el siguiente ejemplo:

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

Los valores válidos de type incluyen lo siguiente:

  • calendar: Configura una cuota según una hora de inicio explícita. El contador de LLMTokenQuota para cada app se actualiza según los valores <StartTime>, <Interval> y <TimeUnit> que establezcas.
  • rollingwindow: Configura una cuota que use una ventana móvil para determinar el uso de la cuota. Con rollingwindow, determina el tamaño de la ventana con los elementos <Interval> y <TimeUnit>. Por ejemplo, 1 día. Cuando llega una solicitud, Apigee analiza la hora exacta de la solicitud (por ejemplo, 5:01 p.m.), cuenta la cantidad de tokens consumidos entre entonces y las 5:01 p.m. del día anterior (1 día) y determina si se superó o no la cuota durante ese período.
  • flexi: Configura una cuota que genere que el contador comience cuando se reciba el primer mensaje de solicitud de una app y se restablezca según los valores <Interval> y <TimeUnit>.

En la siguiente tabla, se describe cuándo se restablece la cuota para cada tipo:

Unidad de tiempo Tipo
default (o nulo) calendar flexi
minuto Inicio del próximo minuto Un minuto después de <StartTime> Un minuto después de la primera solicitud
hora Parte superior de la próxima hora Una hora después de <StartTime> Una hora después de la primera solicitud
día Medianoche GMT del día actual 24 horas después del <StartTime> 24 horas después de la primera solicitud
semana El domingo a la medianoche GMT cuando termina la semana Una semana después de <StartTime> Una semana después de la primera solicitud
mes Medianoche GMT del último día del mes Un mes (28 días) después de <StartTime> Un mes (28 días) después de la primera solicitud

Para type="calendar", debes especificar el valor de <StartTime>.

La tabla no describe cuándo se restablece el recuento para el tipo rollingwindow. Esto se debe a que las cuotas de ventana móvil funcionan de manera un poco diferente, ya que se basan en una ventana de observación, como una de una hora o un día. Para el tipo rollingwindow, el contador nunca se restablece, pero se vuelve a calcular en cada solicitud. Cuando llega una solicitud nueva, la política determina si se superó la cuota en el período anterior.

Por ejemplo, puedes definir un período de dos horas que permita 1,000 tokens. Se envía una solicitud nueva a las 4:45 p.m. La política calcula la cantidad de cuotas para las últimas dos horas, lo que significa la cantidad de tokens consumidos desde las 2:45 p.m. Si el límite de cuota no se excede en esa ventana de dos horas, se permite la solicitud.

Un minuto después, a las 4:46 p.m., ingresa otra solicitud. Ahora la política calcula el recuento de cuotas desde las 2:46 p.m. para determinar si se superó el límite.

Obtén información sobre los contadores de cuota

Cuando una política de LLMTokenQuota se ejecuta en un flujo del proxy de API, se incrementa un contador de cuota. Cuando el contador alcanza su límite, no se permiten más llamadas a la API asociadas con ese contador. Según la configuración que uses para tu producto de API, la política de LLMTokenQuota puede emplear un solo contador o varios contadores independientes. Es importante comprender las situaciones en las que se usarán varios contadores y cómo se comportan.

Configura los parámetros de cuota para los productos de API

Un producto de API puede especificar la configuración de cuota a nivel del producto o a nivel de la operación individual, o ambos. Si tu proxy de API se incluye en un producto de API, puedes configurar la política de LLMTokenQuota para usar la configuración de cuota (recuento de permisos, unidad de tiempo y intervalo) que se define en ese producto. La forma más fácil de hacerlo es a través del elemento useQuotaConfigInAPIProduct. También puedes hacer referencia a estos parámetros de configuración en la política LLMTokenQuota a través de referencias de variables individuales.

Cómo se cuentan las cuotas

De forma predeterminada, Apigee mantiene un contador de cuota independiente para cada operación definida en un producto de API, y se observan las siguientes reglas:

  • Si una operación tiene una cuota definida para ella, la configuración de cuota de la operación tiene prioridad sobre la configuración de cuota definida a nivel del producto.
  • Si una operación no tiene una cuota definida para ella, se aplican los parámetros de configuración de cuota a nivel del producto.
  • Si el producto de API no incluye ningún parámetro de configuración de cuota, ni a nivel del producto ni de la operación, se aplican los parámetros de configuración de cuota para el recuento de permisos, la unidad de tiempo y el intervalo, tal como se especifica en la política de LLMTokenQuota.

En todos los casos, Apigee mantiene un contador de cuota independiente para cada operación definida en un producto de API. Cualquier llamada a la API que coincida con una operación aumentará su contador.

Configura contadores a nivel del proxy de API

Es posible configurar un producto de API para mantener un recuento de cuota en el alcance del proxy de API. En este caso, todas las operaciones que no tienen su propia cuota comparten la configuración de cuota especificada en el nivel de producto de la API. El efecto de esta configuración es crear un contador a nivel del proxy de API para este producto de API.

Para lograr esta configuración, debes usar la API de Apigee /apiproducts para crear o actualizar el producto y establecer el atributo quotaCounterScope como PROXY en la solicitud de creación o actualización. Con la configuración PROXY, las solicitudes que coincidan con cualquiera de las operaciones definidas para el producto de API que estén asociadas con el mismo proxy y no tengan su propia configuración de cuota compartirán un contador de cuota común para ese proxy.

En la Figura 1, la operación 1 y 2 se asocian con el Proxy1 y las operaciones 4 y 5 están asociadas con el Proxy3. Debido a que quotaCounterScope=PROXY se establece en el producto de API, cada una de estas operaciones usa la configuración de cuota a nivel de producto de la API. Las operaciones 1 y 2, asociadas con Proxy1, usan un contador compartido, y las operaciones 4 y 5, asociadas con Proxy3, usan un contador compartido independiente. La operación 3 tiene su propio parámetro de configuración de cuota y, por lo tanto, usa su propio contador, independientemente del valor del atributo quotaCounterScope.

Figura 1: Uso de la marca cuotaCounterScope

Cómo se cuentan las cuotas si no se usan productos de API

Si no hay un producto de API asociado con un proxy de API, una política de LLMTokenQuota mantiene un solo contador, sin importar cuántas veces hagas referencia a él en un proxy de API. El nombre del contador de cuotas se basa en el atributo name de la política.

Por ejemplo, creas una política de LLMTokenQuota llamada MyLLMTokenQuotaPolicy con un límite de 5 tokens y la colocas en varios flujos (flujo A, B y C) en el proxy de API. Aunque se usa en varios flujos, mantiene un solo contador que se actualiza en todas las instancias de la política. Suponiendo que la respuesta del LLM usó 1 token cada vez:

  • Se ejecuta el flujo A -> Se ejecuta MyLLMTokenQuotaPolicy y su contador = 1
  • Se ejecuta el flujo B -> Se ejecuta MyLLMTokenQuotaPolicy y su contador = 2
  • Se ejecuta el flujo A -> Se ejecuta MyLLMTokenQuotaPolicy y su contador = 3
  • Se ejecuta el flujo C -> Se ejecuta MyLLMTokenQuotaPolicy y su contador = 4
  • Se ejecuta el flujo A -> Se ejecuta MyLLMTokenQuotaPolicy y su contador = 5

La siguiente solicitud a cualquiera de los tres flujos es rechazada porque el contador de cuota alcanzó su límite.

El uso de la misma política de LLMTokenQuota en más de un lugar en un flujo de proxy de API, que puede provocar de forma involuntaria que LLMTokenQuota se ejecute más rápido de lo esperado, es un antipatrón descrito en Introducción a los antipatrones.

Como alternativa, puedes definir varias políticas de LLMTokenQuota en tu proxy de API y usar una política diferente en cada flujo. Cada política de LLMTokenQuota mantiene su propio contador, según el atributo name de la política.

Crea varios contadores a través de la configuración de la política

Puedes usar los elementos <Class> o <Identifier> en la política de LLMTokenQuota para definir varios contadores únicos en una sola política. Si usas estos elementos, una sola política puede mantener diferentes contadores según la aplicación que realice la solicitud, el desarrollador de la aplicación que realiza la solicitud, un ID de cliente o cualquier otro identificador de cliente y más. Consulta los ejemplos anteriores para obtener más información sobre el uso de los elementos <Class> o <Identifier>.

Notación de tiempo

Todos los tiempos de LLMTokenQuota se establecen en la zona horaria Hora universal coordinada (UTC).

La notación de hora de LLMTokenQuota sigue la notación de fechas estándar internacional que se define en el estándar internacional ISO 8601.

Las fechas se definen como año, mes y día, con el siguiente formato: YYYY-MM-DD. Por ejemplo, 2025-02-04 representa el 4 de febrero de 2025.

La hora del día se define como horas, minutos y segundos con el siguiente formato: hours:minutes:seconds. Por ejemplo, 23:59:59 representa la hora un segundo antes de la medianoche.

Ten en cuenta que dos notaciones, 00:00:00 y 24:00:00, están disponibles para distinguir las dos medianoches que se pueden asociar con una fecha. Por lo tanto, 2025-02-04 24:00:00 tiene la misma fecha y hora que 2025-02-05 00:00:00. Esta última suele ser la notación preferida.

Obtén la configuración de cuotas desde la configuración de productos de la API

Puedes establecer límites de cuota en las configuraciones de productos de API. Esos límites no aplican automáticamente la cuota. En su lugar, puedes hacer referencia a la configuración de la cuota de productos en una política de LLMTokenQuota. Estas son algunas ventajas de establecer una cuota en el producto para la referencia de las políticas de LLMTokenQuota:

  • Las políticas de LLMTokenQuota pueden usar una configuración uniforme en todos los proxies de API del producto de API.
  • Puedes realizar cambios en el entorno de ejecución a la configuración de cuotas en un producto de API y las políticas de LLMTokenQuota que hacen referencia al valor tienen automáticamente valores de cuota actualizados.

Si deseas obtener más información para usar la configuración de cuota desde un producto de la API, consulta el ejemplo de Cuota dinámica.

Si deseas obtener más información para configurar productos de API con límites de cuota, consulta Administra productos de la API.

Configura contadores de cuotas compartidas

En el caso simple, la política de LLMTokenQuota incrementa su contador una vez por cada token enviado a un proxy de API durante el procesamiento inicial de la solicitud. En algunos casos, es posible que desees verificar si se excedió la cuota en el control inicial de la solicitud entrante, pero aumentar el contador solo durante el control de la respuesta.

Tres elementos de la política de LLMTokenQuota (<SharedName>, <CountOnly> y <EnforceOnly>) cuando se usan en conjunto, te permiten personalizar la política de LLMTokenQuota para aplicar la cuota en las solicitudes entrantes, pero solo incrementan el contador en el flujo de respuesta.

Por ejemplo, supongamos que tienes un proxy de API que usa un LLM como destino y deseas aplicar una cuota de 100,000 tokens por hora. Las respuestas del LLM proporcionan un valor de totalTokenCount. Para lograrlo, haz lo siguiente:

  • Adjunta una política de LLMTokenQuota al flujo de solicitudes de ProxyEndpoint con el elemento <SharedName> establecido con un valor de nombre y el elemento <EnforceOnly> establecido en true.
  • Usa el elemento <LLMTokenUsageSource> en la política de LLMTokenQuota para recuperar el recuento de tokens.

Para ver un ejemplo de cómo usar los contadores compartidos, consulta Contadores compartidos en la sección Ejemplos.

Muestras

En estos ejemplos de código de política, se muestra cómo comenzar y finalizar los períodos de cuota:

Más cuota dinámica de LLMTokenQuota

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

Las cuotas dinámicas te permiten configurar una sola política de LLMTokenQuota que aplique una configuración de cuota diferente según la información que se pase a la política de LLMTokenQuota. Otro término para la configuración de LLMTokenQuota en este contexto es el plan de servicio. La cuota dinámica de LLMTokenQuota comprueba el plan de servicio de las apps y, luego, aplica esa configuración.

Por ejemplo, cuando creas un producto de API, tienes la opción de configurar el límite de cuota, la unidad de tiempo y el intervalo permitidos. Sin embargo, establecer este valor en el producto de API no impone su uso en un proxy de API. También debes agregar una política de LLMTokenQuota al proxy de API que lea estos valores. Consulta Crea productos de API para obtener más información.

En el ejemplo anterior, el proxy de API que contiene la política LLMTokenQuota usa una política VerifyAPIKey, llamada verify-api-key, para validar la clave de API que se pasa en una solicitud. Luego, la política LLMTokenQuota accede a las variables de flujo de la política VerifyAPIKey para leer los valores de cuota establecidos en el producto de API.

Otra opción es establecer atributos personalizados en desarrolladores o apps individuales y, luego, leer esos valores en la política de LLMTokenQuota. Por ejemplo, para establecer diferentes valores de cuota por desarrollador, establece atributos personalizados en el desarrollador que contengan el límite, la unidad de tiempo y el intervalo. Luego, debes hacer referencia a estos valores en la política de LLMTokenQuota como se muestra a continuación:

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

En este ejemplo, también se usan las variables de flujo VerifyAPIKey para hacer referencia a los atributos personalizados establecidos en el desarrollador.

Puedes usar cualquier variable para configurar los parámetros de la política de LLMTokenQuota. Estas variables pueden provenir de las siguientes fuentes:

  • Variables de flujo
  • Propiedades en el producto, la app o el desarrollador de la API
  • Un mapa de clave-valor (KVM)
  • Un encabezado, parámetro de búsqueda, parámetro de formulario y otros

Para cada proxy de API, puedes agregar una política LLMTokenQuota que haga referencia a la misma variable que todas las demás políticas LLMTokenQuota, o la política LLMTokenQuota puede hacer referencia a variables únicas para esa política y proxy.

Hora de inicio

<LLMTokenQuota name="LLMTokenQuotaPolicy" type="calendar">
  <StartTime>2025-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

Para un LLMTokenQuota con type establecido como calendar, debes definir un valor <StartTime> explícito. El valor de tiempo es la hora GMT, no la hora local. Si no proporcionas un valor <StartTime> para una política del tipo calendar, Apigee emite un error.

El contador de LLMTokenQuota para cada app se actualiza en función de los valores <StartTime>, <Interval> y <TimeUnit>. En este ejemplo, el LLMTokenQuota comienza a contar a las 10:30 a.m. GMT del 18 de febrero de 2025 y se actualiza cada 5 horas. Por lo tanto, la próxima actualización es a las 3:30 p.m. GMT del 18 de febrero de 2025.

Contador de acceso

<LLMTokenQuota name="LLMTokenQuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</LLMTokenQuota>

Un proxy de API tiene acceso a las variables de flujo que establece la política de LLMTokenQuota. Puedes acceder a estas variables de flujo en el proxy de API para realizar el procesamiento condicional, supervisar la política a medida que se acerca al límite de la cuota, mostrar el recuento de cuota actual a una app o por otras razones.

Debido a que el acceso a las variables de flujo para la política se basa en el atributo name de las políticas, para la política anterior <LLMTokenQuota>, puedes acceder a sus variables de flujo en el formato:

  • ratelimit.LLMTokenQuotaPolicy.allowed.count: Recuento Permitido
  • ratelimit.LLMTokenQuotaPolicy.used.count: Valor actual de contador
  • ratelimit.LLMTokenQuotaPolicy.expiry.time: Hora de UTC cuando se restablece el contador.

Existen muchas otras variables de flujo a las que puedes acceder, como se describe a continuación.

Por ejemplo, puedes usar la siguiente política AssignMessage para mostrar los valores de las variables de flujo de LLMTokenQuota como encabezados de respuesta:

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

En el siguiente ejemplo, se ilustra cómo configurar un contador compartido para un proxy de API, en el que el contador de cuota también se incrementa cuando la respuesta de destino es el estado HTTP 200. Debido a que ambas políticas de LLMTokenQuota usan el mismo valor <SharedName>, ambas políticas de LLMTokenQuota compartirán el mismo contador de cuota. Para obtener más información, consulta Configura contadores de cuota compartida.

Ejemplo de configuración de 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>

Ejemplo de la primera política de 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 ejemplo de política de 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>

Primera solicitud

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

Usa este código de muestra para aplicar una cuota de 10,000 tokens por hora. La política restablece el recuento de cuotas en la parte superior de cada hora. Si el contador alcanza la cuota de 10,000 tokens antes de que finalice la hora, se rechazan las llamadas a la API que consuman más de 10,000 tokens.

Por ejemplo, si el recuento comienza el 2025-07-08 07:00:00, se restablece en 0 a las 2025-07-08 08:00:00 (1 hora desde la hora de inicio). Si la primera solicitud se recibe a las 2025-07-08 07:35:28 y el recuento de tokens alcanza los 10,000 antes de las 2025-07-08 08:00:00, las solicitudes que consuman tokens más allá de ese recuento se rechazarán hasta que el recuento se restablezca en la parte superior de la hora.

El tiempo de restablecimiento de contadores se basa en la combinación de <Interval> y <TimeUnit>. Por ejemplo, si estableces <Interval> en 12 por un <TimeUnit> de hora, el contador se restablece cada doce horas. Puedes configurar <TimeUnit> como minutos, horas, días, semanas o meses.

Puedes hacer referencia a esta política en varias partes del proxy de API. Por ejemplo, puedes ubicarla en el PreFlow del proxy para que se ejecute en cada solicitud. O bien, puedes ubicarla en varios flujos en el proxy de API. Si usas esta política en varios lugares del proxy, mantendrá un solo contador que se actualice para todas las instancias de la política.

También puedes definir varias políticas de LLMTokenQuota en tu proxy de API. Cada política de LLMTokenQuota mantiene su propio contador, según el atributo name de la política.

Identificador de conjunto

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

De forma predeterminada, una política de LLMTokenQuota define un solo contador para el proxy de API, sin importar el origen de una solicitud. Como alternativa, puedes usar el atributo <Identifier> con una política de LLMTokenQuota para mantener contadores separados según el valor del atributo <Identifier>.

Por ejemplo, usa la etiqueta <Identifier> a fin de definir contadores independientes para cada ID de cliente. En una solicitud a tu proxy, la app cliente pasa un encabezado que contiene clientID, como se muestra en el ejemplo anterior.

Puedes especificar cualquier variable de flujo para el atributo <Identifier>. Por ejemplo, puedes especificar que un parámetro de búsqueda llamado id contenga el identificador único:

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

Si usas la política VerifyAPIKey para validar la clave de API o las políticas de OAuthV2 con tokens de OAuth, puedes usar información de la clave de API o del token para definir contadores individuales para la misma política de LLMTokenQuota. Por ejemplo, el siguiente elemento <Identifier> usa la variable de flujo client_id de una política VerifyAPIKey llamada verify-api-key:

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

Cada valor client_id único ahora define su propio contador en la política de LLMTokenQuota.

Clase

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

Puedes establecer límites de LLMTokenQuota de forma dinámica con un recuento de LLMTokenQuota basado en la clase. En este ejemplo, el límite de cuota se determina según el valor del encabezado developer_segment que se pasa con cada solicitud. Esa variable puede tener un valor de platinum o silver. Si el encabezado tiene un valor no válido, la política muestra un error de incumplimiento de cuota.

En los siguientes ejemplos, se ilustran varias configuraciones de la política LLMTokenQuota.

Calcular tokens

En este ejemplo, se muestra cómo 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>

Variables dinámicas de cuota de recuento con el producto de API, el desarrollador y la app

En este ejemplo, se muestra cómo contar variables dinámicas de cuota con API Product, Developer y 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>

Aplica la cuota sin producto de API

En este ejemplo, se muestra cómo aplicar la cuota sin un producto 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>

Aplica la cuota con el producto de API, el desarrollador y la app

En este ejemplo, se muestra cómo aplicar la cuota con el producto de API, el desarrollador y la 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>

Con transmisión SSE

En este ejemplo, se muestra cómo usar LLMTokenQuota con una transmisión de SSE.

Política de recuento de cuota 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>

Flujo de eventos:

<EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>LTQ-Count-Only</Name>
      </Step>
    </Response>
  </EventFlow>

Elemento <LLMTokenQuota>

A continuación, se muestran los atributos y los elementos secundarios de <LLMTokenQuota>. Ten en cuenta que algunas combinaciones de elementos son mutuamente excluyentes o no obligatorias. Consulta las muestras para un uso específico.

Las variables verifyapikey.my-verify-key-policy.apiproduct.* que se muestran a continuación están disponibles de forma predeterminada cuando se usa una política VerifyAPIKey llamada my-verify-key-policy para verificar la clave de API de la app en la solicitud. Los valores de las variables provienen de la configuración de cuota del producto de API con el que está asociada la clave, como se describe en Obtén la configuración de cuotas desde la configuración de productos de la 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>

Los siguientes atributos son específicos de esta política:

Atributo Descripción Predeterminado Presencia
type

Establece el tipo de política de LLMTokenQuota, que determina cuándo y cómo el contador de cuota verifica el uso de la cuota y cómo se restablece.

Si no configuras type, el contador comienza al principio del minuto/hora/día/semana/mes.

Estos son algunos de los valores válidos:

  • calendar
  • rollingwindow
  • flexi

Para obtener una descripción completa de cada tipo, consulta Tipos de políticas de LLMTokenQuota.

 N/A Opcional

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo Descripción Configuración predeterminada Presence
name

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.

 N/A Obligatorio
continueOnError

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 lo siguiente:

 false Opcional
enabled

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 adjunta a un flujo.

 true Opcional
async

Este atributo dejó de estar disponible.

 false Obsoleto

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

<DisplayName>Policy Display Name</DisplayName>
Configuración predeterminada

N/A

Si omites este elemento, se usa el valor del atributo name de la política.
Presence Opcional
Tipo String

<Allow>

Especifica la cantidad total de tokens permitidos para el intervalo de tiempo especificado. Si el contador de la política alcanza este valor de límite, las llamadas a la API posteriores se rechazan hasta que se restablece el contador.

También puede contener un elemento <Class> que haga que el elemento <Allow> sea condicional según una variable de flujo.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo o número entero
Elemento principal <LLMTokenQuota>
Elementos secundarios <Class>

A continuación, se muestran tres formas de establecer el elemento <Allow>:

<Allow count="2000"/>
 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>
 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.llmquota.limit"/>

Si especificas count y countRef, entonces countRef tiene la prioridad. Si countRef no se resuelve en el entorno de ejecución, se usa el valor de count.

También puedes especificar un elemento <Class> como elemento secundario de <Allow> para determinar el recuento permitido de la política en función de una variable de flujo. Apigee hace coincidir el valor de la variable de flujo con el atributo class del elemento <Allow>, como se muestra a continuación:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

En la siguiente tabla, se enumeran los atributos de <Allow>:

Atributo Descripción Predeterminado Presencia
count

Se usa para especificar un recuento de tokens de la cuota.

Por ejemplo, un valor de atributo count de 100, Interval de 1 y TimeUnit de mes especifican una cuota de 100 tokens por mes.

 2000 Opcional
countRef

Se usa para especificar una variable de flujo que contiene el recuento de tokens de una cuota. countRef tiene prioridad sobre el atributo count.

 ninguno Opcional

<Class>

Te permite hacer condicional el valor del elemento <Allow> según el valor de una variable de flujo. Por cada etiqueta secundaria <Allow> diferente de <Class>, la política mantiene un contador diferente.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <Allow>
Elementos secundarios <Allow> (secundario de <Class>)

Para usar el elemento <Class>, especifica una variable de flujo mediante el atributo ref al elemento <Class>. Luego, Apigee usa el valor de la variable de flujo para seleccionar una de los elementos secundarios <Allow> a fin de determinar el recuento permitido de la política. Apigee hace coincidir el valor de la variable de flujo con el atributo class del elemento <Allow>, como se muestra a continuación:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

En este ejemplo, el contador de la cuota actual se determina por el valor del parámetro de búsqueda time_variable que se pasa con cada solicitud. Esa variable puede tener un valor de peak_time o off_peak_time. Si el parámetro de consulta contiene un valor no válido, la política muestra un error de incumplimiento de cuota.

En la siguiente tabla, se enumeran los atributos de <Class>:

Atributo Descripción Predeterminado Presencia
ref Se usa para especificar una variable de flujo que contiene la clase de cuota de una cuota. ninguno Obligatorio

<Allow> (secundario de <Class>)

Especifica el límite para un contador de cuota definido por el elemento <Class>. Por cada etiqueta secundaria <Allow> diferente de <Class>, la política mantiene un contador diferente.

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

Por ejemplo:

    <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
    </Allow>

En este ejemplo, la política LLMTokenQuota mantiene dos contadores de cuota llamados peak_time y off_peak_time. La opción de cuál se use depende del parámetro de búsqueda que se pase, como se muestra en el ejemplo de <Class>.

En la siguiente tabla, se enumeran los atributos de <Allow>:

Atributo Descripción Predeterminado Presencia
class Define el nombre del contador de cuota. ninguno Obligatorio
count Especifica el límite de cuota del contador. ninguno Obligatorio

<IgnoreUnresolvedVariables>

Determina si se detiene el procesamiento de la política de LLMTokenQuota si Apigee no puede resolver una variable a la que se hace referencia en el atributo ref de la política.

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

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

Si <IgnoreUnresolvedVariables> se establece en true y no se puede resolver la variable especificada en un atributo ref, Apigee ignora el atributo ref. Si el elemento que contiene el atributo ref también contiene un valor, como <Allow count="2000"/>, Apigee usa ese valor. Si no hay ningún valor, Apigee trata el valor del elemento como nulo y sustituye el valor predeterminado, si hay uno, o una cadena vacía.

Si <IgnoreUnresolvedVariables> es false y no se puede resolver la variable especificada en un atributo ref, Apigee devuelve un error.

<Interval>

Especifica la cantidad de períodos en los que se calculan las cuotas.

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

Se usa para especificar un número entero (por ejemplo, 1, 2, 5, 60, etc.) que se sincronizará con el elemento <TimeUnit> que especifiques (minuto, hora, día, semana o mes) para determinar un período durante el cual Apigee calcula el uso de la cuota.

Por ejemplo, un intervalo de 24 con un <TimeUnit> de hour significa que la cuota se calculará durante 24 horas.

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

En la siguiente tabla, se enumeran los atributos de <Interval>:

Atributo Descripción Predeterminado Presencia
ref

Se usa para especificar una variable de flujo que contiene el intervalo de una cuota. ref tiene prioridad sobre un valor del intervalo explícito. Si se especifican la referencia y el valor, la referencia obtiene la prioridad. Si ref no se resuelve en el entorno de ejecución, se usa el valor.

 ninguno Opcional

<TimeUnit>

Especifica la unidad de tiempo aplicable a la cuota.

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

Selecciona entre minute, hour, day, week, month o year.

Por ejemplo, un Interval de 24 con un TimeUnit de hour significa que la cuota se calculará durante 24 horas.

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

En la siguiente tabla, se enumeran los atributos de <TimeUnit>:

Atributo Descripción Predeterminado Presencia
ref Especifica una variable de flujo que contiene la unidad de tiempo de una cuota. ref tiene prioridad sobre un valor del intervalo explícito. Si ref no se resuelve en el entorno de ejecución, se usa el valor del intervalo. ninguno Opcional

<StartTime>

Cuando type se configura como calendar, se especifica la fecha y la hora en que el contador de cuotas comenzará a contar, sin importar si se recibieron solicitudes de alguna app.

Valor predeterminado N/A
¿Es obligatorio? Opcional (obligatorio cuando type se establece en calendar)
Tipo String en formato de fecha y hora ISO 8601
Elemento principal <LLMTokenQuota>
Elementos secundarios Ninguno

Por ejemplo:

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

<Distributed>

Determina si Apigee usa uno o más nodos para procesar solicitudes.

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

Configúralo como true para especificar que la política debe mantener un recuento central y sincronizarlo continuamente en todos los nodos. Los nodos pueden estar ubicados en diferentes zonas o regiones de disponibilidad.

Si usas el valor predeterminado de false, puedes exceder tu cuota, ya que no se comparte el recuento de cada nodo:

<Distributed>false</Distributed>

Para garantizar que los contadores se sincronicen y se actualicen en cada solicitud, configura <Distributed> y <Synchronous> como true:

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

<Synchronous>

Determina si se debe actualizar un contador de cuotas distribuidas de forma síncrona.

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

Configúralo como true para actualizar un contador de cuotas distribuidas de forma síncrona. Esto significa que las actualizaciones de los contadores se realizan al mismo tiempo que la cuota se comprueba en una solicitud a la API. Configúralo como true si es fundamental que no permitas ninguna llamada a la API cuando se supera la cuota.

Configúralo como false para actualizar el recuento de cuotas de forma asíncrona. Esto significa que es posible que algunas llamadas a la API que excedan la cuota se transferirán, dependiendo de cuándo se actualice de forma asíncrona el contador de cuota en el repositorio central. Sin embargo, no tendrás el impacto potencial de rendimiento asociado con las actualizaciones síncronas.

El intervalo de actualización asíncrono predeterminado es de 10 segundos. Usa el elemento <AsynchronousConfiguration> para configurar este comportamiento asíncrono.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration>

Configura el intervalo de sincronización entre los contadores de cuota distribuida cuando el elemento de configuración de la política <Synchronous> no está presente o está presente y se establece en false. Apigee ignora este elemento cuando <Synchronous> se establece en true.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <LLMTokenQuota>
Elementos secundarios <SyncIntervalInSeconds>
<SyncMessageCount>

Puedes especificar el comportamiento de sincronización con los elementos secundarios <SyncIntervalInSeconds> o <SyncMessageCount>. Usa uno o ambos elementos. Por ejemplo:

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Cuando solo está presente <SyncIntervalInSeconds>, la cuota se sincroniza cada N segundos, donde N es el valor especificado en el elemento, independientemente de la cantidad de mensajes que se hayan controlado.
  • Cuando solo está presente <SyncMessageCount>, la cuota sincroniza cada M mensajes, donde M es el valor especificado en el elemento, o cada 10 segundos, lo que ocurra primero.
  • Cuando ambos elementos están presentes, la cuota se sincroniza cada M mensajes o cada N segundos, lo que ocurra primero.
  • Cuando <AsynchronousConfiguration> no está presente o no hay ningún elemento secundario, la cuota se sincroniza cada 10 segundos, independientemente de la cantidad de mensajes que se hayan controlado.

<SyncIntervalInSeconds>

Anula el comportamiento predeterminado en el que se realizan actualizaciones asíncronas después de un intervalo de 10 segundos.

Valor predeterminado 10 segundos
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <AsynchronousConfiguration>
Elementos secundarios Ninguno
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

El intervalo de sincronización debe ser mayor que 10 segundos, como se describe en Límites.

<SyncMessageCount>

Especifica la cantidad de solicitudes que se deben procesar antes de sincronizar el contador de cuotas.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Entero
Elemento principal <AsynchronousConfiguration>
Elementos secundarios Ninguno
 
<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Con la configuración de este ejemplo, en cada nodo, el recuento de cuota se sincronizará después de cada 5 solicitudes o cada 10 segundos, lo que ocurra primero.

<LLMTokenUsageSource>

Proporciona la fuente del uso de tokens de la respuesta del LLM. Debe ser una plantilla de mensaje que se resuelva en un solo valor de uso de token. Si la política no forma parte de un flujo de eventos y no puede extraer el recuento de tokens de la fuente especificada, arroja un error de tiempo de ejecución policies.ratelimit.FailedToResolveTokenUsageCount.

Valor predeterminado {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
¿Es obligatorio? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos secundarios Ninguno

En el siguiente ejemplo, se muestra cómo especificar la fuente de uso del token:

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

<LLMModelSource>

Proporciona la fuente del nombre del modelo a partir de la respuesta o solicitud del LLM. Debe ser una plantilla de mensaje que proporcione un solo valor de nombre del modelo.

Valor predeterminado
¿Es obligatorio? Opcional
Tipo String
Elemento principal <LLMTokenQuota>
Elementos secundarios Ninguno

En el siguiente ejemplo, se muestra cómo especificar la fuente del modelo en la solicitud:

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

<Identifier>

Configura la política para crear contadores únicos basados en una variable de flujo.

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

A través del elemento Identifier, puedes asignar recuentos de tokens a distintos buckets definidos por el valor en una variable de flujo. Por ejemplo, puedes usar la variable developer.id, que se propaga después de una política VerifyAPIKey, para aplicar un límite de cuota a todas las instancias de todas las apps que crea cada desarrollador específico. También puedes usar client_id a fin de aplicar un límite de cuota para cada app en particular. La configuración de esto último luce de la siguiente manera:

<Identifier ref="client_id"/>

Puedes hacer referencia a una variable personalizada que puedas establecer con la política AssignMessage o la política de JavaScript, o una variable establecida de forma implícita, como las que configuran la política VerifyAPIKey o la política VerifyJWT. Para obtener más información sobre las variables, consulta Usa variables de flujo. Para obtener una lista de las variables conocidas que define Apigee, consulta la Referencia de variables de flujo.

Si no usas este elemento, la política asigna todos los recuentos de tokens a un solo contador para la política de LLMTokenQuota específica.

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

Atributo Descripción Predeterminado Presencia
ref

Especifica una variable de flujo que identifica el recuento que se usará para la solicitud. La variable puede hacer referencia a un encabezado HTTP, un parámetro de consulta, un parámetro de formulario o un elemento del contenido del mensaje, o algún otro valor para identificar cómo asignar recuentos de tokens.

Por lo general, client_id se usa como la variable. El client_id también se conoce como la clave de API o de consumidor. Se genera para una app cuando se registra en una organización en Apigee. Puedes usar este identificador si habilitaste la clave de API o las políticas de autorización de OAuth para tu API.

 N/A Opcional

<UseQuotaConfigInAPIProduct>

Define la configuración de cuota para un producto de API, como las unidades de tiempo, el intervalo y el máximo permitido.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <LLMTokenQuota>
Elementos secundarios <DefaultConfig>

Si agregas el elemento <UseQuotaConfigInAPIProduct> a la política de LLMTokenQuota, Apigee ignora los elementos secundarios <Allow>, <Interval> y <TimeUnit> de la LLMTokenQuotaPolicy.

El elemento <UseQuotaConfigInAPIProduct> es solo un contenedor para la configuración predeterminada que defines con el elemento <DefaultConfig>, como se muestra en el siguiente ejemplo:

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

Puedes usar el atributo stepName para hacer referencia a una política VerifyAPIKey o a una operación de política ValidateToken de la política OAuthv2 en el flujo.

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

Atributo Descripción Predeterminado Presencia
stepName Identifica el nombre de la política de autenticación en el flujo. El destino puede ser una política VerifyAPIKey o una política OAuthv2. N/A Obligatorio

Para obtener más información, consulta lo siguiente:

<DefaultConfig>

Contiene valores predeterminados para la cuota de un producto de API. Cuando defines un <DefaultConfig>, se requieren los tres elementos secundarios.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo complejo
Elemento principal <UseQuotaConfigInAPIProduct>
Elementos secundarios <Allow>
<Interval>
<TimeUnit>

Es posible definir estos valores en la operación del producto de API (ya sea con la IU o la API de API Products) y en la política de LLMTokenQuota. Sin embargo, si lo haces, tendrá prioridad la configuración del producto de API y se ignorará la configuración de la política de LLMTokenQuota.

La sintaxis de este elemento es la que se muestra a continuación:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

En el siguiente ejemplo, se especifica una cuota de 10,000 cada semana:

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

Para obtener más información, consulta lo siguiente:

<SharedName>

Identifica esta política de LLMTokenQuota como compartida. Todas las políticas de LLMTokenQuota en un proxy de API con el mismo valor <SharedName> comparten el mismo contador de cuota subyacente.

Para obtener más información y ejemplos, consulta Configura contadores de cuota compartida.

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

<CountOnly>

Coloca una política LLMTokenQuota con este elemento establecido en true en un paso del flujo de respuesta ProxyEndpoint para hacer un seguimiento de la cantidad de tokens sin enviar un error al cliente cuando se supere el límite de la cuota de tokens. Si este elemento está presente, el elemento <SharedName> también debe estar presente y el elemento <EnforceOnly> no debe estar presente.

Para obtener más información y ejemplos, consulta Configura contadores de cuota compartida.

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

<EnforceOnly>

Coloca una política de LLMTokenQuota con este elemento configurado como true en el flujo de solicitud de un proxy de API para aplicar un límite de tokens sin aumentar el contador de cuota. Si este elemento está presente, el elemento <SharedName> también debe estar presente y el elemento <CountOnly> no debe estar presente.

Para obtener más información y ejemplos, consulta Configura contadores de cuota compartida.

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

Variables de flujo

Las siguientes variables de flujo predefinidas se propagan automáticamente cuando se ejecuta una política de LLMTokenQuota. Para obtener más información, consulta Referencia de variables de flujo.

Variables Tipo Permisos Descripción
ratelimit.{policy_name}.allowed.count Largo Solo lectura Muestra el recuento de cuotas permitido.
ratelimit.{policy_name}.used.count Largo Solo lectura Muestra la cuota actual que se usó en un intervalo de cuota.
ratelimit.{policy_name}.available.count Largo Solo lectura Muestra el recuento de cuotas disponible en el intervalo de cuota.
ratelimit.{policy_name}.exceed.count Largo Solo lectura Muestra 1 después de que se excede la cuota.
ratelimit.{policy_name}.total.exceed.count Largo Solo lectura Muestra 1 después de que se excede la cuota.
ratelimit.{policy_name}.expiry.time Largo Solo lectura

Devuelve la hora UTC (en milisegundos), que determina cuándo vence la cuota y cuándo comienza el nuevo intervalo de cuota.

Cuando el tipo de política de LLMTokenQuota es rollingwindow, este valor no es válido porque el intervalo de cuota nunca vence.

ratelimit.{policy_name}.identifier String Solo lectura Muestra la referencia del identificador (cliente) adjunto a la política.
ratelimit.{policy_name}.class String Solo lectura Muestra la clase asociada con el identificador del cliente.
ratelimit.{policy_name}.class.allowed.count Largo Solo lectura Muestra el recuento de cuotas permitido en la clase
ratelimit.{policy_name}.class.used.count Largo Solo lectura Muestra la cuota que se usa en una clase.
ratelimit.{policy_name}.class.available.count Largo Solo lectura Muestra el recuento de cuotas disponible en la clase
ratelimit.{policy_name}.class.exceed.count Largo Solo lectura Muestra el recuento de tokens que exceden el límite en la clase en el intervalo de cuota actual
ratelimit.{policy_name}.class.total.exceed.count Largo Solo lectura Devuelve el recuento total de tokens que exceden el límite en la clase en todos los intervalos de cuota, por lo que es la suma de class.exceed.count para todos los intervalos de cuota.
ratelimit.{policy_name}.failed Booleano Solo lectura

Indica si la política falló (verdadero o falso).
llmtokenquota.{policy_name}.model String Solo lectura Devuelve el modelo extraído.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. 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 Causa Corregir
policies.llmtokenquota.FailedToResolveModelName 400 No se pudo resolver el nombre del modelo. N/A
policies.llmtokenquota.FailedToResolveTokenUsageCount 500 No se pudo resolver el recuento de uso de tokens. N/A
policies.llmtokenquota.MessageTemplateExtractionFailed 400 No se pudo extraer la plantilla de mensaje. N/A
policies.llmtokenquota.LLMTokenQuotaViolation 429 Se superó el límite de cuota de tokens de LLM. N/A
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Ocurre si el elemento <Interval> no está definido dentro de la política LLMTokenQuota. Este elemento es obligatorio y se usa para especificar el intervalo de tiempo aplicable a la cuota de tokens del LLM. El intervalo de tiempo puede ser de minutos, horas, días, semanas o meses, según se defina con el elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Ocurre si el elemento <TimeUnit> no está definido dentro de la política LLMTokenQuota. Este elemento es obligatorio y se usa para especificar la unidad de tiempo aplicable a la cuota de tokens del LLM. El intervalo de tiempo puede ser en minutos, horas, días, semanas o meses.

Errores en la implementación

Nombre del error Causa Corregir
policies.llmtokenquota.MessageWeightNotSupported Se produce un error cuando se usa el elemento "MessageWeight", ya que no es compatible. N/A
policies.llmtokenquota.InvalidConfiguration Se debe establecer exactamente uno de <CountOnly> o <EnforceOnly> como verdadero. N/A
InvalidQuotaInterval Si el intervalo de cuota de tokens del LLM especificado en el elemento <Interval> no es un número entero, fallará la implementación del proxy de API. Por ejemplo, si el intervalo de cuota especificado es 0.1 en el elemento <Interval>, fallará la implementación del proxy de API.
InvalidQuotaTimeUnit Si la unidad de tiempo especificada en el elemento <TimeUnit> no es compatible, fallará la implementación del proxy de API. Las unidades de tiempo admitidas son minute, hour, day, week y month.
InvalidQuotaType Si el tipo de cuota de tokens del LLM especificado por el atributo type en el elemento <LLMTokenQuota> no es válido, fallará la implementación del proxy de API. Los tipos de cuota admitidos son default, calendar, flexi y rollingwindow.
InvalidStartTime Si el formato del tiempo especificado en el elemento <StartTime> no es válido, fallará la implementación del proxy de la API. El formato válido es yyyy-MM-dd HH:mm:ss, que es el formato de fecha y hora ISO 8601. Por ejemplo, si la hora especificada en el elemento <StartTime> es 7-16-2017 12:00:00, fallará la implementación del proxy de API.
StartTimeNotSupported Si se especifica el elemento <StartTime> cuyo tipo de cuota no es calendar, fallará la implementación del proxy de API. El elemento <StartTime> solo es compatible con el tipo de cuota calendar. Por ejemplo, si el atributo type se establece en flexi o rolling window en el elemento <LLMTokenQuota>, fallará la implementación del proxy de la API.
InvalidSynchronizeIntervalForAsyncConfiguration Si el valor especificado para el elemento <SyncIntervalInSeconds> dentro del elemento <AsynchronousConfiguration> en una política de LLMTokenQuota es inferior a cero, fallará la implementación del proxy de la API.
InvalidAsynchronizeConfigurationForSynchronousQuota Si el valor del elemento <AsynchronousConfiguration> se establece en true en una política LLMTokenQuota, que también tiene una configuración asíncrona definida con el elemento <AsynchronousConfiguration>, la implementación del proxy de la API falla.

Variables con fallas

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

Variables Donde Ejemplo
fault.name="fault_name" fault_name es el nombre de la falla, como se indica en la tabla de 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 "LLMTokenQuotaViolation"
ratelimit.policy_name.failed policy_name es el nombre especificado por el usuario de la política que generó la falla. ratelimit.QT-LLMTokenQuotaPolicy.failed = true

Ejemplo de respuesta de error

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.llmtokenquota.LLMTokenQuotaViolation"
      },
      "faultstring":"Rate limit LLM Token quota violation. Quota limit exceeded.

 Identifier : _default"
   }
}

Ejemplo de regla de falla

<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