Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Controlla i costi con le quote di token

Questo documento descrive come definire e gestire i limiti giornalieri sul numero di token di input e output utilizzati dalle funzioni AI generative.

Le funzioni AI generative di BigQuery utilizzano modelli linguistici di grandi dimensioni (LLM) per eseguire analisi avanzate all'interno delle query SQL. Poiché l'utilizzo degli LLM viene generalmente fatturato in base al numero di token elaborati, BigQuery fornisce quote di token per aiutarti a gestire e controllare i costi associati all'utilizzo di queste funzioni.

Le quote di token si applicano alle funzioni SQL di BigQuery progettate per le attività di inferenza dell'AI generativa che utilizzano gli LLM Gemini, come le funzioni AI.CLASSIFY e AI.GENERATE_TEXT. Le quote di token non si applicano alle funzioni di generazione di embedding e ricerca semantica, come AI.EMBED, che hanno strutture di fatturazione diverse.

Dettagli quota

BigQuery fornisce le seguenti quote giornaliere in base all'utilizzo dei token LLM. L'utilizzo dei token è direttamente correlato alla fatturazione di Vertex AI per le funzioni AI generative di BigQuery che utilizzano i modelli Gemini. Queste quote vengono monitorate a livello globale in tutte le regioni. Le quote giornaliere vengono reimpostate alla mezzanotte del fuso orario del Pacifico.

Queste quote di token regolano il numero di token di input e output elaborati dagli LLM per le funzioni di AI generativa:

Token di input: token inviati al modello per l'elaborazione. Sono inclusi i token nel testo del prompt e qualsiasi altro dato fornito al modello come input.
Token di output: token generati dal modello nella sua risposta. Sono inclusi i token nel testo generato (token candidati) e i token generati durante i passaggi di ragionamento interni (token di pensiero).

Quota	ID metrica e quota	Predefinito	Note
Token di input AI al giorno	Metrica: `bigquery.googleapis.com/quota/query/ai_input_tokens` ID quota: `GenAiInputTokensPerDay`	200.000.000.000	Token di input utilizzati dall'LLM. Si applica al giorno, per progetto.
Token di input AI al giorno per utente	Metrica: `bigquery.googleapis.com/quota/query/ai_input_tokens` ID quota: `GenAiInputTokensPerUserPerDay`	150.000.000.000	Token di input utilizzati dall'LLM. Si applica al giorno, per progetto, per utente.
Token di output dell'AI al giorno	Metrica: `bigquery.googleapis.com/quota/query/ai_output_tokens` ID quota: `GenAiOutputTokensPerDay`	20.000.000.000	Token di output e di pensiero utilizzati dall'LLM. Si applica al giorno, per progetto.
Token di output AI al giorno per utente	Metrica: `bigquery.googleapis.com/quota/query/ai_output_tokens` ID quota: `GenAiOutputTokensPerUserPerDay`	15.000.000.000	Token di output e di pensiero utilizzati dall'LLM. Si applica al giorno, per progetto, per utente.

Queste quote vengono monitorate in incrementi di milioni di token. Sebbene tu possa impostare limiti precisi, i valori inferiori a qualche milione di token potrebbero non essere riportati con precisione perfetta a causa della natura dei report e dell'aggregazione dei token.

I token memorizzati nella cache non vengono conteggiati ai fini delle quote.

Prima di iniziare

Se utilizzi Google Cloud CLI, le librerie client dell'API Cloud Quotas o Terraform per gestire le quote di token in modo programmatico, abilita l'API Cloud Quotas (cloudquotas.googleapis.com) nel tuo progetto Google Cloud:

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

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare e aggiornare le quote di token, chiedi all'amministratore di concederti il ruolo IAM Cloud Quotas Admin (roles/cloudquotas.admin) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per visualizzare e aggiornare le quote di token. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per visualizzare e aggiornare le quote di token sono necessarie le seguenti autorizzazioni:

cloudquotas.quotas.get
cloudquotas.quotas.update

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Gestisci quote

A seconda dell'utilizzo delle risorse, potresti voler visualizzare o modificare i valori della quota di token:

Se i tuoi workload richiedono una capacità superiore al limite predefinito, puoi richiedere un aumento della quota.
Se vuoi applicare un limite più rigido all'utilizzo per evitare di superare il budget, puoi creare un override della quota per limitare l'utilizzo.

Per visualizzare e aggiornare le quote di token giornaliere, seleziona una delle seguenti opzioni:

Console

Nella console Google Cloud , vai alla pagina IAM e amministrazione > Quote e limiti di sistema.

