透過權杖配額控管成本
本文說明如何定義及管理生成式 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
管理配額
視資源用量而定,您可能需要查看或調整權杖配額值:
如要查看及更新每日權杖配額,請選取下列其中一個選項:
控制台
在 Google Cloud 控制台,依序前往「IAM & Admin」(IAM 與管理) >「Quotas & System Limits」(配額與系統限制) 頁面。
輸入
Service: BigQuery API篩選配額。從配額清單中搜尋特定配額,例如「AI input tokens per day」(每天 AI 輸入權杖) (
GenAiInputTokensPerDay),或排序「Name」(名稱) 欄,將 AI 權杖配額移至清單頂端。依序點選「more_vert」more_vert。
如要增加或減少配額,請在「Quota changes」(配額變更) 窗格的「New value」(新值) 欄位中輸入新值,然後按一下「Done」(完成)。調降配額會立即生效,不需經過核准。
按一下 [提交要求]。
gcloud
使用 gcloud CLI 管理權杖配額時,請將 bigquery.googleapis.com 指定為服務名稱,並使用下列區分大小寫的配額 ID:
- 每天 AI 輸入詞元:
GenAiInputTokensPerDay - 每位使用者每天的 AI 輸入權杖:
GenAiInputTokensPerUserPerDay - 每日 AI 輸出詞元:
GenAiOutputTokensPerDay - 每位使用者每日 AI 輸出詞元:
GenAiOutputTokensPerUserPerDay
選用:如要列出 BigQuery 生成式 AI 權杖配額和目前的值,請使用
gcloud quotas info list:gcloud quotas info list \ --service=bigquery.googleapis.com \ --project=PROJECT_ID \ --filter="quotaId:GenAi*"如要建立或更新每日權杖用量上限的配額偏好設定,請使用
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:提供調整配額的原因。
如要驗證配額偏好設定的狀態,請使用
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
安裝 Python 適用的 Cloud Quotas 用戶端程式庫:
pip install --user google-cloud-quotas如要檢查現有的配額偏好設定資源,並建立或更新每日權杖限制,請執行下列 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
檢查專案是否已有配額偏好設定。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)"如要在 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)。
初始化並套用 Terraform 設定:
terraform init terraform apply
監控配額
為避免查詢意外失敗、偵測用量激增情形及管理成本,請在 Google Cloud 控制台監控詞元配額用量,步驟如下:
在 Google Cloud 控制台,依序前往「IAM & Admin」(IAM 與管理) >「Quotas & System Limits」(配額與系統限制) 頁面。
輸入
Service: BigQuery API篩選配額。查看「Current usage percentage」(目前用量百分比) 和「Current usage」(目前用量) 欄,確認專案每日的「AI input tokens per day」(每日 AI 輸入權杖) (
GenAiInputTokensPerDay) 和「AI output tokens per day」(每日 AI 輸出權杖) (GenAiOutputTokensPerDay) 配額權杖用量。如要查看歷來的權杖消耗量,請在專案層級權杖配額的資料列中,按一下「monitoring 顯示用量圖表」。
用量資訊卡會顯示設定的限制、目前用量百分比和用量高峰百分比,以及可選取 7 天、14 天、30 天和「Custom」(自訂) 日期範圍的歷來用量圖表:
選用:設定基本配額用量快訊,在權杖用量達到每日上限的指定百分比時,透過電子郵件、簡訊或 Pub/Sub 通知您。
選用:在 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"。
- gcloud CLI:加入
後續步驟
- 進一步瞭解如何最佳化 AI 函式費用。
- 閱讀 BigQuery 生成式 AI 總覽。
- 瞭解如何設定配額警告和監控功能。