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_tokensID 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_tokensID 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_tokensID 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_tokensID 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:
- Se as cargas de trabalho exigirem mais capacidade do que o limite padrão, solicite um aumento de cota.
- Se você quiser limitar o uso de forma mais rigorosa para evitar estouros de orçamento, crie uma substituição de cota para limitar o uso.
Para conferir e atualizar suas cotas diárias de tokens, selecione uma das seguintes opções:
Console
No console do Google Cloud , acesse a página IAM e administrador > Cotas e limites do sistema.
Filtre as cotas inserindo
Service: BigQuery API.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.Clique em more_vert Mais ações > Editar cota.
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.
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
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*"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 doneSubstitua:
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.
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 emgrantedValueé 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
Instale a biblioteca de cliente do Cloud Quotas para Python:
pip install --user google-cloud-quotasPara 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
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)"Para configurar os limites diários de tokens na configuração do Terraform (por exemplo,
main.tf), use o recursogoogle_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).
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:
No console do Google Cloud , acesse a página IAM e administrador > Cotas e limites do sistema.
Filtre as cotas inserindo
Service: BigQuery API.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).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:
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.
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_ratiose usado em funções comoAI.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
QuotaExceededaté 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".
- CLI gcloud: inclua a flag
A seguir
- Saiba como otimizar os custos das funções de IA.
- Leia uma visão geral da IA generativa no BigQuery.
- Saiba como configurar alertas de cota e monitoramento.