Controla los costos con cuotas de tokens

En este documento, se describe cómo puedes definir y administrar límites diarios para la cantidad de tokens de entrada y salida que consumen las funciones de IA generativa.

Las funciones de IA generativa de BigQuery usan modelos de lenguaje grandes (LLM) para realizar análisis avanzados en tus consultas en SQL. Debido a que el uso de LLM suele facturarse según la cantidad de tokens procesados, BigQuery proporciona cuotas de tokens para ayudarte a administrar y controlar los costos asociados con el uso de estas funciones.

Las cuotas de tokens se aplican a las funciones de SQL de BigQuery diseñadas para tareas de inferencia de IA generativa que usan LLM de Gemini, como las funciones AI.CLASSIFY y AI.GENERATE_TEXT. Las cuotas de tokens no se aplican a las funciones de generación de incorporaciones y búsqueda semántica, como AI.EMBED, que tienen diferentes estructuras de facturación.

Detalles de la cuota

BigQuery proporciona las siguientes cuotas diarias según el uso de tokens de LLM. El uso de tokens se correlaciona directamente con tu facturación de Vertex AI para las funciones IA generativa de BigQuery que usan modelos de Gemini. Estas cuotas se supervisan de forma global en todas las regiones. Las cuotas diarias se restablecen a la medianoche, hora del Pacífico.

Estas cuotas de tokens rigen la cantidad de tokens de entrada y salida que procesan los LLM para las funciones de IA generativa:

  • Tokens de entrada: Son los tokens que se envían al modelo para su procesamiento. Esto incluye tokens en el texto de la instrucción, tokens almacenados en caché y cualquier otro dato proporcionado al modelo como entrada.
  • Tokens de salida: Son los tokens que genera el modelo en su respuesta. Esto incluye tokens en el texto generado (tokens candidatos) y tokens generados durante los pasos de razonamiento interno (tokens de pensamiento).

Cuota ID de métrica y cuota Predeterminado Notas
Tokens de entrada de IA por día Métrica: bigquery.googleapis.com/quota/query/ai_input_tokens

ID de cuota: GenAiInputTokensPerDay
200,000,000,000 Son los tokens de entrada (incluidos los tokens almacenados en caché) que usa el LLM. Se aplica por día y por proyecto.
Tokens de entrada de IA por día por usuario Métrica: bigquery.googleapis.com/quota/query/ai_input_tokens

ID de cuota: GenAiInputTokensPerUserPerDay
150,000,000,000 Son los tokens de entrada (incluidos los tokens almacenados en caché) que usa el LLM. Se aplica por día, por proyecto y por usuario.
Tokens de salida de IA por día Métrica: bigquery.googleapis.com/quota/query/ai_output_tokens

ID de cuota: GenAiOutputTokensPerDay
20,000,000,000 Son los tokens de salida y de pensamiento que usa el LLM. Se aplica por día y por proyecto.
Tokens de salida de IA por día y por usuario Métrica: bigquery.googleapis.com/quota/query/ai_output_tokens

ID de cuota: GenAiOutputTokensPerUserPerDay
15,000,000,000 Son los tokens de salida y de pensamiento que usa el LLM. Se aplica por día, por proyecto y por usuario.

Estas cuotas se registran en incrementos de millones de tokens. Si bien puedes establecer límites precisos, es posible que los valores inferiores a unos millones de tokens no se reflejen con precisión perfecta debido a la naturaleza de los informes y la agregación de tokens.

Los tokens almacenados en caché se consideran para las cuotas de tokens de entrada.

Antes de comenzar

Si usas Google Cloud CLI, las bibliotecas cliente de la API de Cloud Quotas o Terraform para administrar las cuotas de tokens de manera programática, habilita la API de Cloud Quotas (cloudquotas.googleapis.com) en tu proyecto de Google Cloud:

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

Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

Roles obligatorios

Para obtener los permisos que necesitas para ver y actualizar las cuotas de tokens, pídele a tu administrador que te otorgue el rol de IAM de administrador de Cloud Quotas (roles/cloudquotas.admin) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para ver y actualizar las cuotas de tokens. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para ver y actualizar las cuotas de tokens:

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

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Administrar las cuotas

Según el uso que hagas de los recursos, es posible que desees ver o ajustar los valores de cuota de tokens hacia arriba o hacia abajo:

  • Si tus cargas de trabajo requieren más capacidad que la que proporciona el límite predeterminado, puedes solicitar un aumento de cuota.
  • Si deseas establecer un límite más estricto para el uso y evitar que se exceda el presupuesto, puedes crear una anulación de cuota para limitar el uso.

Para ver y actualizar tus cuotas de tokens diarias, selecciona una de las siguientes opciones:

Console

  1. En la consola de Google Cloud , ve a la página IAM y administración > Cuotas y límites del sistema.

    Ir a Cuotas y límites del sistema

  2. Ingresa Service: BigQuery API para filtrar las cuotas.

  3. Busca una cuota específica en la lista de cuotas, como Tokens de entrada de IA por día (GenAiInputTokensPerDay), o ordena la columna Nombre para llevar las cuotas de tokens de IA a la parte superior de la lista.

  4. Haz clic en more_vert Más acciones > Editar cuota.

  5. Para aumentar o disminuir la cuota, en el panel Cambios de cuota, ingresa un valor nuevo en el campo Valor nuevo y, luego, haz clic en Listo. La reducción de una cuota se aplica de inmediato sin necesidad de aprobación.

  6. Haz clic en Enviar solicitud.

gcloud

Cuando administres las cuotas de tokens con gcloud CLI, especifica bigquery.googleapis.com como el nombre del servicio y usa los siguientes IDs de cuota que distinguen mayúsculas de minúsculas:

  • Tokens de entrada de IA por día: GenAiInputTokensPerDay
  • Tokens de entrada de IA por día y por usuario: GenAiInputTokensPerUserPerDay
  • Tokens de salida de IA por día: GenAiOutputTokensPerDay
  • Tokens de salida de IA por día por usuario: GenAiOutputTokensPerUserPerDay
  1. Opcional: Para enumerar las cuotas de tokens de IA generativa de BigQuery y sus valores actuales, usa gcloud quotas info list:

    gcloud quotas info list \
        --service=bigquery.googleapis.com \
        --project=PROJECT_ID \
        --filter="quotaId:GenAi*"
    
  2. Para crear o actualizar las preferencias de cuota para tus límites de tokens diarios, usa gcloud quotas preferences update. En el siguiente ejemplo, se verifica si ya existe una preferencia de cuota para cada cuota (por ejemplo, si se modificó antes en la consola deGoogle Cloud ) y se actualiza o crea la preferencia:

    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
    

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INPUT_TOKEN_LIMIT: Es el límite diario de tokens de entrada que deseas establecer (por ejemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: Es el límite diario de tokens de salida que quieres establecer (por ejemplo, 8000000).

    También puedes incluir las siguientes marcas opcionales con gcloud quotas preferences update:

    • --allow-quota-decrease-below-usage: Permite reducir un límite de cuota por debajo de tu uso actual del día.
    • --email: Especifica una dirección de correo electrónico de contacto, que es obligatoria cuando se solicita un aumento de cuota por encima del límite predeterminado.
    • --justification: proporciona un motivo para el ajuste de la cuota.
  3. Para verificar el estado de tus preferencias de cuota, usa gcloud quotas preferences list:

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

    Cuando reconciling es false, el valor en grantedValue se aplica de forma activa.

Python

Cuando administres cuotas de tokens con la biblioteca cliente de Cloud Quotas para Python, especifica bigquery.googleapis.com como el nombre del servicio y usa los siguientes IDs de cuota que distinguen mayúsculas de minúsculas:

  • Tokens de entrada de IA por día: GenAiInputTokensPerDay
  • Tokens de entrada de IA por día y por usuario: GenAiInputTokensPerUserPerDay
  • Tokens de salida de IA por día: GenAiOutputTokensPerDay
  • Tokens de salida de IA por día por usuario: GenAiOutputTokensPerUserPerDay
  1. Instala la biblioteca cliente de Cloud Quotas para Python:

    pip install --user google-cloud-quotas
    
  2. Para verificar los recursos de preferencia de cuota existentes y crear o actualizar tus límites de tokens diarios, ejecuta la siguiente secuencia de comandos de 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")
    

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INPUT_TOKEN_LIMIT: Es tu límite diario objetivo de tokens de entrada como un número entero (por ejemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: Es el límite de tokens de salida diarios objetivo como un número entero (por ejemplo, 8000000).

Terraform

Cuando administres las cuotas de tokens con Terraform, especifica bigquery.googleapis.com como el nombre del servicio y usa los siguientes IDs de cuota que distinguen mayúsculas de minúsculas:

  • Tokens de entrada de IA por día: GenAiInputTokensPerDay
  • Tokens de entrada de IA por día y por usuario: GenAiInputTokensPerUserPerDay
  • Tokens de salida de IA por día: GenAiOutputTokensPerDay
  • Tokens de salida de IA por día por usuario: GenAiOutputTokensPerUserPerDay
  1. Verifica si ya existen preferencias de cuota en tu proyecto. Cloud Quotas permite solo un recurso de preferencia por cuota en un proyecto. Si una cuota se modificó antes en la consola deGoogle Cloud o en otra herramienta, debes usar su ID de preferencia existente:

    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 los límites de tokens diarios en tu configuración de Terraform (por ejemplo, main.tf), usa el 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
        }
      }
    }
    

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INPUT_TOKEN_LIMIT: Es el límite diario de tokens de entrada que deseas establecer (por ejemplo, 754000000).
    • OUTPUT_TOKEN_LIMIT: Es el límite diario de tokens de salida que quieres establecer (por ejemplo, 8000000).
  3. Inicializa y aplica tu configuración de Terraform:

    terraform init
    terraform apply
    

