トークンの割り当てで費用を管理する

このドキュメントでは、生成 AI 関数によって消費される入力トークンと出力トークンの数の 1 日あたりの上限を定義して管理する方法について説明します。

BigQuery の生成 AI 関数は、大規模言語モデル（LLM）を使用して、SQL クエリ内で高度な分析を実行します。LLM の使用量は通常、処理されたトークン数に基づいて課金されるため、BigQuery には、これらの関数の使用に関連する費用を管理および制御するためのトークン割り当てが用意されています。

トークンの割り当ては、Gemini LLM を使用する生成 AI 推論タスク用に設計された BigQuery SQL 関数（AI.CLASSIFY 関数や AI.GENERATE_TEXT 関数など）に適用されます。トークンの割り当ては、AI.EMBED などのエンベディング生成関数とセマンティック検索関数には適用されません。これらの関数には異なる課金構造があります。

割り当ての詳細

BigQuery には、LLM トークンの使用量に基づいて、次の 1 日あたりの割り当てが用意されています。トークンの使用量は、Gemini モデルを使用する BigQuery 生成 AI 関数の Vertex AI の課金に直接関連しています。これらの割り当ては、すべてのリージョンでグローバルに追跡されます。1 日の割り当ては、午前 0 時（太平洋時間）にリセットされます。

これらのトークン割り当ては、生成 AI 関数で LLM によって処理される入力トークンと出力トークンの数を制御します。

• 入力トークン: 処理のためにモデルに送信されるトークン。これには、プロンプト テキスト内のトークンと、入力としてモデルに提供されるその他のデータが含まれます。
• 出力トークン: モデルがレスポンスで生成したトークン。これには、生成されたテキスト内のトークン（候補トークン）と、内部推論ステップ中に生成されたトークン（思考トークン）が含まれます。

割り当て	指標と割り当て ID	デフォルト	メモ
1 日あたりの AI 入力トークン数	指標: bigquery.googleapis.com/quota/query/ai_input_tokens 割り当て ID: GenAiInputTokensPerDay	200,000,000,000	LLM で使用される入力トークン数。1 日あたり、プロジェクトごとに適用されます。
ユーザーごとの 1 日あたりの AI 入力トークン数	指標: bigquery.googleapis.com/quota/query/ai_input_tokens 割り当て ID: GenAiInputTokensPerUserPerDay	150,000,000,000	LLM で使用される入力トークン数。1 日あたり、プロジェクトごと、ユーザーごとに適用されます。
1 日あたりの AI 出力トークン数	指標: bigquery.googleapis.com/quota/query/ai_output_tokens 割り当て ID: GenAiOutputTokensPerDay	20,000,000,000	LLM で使用される出力トークン数と思考トークン数。1 日あたり、プロジェクトごとに適用されます。
ユーザーごとの 1 日あたりの AI 出力トークン数	指標: bigquery.googleapis.com/quota/query/ai_output_tokens 割り当て ID: GenAiOutputTokensPerUserPerDay	15,000,000,000	LLM で使用される出力トークン数と思考トークン数。1 日あたり、プロジェクトごと、ユーザーごとに適用されます。

これらの割り当ては、100 万トークン単位で追跡されます。正確な上限を設定できますが、トークンのレポートと集計の性質上、数百万トークン未満の値は完全に正確に反映されない可能性があります。

キャッシュに保存されたトークンは割り当てにカウントされません。

始める前に

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 ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、トークンの割り当ての表示と更新に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

トークンの割り当てを表示および更新するには、次の権限が必要です。

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

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

割り当てを管理

リソースの使用状況に応じて、トークンの割り当て値を表示したり、増減したりできます。

• ワークロードでデフォルトの上限を超える容量が必要な場合は、割り当ての増加をリクエストできます。
• 予算の超過を防ぐために使用量に厳しい制限を設ける場合は、割り当てオーバーライドを作成して使用量の上限を設定できます。

1 日のトークン割り当てを表示して更新するには、次のいずれかのオプションを選択します。

コンソール

1. Google Cloud コンソールで、[IAM と管理] > [割り当てとシステム上限] ページに移動します。

   [割り当てとシステム上限] に移動

2. 「Service: BigQuery API」と入力して割り当てをフィルタします。

3. 割り当てのリストから特定の割り当て（1 日あたりの AI 入力トークン数（GenAiInputTokensPerDay）など）を検索するか、[名前] 列を並べ替えて、AI トークンの割り当てをリストの一番上に表示します。

4. more_vert [その他の操作] > [割り当ての編集] をクリックします。

5. 割り当てを増減するには、[割り当ての変更] ペインの [新しい値] フィールドに新しい値を入力し、[完了] をクリックします。割り当ての引き下げは、承認を必要とせずにすぐに有効になります。

6. [リクエストを送信] をクリックします。

gcloud

gcloud CLI でトークンの割り当てを管理する場合は、サービス名として bigquery.googleapis.com を指定し、次の大文字と小文字を区別する割り当て ID を使用します。

• 1 日あたりの AI 入力トークン数: GenAiInputTokensPerDay
• ユーザーごとの 1 日あたりの AI 入力トークン数: GenAiInputTokensPerUserPerDay
• 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerDay
• ユーザーごとの 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerUserPerDay

1. 省略可: BigQuery 生成 AI トークンの割り当てとその現在の値を一覧表示するには、gcloud quotas info list を使用します。

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

2. 1 日あたりのトークン上限の割り当て設定を作成または更新するには、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: ターゲットの 1 日あたりの入力トークン上限（例: 754000000）。
   • OUTPUT_TOKEN_LIMIT: ターゲットの 1 日あたりの出力トークン上限（例: 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 を使用します。

