Política LLMTokenQuota

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 LLMTokenQuota se ha diseñado para gestionar y controlar el consumo de tokens de las cargas de trabajo de IA y LLMs. Como las interacciones con los modelos de lenguaje extenso (LLMs) se basan en tokens, es fundamental gestionarlos de forma eficaz para controlar los costes, optimizar el rendimiento y mantener la estabilidad de la plataforma.

Una cuota es una asignación de tokens de LLM (de entrada o de salida) que un proxy de API puede consumir durante un periodo determinado, como un minuto, una hora, un día, una semana o un mes. La política LLMTokenQuota mantiene contadores que registran el número de tokens consumidos por el proxy de API. Esta función permite a los proveedores de APIs aplicar límites al consumo de tokens por parte de las aplicaciones durante 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 aplicar las cuotas de forma precisa y en tiempo real.

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.

Cómo funciona la aplicación de LLMTokenQuota

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

  • Recuento de tokens (<CountOnly>): La política LLMTokenQuota mantiene contadores que registran el número de tokens consumidos por las respuestas de LLM que pasan por el proxy de la API.
  • Aplicar límites (<EnforceOnly>): Esta función permite a los proveedores de APIs establecer límites estrictos en el número de tokens que consumen las aplicaciones durante un intervalo definido. Por ejemplo, puedes limitar las aplicaciones a 1000 tokens por minuto o a 10.000.000 tokens al mes.
  • Superación de la 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 al mes, el límite de tokens empieza a aplicarse cuando se cuenta el token número 10.000, independientemente del momento del mes en el 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 LLMTokenQuota con los productos de API:

Flujo de proxy de LLMTokenQuota
  1. Aplica la política VerifyAPIKey o VerifyAccessToken junto con la política de cumplimiento LLMTokenQuota en la solicitud del proxy de API (no importa si es Proxy o Target).
  2. Aplica la política de recuento LLMTokenQuota en respuesta al proxy de API (no importa si es un proxy o un destino).
  3. La política VerifyAPIKey o VerifyAccessToken compara la clave o el token con el producto de la API, el conjunto de operaciones, el desarrollador y la aplicación. Expone las variables de flujo de la cuota de LLM de todos los modelos de los conjuntos de operaciones de LLM coincidentes.
  4. En la política de cumplimiento de la cuota, extraemos el modelo según la plantilla de mensaje proporcionada.
  5. A continuación, se comparan las variables de cuota de LLM del modelo. Si se encuentra una 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, añade la política como parte del flujo de eventos, tal 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>

Durante el procesamiento del 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. En el resto de los eventos, la política da como resultado NO-OP.

.

Tipos de políticas de LLMTokenQuota

La política LLMTokenQuota admite varias formas de iniciar y restablecer el contador de cuota. Puede definir cuál usar con el atributo type del elemento <LLMTokenQuota>, como se muestra en el siguiente ejemplo:

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

Los valores válidos de type son los siguientes:

  • calendar: configura una cuota basada en una hora de inicio explícita. El contador LLMTokenQuota de cada aplicación se actualiza en función de los valores <StartTime>, <Interval> y <TimeUnit> que hayas definido.
  • rollingwindow: configura una cuota que usa una ventana acumulativa para determinar el uso de la cuota. Con rollingwindow, puedes determinar 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, las 17:01), cuenta el número de tokens consumidos entre ese momento y las 17:01 del día anterior (1 día) y determina si se ha superado la cuota durante ese periodo.
  • flexi: configura una cuota que hace que el contador empiece cuando se recibe el primer mensaje de solicitud de una aplicación y se restablece en función de los valores <Interval> y <TimeUnit>.

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

Unidad de tiempo Tipo
default (o null) calendar flexi
minuto Inicio del minuto siguiente Un minuto después de las <StartTime> Un minuto después de la primera solicitud
hora Al principio de la hora siguiente 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 de <StartTime> 24 horas después de la primera solicitud
semana Domingo a medianoche (GMT) al final de 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

En el caso de type="calendar", debe especificar el valor de <StartTime>.

