¿Por qué puede haber sobregasto incluso con un límite establecido en la clave API? Las tres líneas de presupuesto de las pruebas de AI

¿Por qué puede haber sobregasto incluso con un límite establecido en la clave API? Las tres líneas de presupuesto de las pruebas de AI

Resumen: aunque se configure una cuota para la clave API, el costo todavía puede superar lo previsto. Este artículo explica por qué y divide el control presupuestario de las pruebas de IA en tres líneas de presupuesto que deben aplicarse en orden.

Empecemos por la conclusión: la cuota de la clave API en el gateway es un límite blando; cuando hay solicitudes concurrentes, no se puede tratar como un límite estricto de facturación. En la documentación de tokens de APIYI, por ejemplo, la cuota se comprueba al inicio de la solicitud. Varias solicitudes pueden pasar la comprobación a la vez, o una sola solicitud puede tener un precio muy alto; el consumo final podría acabar superando la cuota configurada.

La forma fiable es tratar el problema en tres capas:

  1. El backend de la aplicación hace la comprobación antes de enviar la solicitud y reserva el presupuesto de forma atómica.
  2. En el gateway, se emite una clave API aparte para el tráfico de prueba, con cuota y lista de modelos permitidos, para reducir el impacto si esa clave se usa de forma indebida.
  3. La alerta de saldo de la cuenta solo notifica; su función es activar una respuesta manual.

Estas tres capas tienen responsabilidades que no se sustituyen entre sí. La verdadera admisión presupuestaria se produce en la contabilidad de la propia aplicación.

api-key-quota-overspend-three-budget-lines-es-image-0

Mapa de conocimiento e índice: orden y reparto de responsabilidades de las tres líneas de presupuesto

La siguiente tabla cumple a la vez la función de mapa de conocimiento e índice. Muestra en qué orden entran en juego las tres líneas de presupuesto, de qué se encarga cada una, por qué se organizan así y a qué sección del texto corresponden.

Orden Línea de presupuesto De qué se encarga Por qué ocupa esta posición Objetivo Texto principal
Premisa Entender la cuota flexible Distinguir la comprobación antes de la solicitud, la retención previa y el cargo real Si no queda claro el orden temporal del cobro, no hay forma de diseñar las tres capas siguientes Entender cómo se produce el exceso de gasto 1, 1.1
Primera Presupuesto del backend de la aplicación Reserva y liquidación atómicas por usuario y pool de prueba Solo la aplicación sabe «quién lo está usando y cuánto puede usar» Hacer que el exceso de gasto se bloquee antes de enviar la solicitud 2.1, 3
Segunda Clave de prueba independiente Cuota, lista de modelos permitidos y aislamiento del tráfico de producción Cuando la aplicación tiene un bug, la pasarela es la segunda barrera Reducir la superficie de exposición de una sola clave 2.2
Tercera Alerta de saldo de la cuenta Notificar cuando el saldo cae por debajo del umbral La alerta es una señal a posteriori y no puede bloquear Permitir que alguien intervenga a tiempo 2.3
Implementación Registro de concurrencia y lista de verificación de lanzamiento Reserva, liquidación, gestión de fallos, conciliación y mensajes amigables Convertir los principios anteriores en un proceso verificable Poder validar cada punto antes del lanzamiento 3, 4

Orden de lectura sugerido: primero lee la sección 1 para entender la secuencia temporal; luego la sección 2 para aclarar el reparto de responsabilidades; la sección 3 es la parte de implementación. La sección 4 conviene usarla por separado como lista de verificación antes del lanzamiento.


Para saber: términos necesarios antes de entender el límite de presupuesto

Término Explicación breve
Límite blando La cuota se comprueba al iniciar la solicitud; superar esa comprobación no garantiza que el consumo total no rebase el límite
Deducción previa La pasarela deduce primero una parte de la cuota según la estimación y, al terminar la solicitud, liquida según el uso real
Reserva atómica Completar “comprobar el saldo y ocuparlo” con una única operación indivisible, para evitar que solicitudes concurrentes pasen al mismo tiempo
Reserva en tránsito La parte del presupuesto que sigue en estado ocupado en el libro contable cuando la solicitud ya se envió pero aún no se confirmó el coste real
remain_quota Campo de cuota total de una sola vez del token de APIYI; según la documentación, 500000 equivale a $1
Conciliación Cotejar una a una las entradas del registro de la pasarela con el libro contable propio para corregir desviaciones entre estimación y uso real

