Contrôler les coûts avec des quotas de jetons

Ce document explique comment définir et gérer des limites quotidiennes pour le nombre de jetons d'entrée et de sortie consommés par les fonctions d'IA générative.

Les fonctions d'IA générative de BigQuery utilisent des grands modèles de langage (LLM) pour effectuer des analyses avancées dans vos requêtes SQL. Étant donné que l'utilisation des LLM est généralement facturée en fonction du nombre de jetons traités, BigQuery fournit des quotas de jetons pour vous aider à gérer et à contrôler les coûts associés à l'utilisation de ces fonctions.

Les quotas de jetons s'appliquent aux fonctions SQL BigQuery conçues pour les tâches d'inférence d'IA générative qui utilisent des LLM Gemini, telles que les fonctions AI.CLASSIFY et AI.GENERATE_TEXT. Les quotas de jetons ne s'appliquent pas aux fonctions de génération d'embeddings et de recherche sémantique, telles que AI.EMBED, qui ont des structures de facturation différentes.

Détails des quotas

BigQuery fournit les quotas quotidiens suivants en fonction de l'utilisation des jetons LLM. L'utilisation des jetons est directement liée à votre facturation Vertex AI pour les fonctions d'IA générative BigQuery qui utilisent des modèles Gemini. Ces quotas sont suivis de manière globale dans toutes les régions. Les quotas quotidiens sont réinitialisés à minuit, heure du Pacifique.

Ces quotas de jetons régissent le nombre de jetons d'entrée et de sortie traités par les LLM pour les fonctions d'IA générative :

  • Jetons d'entrée : jetons envoyés au modèle pour traitement. Cela inclut les jetons du texte de la requête et toutes les autres données fournies au modèle en entrée.
  • Jetons de sortie : jetons générés par le modèle dans sa réponse. Cela inclut les jetons dans le texte généré (jetons candidats) et les jetons générés lors des étapes de raisonnement interne (jetons de réflexion).

Quota ID de métrique et de quota Par défaut Remarques
Jetons d'entrée d'IA par jour Métrique : bigquery.googleapis.com/quota/query/ai_input_tokens

ID de quota : GenAiInputTokensPerDay 		200 000 000 000 Jetons d'entrée utilisés par le LLM. S'applique par jour et par projet.
Jetons d'entrée d'IA par jour et par utilisateur Métrique : bigquery.googleapis.com/quota/query/ai_input_tokens

ID de quota : GenAiInputTokensPerUserPerDay 		150 000 000 000 Jetons d'entrée utilisés par le LLM. S'applique par jour, par projet et par utilisateur.
Jetons de sortie d'IA par jour Métrique : bigquery.googleapis.com/quota/query/ai_output_tokens

ID de quota : GenAiOutputTokensPerDay 		20 000 000 000 Jetons de sortie et de pensée utilisés par le LLM. S'applique par jour et par projet.
Jetons de sortie d'IA par jour et par utilisateur Métrique : bigquery.googleapis.com/quota/query/ai_output_tokens

ID de quota : GenAiOutputTokensPerUserPerDay 		15 000 000 000 Jetons de sortie et de pensée utilisés par le LLM. S'applique par jour, par projet et par utilisateur.

Ces quotas sont suivis par incréments de millions de jetons. Bien que vous puissiez définir des limites précises, les valeurs inférieures à quelques millions de jetons peuvent ne pas être reflétées avec une précision parfaite en raison de la nature des rapports et de l'agrégation des jetons.

Les jetons mis en cache ne sont pas comptabilisés dans les quotas.

Avant de commencer

Si vous utilisez la Google Cloud CLI, les bibliothèques clientes de l'API Cloud Quotas ou Terraform pour gérer les quotas de jetons de manière programmatique, activez l'API Cloud Quotas (cloudquotas.googleapis.com) sur votre projet Google Cloud :

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

Remplacez PROJECT_ID par l'ID du projet Google Cloud .

Rôles requis