En la tabla no se describe cuándo se restablece el recuento del tipo rollingwindow. Esto se debe a que las cuotas de ventana de tiempo funcionan de forma diferente, ya que se basan en una ventana retrospectiva, como una hora o un día. En el caso del tipo rollingwindow, el contador nunca se reinicia, sino que se vuelve a calcular en cada solicitud. Cuando se recibe una nueva solicitud, la política determina si se ha superado la cuota en el periodo anterior.

Por ejemplo, defines un periodo de dos horas que permite 1000 tokens. A las 16:45, se recibe una nueva solicitud.La política calcula el número de tokens de cuota de las dos horas anteriores, es decir, el número de tokens consumidos desde las 14:45. Si no se ha superado el límite de cuota en ese periodo de dos horas, se permitirá la solicitud.

Un minuto después, a las 16:46, llega otra solicitud. Ahora, la política calcula el número de cuotas desde las 14:46 para determinar si se ha superado el límite.

Información sobre los contadores de cuotas

Cuando se ejecuta una política LLMTokenQuota en un flujo de 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 a ese contador. En función de la configuración que uses para tu producto de API, la política LLMTokenQuota puede usar un solo contador o varios contadores independientes. Es importante entender los casos en los que se usarán varios contadores y cómo se comportan.

Configurar los ajustes de cuota de los productos de API

En un producto de API se pueden especificar ajustes de cuota a nivel de producto o de operación individual, o en ambos. Si tu proxy de API está incluido en un producto de API, puedes configurar la política LLMTokenQuota para que use los ajustes de cuota (número permitido, unidad de tiempo e intervalo) definidos en ese producto. La forma más sencilla de hacerlo es mediante el elemento useQuotaConfigInAPIProduct. También puedes hacer referencia a estos ajustes en la política LLMTokenQuota mediante referencias de variables individuales.

Cómo se contabilizan las cuotas

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

  • Si una operación tiene una cuota definida, los ajustes de cuota de la operación tienen prioridad sobre los ajustes de cuota definidos a nivel de producto.
  • Si una operación no tiene una cuota definida, se aplican los ajustes de cuota a nivel de producto.
  • Si el producto de la API no incluye ningún ajuste de cuota (ni a nivel de producto ni de operación), se aplicarán los ajustes de cuota de recuento permitido, unidad de tiempo e intervalo especificados en la política LLMTokenQuota.

En todos los casos, Apigee mantiene un contador de cuota independiente para cada operación definida en un producto de API. Las llamadas a la API que coincidan con una operación incrementarán su contador.

Configurar contadores a nivel de proxy de API

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

Para conseguir esta configuración, debes usar la API/apiproducts de Apigee para crear o actualizar el producto y definir el atributo quotaCounterScope en 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 la API que estén asociadas al 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, las operaciones 1 y 2 están asociadas a Proxy1, y las operaciones 4 y 5 están asociadas a Proxy3. Como quotaCounterScope=PROXY se define en el producto de API, cada una de estas operaciones usa el ajuste de cuota a nivel de producto de API. Las operaciones 1 y 2, asociadas a Proxy1, usan un contador compartido, mientras que las operaciones 4 y 5, asociadas a Proxy3, usan otro contador compartido. La operación 3 tiene su propio ajuste 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 quotaCounterScope

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

Si no hay ningún producto de API asociado a un proxy de API, una política LLMTokenQuota mantiene un solo contador, independientemente del número de veces que se haga referencia a él en un proxy de API. El nombre del contador de cuota se basa en el atributo name de la política.

Por ejemplo, creas una política LLMTokenQuota llamada MyLLMTokenQuotaPolicy con un límite de 5 tokens y la colocas en varios flujos (A, B y C) del proxy de API. Aunque se usa en varios flujos, mantiene un solo contador que actualizan todas las instancias de la política. Si la respuesta del LLM ha usado 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 es 4
  • Se ejecuta el flujo A -> se ejecuta MyLLMTokenQuotaPolicy y su contador es 5

La siguiente solicitud a cualquiera de los tres flujos se rechaza porque el contador de cuotas ha alcanzado su límite.

Usar la misma política LLMTokenQuota en más de un lugar en un flujo de proxy de API, lo que puede provocar que LLMTokenQuota se agote más rápido de lo esperado, es un antipatrón que se describe en Introducción a los antipatrones.

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

Crear varios contadores mediante la configuración de políticas

