透過權杖配額控管成本

本文說明如何定義及管理生成式 AI 函式每日消耗的輸入和輸出權杖數量上限。

BigQuery 生成式 AI 函式會使用大型語言模型 (LLM),在 SQL 查詢中執行進階分析。由於 LLM 的計費方式通常是根據處理的詞元數量,BigQuery 提供詞元配額,協助您管理及控管使用這些函式的相關費用。

權杖配額適用於專為生成式 AI 推論工作設計的 BigQuery SQL 函式,這些工作使用 Gemini LLM,例如 AI.CLASSIFY 和 AI.GENERATE_TEXT 函式。權杖配額不適用於嵌入生成和語意搜尋函式,例如 AI.EMBED,這些函式有不同的計費結構。

配額詳細資料

BigQuery 會根據 LLM 詞元用量,提供下列每日配額。詞元用量會直接影響 Vertex AI 帳單費用,適用於使用 Gemini 模型的 BigQuery 生成式 AI 函式。這些配額會在全球所有區域追蹤。系統會在太平洋時間凌晨 12 點重設每日配額。

這些詞元配額控管 LLM 處理生成式 AI 函式的輸入和輸出詞元數量:

  • 輸入詞元:傳送至模型處理的詞元。包括提示文字中的詞元、快取詞元,以及提供給模型的任何其他輸入資料。
  • 輸出詞元:模型在回覆中生成的詞元。包括生成文字中的詞元 (候選詞元),以及內部推論步驟中生成的詞元 (思考詞元)。

配額 指標和配額 ID 預設 附註
每日 AI 輸入詞元數 指標:bigquery.googleapis.com/quota/query/ai_input_tokens

配額 ID:GenAiInputTokensPerDay
200,000,000,000 LLM 使用的輸入詞元 (包括快取詞元)。適用於每項專案,每日計算。
每位使用者每天的 AI 輸入詞元 指標:bigquery.googleapis.com/quota/query/ai_input_tokens

配額 ID:GenAiInputTokensPerUserPerDay
150,000,000,000 LLM 使用的輸入詞元 (包括快取詞元)。適用於每位使用者、每項專案、每天。
每日 AI 輸出詞元數 指標:bigquery.googleapis.com/quota/query/ai_output_tokens

配額 ID:GenAiOutputTokensPerDay
20,000,000,000 LLM 使用的輸出和思考詞元。適用於每項專案,每日計算。
每位使用者每天的 AI 輸出詞元數量 指標:bigquery.googleapis.com/quota/query/ai_output_tokens

配額 ID:GenAiOutputTokensPerUserPerDay
15,000,000,000 LLM 使用的輸出和思考詞元。適用於每位使用者、每項專案、每天。

這些配額是以百萬個詞元為單位追蹤。雖然您可以設定精確的限制,但由於權杖報表和匯總的性質,低於數百萬個權杖的值可能無法完全準確反映。

快取詞元會計入輸入詞元配額。

事前準備

如果您使用 Google Cloud CLI、Cloud Quotas API 用戶端程式庫或 Terraform,以程式輔助方式管理權杖配額,請在 Google Cloud專案中啟用 Cloud Quotas API (cloudquotas.googleapis.com):

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

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

必要的角色