1 Por qué la cuota de una clave API puede superarse por concurrencia

La documentación de tokens de APIYI lo deja claro: la cuota de la clave es un límite blando y se comprueba al iniciar la solicitud. Por eso, las solicitudes concurrentes, o una única solicitud de alto coste, pueden hacer que el consumo real supere la cuota establecida. Esto es una característica de la propia estructura de facturación de “comprobar al inicio y liquidar al final”, no tiene nada que ver con que alguna plataforma tenga o no un fallo.

Se puede entender con un escenario hipotético (las cifras son ilustrativas, no medidas reales). Una clave de prueba tiene una cuota restante equivalente a $1 y, en el mismo instante, entran 20 solicitudes. Cada solicitud, al comenzar, ve “saldo positivo”, así que todas se dejan pasar. Cuando terminan una tras otra y se liquida según el uso real, el consumo total ya supera con mucho los $1. Incluso sin concurrencia, una solicitud con un contexto largo y una salida grande podría costar más que la cuota restante en una sola vez.

También hay dos malentendidos frecuentes que conviene aclarar:

  • La cuota no se recupera automáticamente cada día. La documentación indica que remain_quota es una cuota total de una sola vez; para “restablecerla cada día”, la aplicación debe escribir su propio script programado.
  • La lista blanca de modelos no equivale a un límite de coste. Solo restringe qué modelos se pueden invocar; no impone límites al número de llamadas de un mismo modelo ni a la escala de cada llamada.

api-key-quota-overspend-three-budget-lines-es-image-1

1.1 Los tres momentos de la cuota de una clave API: comprobación previa, estimación y deducción real

Una llamada tiene tres momentos distintos en términos de facturación, y cada uno responde a una pregunta diferente:

Momento Dónde ocurre Pregunta que responde ¿Puede servir como límite duro?
Comprobación previa a la solicitud Pasarela, al iniciar la solicitud ¿Esta clave tiene cuota disponible en este momento? No, con concurrencia pueden pasar varias a la vez
Estimación y deducción previa Pasarela, según la estimación ¿Cuánto ocupará aproximadamente esta solicitud? No, la estimación difiere del uso real
Deducción real Pasarela, al finalizar la solicitud ¿Cuánto se usó realmente en esta solicitud? Son datos a posteriori, no sirven para la admisión

La explicación de APIYI sobre la deducción previa de cuota es esta: la pasarela hace una deducción previa basada en la estimación y luego liquida según el uso real; este mecanismo no sustituye la reserva atómica del lado del negocio. La deducción previa de la pasarela responde a su propia facturación y no sabe cuánta cuota de prueba le queda hoy a uno de tus usuarios. Por eso, la pregunta “¿este usuario puede enviar otra solicitud?” solo puede responderla el backend de la aplicación.


2 Las tres líneas de presupuesto para las pruebas de AI

Las tres líneas responden a tres tipos de riesgo: el uso excesivo en la capa de la lógica de negocio, el abuso o la filtración de la clave (Key) y el agotamiento del saldo en la capa de la cuenta. El punto API4 «Unrestricted Resource Consumption» del OWASP API Security Top 10 (2023) aborda exactamente el mismo tipo de problema: una interfaz que no impone límites al consumo de recursos genera riesgos tanto para el servicio como para los costos. En las interfaces de AI, el riesgo de costo suele ser el más directo.

2.1 Primera línea de presupuesto: el presupuesto de usuario y del pool de pruebas en el backend de la aplicación

Esta es la única capa que puede hacer control de admisión, y debe gestionar dos niveles:

  • Presupuesto por usuario: la cuota total de cada usuario de prueba, o su cuota diaria. La cuota diaria se restablece con una tarea programada propia de la aplicación, sin depender del gateway.
  • Presupuesto del pool de pruebas: el límite superior compartido por todos los usuarios de prueba. Aunque ningún usuario individual supere su límite, cuando el número de usuarios se dispara, el costo total también debe tener un techo.