• 1 日あたりの AI 入力トークン数: GenAiInputTokensPerDay
• ユーザーごとの 1 日あたりの AI 入力トークン数: GenAiInputTokensPerUserPerDay
• 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerDay
• ユーザーごとの 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerUserPerDay

1. Python 用の Cloud Quotas クライアント ライブラリをインストールします。

   pip install --user google-cloud-quotas
   

2. 既存の割り当て設定リソースを確認し、1 日あたりのトークン上限を作成または更新するには、次の 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: ターゲットの 1 日あたりの入力トークン上限（整数）（例: 754000000）。
   • OUTPUT_TOKEN_LIMIT: ターゲットの 1 日あたりの出力トークン数の上限（整数）（例: 8000000）。

Terraform

Terraform でトークン割り当てを管理する場合は、サービス名として bigquery.googleapis.com を指定し、次の大文字と小文字を区別する割り当て ID を使用します。

• 1 日あたりの AI 入力トークン数: GenAiInputTokensPerDay
• ユーザーごとの 1 日あたりの AI 入力トークン数: GenAiInputTokensPerUserPerDay
• 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerDay
• ユーザーごとの 1 日あたりの AI 出力トークン数: GenAiOutputTokensPerUserPerDay

1. プロジェクトに割り当て設定がすでに存在するかどうかを確認します。Cloud Quotas では、プロジェクトの割り当てごとに 1 つの優先度リソースのみが許可されます。以前に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 など）で 1 日あたりのトークン上限を構成するには、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: ターゲットの 1 日あたりの入力トークン上限（例: 754000000）。
   • OUTPUT_TOKEN_LIMIT: ターゲットの 1 日あたりの出力トークン上限（例: 8000000）。

3. Terraform 構成を初期化して適用します。

   terraform init
   terraform apply
   

割り当てをモニタリングする

予期しないクエリの失敗を防ぎ、使用量の急増を検出し、費用を管理するには、 Google Cloud コンソールで次の操作を行い、トークン割り当ての消費量をモニタリングします。

1. Google Cloud コンソールで、[IAM と管理] > [割り当てとシステム上限] ページに移動します。

   [割り当てとシステム上限] に移動

2. 「Service: BigQuery API」と入力して割り当てをフィルタします。

3. [現在の使用率] 列と [現在の使用量] 列を表示して、1 日あたりの AI 入力トークン数（GenAiInputTokensPerDay）と 1 日あたりの AI 出力トークン数（GenAiOutputTokensPerDay）の割り当てに対するプロジェクトの 1 日あたりのトークン消費量を確認します。

4. 過去のトークン消費量の推移を表示するには、プロジェクト レベルのトークン割り当ての行で、モニタリング [使用状況グラフを表示] をクリックします。

   使用量カードには、構成済みの上限、現在の使用率、ピーク使用率が表示されます。また、7 日間、14 日間、30 日間、カスタムの期間を選択できる過去の使用量グラフも表示されます。

   

5. 省略可: 基本的な割り当ての使用量アラートを設定して、トークンの消費量が 1 日の利用時間の上限の指定された割合に達したときに、メール、SMS、または Pub/Sub で通知します。

6. 省略可: Cloud Monitoring でグラフを作成して、トークンの使用傾向を可視化し、カスタム ダッシュボードを構築します。割り当てのモニタリングとアラート ポリシーの構成の詳細については、割り当てアラートとモニタリングの設定をご覧ください。

クエリを実行する前に入力トークンの使用量を見積もるには、AI.COUNT_TOKENS 関数を使用します。[クエリ結果] ペインの [ジョブ情報] タブで、個々のクエリで処理されたトークン数を確認することもできます。

割り当ての適用動作

BigQuery は、クエリ実行の複数のステージでトークンの消費量をモニタリングします。

• 実行前チェック: BigQuery は、生成 AI 関数を含むクエリを実行する前に、使用可能なトークン割り当てを確認します。関連する割り当て（プロジェクトの 1 日あたりの入力トークンなど）がすでに使い果たされている場合、クエリは QuotaExceeded エラーで拒否されます。
• 実行中: クエリが実行され、構成された割り当て（入力または出力、プロジェクトごと、ユーザーごと）のいずれかを使い果たすようにトークンを消費すると、そのクエリ内の新しい LLM 呼び出しは拒否されます。
  • LLM 呼び出しに依存する残りの行で、割り当て超過エラーが発生します。
  • AI.IF などの関数で使用する場合、クエリの結果は max_error_ratio 引数によって異なります。エラー率が許容範囲内であれば、部分的な結果が返されることがあります。それ以外の場合、クエリ全体が失敗します。
  • 生成 AI 関数を使用しようとする後続のクエリは、1 日の割り当てがリセットされるまで QuotaExceeded エラーで失敗します。

重要な考慮事項

• グローバル割り当て: 定義された割り当てはグローバルです。トークンの使用量は、プロジェクトが動作するすべてのリージョンで集計され、統合された費用管理メカニズムが提供されます。これにより、異なるリージョンでの使用による予期しない課金を回避できます。
• プロビジョンド スループット: プロビジョンド スループットで Gemini Enterprise Agent Platform モデルを使用している場合、課金はトークンの使用量に基づいて行われません。クエリが不必要にブロックされないように、これらの BigQuery トークンの割り当てを高い値に設定する必要があります。
• 割り当て削減の安全チェック: デフォルトでは、Cloud Quotas API は、有効な割り当て上限を一度に 10% 以上削減するプログラムによる更新をブロックします。デフォルトのトークン上限は数千億であるため、より厳格な 1 日の上限を設定すると、通常は 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" を設定します。

次のステップ

• 詳しくは、AI 関数の費用の最適化をご覧ください。
• BigQuery の生成 AI の概要を確認する。
• 割り当てアラートとモニタリングの設定方法を確認する。