Controlar custos com cotas de token

Neste documento, descrevemos como definir e gerenciar limites diários no número de tokens de entrada e saída consumidos por funções de IA generativa.

As funções de IA generativa do BigQuery usam modelos de linguagem grandes (LLMs) para realizar análises avançadas nas suas consultas SQL. Como o uso de LLM geralmente é faturado com base no número de tokens processados, o BigQuery fornece cotas de token para ajudar você a gerenciar e controlar os custos associados ao uso dessas funções.

As cotas de token se aplicam às funções SQL do BigQuery projetadas para tarefas de inferência de IA generativa que usam LLMs do Gemini, como as funções AI.CLASSIFY e AI.GENERATE_TEXT. As cotas de token não se aplicam às funções de geração de embedding e pesquisa semântica, como AI.EMBED, que têm estruturas de faturamento diferentes.

Detalhes da cota

O BigQuery fornece as seguintes cotas diárias com base no uso de tokens de LLM. O uso de tokens está diretamente relacionado ao faturamento da Vertex AI para funções de IA generativa do BigQuery que usam modelos do Gemini. Essas cotas são monitoradas globalmente em todas as regiões. As cotas diárias são zeradas à meia-noite do fuso horário do Pacífico.

Essas cotas de tokens controlam o número de tokens de entrada e saída processados pelos LLMs para funções de IA generativa:

  • Tokens de entrada: tokens enviados ao modelo para processamento. Isso inclui tokens no texto do comando, tokens em cache e quaisquer outros dados fornecidos ao modelo como entrada.
  • Tokens de saída: tokens gerados pelo modelo na resposta. Isso inclui tokens no texto gerado (tokens candidatos) e tokens gerados durante as etapas de raciocínio interno (tokens de pensamento).

Cota ID da métrica e da cota Padrão Observações
Tokens de entrada de IA por dia Métrica: bigquery.googleapis.com/quota/query/ai_input_tokens

ID da cota: GenAiInputTokensPerDay
200.000.000.000 Tokens de entrada (incluindo tokens em cache) usados pelo LLM. Aplica-se por dia, por projeto.
Tokens de entrada de IA por dia por usuário Métrica: bigquery.googleapis.com/quota/query/ai_input_tokens

ID da cota: GenAiInputTokensPerUserPerDay
150.000.000.000 Tokens de entrada (incluindo tokens em cache) usados pelo LLM. Válido por dia, por projeto e por usuário.
Tokens de saída de IA por dia Métrica: bigquery.googleapis.com/quota/query/ai_output_tokens

ID da cota: GenAiOutputTokensPerDay
20.000.000.000 Tokens de saída e de pensamento usados pelo LLM. Aplica-se por dia, por projeto.
Tokens de saída de IA por dia por usuário Métrica: bigquery.googleapis.com/quota/query/ai_output_tokens

ID da cota: GenAiOutputTokensPerUserPerDay
15.000.000.000 Tokens de saída e de pensamento usados pelo LLM. Válido por dia, por projeto e por usuário.

Essas cotas são monitoradas em incrementos de milhões de tokens. Embora seja possível definir limites precisos, valores menores que alguns milhões de tokens podem não ser refletidos com precisão perfeita devido à natureza dos relatórios e da agregação de tokens.

Os tokens em cache são contabilizados nas cotas de tokens de entrada.

Antes de começar

Se você usa a Google Cloud CLI, as bibliotecas de cliente da API Cloud Quotas ou o Terraform para gerenciar cotas de token de maneira programática, ative a API Cloud Quotas (cloudquotas.googleapis.com) no projeto do Google Cloud:

gcloud services enable cloudquotas.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

Funções exigidas