Vai a Quote e Limiti di sistema
Filtra le quote inserendo Service: BigQuery API.
Cerca una quota specifica nell'elenco delle quote, ad esempio Token di input AI al giorno (GenAiInputTokensPerDay), oppure ordina la colonna Nome per visualizzare le quote dei token AI in cima all'elenco.
Fai clic su more_vert Altre azioni > Modifica quota.
Per aumentare o diminuire la quota, nel riquadro Modifiche alla quota, inserisci un nuovo valore nel campo Nuovo valore, quindi fai clic su Fine. La riduzione di una quota ha effetto immediato senza richiedere l'approvazione.
Fai clic su Invia richiesta.

gcloud

Quando gestisci le quote di token con gcloud CLI, specifica bigquery.googleapis.com come nome del servizio e utilizza i seguenti ID quota sensibili alle maiuscole:

Token di input AI al giorno: GenAiInputTokensPerDay
Token di input AI al giorno per utente: GenAiInputTokensPerUserPerDay
Token di output dell'AI al giorno: GenAiOutputTokensPerDay
Token di output dell'AI al giorno per utente: GenAiOutputTokensPerUserPerDay

(Facoltativo) Per elencare le quote dei token di AI generativa di BigQuery e i relativi valori attuali, utilizza gcloud quotas info list:

gcloud quotas info list \
    --service=bigquery.googleapis.com \
    --project=PROJECT_ID \
    --filter="quotaId:GenAi*"

Per creare o aggiornare le preferenze di quota per i limiti di token giornalieri, utilizza gcloud quotas preferences update. L'esempio seguente verifica se esiste già una preferenza di quota per ogni quota (ad esempio, se è stata modificata in precedenza nella consoleGoogle Cloud ) e aggiorna o crea la preferenza:
```
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
```
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- INPUT_TOKEN_LIMIT: il limite di token di input giornaliero target (ad esempio 754000000).
- OUTPUT_TOKEN_LIMIT: il limite di token di output giornaliero target (ad esempio, 8000000).
Puoi anche includere i seguenti flag facoltativi con gcloud quotas preferences update:
- --allow-quota-decrease-below-usage: consente di abbassare un limite di quota al di sotto dell'utilizzo attuale per il giorno.
- --email: specifica un indirizzo email di contatto, obbligatorio quando richiedi un aumento della quota oltre il limite predefinito.
- --justification: fornisce un motivo per l'aggiustamento della quota.
Per verificare lo stato delle preferenze di quota, utilizza gcloud quotas preferences list:
```
gcloud quotas preferences list \
    --project=PROJECT_ID \
    --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay"
```
Quando reconciling è false, il valore in grantedValue viene applicato attivamente.

Python

Quando gestisci le quote di token con la libreria client di Cloud Quotas per Python, specifica bigquery.googleapis.com come nome del servizio e utilizza i seguenti ID quota sensibili alle maiuscole:

Token di input AI al giorno: GenAiInputTokensPerDay
Token di input AI al giorno per utente: GenAiInputTokensPerUserPerDay
Token di output dell'AI al giorno: GenAiOutputTokensPerDay
Token di output dell'AI al giorno per utente: GenAiOutputTokensPerUserPerDay

Installa la libreria client di Cloud Quotas per Python:
```
pip install --user google-cloud-quotas
```

Per verificare la presenza di risorse di preferenza di quota esistenti e creare o aggiornare i limiti di token giornalieri, esegui questo script 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")

Sostituisci quanto segue:

PROJECT_ID: il tuo ID progetto Google Cloud .
INPUT_TOKEN_LIMIT: il limite di token di input giornaliero target come numero intero (ad esempio 754000000).
OUTPUT_TOKEN_LIMIT: il limite di token di output giornaliero target come numero intero (ad esempio, 8000000).

Terraform

Quando gestisci le quote di token con Terraform, specifica bigquery.googleapis.com come nome del servizio e utilizza i seguenti ID quota sensibili alle maiuscole:

Token di input AI al giorno: GenAiInputTokensPerDay
Token di input AI al giorno per utente: GenAiInputTokensPerUserPerDay
Token di output dell'AI al giorno: GenAiOutputTokensPerDay
Token di output dell'AI al giorno per utente: GenAiOutputTokensPerUserPerDay

Controlla se nel progetto esistono già preferenze relative alle quote. Cloud Quotas consente una sola risorsa di preferenza per quota in un progetto. Se una quota è stata modificata in precedenza nella consoleGoogle Cloud o in un altro strumento, devi utilizzare l'ID preferenza esistente:
```
gcloud quotas preferences list \
    --project=PROJECT_ID \
    --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay" \
    --format="table(quotaId, name.basename():label=PREFERENCE_ID, quotaConfig.preferredValue)"
```

Per configurare i limiti giornalieri di token nella configurazione Terraform (ad esempio main.tf), utilizza la risorsa 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
    }
  }
}

Sostituisci quanto segue:

PROJECT_ID: il tuo ID progetto Google Cloud .
INPUT_TOKEN_LIMIT: il limite di token di input giornaliero target (ad esempio 754000000).
OUTPUT_TOKEN_LIMIT: il limite di token di output giornaliero target (ad esempio, 8000000).

Inizializza e applica la configurazione Terraform:
```
terraform init
terraform apply
```

Monitora le quote

Per evitare errori imprevisti delle query, rilevare picchi di utilizzo e gestire i costi, monitora il consumo della quota di token nella console Google Cloud procedendo come segue:

Nella console Google Cloud , vai alla pagina IAM e amministrazione > Quote e limiti di sistema.

Vai a Quote e Limiti di sistema
Filtra le quote inserendo Service: BigQuery API.
Visualizza le colonne Percentuale di utilizzo corrente e Utilizzo corrente per verificare il consumo giornaliero di token del tuo progetto per le quote di Token di input AI al giorno (GenAiInputTokensPerDay) e Token di output AI al giorno (GenAiOutputTokensPerDay).
Per visualizzare il consumo storico dei token nel tempo, nella riga di una quota di token a livello di progetto, fai clic su monitoring Mostra grafico di utilizzo.

La scheda Utilizzo mostra il limite configurato, la percentuale di utilizzo attuale e la percentuale di utilizzo di picco, insieme a un grafico del consumo storico per intervalli di tempo selezionabili di 7 giorni, 14 giorni, 30 giorni e Personalizzato:
(Facoltativo) Configura avvisi di base sull'utilizzo della quota per ricevere notifiche via email, SMS o Pub/Sub quando il consumo di token raggiunge una percentuale specificata del limite giornaliero.
(Facoltativo) Crea grafici in Cloud Monitoring per visualizzare le tendenze di utilizzo dei token e creare dashboard personalizzate. Per saperne di più sul monitoraggio delle quote e sulla configurazione delle policy di avviso, consulta Configura il monitoraggio e gli avvisi relativi alla quota.

Per stimare l'utilizzo dei token di input prima di eseguire una query, utilizza la funzione AI.COUNT_TOKENS. Puoi anche visualizzare il numero di token elaborati da una singola query nella scheda Informazioni job del riquadro Risultati delle query.

Comportamento di applicazione della quota

BigQuery monitora il consumo di token in più fasi dell'esecuzione delle query:

Controllo pre-esecuzione: BigQuery controlla la quota di token disponibile prima di eseguire una query che contiene funzioni AI generative. Se la quota pertinente (ad esempio, i token di input giornalieri del progetto) è già esaurita, la query viene rifiutata con un errore QuotaExceeded.
Durante l'esecuzione: se una query è in esecuzione e consuma token in modo da esaurire una delle quote configurate (input o output, per progetto o per utente), le nuove chiamate LLM all'interno della query vengono rifiutate.
- Le righe rimanenti che dipendono dalle chiamate LLM riscontrano un errore di esaurimento della quota.
- Il risultato della query dipende dall'argomento max_error_ratio se utilizzato in funzioni come AI.IF. Se il rapporto di errore rimane entro il limite consentito, potrebbero essere restituiti risultati parziali. In caso contrario, l'intera query non va a buon fine.
- Le query successive che tentano di utilizzare le funzioni AI generative non riusciranno e restituiranno un errore QuotaExceeded fino alla reimpostazione della quota giornaliera.

Considerazioni importanti

Quote globali: le quote definite sono globali. L'utilizzo dei token viene aggregato in tutte le regioni in cui opera il progetto, fornendo un meccanismo di controllo dei costi unificato. In questo modo eviti addebiti imprevisti per l'utilizzo in regioni diverse.
Throughput riservato: se utilizzi i modelli di Gemini Enterprise Agent Platform con throughput riservato, la fatturazione non si basa sull'utilizzo dei token. Devi impostare queste quote di token BigQuery su un valore elevato per evitare di bloccare inutilmente le query.
Controllo di sicurezza per la riduzione della quota: per impostazione predefinita, l'API Cloud Quotas blocca qualsiasi aggiornamento programmatico che riduca un limite di quota effettivo di oltre il 10% alla volta. Poiché i limiti di token predefiniti sono nell'ordine delle centinaia di miliardi, l'impostazione di un limite giornaliero più rigido in genere supera una riduzione del 10% e non va a buon fine con un errore QUOTA_DECREASE_PERCENTAGE_TOO_HIGH, a meno che non esegui l'override di questo controllo di sicurezza:
- gcloud CLI: includi il flag --allow-high-percentage-quota-decrease.
- Libreria client Python: passa ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH].
- Terraform: imposta ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH".

Passaggi successivi

Scopri di più sull'ottimizzazione dei costi delle funzioni AI.
Leggi una panoramica dell'AI generativa in BigQuery.
Scopri come configurare gli avvisi quota e il monitoraggio.