Una solicitud debe pasar al mismo tiempo la reserva a nivel de usuario y la reserva a nivel de pool para poder continuar, y ambas deben completarse en la misma operación atómica o en la misma transacción. De lo contrario, aparece la condición de carrera en la que «la reserva del usuario se completó, pero el pool ya está lleno».

Esta capa también debe decidir en el servidor la escala de la solicitud: qué modelo se permite usar, cuál es el límite de max_tokens y cuánto puede medir como máximo la entrada. Estos parámetros no deben recibirse desde el frontend y pasarse tal cual, porque bastaría que el usuario modifique un parámetro para que el importe estimado quede distorsionado.

2.2 Segunda línea de presupuesto: una clave de prueba independiente, su cuota y la lista blanca de modelos

En el lado del gateway se emite una clave (Key) separada para el tráfico de prueba, completamente aislada del tráfico de producción. La responsabilidad de esta Key es limitar la superficie de exposición: si aparece un bug en la contabilidad de la aplicación, o si la clave se filtra, la pérdida queda acotada a la cuota de esta clave y no afecta al negocio de producción.

Al configurarla, hay que tener en cuenta:

  • La cuota se establece como «presupuesto del pool de pruebas + un cierto margen». Debe ser algo superior al presupuesto de pool del lado de la aplicación, para que actúe como red de seguridad; no la fijes igual al presupuesto de pool, porque entonces la reserva de la capa de aplicación queda en papel mojado.
  • La lista blanca de modelos solo debe incluir los modelos habilitados para la prueba. Impide que la clave de prueba se use para llamar modelos caros, pero no limita el número de llamadas ni la escala, así que el límite de escala en el servidor descrito en la sección 2.1 sigue siendo imprescindible.
  • Como la cuota es un límite flexible, esta línea permite «pasarse un poco». Su sentido es mantener el exceso dentro de un rango aceptable; no esperes que garantice cero sobregiro.

La práctica general de separar claves, cuotas y logs por proyecto es otro tema; aquí solo subrayo un punto: una clave separada para el tráfico de prueba.

2.3 Tercera línea de presupuesto: alerta de saldo de la cuenta

La documentación de alertas de saldo de APIYI deja claro que una alerta es solo una notificación y no bloquea las solicitudes. Cuando el saldo cae por debajo del umbral, la alerta se encarga de enviar el mensaje al responsable, y es la persona quien decide si recarga, pausa la entrada de pruebas o investiga un tráfico anómalo.

Al usar esta capa, hay dos recomendaciones:

  • Fija el umbral de alerta según «el consumo máximo durante el tiempo que transcurre desde la detección hasta la resolución», no pongas un número redondo al azar.
  • La alerta debe ir asociada a una acción concreta de respuesta, por ejemplo, dejarlo escrito en el manual de guardia: «al recibir la alerta, primero cerrar el registro de pruebas». Una alerta que solo notifica y no va seguida de ninguna acción es puro trámite.

3 Un libro de concurrencia hipotético: de la reserva atómica a la conciliación

Esta sección presenta un diseño ilustrativo. La estructura de las tablas, los precios y las cifras son hipotéticos: sirven para explicar el flujo y no representan datos medidos de ningún sistema. El flujo consta de cinco pasos:

Verificación y reserva atómica → el servidor bloquea el model y la escala → enviar la petición
      → liquidación / manejo de fallos → conciliación offline y corrección

api-key-quota-overspend-three-budget-lines-es-image-2

3.1 Estructura de tablas y estados del libro de presupuestos

La estructura de datos ilustrativa consta de dos tablas: budgets registra el límite, lo gastado y lo reservado de cada usuario y del pool de prueba; reservations registra cada reserva y su estado.

Estado de la reserva Significado Efecto sobre el «saldo disponible»
reserved Reservada; la petición está en curso Ocupa el importe estimado
settled Se obtuvo el uso real; liquidada Pasa a gastado y libera la diferencia
released Se confirma que la petición no se ejecutó Libera el importe completo
unknown Timeout, desconexión, coste desconocido Sigue ocupando el importe, a la espera de conciliación

