Gestion de cuotas

Los costos de IA pueden crecer rapidamente sin control. El sistema de cuotas de Almirant te da las barreras de proteccion que necesitas para mantener los gastos bajo control sin tener que microgestionar cada ejecucion.

Que son las cuotas

Las cuotas son limites configurables que definen cuanto puede consumir tu organizacion en terminos de:

Metrica	Descripcion
Tokens	Cantidad maxima de tokens que pueden procesarse
Costo USD	Gasto maximo en dolares estadounidenses
Solicitudes	Numero maximo de llamadas a la API del proveedor

Puedes configurar cuotas independientes para cada proveedor de IA (OpenAI, Anthropic) y definir diferentes limites segun el periodo de tiempo.

Tipos de periodo

Las cuotas se configuran por periodo, lo que te permite establecer limites que se ajusten a tu presupuesto:

Tipo	Descripcion	Caso de uso
Diario	Se reinicia cada 24 horas a medianoche (UTC)	Control granular para equipos con uso intensivo
Semanal	Se reinicia cada lunes a medianoche (UTC)	Balance entre flexibilidad y control
Mensual	Se reinicia el primer dia de cada mes	Alineacion con ciclos de facturacion

tip

Recomendamos comenzar con cuotas mensuales alineadas a tu presupuesto de IA, y agregar cuotas diarias si detectas picos de consumo que afectan la disponibilidad para todo el equipo.

Configurar cuotas

Para configurar las cuotas de tu organizacion:

1. Accede a Configuracion > Cuotas de IA (o Quota Management).
2. Selecciona el proveedor que deseas configurar.
3. Define los limites para cada tipo de periodo:
   • Tokens maximos: Limite de tokens por periodo
   • Costo maximo USD: Limite de gasto en dolares
   • Solicitudes maximas: Limite de llamadas a la API
4. Activa o desactiva la cuota con el toggle Activo.
5. Guarda los cambios.

Configuracion por proveedor

Cada proveedor puede tener configuraciones independientes. Esto es util cuando:

• Tienes diferentes presupuestos asignados a cada proveedor
• Quieres limitar un proveedor mas estrictamente mientras pruebas otro
• Necesitas controlar costos de modelos premium (como o1) separadamente

Ejemplo de configuracion:

OpenAI:
  - Mensual: 500,000 tokens / $50 USD / 1,000 solicitudes
  - Diario: 50,000 tokens / $10 USD / 200 solicitudes

Anthropic:
  - Mensual: 300,000 tokens / $30 USD / 500 solicitudes

Sistema de alertas

Almirant te notifica proactivamente cuando tu consumo se acerca a los limites configurados. Las alertas se disparan en los siguientes umbrales:

Tipo de alerta	Umbral	Accion recomendada
warning_75	75% del limite	Monitorea el consumo de cerca
warning_80	80% del limite	Considera reducir operaciones no criticas
warning_90	90% del limite	Prepara ampliacion de cuota si es necesario
exceeded	100% del limite	Cuota agotada, nuevas operaciones bloqueadas

Recibir alertas

Las alertas se envian a:

• Administradores de organizacion: Reciben todas las alertas por correo electronico
• Panel de configuracion: Las alertas activas aparecen en la seccion de cuotas
• Dashboard: Indicador visual cuando hay alertas pendientes

Reconocer alertas

Puedes reconocer una alerta para indicar que ya tomaste accion:

1. Ve a Configuracion > Cuotas de IA.
2. En la seccion Alertas activas, haz clic en la alerta.
3. Selecciona Reconocer para marcarla como atendida.

Las alertas reconocidas no se vuelven a mostrar para el mismo periodo, pero una nueva alerta se generara si se alcanza el siguiente umbral.

Ver el uso actual

La pagina de gestion de cuotas muestra un resumen del consumo actual por proveedor y periodo:

Campo	Descripcion
Proveedor	OpenAI o Anthropic
Tipo de periodo	Diario, semanal o mensual
Tokens usados / maximos	Consumo actual vs limite
Costo usado / maximo	Gasto actual vs limite
Solicitudes usadas / maximas	Llamadas actuales vs limite
Porcentaje	Indicador visual del consumo
Fin del periodo	Cuando se reinicia la cuota

info

El porcentaje mostrado corresponde a la metrica mas alta entre tokens, costo y solicitudes. Esto asegura que veas el indicador mas restrictivo.

Reanudacion automatica

Cuando un periodo termina, las cuotas se reinician automaticamente:

1. Reinicio de contadores: Los contadores de tokens, costo y solicitudes vuelven a cero.
2. Desbloqueo de operaciones: Las operaciones bloqueadas pueden reanudarse.
3. Limpieza de alertas: Las alertas del periodo anterior se archivan.