如要取得查看及更新權杖配額所需的權限,請要求管理員授予您專案的 Cloud Quotas 管理員 (roles/cloudquotas.admin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備查看及更新權杖配額所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

必須具備下列權限,才能查看及更新權杖配額:

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

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

管理配額

視資源用量而定,您可能需要查看或調整權杖配額值:

  • 如果工作負載需要的容量超過預設限制,您可以要求提高配額。
  • 如要對用量設定更嚴格的限制,避免預算超支,可以建立配額覆寫來限制用量。

如要查看及更新每日權杖配額,請選取下列其中一個選項:

控制台

  1. 在 Google Cloud 控制台,依序前往「IAM & Admin」(IAM 與管理) >「Quotas & System Limits」(配額與系統限制) 頁面。

    前往「Quotas & System Limits」(配額與系統限制) 頁面

  2. 輸入 Service: BigQuery API 篩選配額。

  3. 從配額清單中搜尋特定配額,例如「AI input tokens per day」(每天 AI 輸入權杖) (GenAiInputTokensPerDay),或排序「Name」(名稱) 欄,將 AI 權杖配額移至清單頂端。

  4. 依序點選「more_vert」more_vert。

  5. 如要增加或減少配額,請在「Quota changes」(配額變更) 窗格的「New value」(新值) 欄位中輸入新值,然後按一下「Done」(完成)。調降配額會立即生效,不需經過核准。

  6. 按一下 [提交要求]。

gcloud

使用 gcloud CLI 管理權杖配額時,請將 bigquery.googleapis.com 指定為服務名稱,並使用下列區分大小寫的配額 ID:

  • 每天 AI 輸入詞元:GenAiInputTokensPerDay
  • 每位使用者每天的 AI 輸入權杖:GenAiInputTokensPerUserPerDay
  • 每日 AI 輸出詞元:GenAiOutputTokensPerDay
  • 每位使用者每日 AI 輸出詞元:GenAiOutputTokensPerUserPerDay
  1. 選用:如要列出 BigQuery 生成式 AI 權杖配額和目前的值,請使用 gcloud quotas info list:

    gcloud quotas info list \
        --service=bigquery.googleapis.com \
        --project=PROJECT_ID \
        --filter="quotaId:GenAi*"
    
  2. 如要建立或更新每日權杖用量上限的配額偏好設定,請使用 gcloud quotas preferences update。以下範例會檢查每項配額是否已有配額偏好設定 (例如先前是否在Google Cloud 控制台中修改過),並更新或建立偏好設定:

    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
    

    更改下列內容:

    • PROJECT_ID:您的 Google Cloud 專案 ID。
    • INPUT_TOKEN_LIMIT:每日輸入詞元數量上限目標 (例如 754000000)。
    • OUTPUT_TOKEN_LIMIT:每日輸出詞元數量目標上限 (例如 8000000)。

    您也可以在 gcloud quotas preferences update 中加入下列選用旗標:

    • --allow-quota-decrease-below-usage:允許將配額限制調降至低於當天目前用量。
    • --email:指定聯絡電子郵件地址,如要申請提高配額,超過預設上限,就必須提供這項資訊。
    • --justification:提供調整配額的原因。
  3. 如要驗證配額偏好設定的狀態,請使用 gcloud quotas preferences list:

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

    當 reconciling 為 false 時,系統會主動強制執行 grantedValue 中的值。

Python

使用 Python 適用的 Cloud Quotas 用戶端程式庫管理權杖配額時,請將服務名稱指定為 bigquery.googleapis.com,並使用下列配額 ID (區分大小寫):

  • 每天 AI 輸入詞元:GenAiInputTokensPerDay
  • 每位使用者每天的 AI 輸入權杖:GenAiInputTokensPerUserPerDay
  • 每日 AI 輸出詞元:GenAiOutputTokensPerDay
  • 每位使用者每日 AI 輸出詞元:GenAiOutputTokensPerUserPerDay
  1. 安裝 Python 適用的 Cloud Quotas 用戶端程式庫:

    pip install --user google-cloud-quotas
    
  2. 如要檢查現有的配額偏好設定資源,並建立或更新每日權杖限制,請執行下列 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")
    

    更改下列內容:

    • PROJECT_ID:您的 Google Cloud 專案 ID。
    • INPUT_TOKEN_LIMIT:每日輸入詞元數量上限目標,以整數表示 (例如 754000000)。
    • OUTPUT_TOKEN_LIMIT:目標每日輸出詞元限制,以整數表示 (例如 8000000)。

Terraform

使用 Terraform 管理權杖配額時,請將服務名稱指定為 bigquery.googleapis.com,並使用下列區分大小寫的配額 ID:

  • 每天 AI 輸入詞元:GenAiInputTokensPerDay
  • 每位使用者每天的 AI 輸入權杖:GenAiInputTokensPerUserPerDay
  • 每日 AI 輸出詞元:GenAiOutputTokensPerDay
  • 每位使用者每日 AI 輸出詞元:GenAiOutputTokensPerUserPerDay
  1. 檢查專案是否已有配額偏好設定。Cloud Quotas 規定,專案中的每項配額只能有一個偏好設定資源。如果先前曾在Google Cloud 控制台或其他工具中修改配額,則必須使用現有的偏好設定 ID:

    gcloud quotas preferences list \
        --project=PROJECT_ID \
        --filter="quotaId:GenAiInputTokensPerDay OR quotaId:GenAiOutputTokensPerDay" \
        --format="table(quotaId, name.basename():label=PREFERENCE_ID, quotaConfig.preferredValue)"
    
  2. 如要在 Terraform 設定 (例如 main.tf) 中設定每日權杖限制,請使用 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
        }
      }
    }
    

    更改下列內容:

    • PROJECT_ID:您的 Google Cloud 專案 ID。
    • INPUT_TOKEN_LIMIT:每日輸入詞元數量上限目標 (例如 754000000)。
    • OUTPUT_TOKEN_LIMIT:每日輸出詞元數量目標上限 (例如 8000000)。
  3. 初始化並套用 Terraform 設定:

    terraform init
    terraform apply
    

