Mengontrol biaya dengan kuota token

Dokumen ini menjelaskan cara menentukan dan mengelola batas harian jumlah token input dan output yang digunakan oleh fungsi AI generatif.

Fungsi AI generatif BigQuery menggunakan model bahasa besar (LLM) untuk melakukan analisis lanjutan dalam kueri SQL Anda. Karena penggunaan LLM biasanya ditagih berdasarkan jumlah token yang diproses, BigQuery menyediakan kuota token untuk membantu Anda mengelola dan mengontrol biaya yang terkait dengan penggunaan fungsi ini.

Kuota token berlaku untuk fungsi SQL BigQuery yang dirancang untuk tugas inferensi AI generatif yang menggunakan LLM Gemini, seperti fungsi AI.CLASSIFY dan AI.GENERATE_TEXT. Kuota token tidak berlaku untuk pembuatan embedding dan fungsi penelusuran semantik, seperti AI.EMBED, yang memiliki struktur penagihan berbeda.

Detail kuota

BigQuery menyediakan kuota harian berikut berdasarkan penggunaan token LLM. Penggunaan token berkorelasi langsung dengan penagihan Vertex AI Anda untuk fungsi AI generatif BigQuery yang menggunakan model Gemini. Kuota ini dilacak secara global di semua region. Kuota harian direset pada tengah malam waktu Pasifik.

Kuota token ini mengatur jumlah token input dan output yang diproses oleh LLM untuk fungsi AI generatif:

  • Token input: Token yang dikirim ke model untuk diproses. Hal ini mencakup token dalam teks perintah dan data lain yang diberikan ke model sebagai input.
  • Token output: Token yang dihasilkan oleh model dalam responsnya. Hal ini mencakup token dalam teks yang dihasilkan (token kandidat) dan token yang dihasilkan selama langkah-langkah penalaran internal (token pemikiran).

Kuota ID metrik dan kuota Default Catatan
Token input AI per hari Metric: bigquery.googleapis.com/quota/query/ai_input_tokens

Quota ID: GenAiInputTokensPerDay 		200.000.000.000 Token input yang digunakan oleh LLM. Berlaku per hari, per project.
Token input AI per hari per pengguna Metric: bigquery.googleapis.com/quota/query/ai_input_tokens

Quota ID: GenAiInputTokensPerUserPerDay 		150.000.000.000 Token input yang digunakan oleh LLM. Berlaku per hari, per project, per pengguna.
Token output AI per hari Metric: bigquery.googleapis.com/quota/query/ai_output_tokens

Quota ID: GenAiOutputTokensPerDay 		20.000.000.000 Token output dan pemikiran yang digunakan oleh LLM. Berlaku per hari, per project.
Token output AI per hari per pengguna Metric: bigquery.googleapis.com/quota/query/ai_output_tokens

Quota ID: GenAiOutputTokensPerUserPerDay 		15.000.000.000 Token output dan pemikiran yang digunakan oleh LLM. Berlaku per hari, per project, per pengguna.

Kuota ini dilacak dalam kelipatan jutaan token. Meskipun Anda dapat menetapkan batas yang tepat, nilai yang lebih kecil dari beberapa juta token mungkin tidak akan ditampilkan dengan akurasi sempurna karena sifat pelaporan dan agregasi token.

Token yang di-cache tidak mengurangi kuota.

Sebelum memulai