No es necesario realizar ninguna accion manual para que la cuota se renueve.

Comportamiento de operaciones bloqueadas

Cuando la cuota se agota:

• AI Planning: Las nuevas conversaciones muestran un mensaje de cuota agotada
• Agentes IA: Los jobs quedan en estado pending y se procesan automaticamente cuando hay cuota disponible
• Jobs en ejecucion: No se interrumpen, pero no pueden iniciar nuevas llamadas al proveedor

Cuando la cuota se renueva, los jobs pendientes comienzan a procesarse en orden FIFO (primero en entrar, primero en salir).

Buenas practicas

• Configura alertas tempranas -- El umbral del 75% te da tiempo para reaccionar antes de quedarte sin cuota.
• Usa cuotas diarias para control granular -- Si tu equipo consume mucho en un dia, una cuota diaria evita dejar sin servicio al resto de la semana.
• Alinea cuotas mensuales con facturacion -- Configura limites que coincidan con tu presupuesto mensual de IA.
• Revisa el desglose por proyecto -- Identifica proyectos con alto consumo para optimizar o ajustar expectativas.
• Reserva margen para urgencias -- No configures cuotas al 100% del presupuesto; deja un 10-15% de margen.

Para Developers

Herramientas MCP

Los siguientes tools estan disponibles via MCP para consultar y verificar cuotas:

Tool	Descripcion	Parametros principales
check_quota	Verifica si hay cuota disponible para una operacion	organizationId, provider, estimatedTokens
get_quota_usage	Obtiene el detalle de consumo por proveedor y periodo	organizationId, provider, periodType

Ejemplo: Verificar cuota antes de una operacion

Tool: check_quota
Parametros:
  organizationId: "uuid-de-la-organizacion"
  provider: "openai"
  estimatedTokens: 10000

Respuesta cuando hay cuota disponible:

{
  "available": true,
  "provider": "openai",
  "remainingTokens": 45000,
  "remainingCostUsd": 12.50,
  "remainingRequests": 150,
  "periodEnd": "2024-02-01T00:00:00Z"
}

Respuesta cuando no hay cuota:

{
  "available": false,
  "provider": "openai",
  "remainingTokens": 0,
  "reason": "exceeded",
  "periodEnd": "2024-02-01T00:00:00Z"
}

Ejemplo: Consultar uso detallado

Tool: get_quota_usage
Parametros:
  organizationId: "uuid-de-la-organizacion"
  provider: "openai"
  periodType: "monthly"

Respuesta:

{
  "provider": "openai",
  "periodType": "monthly",
  "maxTokens": 500000,
  "maxCostUsd": 50.00,
  "maxRequests": 1000,
  "usedTokens": 125000,
  "usedCostUsd": 12.50,
  "usedRequests": 250,
  "percentTokens": 25,
  "percentCost": 25,
  "percentRequests": 25,
  "periodStart": "2024-01-01T00:00:00Z",
  "periodEnd": "2024-02-01T00:00:00Z"
}

Modelo de datos

Para referencia tecnica, estos son los tipos principales del sistema de cuotas:

QuotaConfig

Campo	Tipo	Descripcion
id	UUID	Identificador unico de la configuracion
provider	string	Proveedor de IA (openai, anthropic)
quotaType	QuotaType	Tipo de periodo (daily, weekly, monthly)
maxTokens	number	Limite de tokens
maxCostUsd	number	Limite de costo en USD
maxRequests	number	Limite de solicitudes
isActive	boolean	Si la cuota esta activa

UsageSummaryItem

Campo	Tipo	Descripcion
provider	string	Proveedor de IA
periodType	QuotaType	Tipo de periodo
maxTokens	number	Limite configurado
usedTokens	number	Tokens consumidos
percentTokens	number	Porcentaje de uso (0-100)
maxCostUsd	number	Limite de costo
usedCostUsd	number	Costo consumido
percentCost	number	Porcentaje de costo
maxRequests	number	Limite de solicitudes
usedRequests	number	Solicitudes realizadas
percentRequests	number	Porcentaje de solicitudes
periodEnd	DateTime	Fin del periodo actual

QuotaAlert

Campo	Tipo	Descripcion
id	UUID	Identificador de la alerta
providerQuotaId	UUID	Referencia a QuotaConfig
alertType	AlertType	Tipo de alerta (warning_75, warning_80, warning_90, exceeded)
periodStart	DateTime	Inicio del periodo de la alerta
message	string	Mensaje descriptivo
acknowledgedAt	DateTime	Fecha de reconocimiento (null si no reconocida)