El saldo disponible se calcula como limit - spent - reserved, donde reserved incluye las reservas en estado unknown.

3.2 Comprobación atómica y reserva: evitar que dos solicitudes concurrentes pasen a la vez

La clave está en combinar la «comprobación» y la «reserva» en una única sentencia de actualización condicional, y dejar que la base de datos garantice la atomicidad:

-- Ejemplo: solo se reserva si hay saldo suficiente; devuelve el número de filas afectadas
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
  AND limit_amount - spent - reserved >= :estimate;
-- El número de filas afectadas debe ser igual a 2 (tanto el usuario como el pool deben tener éxito); de lo contrario, se revierte la transacción y se rechaza la solicitud

El importe estimado debe tomar el valor máximo: multiplica el número de tokens de entrada por el precio unitario de entrada y suma max_tokens multiplicado por el precio unitario de salida. El uso real normalmente será inferior a esa cifra; al liquidar, basta devolver la diferencia. Mejor reservar un poco de más que quedarse corto.

3.3 Bloqueo del modelo y del tamaño de la tarea en el servidor

Los parámetros de estimación usados para la reserva deben coincidir exactamente con los de la solicitud que realmente se envía. El código de ejemplo es el siguiente:

ALLOWED_TRIAL_MODELS = {"trial-model-a"}   # Ejemplo: modelos habilitados para la prueba
MAX_OUTPUT_TOKENS = 1024                   # Ejemplo: límite máximo impuesto por el servidor
MAX_INPUT_TOKENS = 8000

def build_trial_request(user_input, requested_model):
    model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
        else "trial-model-a"
    input_tokens = count_tokens(user_input)
    if input_tokens > MAX_INPUT_TOKENS:
        raise InputTooLarge()
    estimate = price_in(model) * input_tokens \
             + price_out(model) * MAX_OUTPUT_TOKENS
    return model, MAX_OUTPUT_TOKENS, estimate

El max_tokens y el model que envía el frontend son solo valores de referencia; al final, manda lo que decida el servidor.

3.4 Enviar la solicitud, liquidar y gestionar fallos

Antes de enviar la solicitud, genera un ID de solicitud único y escríbelo en el registro de reserva, para poder emparejarlo después en los logs. Una vez que la solicitud regresa, hay tres casos posibles:

  1. Éxito con usage disponible: calcula el importe según el uso real, spent += actual, reserved -= estimate, y cambia el estado de la reserva a settled.
  2. Fallo claro de no ejecución: por ejemplo, errores de validación de parámetros o de autenticación, que permiten confirmar que la solicitud no llegó a entrar en facturación. En este caso, libera la reserva y cambia el estado a released.
  3. Timeout o conexión interrumpida: puede que la solicitud ya se haya ejecutado aguas arriba y haya generado costo, solo que el resultado no volvió. Aquí no tomes el costo como cero; registra el estado como unknown y mantén la reserva ocupada.

El tercer caso es el que más se presta a errores. Si liberas la reserva en cuanto hay un timeout, equivale a borrar del libro mayor un costo que posiblemente ya ocurrió. En franjas de alta concurrencia y alto índice de timeouts, ese error se acumula sin parar.

3.5 Reconciliación offline: corregir los unknown y las desviaciones de estimación

La consulta de logs de APIYI admite exportación incremental; la documentación la plantea como reconciliación offline, y no como base para autorizar solicitud por solicitud. Por eso la reconciliación debe montarse como tarea programada:

  • Extrae los logs incrementales desde la última reconciliación y emparéjalos con la tabla reservations por ID de solicitud o por ventana temporal.
  • Las reservas en estado unknown que aparezcan en los logs se cambian a settled con el importe real que figure en el log; las que sigan sin aparecer pasado el intervalo acordado se cambian a released.
  • Calcula la distribución de la desviación entre «importe estimado e importe real». Si el importe real se acerca con frecuencia a la estimación o incluso la supera, toca revisar la fórmula de estimación de la sección 3.3.

El resultado de la reconciliación es también la entrada para la tercera línea de presupuesto: si el total del libro mayor y el consumo real de la cuenta no cuadran de forma sostenida, eso en sí mismo ya es una señal de que hace falta una revisión manual.