Jika Anda menggunakan Google Cloud CLI, library klien Cloud Quotas API, atau Terraform untuk mengelola kuota token secara terprogram, aktifkan Cloud Quotas API (cloudquotas.googleapis.com) di project Google CloudAnda:

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

Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk melihat dan memperbarui kuota token, minta administrator untuk memberi Anda peran IAM Cloud Quotas Admin (roles/cloudquotas.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk melihat dan memperbarui kuota token. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk melihat dan memperbarui kuota token:

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

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mengelola kuota

Bergantung pada penggunaan resource, Anda mungkin ingin melihat atau menyesuaikan nilai kuota token ke atas atau ke bawah:

  • Jika workload Anda memerlukan kapasitas lebih besar daripada batas default, Anda dapat meminta penambahan kuota.
  • Jika ingin menerapkan batas yang lebih ketat pada penggunaan untuk mencegah anggaran berlebih, Anda dapat membuat penggantian kuota untuk membatasi penggunaan.

Untuk melihat dan memperbarui kuota token harian, pilih salah satu opsi berikut:

Konsol

  1. Di konsol Google Cloud , buka halaman IAM & Admin > Quotas & System Limits.

    Buka Quotas & System Limits

  2. Filter kuota dengan memasukkan Service: BigQuery API.

  3. Telusuri kuota tertentu dari daftar kuota, seperti AI input tokens per day (GenAiInputTokensPerDay), atau urutkan kolom Name untuk menampilkan kuota token AI di bagian atas daftar.

  4. Klik more_vert More actions > Edit quota.

  5. Untuk menambah atau mengurangi kuota, di panel Quota changes, masukkan nilai baru di kolom New value, lalu klik Done. Penurunan kuota akan langsung berlaku tanpa memerlukan persetujuan.

  6. Klik Submit request.

gcloud

Saat Anda mengelola kuota token dengan gcloud CLI, tentukan bigquery.googleapis.com sebagai nama layanan dan gunakan ID kuota peka huruf besar/kecil berikut:

  • Token input AI per hari: GenAiInputTokensPerDay
  • Token input AI per hari per pengguna: GenAiInputTokensPerUserPerDay
  • Token output AI per hari: GenAiOutputTokensPerDay
  • Token output AI per hari per pengguna: GenAiOutputTokensPerUserPerDay

  1. Opsional: Untuk mencantumkan kuota token AI generatif BigQuery dan nilainya saat ini, gunakan gcloud quotas info list:

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

  2. Untuk membuat atau memperbarui preferensi kuota untuk batas token harian Anda, gunakan gcloud quotas preferences update. Contoh berikut memeriksa apakah preferensi kuota sudah ada untuk setiap kuota (misalnya, jika sebelumnya diubah di konsolGoogle Cloud ) dan memperbarui atau membuat preferensi:

    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

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INPUT_TOKEN_LIMIT: target batas token input harian Anda (misalnya, 754000000).
    • OUTPUT_TOKEN_LIMIT: batas token output harian target Anda (misalnya, 8000000).

    Anda juga dapat menyertakan flag opsional berikut dengan gcloud quotas preferences update:

    • --allow-quota-decrease-below-usage: memungkinkan penurunan batas kuota di bawah penggunaan Anda saat ini untuk hari tersebut.
    • --email: menentukan alamat email kontak, yang diperlukan saat meminta penambahan kuota di atas batas default.
    • --justification: memberikan alasan penyesuaian kuota.

  3. Untuk memverifikasi status preferensi kuota Anda, gunakan gcloud quotas preferences list:

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

    Jika reconciling adalah false, nilai di grantedValue akan diterapkan secara aktif.

Python

Saat Anda mengelola kuota token dengan library klien Cloud Quotas untuk Python, tentukan bigquery.googleapis.com sebagai nama layanan dan gunakan ID kuota peka huruf besar/kecil berikut:

  • Token input AI per hari: GenAiInputTokensPerDay
  • Token input AI per hari per pengguna: GenAiInputTokensPerUserPerDay
  • Token output AI per hari: GenAiOutputTokensPerDay
  • Token output AI per hari per pengguna: GenAiOutputTokensPerUserPerDay

  1. Instal library klien Cloud Quotas untuk Python:

    pip install --user google-cloud-quotas

  2. Untuk memeriksa resource preferensi kuota yang ada dan membuat atau memperbarui batas token harian Anda, jalankan skrip Python berikut:

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

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INPUT_TOKEN_LIMIT: batas token input harian target Anda sebagai bilangan bulat (misalnya, 754000000).
    • OUTPUT_TOKEN_LIMIT: batas token output harian target Anda sebagai bilangan bulat (misalnya, 8000000).

Terraform

Saat Anda mengelola kuota token dengan Terraform, tentukan bigquery.googleapis.com sebagai nama layanan dan gunakan ID kuota peka huruf besar/kecil berikut:

  • Token input AI per hari: GenAiInputTokensPerDay
  • Token input AI per hari per pengguna: GenAiInputTokensPerUserPerDay
  • Token output AI per hari: GenAiOutputTokensPerDay
  • Token output AI per hari per pengguna: GenAiOutputTokensPerUserPerDay

  1. Periksa apakah preferensi kuota sudah ada di project Anda. Cloud Quotas hanya mengizinkan satu resource preferensi per kuota pada sebuah project. Jika kuota sebelumnya diubah di konsolGoogle Cloud atau alat lain, Anda harus menggunakan ID preferensi yang ada:

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

  2. Untuk mengonfigurasi batas token harian dalam konfigurasi Terraform (misalnya, main.tf), gunakan resource 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
    }
  }
}

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • INPUT_TOKEN_LIMIT: target batas token input harian Anda (misalnya, 754000000).
    • OUTPUT_TOKEN_LIMIT: batas token output harian target Anda (misalnya, 8000000).

  3. Lakukan inisialisasi dan terapkan konfigurasi Terraform Anda:

    terraform init
terraform apply

Memantau kuota