Puedes usar los elementos <Class> o <Identifier> en la política LLMTokenQuota para definir varios contadores únicos en una sola política. Al usar estos elementos, una sola política puede mantener diferentes contadores en función de la aplicación que haga la solicitud, el desarrollador de la aplicación que haga la solicitud, un ID de cliente u otro identificador de cliente, entre otros. Consulta los ejemplos anteriores para obtener más información sobre cómo usar los elementos <Class> o <Identifier>.

Notación de tiempo

Todas las horas de LLMTokenQuota se definen en la zona horaria del tiempo universal coordinado (UTC).

La notación de tiempo de LLMTokenQuota sigue la notación de fecha estándar internacional definida 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 del 2025.

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

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

Obtener la configuración de cuota de la configuración del producto de API

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

  • Las políticas LLMTokenQuota pueden usar un ajuste uniforme en todos los proxies de API del producto de API.
  • Puedes hacer cambios en el tiempo de ejecución en la configuración de cuota de un producto de API y las políticas LLMTokenQuota que hagan referencia al valor tendrán automáticamente valores de cuota actualizados.

Para obtener más información sobre cómo usar los ajustes de cuota de un producto de API, consulta el ejemplo de cuota dinámica.

Para obtener información sobre cómo configurar productos de API con límites de cuota, consulta Gestionar productos de API.

Configurar contadores de cuota compartidos

En el caso más sencillo, la política LLMTokenQuota incrementa su contador una vez por cada token enviado a un proxy de API durante el procesamiento de la solicitud inicial. En algunos casos, puede que quieras comprobar si se ha superado la cuota en la gestión inicial de la solicitud entrante, pero incrementar el contador solo durante la gestión de la respuesta.

Los tres elementos de la política LLMTokenQuota (<SharedName>, <CountOnly> y <EnforceOnly>) te permiten personalizar la política LLMTokenQuota para aplicar la cuota a 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 quieres aplicar una cuota de 100.000 tokens por hora. Las respuestas del LLM proporcionan un valor totalTokenCount. Para ello, sigue estos pasos:

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

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

Ejemplos

Estos ejemplos de código de la política muestran cómo iniciar y finalizar periodos de cuota:

Más información sobre Dynamic 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 LLMTokenQuota que aplique diferentes ajustes de cuota en función de la información que se le proporcione. Otro término para los ajustes de LLMTokenQuota en este contexto es plan de servicio. LLMTokenQuota dinámico comprueba el plan de servicio de las aplicaciones y, a continuación, aplica esos ajustes.

Por ejemplo, cuando creas un producto de API, puedes definir de forma opcional el límite de cuota permitido, la unidad de tiempo y el intervalo. Sin embargo, si se definen estos valores en el producto de API, no se obliga a usarlos en un proxy de API. También debe añadir una política LLMTokenQuota al proxy de API que lea estos valores. Consulta más información sobre cómo crear productos de API.

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 transmitida en una solicitud. A continuación, la política LLMTokenQuota accede a las variables de flujo de la política VerifyAPIKey para leer los valores de cuota definidos en el producto de API.

Otra opción es definir atributos personalizados en desarrolladores o aplicaciones concretos y, a continuación, leer esos valores en la política LLMTokenQuota. Por ejemplo, para definir diferentes valores de cuota por desarrollador, debe definir atributos personalizados en el desarrollador que contengan el límite, la unidad de tiempo y el intervalo. A continuación, haga referencia a estos valores en la política LLMTokenQuota, tal 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 definidos en el desarrollador.

Puedes usar cualquier variable para definir los parámetros de la política LLMTokenQuota. Esas variables pueden proceder de:

  • Variables de flujo
  • Propiedades del producto de API, la aplicación o el desarrollador
  • Un mapa de clave-valor (KVM)
  • Un encabezado, un parámetro de consulta, un parámetro de formulario, etc.

En cada proxy de API, puedes añadir una política LLMTokenQuota que haga referencia a la misma variable que todas las demás políticas LLMTokenQuota de los demás proxies. También puedes añadir una política LLMTokenQuota que haga referencia a variables únicas de 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>