Para receber as permissões necessárias para visualizar e atualizar cotas de token, peça ao administrador para conceder a você o papel do IAM de Administrador de cotas do Cloud (roles/cloudquotas.admin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para visualizar e atualizar cotas de token. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para visualizar e atualizar as cotas de token:

  • cloudquotas.quotas.get
  • cloudquotas.quotas.update

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Gerenciar cotas

Dependendo do uso de recursos, talvez você queira aumentar ou diminuir os valores da cota de tokens:

Para conferir e atualizar suas cotas diárias de tokens, selecione uma das seguintes opções:

Console

  1. No console do Google Cloud , acesse a página IAM e administrador > Cotas e limites do sistema.

    Acesse Cotas e limites do sistema

  2. Filtre as cotas inserindo Service: BigQuery API.

  3. Pesquise uma cota específica na lista de cotas, como Tokens de entrada de IA por dia (GenAiInputTokensPerDay), ou classifique a coluna Nome para trazer as cotas de token de IA para o topo da lista.

  4. Clique em more_vert Mais ações > Editar cota.

  5. Para aumentar ou diminuir a cota, no painel Mudanças de cota, insira um novo valor no campo Novo valor e clique em Concluído. A redução de uma cota entra em vigor imediatamente, sem precisar de aprovação.

  6. Clique em Enviar solicitação.

gcloud

Ao gerenciar cotas de token com a CLI gcloud, especifique bigquery.googleapis.com como o nome do serviço e use os seguintes IDs de cota que diferenciam maiúsculas de minúsculas:

  • Tokens de entrada de IA por dia: GenAiInputTokensPerDay
  • Tokens de entrada de IA por dia por usuário: GenAiInputTokensPerUserPerDay
  • Tokens de saída de IA por dia: GenAiOutputTokensPerDay
  • Tokens de saída de IA por dia por usuário: GenAiOutputTokensPerUserPerDay
  1. Opcional: para listar as cotas de token de IA generativa do BigQuery e os valores atuais, use gcloud quotas info list:

    gcloud quotas info list \
        --service=bigquery.googleapis.com \
        --project=PROJECT_ID \
        --filter="quotaId:GenAi*"
    
  2. Para criar ou atualizar as preferências de cota para seus limites diários de tokens, use gcloud quotas preferences update. O exemplo a seguir verifica se já existe uma preferência de cota para cada cota (por exemplo, se ela foi modificada anteriormente no console doGoogle Cloud ) e atualiza ou cria a preferência:

    PROJECT_ID="PROJECT_ID"
    
    for ITEM in \
      "GenAiInputTokensPerDay:INPUT_TOKEN_LIMIT" \
      "GenAiOutputTokensPerDay:OUTPUT_TOKEN_LIMIT"; do
      QUOTA_ID="${ITEM%:*}"
      NEW_LIMIT="${ITEM#*:}"
    
      PREF_ID=$(gcloud quotas preferences list \
        --project="${PROJECT_ID}" \
        --filter="quotaId:${QUOTA_ID}" \
        --format="value(name.basename())")
      PREF_ID="${PREF_ID:-custom-${QUOTA_ID}}"
    
      gcloud quotas preferences update "${PREF_ID}" \
        --project="${PROJECT_ID}" \
        --service=bigquery.googleapis.com \
        --quota-id="${QUOTA_ID}" \
        --preferred-value="${NEW_LIMIT}" \
        --allow-high-percentage-quota-decrease \
        --allow-missing
    done
    

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • INPUT_TOKEN_LIMIT: seu limite diário de tokens de entrada (por exemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: o limite de tokens de saída diário desejado (por exemplo, 8000000).

    Também é possível incluir as seguintes flags opcionais com gcloud quotas preferences update:

    • --allow-quota-decrease-below-usage: permite reduzir um limite de cota abaixo do uso atual do dia.
    • --email: especifica um endereço de e-mail para contato, que é obrigatório ao solicitar um aumento de cota acima do limite padrão.
    • --justification: fornece um motivo para o ajuste da cota.
  3. Para verificar o status das suas preferências de cota, use gcloud quotas preferences list:

    gcloud quotas preferences list \
        --project=PROJECT_ID \
        --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay"
    

    Quando reconciling é false, o valor em grantedValue é aplicado ativamente.

Python

Ao gerenciar cotas de token com a biblioteca de cliente do Cloud Quotas para Python, especifique bigquery.googleapis.com como o nome do serviço e use os seguintes IDs de cota que diferenciam maiúsculas de minúsculas:

  • Tokens de entrada de IA por dia: GenAiInputTokensPerDay
  • Tokens de entrada de IA por dia por usuário: GenAiInputTokensPerUserPerDay
  • Tokens de saída de IA por dia: GenAiOutputTokensPerDay
  • Tokens de saída de IA por dia por usuário: GenAiOutputTokensPerUserPerDay
  1. Instale a biblioteca de cliente do Cloud Quotas para Python:

    pip install --user google-cloud-quotas
    
  2. Para verificar os recursos de preferência de cota atuais e criar ou atualizar seus limites diários de tokens, execute o seguinte script em Python:

    from google.cloud import cloudquotas_v1
    
    PROJECT_ID = "PROJECT_ID"
    QUOTA_LIMITS = {
        "GenAiInputTokensPerDay": INPUT_TOKEN_LIMIT,
        "GenAiOutputTokensPerDay": OUTPUT_TOKEN_LIMIT,
    }
    
    # Initialize the client with quota_project_id (required by the Cloud Quotas API).
    client = cloudquotas_v1.CloudQuotasClient(
        client_options={"quota_project_id": PROJECT_ID}
    )
    parent = f"projects/{PROJECT_ID}/locations/global"
    
    for quota_id, new_limit in QUOTA_LIMITS.items():
        # Check for an existing preference ID, or fall back to a default name.
        list_request = cloudquotas_v1.ListQuotaPreferencesRequest(
            parent=parent,
            filter=f"quotaId:{quota_id}",
        )
        prefs = list(client.list_quota_preferences(request=list_request))
        pref_name = (
            prefs[0].name
            if prefs
            else f"{parent}/quotaPreferences/custom-{quota_id}"
        )
    
        # Update the existing preference or create it if missing (allow_missing=True).
        update_request = cloudquotas_v1.UpdateQuotaPreferenceRequest(
            quota_preference=cloudquotas_v1.QuotaPreference(
                name=pref_name,
                service="bigquery.googleapis.com",
                quota_id=quota_id,
                quota_config=cloudquotas_v1.QuotaConfig(preferred_value=new_limit),
            ),
            allow_missing=True,
            ignore_safety_checks=[
                cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH
            ],
        )
        response = client.update_quota_preference(request=update_request)
        print(f"Quota ID: {quota_id}")
        print(f"Preference Name: {response.name}")
        print(f"Preferred Value: {response.quota_config.preferred_value}")
        print(f"Granted Value: {response.quota_config.granted_value}")
        print(f"Reconciling: {response.reconciling}\n")
    

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • INPUT_TOKEN_LIMIT: o limite diário de tokens de entrada como um número inteiro (por exemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: o limite diário de tokens de saída como um número inteiro (por exemplo, 8000000).

Terraform

Ao gerenciar cotas de token com o Terraform, especifique bigquery.googleapis.com como o nome do serviço e use os seguintes IDs de cota que diferenciam maiúsculas de minúsculas:

  • Tokens de entrada de IA por dia: GenAiInputTokensPerDay
  • Tokens de entrada de IA por dia por usuário: GenAiInputTokensPerUserPerDay
  • Tokens de saída de IA por dia: GenAiOutputTokensPerDay
  • Tokens de saída de IA por dia por usuário: GenAiOutputTokensPerUserPerDay
  1. Verifique se já existem preferências de cota no seu projeto. As Cotas do Cloud permitem apenas um recurso de preferência por cota em um projeto. Se uma cota foi modificada anteriormente no console doGoogle Cloud ou em outra ferramenta, use o ID de preferência atual:

    gcloud quotas preferences list \
        --project=PROJECT_ID \
        --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay" \
        --format="table(quotaId, name.basename():label=PREFERENCE_ID, quotaConfig.preferredValue)"
    
  2. Para configurar os limites diários de tokens na configuração do Terraform (por exemplo, main.tf), use o recurso google_cloud_quotas_quota_preference:

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = ">= 5.30.0"
        }
      }
    }
    
    locals {
      project_id = "PROJECT_ID"
    
      # If you previously modified a quota in the console or another
      # tool, replace `name` with the existing PREFERENCE_ID from
      # `gcloud quotas preferences list` and uncomment the `import` block.
      bq_genai_quotas = {
        GenAiInputTokensPerDay = {
          name            = "custom-GenAiInputTokensPerDay"
          preferred_value = "INPUT_TOKEN_LIMIT" # Default: 200,000,000,000
        }
        GenAiOutputTokensPerDay = {
          name            = "custom-GenAiOutputTokensPerDay"
          preferred_value = "OUTPUT_TOKEN_LIMIT" # Default: 20,000,000,000
        }
      }
    }
    
    # If quota preferences already exist on your project, uncomment this `import`
    # block so that Terraform imports the existing preferences instead of
    # attempting to create duplicates.
    #
    # import {
    #   for_each = local.bq_genai_quotas
    #   to       = google_cloud_quotas_quota_preference.bq_genai[each.key]
    #   id       = "projects/${local.project_id}/locations/global/quotaPreferences/${each.value.name}"
    # }
    
    resource "google_cloud_quotas_quota_preference" "bq_genai" {
      for_each      = local.bq_genai_quotas
      parent        = "projects/${local.project_id}"
      name          = each.value.name
      service       = "bigquery.googleapis.com"
      quota_id      = each.key
      justification = "Managing BigQuery GenAI daily token budget"
    
      # Allows decreases greater than 10% when setting a stricter cost cap.
      ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH"
    
      quota_config {
        preferred_value = each.value.preferred_value
      }
    }
    
    output "quota_status" {
      value = {
        for k, v in google_cloud_quotas_quota_preference.bq_genai : k => {
          preferred_value = v.quota_config[0].preferred_value
          granted_value   = v.quota_config[0].granted_value
          reconciling     = v.reconciling
        }
      }
    }
    

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • INPUT_TOKEN_LIMIT: seu limite diário de tokens de entrada (por exemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: o limite de tokens de saída diário desejado (por exemplo, 8000000).
  3. Inicialize e aplique a configuração do Terraform:

    terraform init
    terraform apply
    

Monitorar cotas

Para evitar falhas inesperadas de consulta, detectar picos de uso e gerenciar custos, monitore o consumo da cota de tokens no console do Google Cloud fazendo o seguinte:

  1. No console do Google Cloud , acesse a página IAM e administrador > Cotas e limites do sistema.

    Acesse Cotas e limites do sistema

  2. Filtre as cotas inserindo Service: BigQuery API.

  3. Confira as colunas Porcentagem de uso atual e Uso atual para verificar o consumo diário de tokens do seu projeto para as cotas Tokens de entrada de IA por dia (GenAiInputTokensPerDay) e Tokens de saída de IA por dia (GenAiOutputTokensPerDay).

  4. Para conferir o histórico de consumo de tokens ao longo do tempo, na linha de uma cota de tokens no nível do projeto, clique em monitoramento Mostrar gráfico de uso.

    O card de uso mostra o limite configurado, a porcentagem de uso atual e a porcentagem de uso de pico, além de um gráfico de consumo histórico para períodos selecionáveis de 7 dias, 14 dias, 30 dias e Personalizado:

    Gráfico de uso da cota de tokens de entrada de IA por dia no console do Google Cloud .

  5. Opcional: configure alertas básicos de uso de cota para receber notificações por e-mail, SMS ou Pub/Sub quando o consumo de tokens atingir uma porcentagem especificada do limite diário.

  6. Opcional: crie gráficos no Cloud Monitoring para visualizar as tendências de uso de tokens e criar painéis personalizados. Para mais informações sobre como monitorar cotas e configurar políticas de alertas, consulte Configurar alertas e monitoramento de cotas.

Para estimar o uso de tokens de entrada antes de executar uma consulta, use a função AI.COUNT_TOKENS. Também é possível ver o número de tokens processados por uma consulta individual na guia Informações do job do painel Resultados da consulta.

Comportamento de aplicação de cotas

O BigQuery monitora o consumo de tokens em vários estágios da execução da consulta:

  • Verificação pré-execução: o BigQuery verifica a cota de tokens disponível antes de executar uma consulta que contém funções de IA generativa. Se a cota relevante (por exemplo, tokens de entrada diários do projeto) já estiver esgotada, a consulta será rejeitada com um erro QuotaExceeded.
  • Durante a execução: se uma consulta estiver em execução e consumir tokens de modo que esgote qualquer uma das cotas configuradas (entrada ou saída, por projeto ou por usuário), as novas chamadas de LLM nessa consulta serão rejeitadas.
    • As linhas restantes que dependem de chamadas de LLM encontram um erro de esgotamento de cota.
    • O resultado da consulta depende do argumento max_error_ratio se usado em funções como AI.IF. Se a proporção de erros permanecer dentro do limite permitido, resultados parciais poderão ser retornados. Caso contrário, toda a consulta vai falhar.
    • As consultas seguintes que tentarem usar funções de IA generativa vão falhar com um erro QuotaExceeded até que a cota diária seja redefinida.

Considerações importantes

  • Cotas globais: as cotas definidas são globais. O uso de tokens é agregado em todas as regiões em que seu projeto opera, fornecendo um mecanismo unificado de controle de custos. Isso evita cobranças inesperadas pelo uso em diferentes regiões.
  • Capacidade de processamento provisionada: se você estiver usando modelos da Gemini Enterprise Agent Platform com capacidade de processamento provisionada, o faturamento não será baseado no uso de tokens. Defina essas cotas de token do BigQuery com um valor alto para evitar o bloqueio desnecessário das consultas.
  • Verificação de segurança de redução de cota: por padrão, a API Cloud Quotas bloqueia qualquer atualização programática que reduza um limite de cota efetivo em mais de 10% de uma só vez. Como os limites de token padrão estão na casa das centenas de bilhões, definir um limite diário mais rígido geralmente excede uma redução de 10% e falha com um erro QUOTA_DECREASE_PERCENTAGE_TOO_HIGH, a menos que você substitua essa verificação de segurança:
    • CLI gcloud: inclua a flag --allow-high-percentage-quota-decrease.
    • Biblioteca de cliente do Python: transmita ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH].
    • Terraform: defina ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH".

A seguir