api-key-quota-overspend-three-budget-lines-es-image-3


4 Verificación de puesta en producción de las líneas de presupuesto y mensajes amigables cuando la cuota es insuficiente

4.1 Lista de verificación de las tres líneas de presupuesto

Elemento de verificación Línea de presupuesto a la que pertenece Método de aceptación
La reserva del usuario y la del pool se completan dentro de la misma transacción Primera línea Someter a pruebas de carga con solicitudes concurrentes y confirmar que lo gastado más lo reservado no supera el límite
El servidor determina model, max_tokens y la longitud de entrada Primera línea Alterar los parámetros del frontend y confirmar que no tienen efecto
Las solicitudes que agotan el tiempo de espera se registran como unknown y mantienen la reserva Primera línea Inyectar una falla de timeout y revisar el estado del libro de cuentas
La tarea de conciliación se ejecuta periódicamente y gestiona los unknown Primera línea Revisar los logs de conciliación y las transiciones de estado
La clave de prueba es independiente y su cuota es ligeramente superior al presupuesto del pool Segunda línea Verificar la configuración de la clave y el valor numérico del presupuesto del pool
La lista blanca de modelos de la clave de prueba solo contiene modelos de prueba Segunda línea Invocar con un modelo que no está en la lista blanca y confirmar que se rechaza
Existe un script de reinicio de la cuota diaria y tiene monitorización Primera y segunda línea Revisar el historial de ejecución de las tareas programadas
El umbral de alerta de saldo se corresponde con el manual de actuación Tercera línea Simular una vez el flujo desde la alerta hasta el cierre del acceso

4.2 Mensajes al usuario cuando la cuota es insuficiente

Cuando falla la reserva, la aplicación debe devolver un error de negocio claro, y no dejar que la solicitud llegue al gateway para luego mostrar un error difícil de comprender. Se recomienda que el mensaje incluya tres elementos de información:

  • Qué ha ocurrido: por ejemplo, «La cuota de prueba de hoy se ha agotado» o «Los cupos de prueba están llenos en este momento». Hay que avisar por separado cuando la cuota del usuario no alcanza y cuando el pool de pruebas está lleno.
  • Cuándo se recupera: si se ha configurado una cuota diaria, indicar la hora de reinicio; si se agotó una cuota de un solo uso, explicar las opciones de mejora de plan disponibles después.
  • Estado actual: se puede mostrar la cuota restante, pero debe calcularse a partir del saldo disponible del libro de cuentas, descontando las reservas en tránsito, para evitar situaciones en las que «aparece saldo disponible pero la solicitud se rechaza».

Una vez completadas estas verificaciones, se puede validar todo el conjunto de líneas de presupuesto con un método sencillo: simular un pico de concurrencia combinado con un timeout del upstream, confirmar que «gastado + reservado en tránsito» en el libro de cuentas nunca queda por debajo del consumo real después de la conciliación, y que el consumo de la clave de prueba no supera de forma significativa su cuota. Solo si se cumplen ambas condiciones se puede considerar que las tres líneas de presupuesto están realmente operativas.


Referencias

  1. Documentación de gestión de tokens de APIYI: límite flexible (soft cap), remain_quota, restablecimiento diario y lista blanca de modelos
    • Enlace: docs.apiyi.com/api-capabilities/token-management
  2. Explicación de la cuota de pre-deducción de APIYI: mecanismo de retención estimada y liquidación posterior
    • Enlace: docs.apiyi.com/faq/pre-deduction-quota
  3. Explicación de las alertas de saldo de APIYI: las alertas solo notifican, no bloquean
    • Enlace: docs.apiyi.com/faq/balance-alerts
  4. Documentación de consulta de logs de APIYI: exportación incremental y conciliación offline
    • Enlace: docs.apiyi.com/api-capabilities/log-query
  5. OWASP API Security Top 10 2023: API4 Consumo de recursos sin restricciones
    • Enlace: api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/

Lo que se prepara de antemano se cumple; lo que no se prepara fracasa. — Libro de los Ritos · Zhongyong

Publicaciones Similares