En el caso de un LLMTokenQuota con type definido como calendar, debes definir un valor <StartTime> explícito. El valor de la hora es la hora GMT, no la hora local. Si no proporciona un valor de <StartTime> para una política de tipo calendar, Apigee emitirá un error.

El contador LLMTokenQuota de cada aplicación se actualiza en función de los valores <StartTime>, <Interval> y <TimeUnit>. En este ejemplo, el LLMTokenQuota empieza a contar a las 10:30 (GMT) del 18 de febrero del 2025 y se actualiza cada 5 horas. Por lo tanto, la próxima actualización se realizará el 18 de febrero del 2025 a las 15:30 (GMT).

Contador de accesos

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

Un proxy de API tiene acceso a las variables de flujo definidas por la política LLMTokenQuota. Puedes acceder a estas variables de flujo en el proxy de API para realizar un procesamiento condicional, monitorizar la política a medida que se acerca al límite de cuota, devolver el contador de cuota actual a una aplicación o por otros motivos.

Como el acceso a las variables de flujo de la política se basa en el atributo name de las políticas, para la política anterior llamada <LLMTokenQuota>, puedes acceder a sus variables de flujo de la siguiente forma:

  • ratelimit.LLMTokenQuotaPolicy.allowed.count: recuento permitido.
  • ratelimit.LLMTokenQuotaPolicy.used.count: valor actual del contador.
  • ratelimit.LLMTokenQuotaPolicy.expiry.time: hora UTC en la que se restablece el contador.

Puedes acceder a muchas otras variables de flujo, como se describe a continuación.

Por ejemplo, puedes usar la siguiente política AssignMessage para devolver los valores de las variables de flujo 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 muestra cómo configurar un contador compartido para un proxy de API, donde el contador de cuota también se incrementa cuando la respuesta de destino es el estado HTTP 200. Como ambas políticas de LLMTokenQuota usan el mismo valor de <SharedName>, compartirán el mismo contador de cuotas. Para obtener más información, consulta Configurar contadores de cuota compartidos.

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>

Primer ejemplo de política 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 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 ejemplo para aplicar una cuota de 10.000 tokens por hora. La política restablece el contador de cuota al principio de cada hora. Si el contador alcanza la cuota de 10.000 tokens antes de que termine la hora, se rechazarán las llamadas a la API que consuman más de 10.000 tokens.

Por ejemplo, si el contador empieza en 2025-07-08 07:00:00, se restablecerá a 0 a las 2025-07-08 08:00:00 (1 hora después de la hora de inicio). Si la primera solicitud se recibe a las 2025-07-08 07:35:28 y el recuento de tokens llega a 10.000 antes de las 2025-07-08 08:00:00, las solicitudes que consuman tokens por encima de ese recuento se rechazarán hasta que el recuento se restablezca al principio de la hora.

La hora de restablecimiento del contador se basa en la combinación de <Interval> y <TimeUnit>. Por ejemplo, si asignas el valor <Interval> a 12 para un <TimeUnit> de una hora, el contador se restablecerá cada doce horas. Puedes definir <TimeUnit> en minutos, horas, días, semanas o meses.

Puedes hacer referencia a esta política en varios lugares de tu proxy de API. Por ejemplo, puede colocarla en Proxy PreFlow para que se ejecute en cada solicitud. También puedes colocarlo en varios flujos del proxy de API. Si usa esta política en varios lugares del proxy, se mantendrá un solo contador que se actualizará con todas las instancias de la política.

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

Definir identificador

<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 LLMTokenQuota define un único contador para el proxy de API, independientemente del origen de una solicitud. También puede usar el atributo <Identifier> con una política LLMTokenQuota para mantener contadores independientes en función del valor del atributo <Identifier>.

Por ejemplo, use la etiqueta <Identifier> para definir contadores independientes para cada ID de cliente. En una solicitud a tu proxy, la aplicación cliente envía un encabezado que contiene el clientID, como se muestra en el ejemplo anterior.