Untuk mencegah kegagalan kueri yang tidak terduga, mendeteksi lonjakan penggunaan, dan mengelola biaya, pantau konsumsi kuota token Anda di konsol Google Cloud dengan melakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman IAM & Admin > Quotas & System Limits.

    Buka Quotas & System Limits

  2. Filter kuota dengan memasukkan Service: BigQuery API.

  3. Lihat kolom Current usage percentage dan Current usage untuk memeriksa konsumsi token harian project Anda untuk kuota AI input tokens per day (GenAiInputTokensPerDay) dan AI output tokens per day (GenAiOutputTokensPerDay).

  4. Untuk melihat pemakaian token historis dari waktu ke waktu, di baris untuk kuota token level project, klik monitoring Show usage chart.

    Kartu penggunaan menampilkan batas yang dikonfigurasi, persentase penggunaan saat ini, dan persentase penggunaan puncak, beserta diagram konsumsi historis untuk rentang waktu 7 hari, 14 hari, 30 hari, dan Kustom yang dapat dipilih:

    Diagram penggunaan untuk kuota token input AI per hari di konsol Google Cloud .

  5. Opsional: Siapkan pemberitahuan penggunaan kuota dasar untuk memberi tahu Anda melalui email, SMS, atau Pub/Sub saat konsumsi token mencapai persentase tertentu dari batas harian Anda.

  6. Opsional: Buat diagram di Cloud Monitoring untuk memvisualisasikan tren penggunaan token dan membuat dasbor kustom. Untuk mengetahui informasi selengkapnya tentang cara memantau kuota dan mengonfigurasi kebijakan pemberitahuan, lihat Menyiapkan pemberitahuan dan pemantauan kuota.

Untuk memperkirakan penggunaan token input sebelum menjalankan kueri, gunakan fungsi AI.COUNT_TOKENS. Anda juga dapat melihat jumlah token yang diproses oleh setiap kueri di tab Job information pada panel Query results.

Perilaku penerapan kuota

BigQuery memantau konsumsi token Anda di beberapa tahap eksekusi kueri:

  • Pemeriksaan pra-eksekusi: BigQuery memeriksa kuota token yang tersedia sebelum menjalankan kueri yang berisi fungsi AI generatif. Jika kuota yang relevan (misalnya, token input harian project) sudah habis, kueri akan ditolak dengan error QuotaExceeded.
  • Selama eksekusi: Jika kueri berjalan dan menggunakan token sedemikian rupa sehingga menghabiskan kuota yang dikonfigurasi (input atau output, per project atau per pengguna), panggilan LLM baru dalam kueri tersebut akan ditolak.
    • Baris yang tersisa yang bergantung pada panggilan LLM akan mengalami error kuota habis.
    • Hasil kueri bergantung pada argumen max_error_ratio jika digunakan dalam fungsi seperti AI.IF. Jika rasio error tetap dalam batas yang diizinkan, hasil parsial mungkin akan ditampilkan. Jika tidak, seluruh kueri akan gagal.
    • Kueri berikutnya yang mencoba menggunakan fungsi AI generatif akan gagal dengan error QuotaExceeded hingga kuota harian direset.

Pertimbangan penting

  • Kuota global: Kuota yang ditentukan bersifat global. Penggunaan token digabungkan di semua region tempat project Anda beroperasi, sehingga memberikan mekanisme kontrol biaya yang terpadu. Tindakan ini mencegah tagihan tak terduga dari penggunaan di berbagai region.
  • Throughput yang disediakan: Jika Anda menggunakan model Gemini Enterprise Agent Platform dengan throughput yang disediakan, penagihan tidak didasarkan pada penggunaan token. Anda harus menetapkan kuota token BigQuery ini ke nilai yang tinggi untuk menghindari pemblokiran kueri yang tidak perlu.
  • Pemeriksaan keamanan pengurangan kuota: Secara default, Cloud Quotas API memblokir update terprogram yang mengurangi batas kuota efektif lebih dari 10% sekaligus. Karena batas token default mencapai ratusan miliar, menetapkan batas harian yang lebih ketat biasanya melebihi pengurangan 10% dan gagal dengan error QUOTA_DECREASE_PERCENTAGE_TOO_HIGH, kecuali jika Anda mengganti pemeriksaan keamanan ini:
    • gcloud CLI: sertakan flag --allow-high-percentage-quota-decrease.
    • Library klien Python: teruskan ignore_safety_checks=[cloudquotas_v1.QuotaSafetyCheck.QUOTA_DECREASE_PERCENTAGE_TOO_HIGH].
    • Terraform: tetapkan ignore_safety_checks = "QUOTA_DECREASE_PERCENTAGE_TOO_HIGH".

Langkah berikutnya