Pour obtenir les autorisations nécessaires pour afficher et mettre à jour les quotas de jetons, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Cloud Quotas (roles/cloudquotas.admin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour afficher et mettre à jour les quotas de jetons. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour afficher et mettre à jour les quotas de jetons :

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Gérer les quotas

Selon l'utilisation de vos ressources, vous pouvez afficher ou ajuster les valeurs de quota de jetons à la hausse ou à la baisse :

Pour afficher et mettre à jour vos quotas de jetons quotidiens, sélectionnez l'une des options suivantes :

Console

  1. Dans la console Google Cloud , accédez à la page IAM et administration > Quotas et limites du système.

    Accéder à la page Quotas et limites du système

  2. Filtrez les quotas en saisissant Service: BigQuery API.

  3. Recherchez un quota spécifique dans la liste des quotas, par exemple Jetons d'entrée d'IA par jour (GenAiInputTokensPerDay), ou triez la colonne Nom pour placer les quotas de jetons d'IA en haut de la liste.

  4. Cliquez sur more_vert Autres actions > Modifier le quota.

  5. Pour augmenter ou diminuer le quota, dans le volet Modifications de quota, saisissez une nouvelle valeur dans le champ Nouvelle valeur, puis cliquez sur OK. La réduction d'un quota prend effet immédiatement, sans nécessiter d'approbation.

  6. Cliquez sur Envoyer la requête.

gcloud

Lorsque vous gérez les quotas de jetons avec la gcloud CLI, spécifiez bigquery.googleapis.com comme nom de service et utilisez les ID de quota suivants (sensibles à la casse) :

  • Jetons d'entrée d'IA par jour : GenAiInputTokensPerDay
  • Jetons d'entrée d'IA par jour et par utilisateur : GenAiInputTokensPerUserPerDay
  • Jetons de sortie d'IA par jour : GenAiOutputTokensPerDay
  • Jetons de sortie d'IA par jour et par utilisateur : GenAiOutputTokensPerUserPerDay

  1. Facultatif : Pour lister les quotas de jetons d'IA générative BigQuery et leurs valeurs actuelles, utilisez gcloud quotas info list :

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

  2. Pour créer ou mettre à jour les préférences de quota pour vos limites de jetons quotidiennes, utilisez gcloud quotas preferences update. L'exemple suivant vérifie si une préférence de quota existe déjà pour chaque quota (par exemple, s'il a déjà été modifié dans la consoleGoogle Cloud ) et met à jour ou crée la préférence :

    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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INPUT_TOKEN_LIMIT : votre limite quotidienne de jetons d'entrée cible (par exemple, 754000000).
    • OUTPUT_TOKEN_LIMIT : limite de jetons de sortie quotidienne cible (par exemple, 8000000).

    Vous pouvez également inclure les options facultatives suivantes avec gcloud quotas preferences update :

    • --allow-quota-decrease-below-usage : permet de réduire une limite de quota en dessous de votre utilisation actuelle pour la journée.
    • --email : spécifie une adresse e-mail de contact, qui est requise lorsque vous demandez une augmentation de quota au-delà de la limite par défaut.
    • --justification : indique la raison de l'ajustement du quota.

  3. Pour vérifier l'état de vos préférences de quota, utilisez gcloud quotas preferences list :

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

    Lorsque reconciling est défini sur false, la valeur de grantedValue est appliquée de manière active.

Python

Lorsque vous gérez des quotas de jetons avec la bibliothèque cliente Cloud Quotas pour Python, spécifiez bigquery.googleapis.com comme nom de service et utilisez les ID de quota suivants (sensibles à la casse) :

  • Jetons d'entrée d'IA par jour : GenAiInputTokensPerDay
  • Jetons d'entrée d'IA par jour et par utilisateur : GenAiInputTokensPerUserPerDay
  • Jetons de sortie d'IA par jour : GenAiOutputTokensPerDay
  • Jetons de sortie d'IA par jour et par utilisateur : GenAiOutputTokensPerUserPerDay

  1. Installez la bibliothèque cliente Cloud Quotas pour Python :

    pip install --user google-cloud-quotas

  2. Pour vérifier les ressources de préférence de quota existantes et créer ou mettre à jour vos limites de jetons quotidiennes, exécutez le script Python suivant :

    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")

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INPUT_TOKEN_LIMIT : limite quotidienne de jetons d'entrée cible sous forme d'entier (par exemple, 754000000).
    • OUTPUT_TOKEN_LIMIT : limite de jetons de sortie quotidienne cible sous forme d'entier (par exemple, 8000000).

Terraform

Lorsque vous gérez les quotas de jetons avec Terraform, spécifiez bigquery.googleapis.com comme nom de service et utilisez les ID de quota suivants (sensibles à la casse) :

  • Jetons d'entrée d'IA par jour : GenAiInputTokensPerDay
  • Jetons d'entrée d'IA par jour et par utilisateur : GenAiInputTokensPerUserPerDay
  • Jetons de sortie d'IA par jour : GenAiOutputTokensPerDay
  • Jetons de sortie d'IA par jour et par utilisateur : GenAiOutputTokensPerUserPerDay

  1. Vérifiez si des préférences de quota existent déjà dans votre projet. Cloud Quotas n'autorise qu'une seule ressource de préférence par quota sur un projet. Si un quota a déjà été modifié dans la consoleGoogle Cloud ou un autre outil, vous devez utiliser son ID de préférence existant :

    gcloud quotas preferences list \
    --project=PROJECT_ID \
    --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay" \
    --format="table(quotaId, name.basename():label=PREFERENCE_ID, quotaConfig.preferredValue)"

  2. Pour configurer vos limites de jetons quotidiennes dans votre configuration Terraform (par exemple, main.tf), utilisez la ressource 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
    }
  }
}

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INPUT_TOKEN_LIMIT : votre limite quotidienne de jetons d'entrée cible (par exemple, 754000000).
    • OUTPUT_TOKEN_LIMIT : limite de jetons de sortie quotidienne cible (par exemple, 8000000).

  3. Initialisez et appliquez votre configuration Terraform :

    terraform init