Puede especificar cualquier variable de flujo en el atributo <Identifier>. Por ejemplo, puede especificar que un parámetro de consulta 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 OAuthV2 con tokens de OAuth, puedes usar la información de la clave de API o del token para definir contadores individuales de la misma política 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 único de client_id define ahora su propio contador en la política 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 definir límites de LLMTokenQuota de forma dinámica usando un recuento de LLMTokenQuota basado en clases. En este ejemplo, el límite de cuota se determina mediante el valor del encabezado developer_segment que se envía con cada solicitud. Esta variable puede tener el valor platinum o silver. Si el encabezado tiene un valor no válido, la política devuelve un error de infracción de cuota.

En los siguientes ejemplos se ilustran varias configuraciones de la política de 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>

Contar variables dinámicas de cuota mediante API Product, Developer y App

En este ejemplo se muestra cómo contar variables dinámicas de cuota mediante 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>

Aplicar cuotas sin producto de API

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

Aplicar cuotas con productos de API, desarrolladores y aplicaciones

En este ejemplo se muestra cómo aplicar cuotas con productos de API, desarrolladores y aplicaciones.

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

En este ejemplo se muestra cómo usar LLMTokenQuota con un flujo SSE.

Política de recuento de cuotas 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 son obligatorias. Consulta los ejemplos para ver cómo se usa.

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 comprobar la clave de API de la aplicación en la solicitud. Los valores de las variables proceden de la configuración de cuota del producto de API al que está asociada la clave, tal como se describe en el artículo Obtener la configuración de cuota de la configuración del producto de 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

Define el tipo de política LLMTokenQuota, que determina cuándo y cómo comprueba el contador de cuotas el uso de cuotas, así como cómo se restablece.

Si no defines type, el contador empieza al principio del minuto, la hora, el día, la semana o el mes.

A continuación se muestran los valores válidos.

  • calendar
  • rollingwindow
  • flexi

Para ver una descripción completa de cada tipo, consulta los tipos de política LLMTokenQuota.

 N/A Opcional

En la siguiente tabla se describen los atributos que son comunes a todos los elementos superiores de la política:

Atributo Descripción Predeterminado Presencia
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.

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.

 N/A Obligatorio
continueOnError

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:

 falso Opcional
enabled

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.

 true Opcional
async

Este atributo está obsoleto.

 falso Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>
Predeterminado

N/A

Si omite este elemento, se usará el valor del atributo name de la política.
Presencia Opcional
Tipo Cadena

<Allow>

Especifica el número total de tokens permitidos en el intervalo de tiempo especificado. Si el contador de la política alcanza este valor límite, se rechazarán las llamadas a la API posteriores hasta que se restablezca el contador.

También puede contener un elemento <Class> que condicione el elemento <Allow> en función de una variable de flujo.

Valor predeterminado N/A
¿Es obligatorio? Opcional
Tipo Tipo Entero o Complejo
Elemento principal <LLMTokenQuota>
Elementos secundarios <Class>

A continuación, se muestran tres formas de definir 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 tanto count como countRef, countRef tiene prioridad. Si countRef no se resuelve en el tiempo de ejecución, se usa el valor de count.

También puede especificar un elemento <Class> como elemento secundario de <Allow> para determinar el número permitido de la política en función de una variable de flujo. Apigee compara el valor de la variable de flujo con el atributo class del elemento <Allow>, tal 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 el número de tokens de la cuota.

Por ejemplo, si el valor del atributo count es 100, el de Interval es 1 y el de TimeUnit es "month" (mes), se especifica una cuota de 100 tokens al mes.

 2000 Opcional
countRef

Se usa para especificar una variable de flujo que contenga el número de tokens de una cuota. countRef tiene prioridad sobre el atributo count.

 ninguno Opcional

<Class>

Te permite condicionar el valor del elemento <Allow> en función del valor de una variable de flujo. Para 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> (elemento secundario de <Class>)

Para usar el elemento <Class>, especifica una variable de flujo mediante el atributo ref del elemento <Class>. A continuación, Apigee usa el valor de la variable de flujo para seleccionar uno de los elementos secundarios <Allow> y determinar el número permitido de la política. Apigee compara el valor de la variable de flujo con el atributo class del elemento <Allow>, tal 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 cuota actual se determina mediante el valor del parámetro de consulta time_variable que se envía con cada solicitud. Esta variable puede tener el valor peak_time o off_peak_time. Si el parámetro de consulta contiene un valor no válido, la política devuelve un error de infracción 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 contenga la clase de cuota de una cuota. ninguno Obligatorio

