Gerenciamento de cotas

Os custos de IA podem crescer rapidamente sem controle. O sistema de cotas do Almirant oferece as proteções necessárias para manter os gastos sob controle sem precisar microgerenciar cada execução.

O que são cotas

Cotas são limites configuráveis que definem quanto a sua organização pode consumir em termos de:

Métrica	Descrição
Tokens	Quantidade máxima de tokens que podem ser processados
Custo em USD	Gasto máximo em dólares americanos
Solicitações	Número máximo de chamadas à API do provedor

Você pode configurar cotas independentes para cada provedor de IA (OpenAI, Anthropic) e definir limites diferentes conforme o período.

Tipos de período

As cotas são configuradas por período, o que permite estabelecer limites adequados ao seu orçamento:

Tipo	Descrição	Caso de uso
Diário	É redefinida a cada 24 horas, à meia-noite (UTC)	Controle detalhado para equipes com uso intenso
Semanal	É redefinida toda segunda-feira, à meia-noite (UTC)	Equilíbrio entre flexibilidade e controle
Mensal	É redefinida no primeiro dia de cada mês	Alinhamento com ciclos de cobrança

dica

Recomendamos começar com cotas mensais alinhadas ao seu orçamento de IA e adicionar cotas diárias se identificar picos de consumo que afetam a disponibilidade para toda a equipe.

Configurar cotas

Para configurar as cotas da sua organização:

1. Acesse Configurações > Cotas de IA (ou Quota Management).
2. Selecione o provedor que deseja configurar.
3. Defina os limites para cada tipo de período:
   • Máximo de tokens: limite de tokens por período
   • Custo máximo em USD: limite de gastos em dólares
   • Máximo de solicitações: limite de chamadas à API
4. Ative ou desative a cota com o toggle Ativo.
5. Salve as alterações.

Configuração por provedor

Cada provedor pode ter configurações independentes. Isso é útil quando:

• Você tem orçamentos diferentes atribuídos a cada provedor.
• Deseja limitar um provedor de forma mais rigorosa enquanto testa outro.
• Precisa controlar separadamente os custos de modelos premium, como o1.

Exemplo de configuração:

OpenAI:
  - Mensal: 500,000 tokens / $50 USD / 1,000 solicitações
  - Diário: 50,000 tokens / $10 USD / 200 solicitações

Anthropic:
  - Mensal: 300,000 tokens / $30 USD / 500 solicitações

Sistema de alertas

O Almirant notifica você proativamente quando o consumo se aproxima dos limites configurados. Os alertas são disparados nos seguintes limites:

Tipo de alerta	Limite	Ação recomendada
warning_75	75% do limite	Monitore o consumo de perto
warning_80	80% do limite	Considere reduzir operações não críticas
warning_90	90% do limite	Prepare uma ampliação da cota se necessário
exceeded	100% do limite	Cota esgotada; novas operações bloqueadas

Receber alertas

Os alertas são enviados para:

• Administradores da organização: recebem todos os alertas por e-mail.
• Painel de configurações: os alertas ativos aparecem na seção de cotas.
• Dashboard: indicador visual quando há alertas pendentes.

Reconhecer alertas

Você pode reconhecer um alerta para indicar que já tomou uma ação:

1. Acesse Configurações > Cotas de IA.
2. Na seção Alertas ativos, clique no alerta.
3. Selecione Reconhecer para marcá-lo como tratado.

Os alertas reconhecidos não voltam a ser exibidos no mesmo período, mas um novo alerta será gerado se o próximo limite for atingido.

Ver o uso atual

A página de gerenciamento de cotas mostra um resumo do consumo atual por provedor e período:

Campo	Descrição
Provedor	OpenAI ou Anthropic
Tipo de período	Diário, semanal ou mensal
Tokens usados / máximos	Consumo atual em relação ao limite
Custo usado / máximo	Gasto atual em relação ao limite
Solicitações usadas / máximas	Chamadas atuais em relação ao limite
Percentual	Indicador visual de consumo
Fim do período	Quando a cota é redefinida