監控配額

為避免查詢意外失敗、偵測用量激增情形及管理成本,請在 Google Cloud 控制台監控詞元配額用量,步驟如下:

  1. 在 Google Cloud 控制台,依序前往「IAM & Admin」(IAM 與管理) >「Quotas & System Limits」(配額與系統限制) 頁面。

    前往「Quotas & System Limits」(配額與系統限制) 頁面

  2. 輸入 Service: BigQuery API 篩選配額。

  3. 查看「Current usage percentage」(目前用量百分比) 和「Current usage」(目前用量) 欄,確認專案每日的「AI input tokens per day」(每日 AI 輸入權杖) (GenAiInputTokensPerDay) 和「AI output tokens per day」(每日 AI 輸出權杖) (GenAiOutputTokensPerDay) 配額權杖用量。

  4. 如要查看歷來的權杖消耗量,請在專案層級權杖配額的資料列中,按一下「monitoring 顯示用量圖表」。

    用量資訊卡會顯示設定的限制、目前用量百分比和用量高峰百分比,以及可選取 7 天、14 天、30 天和「Custom」(自訂) 日期範圍的歷來用量圖表:

     Google Cloud 控制台中的 AI 輸入權杖每日配額用量圖表。

  5. 選用:設定基本配額用量快訊,在權杖用量達到每日上限的指定百分比時,透過電子郵件、簡訊或 Pub/Sub 通知您。

  6. 選用:在 Cloud Monitoring 中建立圖表,以視覺化方式呈現權杖用量趨勢,並建立自訂資訊主頁。如要進一步瞭解如何監控配額及設定警告政策,請參閱「設定配額警告和監控功能」。

如要在執行查詢前估算輸入詞元用量,請使用 AI.COUNT_TOKENS 函式。您也可以在「查詢結果」窗格的「工作資訊」分頁中,查看個別查詢處理的權杖數量。

配額強制執行行為

BigQuery 會在查詢執行的多個階段監控權杖用量:

  • 執行前檢查:BigQuery 會先檢查可用的權杖配額,再執行含有生成式 AI 函式的查詢。如果相關配額 (例如專案每日輸入權杖) 已用盡,系統會拒絕查詢並傳回 QuotaExceeded 錯誤。
  • 執行期間:如果查詢正在執行,且消耗的詞元數量超過任何設定的配額 (輸入或輸出、每項專案或每位使用者),系統會拒絕該查詢中的新 LLM 呼叫。
    • 其餘依賴 LLM 呼叫的資料列則會發生配額用盡錯誤。
    • 如果用於 AI.IF 等函式,查詢結果會取決於 max_error_ratio 引數。如果錯誤率仍在允許範圍內,系統可能會傳回部分結果。否則整個查詢都會失敗。
    • 在每日配額重設前,後續嘗試使用生成式 AI 函式的查詢都會失敗,並傳回 QuotaExceeded 錯誤。

重要事項

  • 全域配額:定義的配額為全域配額。系統會匯總專案運作的所有區域的詞元用量,提供統一的費用控管機制。這可避免因在不同區域使用而產生非預期費用。
  • 佈建輸送量:如果使用 Gemini Enterprise Agent Platform 模型,並搭配佈建輸送量,計費方式就不會依據權杖用量。建議您將這些 BigQuery 權杖配額設為較高的值,以免不必要地封鎖查詢。
  • 配額縮減安全檢查:根據預設,Cloud Quotas API 會封鎖任何一次將有效配額上限縮減超過 10% 的程式輔助更新。由於預設的詞元限制為數千億,因此設定更嚴格的每日上限通常會超過 10% 的縮減幅度,並失敗並顯示 QUOTA_DECREASE_PERCENTAGE_TOO_HIGH 錯誤,除非您覆寫這項安全檢查:
    • gcloud CLI:加入 --allow-high-percentage-quota-decrease 旗標。
    • Python 用戶端程式庫:傳遞 ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH]。
    • Terraform:設定 ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH"。

後續步驟