<Allow> (hijo de <Class>)

Especifica el límite de un contador de cuota definido por el elemento <Class>. Para 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. El parámetro que se usa depende del parámetro de consulta que se haya enviado, 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 LLMTokenQuota si Apigee no puede resolver una variable a la que hace referencia el atributo ref de la política.

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

Se define 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 define como 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 lo hay, 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 el número de periodos 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 emparejará con el elemento <TimeUnit> que especifiques (minuto, hora, día, semana o mes) para determinar un periodo 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á a lo largo de 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 de intervalo explícito. Si se especifican tanto la referencia como el valor, la referencia tiene prioridad. Si ref no se resuelve en el tiempo 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 Cadena
Elemento principal <LLMTokenQuota>
Elementos secundarios Ninguno

Elige 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á a lo largo de 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 de intervalo explícito. Si ref no se resuelve en el tiempo de ejecución, se usa el valor del intervalo. ninguno Opcional

<StartTime>

Si type se define como calendar, se especifica la fecha y la hora en las que el contador de cuota empieza a contar, independientemente de si se han recibido solicitudes de alguna aplicación.

Valor predeterminado N/A
¿Es obligatorio? Opcional (obligatorio cuando type está definido como calendar)
Tipo Cadena 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 varios nodos para procesar solicitudes.

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

Defina el valor true para especificar que la política debe mantener un contador central y sincronizarlo continuamente en todos los nodos. Los nodos pueden estar en zonas de disponibilidad o regiones diferentes.

Si usas el valor predeterminado false, es posible que superes tu cuota, ya que el recuento de cada nodo no se comparte:

<Distributed>false</Distributed>

Para asegurarte de que los contadores se sincronicen y se actualicen en cada solicitud, define <Distributed> y <Synchronous> como true:

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

<Synchronous>

Determina si se debe actualizar un contador de cuota distribuida de forma síncrona.

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

Se define como true para actualizar un contador de cuota distribuida de forma síncrona. Esto significa que los contadores se actualizan al mismo tiempo que se comprueba la cuota de una solicitud a la API. Asigna el valor true si es fundamental que no permitas ninguna llamada a la API que supere la cuota.

Asigna el valor false para actualizar el contador de cuota de forma asíncrona. Esto significa que es posible que se completen algunas llamadas a la API que superen la cuota, en función de cuándo se actualice de forma asíncrona el contador de cuotas en el repositorio central. Sin embargo, no tendrás que hacer frente a los posibles problemas de rendimiento asociados a las actualizaciones síncronas.

El intervalo de actualización asíncrona 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 distribuidos cuando el elemento de configuración de la política <Synchronous> no está presente o está presente y se ha definido como false. Apigee ignora este elemento cuando <Synchronous> tiene el valor true.

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

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

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

o

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Si solo está presente <SyncIntervalInSeconds>, la cuota se sincroniza cada N segundos, donde N es el valor especificado en el elemento, independientemente del número de mensajes que se hayan gestionado.
  • Si solo se incluye <SyncMessageCount>, la cuota se 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.
  • Si <AsynchronousConfiguration> no está presente o no hay ningún elemento secundario, la cuota se sincroniza cada 10 segundos, independientemente del número de mensajes que se hayan gestionado.

<SyncIntervalInSeconds>

Anula el comportamiento predeterminado en el que las actualizaciones asíncronas se realizan 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 igual o superior a 10 segundos, tal como se describe en la sección Límites.

<SyncMessageCount>

Especifica el número de solicitudes que se deben procesar antes de sincronizar el contador de cuota.

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á cada 5 solicitudes o cada 10 segundos, lo que ocurra primero.

<LLMTokenUsageSource>

Proporciona la fuente del uso del token de la respuesta del LLM. Debe ser una plantilla de mensaje que se resuelva en un único 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, se produce un error de tiempo de ejecución policies.ratelimit.FailedToResolveTokenUsageCount.

Valor predeterminado {jsonPath('$.usageMetadata.candidatesTokenCount',response.content,true)}
¿Es obligatorio? Opcional
Tipo Cadena
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 la solicitud del LLM. Debe ser una plantilla de mensaje que proporcione un solo valor de nombre de modelo.

