Visão geral das políticas de gerenciamento de tokens

Visão geral

As políticas de gerenciamento de tokens permitem monitorar e atribuir com precisão o uso de tokens de modelos de linguagem grandes (LLMs) e aplicar orçamentos de tokens compartilhados em todos os agentes e aplicativos de IA da empresa.

Quando os agentes de IA interagem com LLMs, a limitação de taxa de contagem de solicitações, como solicitações por segundo ou por minuto, não é suficiente para controlar os gastos ou a capacidade. Uma única solicitação HTTP para um LLM pode consumir de uma dúzia a mais de 100.000 tokens. Sem a governança no nível do token, um único loop de agente descontrolado pode esgotar as cotas de modelos empresariais compartilhados e causar picos de custo inesperados. Para gerenciar os gastos com IA, as empresas também precisam definir orçamentos de cotas de modelos para usuários e departamentos em toda a organização.

Com as políticas de gerenciamento de tokens, é possível:

• Calcule o uso de tokens de entrada, saída e em cache em todas as interações entre o agente e o modelo.
• Atribua o consumo de tokens e o custo estimado a grupos relevantes para os negócios, aplicativos de IA e identidades de agentes individuais em modelos hospedados na Gemini Enterprise Agent Platform ou em qualquer outra plataforma de hospedagem de modelos.
• Aplique orçamentos de tokens compartilhados em tempo real, emitindo alertas de limite ou retornando HTTP 429 Too Many Requests quando o orçamento de um pool de tokens estiver esgotado.
• Exporte telemetria de observabilidade granular para o Cloud Monitoring e agregue alertas de uso de tokens no Cloud Logging.

Como funciona

A Figura 1 mostra como as políticas de gerenciamento de tokens avaliam as solicitações e respostas de LLM na camada de gateway.

O gerenciamento de tokens usa três recursos de política que trabalham juntos para classificar o tráfego, aplicar orçamentos de tokens e personalizar os cálculos de custo:

• Política de agregação de tokens (TokenAggregationPolicy): classifica as solicitações de agente para modelo recebidas e agrega o consumo de tokens em grupos de tokens lógicos. Os agrupamentos podem ser baseados na hierarquia de recursos (escopo do projeto), aplicativos de IA, agentes individuais, modelos de destino ou tags personalizadas transmitidas em cabeçalhos de solicitação HTTP (incluindo chaves de API).
• Política de orçamento de tokens (TokenBudgetPolicy): define os pools de tokens que aplicam cotas de tokens em um ou mais grupos de tokens identificados pela política de agregação de tokens. Cada pool de tokens especifica uma contagem máxima de tokens, uma janela de redefinição periódica (por hora ou por dia), uma lista opcional de modelos de destino, um limite de alerta e um modo de aplicação.
• Política de custo por token (CostPerTokenPolicy): substitui o preço padrão por token de modelo usado para calcular a métrica gcp.token_management.token.estimated_cost no Monitoring. É possível configurar um desconto percentual no preço padrão do modelo ou taxas personalizadas por token em USD para tokens de entrada, saída e em cache.

Dependência de políticas e ordem de criação

O gerenciamento de tokens aplica uma hierarquia de dependência estrita entre os recursos de política anexados ao mesmo escopo de destino na seguinte ordem:

1. TokenAggregationPolicy precisa ser criado primeiro para classificar as solicitações em grupos de tokens para o escopo de destino. Essa política é o requisito mínimo para ter observabilidade granular no nível do agente sobre o uso de tokens.
2. (Opcional) TokenBudgetPolicy precisa ser configurado para limitar o uso de tokens em relação aos grupos de tokens identificados no TokenAggregationPolicy.
3. (Opcional) CostPerTokenPolicy só pode ser criado depois que um TokenBudgetPolicy correspondente existir para o escopo de destino.

Ao excluir políticas, faça isso na ordem inversa: primeiro CostPerTokenPolicy, depois TokenBudgetPolicy e, em seguida, TokenAggregationPolicy.

Avaliação de regras e correspondência padrão

Em um TokenAggregationPolicy, as regras são avaliadas na ordem em que estão listadas, e a primeira regra correspondente vence:

• Tráfego correspondente:quando uma solicitação de agente corresponde aos critérios de origem de uma regra (aplicativo de IA ou identidade do agente) e aos critérios de destino (cabeçalhos HTTP ou endpoints do provedor de modelos), o uso de tokens é atribuído ao grupo de tokens da regra (tokenGroup).
• Regra catch-all:é possível colocar uma regra com um bloco de correspondência vazio no final da lista de regras para atribuir todo o tráfego restante a um grupo de tokens padrão, como Default.
• Tráfego sem correspondência:se você não incluir uma regra geral e uma solicitação não corresponder a nenhuma regra na política, o consumo de tokens será registrado no grupo unmatched do sistema no Monitoring.
• Tráfego de pool indefinido:se um TokenPool na política de orçamento de tokens (TokenBudgetPolicy) restringir a aplicação a modelos específicos, as solicitações para modelos fora dessa lista não serão bloqueadas e serão registradas com o nome do pool definido como undefined no Monitoring.

Ambientes e modelos compatíveis

As políticas de gerenciamento de tokens são compatíveis com os seguintes Agent Runtimes, implantações de Gateway de Agente e modelos:

Fluxo de aplicação de políticas

Com a limitação de taxa padrão, cada solicitação conta como uma unidade antes de chegar ao back-end. Com as chamadas de LLM, o número total de tokens de entrada e saída só é conhecido depois que o modelo responde. Para lidar com isso, o Gateway de Agente processa cada solicitação em duas fases:

1. Verificação de orçamento para o flight pré-flight (caminho da solicitação):
   • Um agente envia uma solicitação de inferência para um endpoint de LLM pelo Gateway de Agente.
   • O gateway avalia a solicitação em relação ao TokenAggregationPolicy para identificar o tokenGroup correspondente e procura o TokenPool associado no TokenBudgetPolicy.
   • Se o orçamento de tokens do pool estiver esgotado e a aplicação rigorosa estiver ativada, o gateway rejeitará a solicitação imediatamente com um código de status HTTP 429. Se o pool tiver orçamento restante ou estiver configurado para o modo somente alerta, o gateway encaminhará a solicitação para o LLM.
2. Reconciliação de tokens e telemetria (caminho de resposta):
   • Quando o endpoint do LLM retorna a resposta de conclusão, o gateway extrai as contagens reais de tokens input, output e cached do payload de resposta.
   • O gerenciamento de tokens reconcilia os tokens consumidos com a cota de maxTokens do pool.
   • Se o consumo atualizado ultrapassar o limite de aviso ou atingir 100% do orçamento, o gateway vai gravar um aviso no Logging.
   • O gateway exporta métricas de consumo de tokens por agente (gen_ai.client.token.usage) e custo estimado de tokens (gcp.token_management.token.estimated_cost) para o Monitoring.

As contagens de tokens de saída são registradas somente após a conclusão de uma resposta do LLM. Como resultado, as solicitações simultâneas admitidas antes que um pool atinja maxTokens podem exceder o limite antes que as solicitações posteriores sejam bloqueadas com HTTP 429. Para evitar limitações inesperadas, defina um alertThreshold, como 0.6 ou 0.8, para testar novas políticas com validateOnly: true antes de ativar a aplicação estrita.

Controles de governança relacionados

A tabela a seguir mostra como as políticas de gerenciamento de tokens funcionam com outros controles de governança e da plataforma de agentes do Cloud de Confiance :

Limitações

As políticas de gerenciamento de tokens têm as seguintes limitações:

• É possível anexar no máximo um TokenAggregationPolicy, um TokenBudgetPolicy e um CostPerTokenPolicy a um determinado escopo de destino do projeto.
• Cada TokenAggregationPolicy aceita até 10 regras de agregação (rules), e cada TokenBudgetPolicy aceita até 10 pools de tokens.
• Os pools de tokens são redefinidos a cada HOURLY e DAILY. Os orçamentos diários são redefinidos à meia-noite, horário do Pacífico.
• O Logging gera entradas de registro somente quando um pool de tokens ultrapassa o alertThreshold configurado ou atinge 100% de maxTokens (token_management_alert_logs).