Supervisa las cuotas

Para evitar fallas inesperadas en las consultas, detectar aumentos repentinos en el uso y administrar los costos, supervisa el consumo de la cuota de tokens en la consola de Google Cloud siguiendo estos pasos:

  1. En la consola de Google Cloud , ve a la página IAM y administración > Cuotas y límites del sistema.

    Ir a Cuotas y límites del sistema

  2. Ingresa Service: BigQuery API para filtrar las cuotas.

  3. Consulta las columnas Porcentaje de uso actual y Uso actual para verificar el consumo diario de tokens de tu proyecto para las cuotas de Tokens de entrada de IA por día (GenAiInputTokensPerDay) y Tokens de salida de IA por día (GenAiOutputTokensPerDay).

  4. Para ver el consumo histórico de tokens a lo largo del tiempo, en la fila de una cuota de tokens a nivel de proyecto, haz clic en Supervisión Mostrar gráfico de uso.

    En la tarjeta de uso, se muestra el límite configurado, el porcentaje de uso actual y el porcentaje de uso máximo, junto con un gráfico de consumo histórico para los períodos seleccionables de 7 días, 14 días, 30 días y Personalizado:

    Gráfico de uso de la cuota de tokens de entrada de IA por día en la consola de Google Cloud .

  5. Opcional: Configura alertas básicas de uso de cuota para recibir notificaciones por correo electrónico, SMS o Pub/Sub cuando el consumo de tokens alcance un porcentaje especificado de tu límite diario.

  6. Opcional: Crea gráficos en Cloud Monitoring para visualizar las tendencias de uso de tokens y crear paneles personalizados. Para obtener más información sobre cómo supervisar las cuotas y configurar las políticas de alertas, consulta Configura alertas y supervisión de cuotas.

Para estimar el uso de tokens de entrada antes de ejecutar una consulta, usa la función AI.COUNT_TOKENS. También puedes ver la cantidad de tokens que procesó una consulta individual en la pestaña Información del trabajo del panel Resultados de la consulta.

Comportamiento de la aplicación de cuotas

BigQuery supervisa el consumo de tokens en varias etapas de la ejecución de la consulta:

  • Verificación previa a la ejecución: BigQuery verifica la cuota de tokens disponible antes de ejecutar una consulta que contenga funciones de IA generativa. Si la cuota pertinente (por ejemplo, los tokens de entrada diarios del proyecto) ya se agotó, la consulta se rechaza con un error QuotaExceeded.
  • Durante la ejecución: Si se ejecuta una consulta y consume tokens de modo que agota cualquiera de las cuotas configuradas (entrada o salida, por proyecto o por usuario), se rechazan las llamadas nuevas al LLM dentro de esa consulta.
    • Las filas restantes que dependen de las llamadas al LLM encuentran un error de agotamiento de la cuota.
    • El resultado de la consulta depende del argumento max_error_ratio si se usa en funciones como AI.IF. Si la proporción de errores se mantiene dentro del límite permitido, es posible que se muestren resultados parciales. De lo contrario, fallará toda la consulta.
    • Las consultas posteriores que intenten usar funciones de IA generativa fallarán con un error QuotaExceeded hasta que se restablezca la cuota diaria.

Consideraciones importantes

  • Cuotas globales: Las cuotas definidas son globales. El uso de tokens se agrega en todas las regiones en las que opera tu proyecto, lo que proporciona un mecanismo de control de costos unificado. Esto evita cargos inesperados por el uso en diferentes regiones.
  • Capacidad de procesamiento aprovisionada: Si usas modelos de Gemini Enterprise Agent Platform con capacidad de procesamiento aprovisionada, la facturación no se basa en el uso de tokens. Debes establecer estas cuotas de tokens de BigQuery en un valor alto para evitar bloquear tus consultas de forma innecesaria.
  • Verificación de seguridad de reducción de cuota: De forma predeterminada, la API de Cloud Quotas bloquea cualquier actualización programática que reduzca un límite de cuota efectivo en más de un 10% a la vez. Debido a que los límites de tokens predeterminados son de cientos de miles de millones, establecer un límite diario más estricto suele superar una reducción del 10% y falla con un error QUOTA_DECREASE_PERCENTAGE_TOO_HIGH, a menos que anules esta verificación de seguridad:
    • gcloud CLI: Incluye la marca --allow-high-percentage-quota-decrease.
    • Biblioteca cliente de Python: pasa ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH].
    • Terraform: Establece ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH".

¿Qué sigue?