Valor predeterminado
¿Es obligatorio? Opcional
Tipo Cadena
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 Cadena
Elemento principal <LLMTokenQuota>
Elementos secundarios Ninguno

Con el elemento Identifier, puede asignar recuentos de tokens a distintos contenedores definidos por el valor de una variable de flujo. Por ejemplo, puede usar la variable developer.id, que se rellena después de una política VerifyAPIKey, para aplicar un límite de cuota a todas las instancias de todas las aplicaciones creadas por cada desarrollador específico, o bien puede usar client_id para aplicar un límite de cuota a cada aplicación en concreto. La configuración de esta última opción es la siguiente:

<Identifier ref="client_id"/>

Puedes hacer referencia a una variable personalizada que hayas definido con la política AssignMessage o la política JavaScript, o bien a una variable que se haya definido implícitamente, como las que definen la política VerifyAPIKey o la política VerifyJWT. Para obtener más información sobre las variables, consulta el artículo Usar variables de flujo. Para ver una lista de las variables conocidas definidas por 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 de la política LLMTokenQuota concreta.

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

Atributo Descripción Predeterminado Presencia
ref

Especifica una variable de flujo que identifica el contador que se va a usar en 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 bien a otro valor para identificar cómo asignar los recuentos de tokens.

client_id se suele usar como variable. La client_id también se conoce como clave de API o clave de consumidor, y se genera para una aplicación cuando se registra en una organización de Apigee. Puedes usar este identificador si has habilitado las políticas de autorización de claves de API u OAuth para tu API.

 N/A Opcional

<UseQuotaConfigInAPIProduct>

Define los ajustes de cuota de 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 añade el elemento <UseQuotaConfigInAPIProduct> a la política LLMTokenQuota, Apigee ignorará los elementos secundarios <Allow>, <Interval> y <TimeUnit> de LLMTokenQuotaPolicy.

El elemento <UseQuotaConfigInAPIProduct> es simplemente un contenedor de los ajustes predeterminados que definas con el elemento <DefaultConfig>, como se muestra en el siguiente ejemplo:

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

Puede 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 las siguientes secciones:

<DefaultConfig>

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

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

Estos valores se pueden definir tanto en la operación del producto de API (ya sea con la interfaz de usuario o con la API Products API) como en la política LLMTokenQuota. Sin embargo, si lo hace, los ajustes del producto de API tendrán prioridad y se ignorarán los ajustes de la política LLMTokenQuota.

La sintaxis de este elemento es la siguiente:

<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 las siguientes secciones:

<SharedName>

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

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

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

<CountOnly>

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

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

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

<EnforceOnly>

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

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

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

Variables de flujo

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

Variables Tipo Permisos Descripción
ratelimit.{policy_name}.allowed.count Long Solo lectura Devuelve el recuento de cuota permitido.
ratelimit.{policy_name}.used.count Long Solo lectura Devuelve la cuota actual utilizada en un intervalo de cuota.
ratelimit.{policy_name}.available.count Long Solo lectura Devuelve el número de cuotas disponibles en el intervalo de cuota.
ratelimit.{policy_name}.exceed.count Long Solo lectura Devuelve 1 cuando se supera la cuota.
ratelimit.{policy_name}.total.exceed.count Long Solo lectura Devuelve 1 cuando se supera la cuota.
ratelimit.{policy_name}.expiry.time Long Solo lectura

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

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

ratelimit.{policy_name}.identifier Cadena Solo lectura Devuelve la referencia del identificador (de cliente) adjunta a la política.
ratelimit.{policy_name}.class Cadena Solo lectura Devuelve la clase asociada al identificador de cliente.
ratelimit.{policy_name}.class.allowed.count Long Solo lectura Devuelve el recuento de cuota permitido definido en la clase.
ratelimit.{policy_name}.class.used.count Long Solo lectura Devuelve la cuota utilizada en una clase.
ratelimit.{policy_name}.class.available.count Long Solo lectura Devuelve el número de cuotas disponibles en la clase.
ratelimit.{policy_name}.class.exceed.count Long Solo lectura Devuelve el recuento de tokens que supera el límite de la clase en el intervalo de cuota actual.
ratelimit.{policy_name}.class.total.exceed.count Long Solo lectura Devuelve el recuento total de tokens que supera el límite de la clase en todos los intervalos de cuota, por lo que es la suma de class.exceed.count de todos los intervalos de cuota.
ratelimit.{policy_name}.failed Booleano Solo lectura