terraform apply

Surveiller les quotas

Pour éviter les échecs de requêtes inattendus, détecter les pics d'utilisation et gérer les coûts, surveillez votre consommation de quota de jetons dans la console Google Cloud en procédant comme suit :

  1. Dans la console Google Cloud , accédez à la page IAM et administration > Quotas et limites du système.

    Accéder à la page Quotas et limites du système

  2. Filtrez les quotas en saisissant Service: BigQuery API.

  3. Consultez les colonnes Pourcentage d'utilisation actuel et Utilisation actuelle pour vérifier la consommation quotidienne de jetons de votre projet pour les quotas Jetons d'entrée d'IA par jour (GenAiInputTokensPerDay) et Jetons de sortie d'IA par jour (GenAiOutputTokensPerDay).

  4. Pour afficher l'historique de la consommation de jetons au fil du temps, dans la ligne d'un quota de jetons au niveau du projet, cliquez sur monitoring Afficher le graphique d'utilisation.

    La fiche d'utilisation affiche la limite configurée, le pourcentage d'utilisation actuel et le pourcentage d'utilisation maximal, ainsi qu'un graphique de l'historique de consommation pour les périodes sélectionnables de 7 jours, 14 jours, 30 jours et Personnalisé :

    Graphique d'utilisation du quota de jetons d'entrée d'IA par jour dans la console Google Cloud .

  5. Facultatif : Configurez des alertes d'utilisation de quota de base pour être averti par e-mail, SMS ou Pub/Sub lorsque la consommation de jetons atteint un pourcentage spécifié de votre limite quotidienne.

  6. Facultatif : Créez des graphiques dans Cloud Monitoring pour visualiser les tendances d'utilisation des jetons et créer des tableaux de bord personnalisés. Pour en savoir plus sur la surveillance des quotas et la configuration des règles d'alerte, consultez Configurer des alertes de quota et une surveillance.

Pour estimer l'utilisation des jetons d'entrée avant d'exécuter une requête, utilisez la fonction AI.COUNT_TOKENS. Vous pouvez également afficher le nombre de jetons traités par une requête individuelle dans l'onglet Informations sur le job du volet Résultats de la requête.

Comportement d'application des quotas

BigQuery surveille votre consommation de jetons à plusieurs étapes de l'exécution de la requête :

  • Vérification avant exécution : BigQuery vérifie le quota de jetons disponible avant d'exécuter une requête contenant des fonctions d'IA générative. Si le quota concerné (par exemple, les jetons d'entrée quotidiens du projet) est déjà épuisé, la requête est rejetée avec une erreur QuotaExceeded.
  • Pendant l'exécution : si une requête est en cours d'exécution et consomme des jetons de manière à épuiser l'un des quotas configurés (entrée ou sortie, par projet ou par utilisateur), les nouveaux appels de LLM dans cette requête sont rejetés.
    • Toutes les lignes restantes qui dépendent d'appels de LLM rencontrent une erreur d'épuisement du quota.
    • Le résultat de la requête dépend de l'argument max_error_ratio s'il est utilisé dans des fonctions telles que AI.IF. Si le taux d'erreur reste dans la limite autorisée, des résultats partiels peuvent être renvoyés. Sinon, l'ensemble de la requête échoue.
    • Les requêtes suivantes qui tentent d'utiliser des fonctions d'IA générative échoueront avec une erreur QuotaExceeded jusqu'à la réinitialisation du quota quotidien.

Remarques importantes

  • Quotas globaux : les quotas définis sont globaux. L'utilisation des jetons est agrégée dans toutes les régions où votre projet est actif, ce qui fournit un mécanisme unifié de contrôle des coûts. Cela permet d'éviter des frais inattendus liés à l'utilisation dans différentes régions.
  • Débit provisionné : si vous utilisez des modèles Gemini Enterprise Agent Platform avec un débit provisionné, la facturation n'est pas basée sur l'utilisation des jetons. Vous devez définir ces quotas de jetons BigQuery sur une valeur élevée pour éviter de bloquer inutilement vos requêtes.
  • Contrôle de sécurité de la réduction des quotas : par défaut, l'API Cloud Quotas bloque toute mise à jour programmatique qui réduit une limite de quota effective de plus de 10 % à la fois. Étant donné que les limites de jetons par défaut se comptent en centaines de milliards, la définition d'un plafond quotidien plus strict dépasse généralement une réduction de 10 % et échoue avec une erreur QUOTA_DECREASE_PERCENTAGE_TOO_HIGH, sauf si vous ignorez cette vérification de sécurité :
    • gcloud CLI : incluez l'option --allow-high-percentage-quota-decrease.
    • Bibliothèque cliente Python : transmettez ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH].
    • Terraform : définissez ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH".

Étapes suivantes