informação

O percentual exibido corresponde à métrica mais alta entre tokens, custo e solicitações. Isso garante que você veja o indicador mais restritivo.

Redefinição automática

Quando um período termina, as cotas são redefinidas automaticamente:

1. Redefinição de contadores: os contadores de tokens, custo e solicitações voltam a zero.
2. Desbloqueio de operações: as operações bloqueadas podem ser retomadas.
3. Limpeza de alertas: os alertas do período anterior são arquivados.

Não é necessário realizar nenhuma ação manual para renovar a cota.

Comportamento das operações bloqueadas

Quando a cota se esgota:

• AI Planning: novas conversas exibem uma mensagem de cota esgotada.
• Agentes de IA: os jobs ficam no estado pending e são processados automaticamente quando houver cota disponível.
• Jobs em execução: não são interrompidos, mas não podem iniciar novas chamadas ao provedor.

Quando a cota é renovada, os jobs pendentes começam a ser processados em ordem FIFO (primeiro a entrar, primeiro a sair).

Boas práticas

• Configure alertas antecipados: o limite de 75% dá tempo para reagir antes que a cota se esgote.
• Use cotas diárias para controle detalhado: se a equipe consome muito em um dia, uma cota diária evita deixar o restante da semana sem serviço.
• Alinhe as cotas mensais com a cobrança: configure limites que correspondam ao seu orçamento mensal de IA.
• Revise o detalhamento por projeto: identifique projetos com alto consumo para otimizar ou ajustar as expectativas.
• Reserve margem para urgências: não configure cotas em 100% do orçamento; deixe uma margem de 10 a 15%.

Para desenvolvedores

Ferramentas MCP

As seguintes tools estão disponíveis via MCP para consultar e verificar cotas:

Tool	Descrição	Parâmetros principais
check_quota	Verifica se há cota disponível para uma operação	organizationId, provider, estimatedTokens
get_quota_usage	Obtém o detalhamento do consumo por provedor e período	organizationId, provider, periodType

Exemplo: verificar a cota antes de uma operação

Tool: check_quota
Parâmetros:
  organizationId: "uuid-da-organização"
  provider: "openai"
  estimatedTokens: 10000

Resposta quando há cota disponível:

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

Resposta quando não há cota:

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

Exemplo: consultar o uso detalhado

Tool: get_quota_usage
Parâmetros:
  organizationId: "uuid-da-organização"
  provider: "openai"
  periodType: "monthly"

Resposta:

{
  "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 dados

Como referência técnica, estes são os tipos principais do sistema de cotas:

QuotaConfig

Campo	Tipo	Descrição
id	UUID	Identificador único da configuração
provider	string	Provedor de IA (openai, anthropic)
quotaType	QuotaType	Tipo de período (daily, weekly, monthly)
maxTokens	number	Limite de tokens
maxCostUsd	number	Limite de custo em USD
maxRequests	number	Limite de solicitações
isActive	boolean	Indica se a cota está ativa

UsageSummaryItem

Campo	Tipo	Descrição
provider	string	Provedor de IA
periodType	QuotaType	Tipo de período
maxTokens	number	Limite configurado
usedTokens	number	Tokens consumidos
percentTokens	number	Percentual de uso (0-100)
maxCostUsd	number	Limite de custo
usedCostUsd	number	Custo consumido
percentCost	number	Percentual de custo
maxRequests	number	Limite de solicitações
usedRequests	number	Solicitações realizadas
percentRequests	number	Percentual de solicitações
periodEnd	DateTime	Fim do período atual

QuotaAlert

Campo	Tipo	Descrição
id	UUID	Identificador do alerta
providerQuotaId	UUID	Referência a QuotaConfig
alertType	AlertType	Tipo de alerta (warning_75, warning_80, warning_90, exceeded)
periodStart	DateTime	Início do período do alerta
message	string	Mensagem descritiva
acknowledgedAt	DateTime	Data de reconhecimento (null se não for reconhecido)