Indica si la política ha fallado (true o false).
llmtokenquota.{policy_name}.model Cadena Solo lectura Devuelve el modelo extraído.

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 define, cuando esta política activa un error. Es importante conocer esta información si vas a desarrollar reglas de errores para gestionarlos. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Código de fallo Estado de HTTP Causa Solucionar
policies.llmtokenquota.FailedToResolveModelName 400 No se ha podido resolver el nombre del modelo. N/A
policies.llmtokenquota.FailedToResolveTokenUsageCount 500 No se ha podido resolver el recuento de uso de tokens. N/A
policies.llmtokenquota.MessageTemplateExtractionFailed 400 No se ha podido extraer la plantilla de mensaje. N/A
policies.llmtokenquota.LLMTokenQuotaViolation 429 Se ha superado el límite de cuota de tokens de LLM. N/A
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Se produce si el elemento <Interval> no se define en la política LLMTokenQuota. Este elemento es obligatorio y se usa para especificar el intervalo de tiempo aplicable a la cuota de tokens de LLM. El intervalo de tiempo puede ser en minutos, horas, días, semanas o meses, tal como se define con el elemento <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Se produce si el elemento <TimeUnit> no se define en la política LLMTokenQuota. Este elemento es obligatorio y se usa para especificar la unidad de tiempo aplicable a la cuota de tokens de LLM. El intervalo de tiempo puede ser en minutos, horas, días, semanas o meses.

Errores de implementación

Nombre del error Causa Solucionar
policies.llmtokenquota.MessageWeightNotSupported Error cuando se usa el elemento "MessageWeight", ya que no se admite. N/A
policies.llmtokenquota.InvalidConfiguration Solo uno de los elementos <CountOnly> o <EnforceOnly> debe tener el valor "true". N/A
InvalidQuotaInterval Si el intervalo de cuota de tokens de LLM especificado en el elemento <Interval> no es un número entero, la implementación del proxy de la API fallará. Por ejemplo, si el intervalo de cuota especificado es 0,1 en el elemento <Interval>, se producirá un error al desplegar el proxy de API.
InvalidQuotaTimeUnit Si la unidad de tiempo especificada en el elemento <TimeUnit> no es compatible, se producirá un error en 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 de LLM especificado por el atributo type en el elemento <LLMTokenQuota> no es válido, no se podrá desplegar el proxy de API. Los tipos de cuota admitidos son default, calendar, flexi y rollingwindow.
InvalidStartTime Si el formato de la hora especificada en el elemento <StartTime> no es válido, se producirá un error al implementar el proxy de 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, se producirá un error al implementar el proxy de API.
StartTimeNotSupported Si se especifica el elemento <StartTime> cuyo tipo de cuota no es calendar, el despliegue del proxy de API falla. El elemento <StartTime> solo se admite en el tipo de cuota calendar. Por ejemplo, si el atributo type se define como flexi o rolling window en el elemento <LLMTokenQuota>, se producirá un error al implementar el proxy de API.
InvalidSynchronizeIntervalForAsyncConfiguration Si el valor especificado para el elemento <SyncIntervalInSeconds> dentro del elemento <AsynchronousConfiguration> de una política LLMTokenQuota es inferior a cero, se produce un error en la implementación del proxy de API.
InvalidAsynchronizeConfigurationForSynchronousQuota Si el valor del elemento <AsynchronousConfiguration> es true en una política LLMTokenQuota, que también tiene una configuración asíncrona definida mediante el elemento <AsynchronousConfiguration>, se produce un error en la implementación del proxy de API.

Variables de error

Estas variables se definen cuando esta política activa un error. Para obtener más información, consulta el artículo Qué debes saber sobre los errores de las políticas.

Variables Dónde Ejemplo
fault.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 "LLMTokenQuotaViolation"
ratelimit.policy_name.failed policy_name es el nombre de la política especificado por el usuario que ha provocado el error. 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"
   }
}

Regla de fallo de ejemplo

<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