토큰 할당량으로 비용 관리

이 문서에서는 생성형 AI 함수에서 사용하는 입력 및 출력 토큰 수에 대한 일일 한도를 정의하고 관리하는 방법을 설명합니다.

BigQuery 생성형 AI 함수는 대규모 언어 모델 (LLM)을 사용하여 SQL 쿼리 내에서 고급 분석을 수행합니다. LLM 사용량은 일반적으로 처리된 토큰 수를 기준으로 청구되므로 BigQuery는 이러한 함수 사용과 관련된 비용을 관리하고 제어하는 데 도움이 되는 토큰 할당량을 제공합니다.

토큰 할당량은 AI.CLASSIFY 및 AI.GENERATE_TEXT 함수와 같이 Gemini LLM을 사용하는 생성형 AI 추론 태스크를 위해 설계된 BigQuery SQL 함수에 적용됩니다. 토큰 할당량은 결제 구조가 다른 임베딩 생성 및 시맨틱 검색 함수(예: AI.EMBED)에는 적용되지 않습니다.

할당량 세부정보

BigQuery는 LLM 토큰 사용량을 기준으로 다음과 같은 일일 할당량을 제공합니다. 토큰 사용량은 Gemini 모델을 사용하는 BigQuery 생성형 AI 함수의 Vertex AI 청구와 직접적인 상관관계가 있습니다. 이러한 할당량은 모든 리전에서 전역적으로 추적됩니다. 일일 할당량은 태평양 표준시 자정에 재설정됩니다.

이러한 토큰 할당량은 생성형 AI 함수를 위해 LLM에서 처리하는 입력 및 출력 토큰 수를 제어합니다.

• 입력 토큰: 처리를 위해 모델로 전송되는 토큰입니다. 여기에는 프롬프트 텍스트의 토큰과 모델에 입력으로 제공되는 기타 데이터가 포함됩니다.
• 출력 토큰: 모델이 대답에서 생성한 토큰입니다. 여기에는 생성된 텍스트의 토큰 (대답 후보 토큰)과 내부 추론 단계에서 생성된 토큰 (사고 토큰)이 포함됩니다.

할당량	측정항목 및 할당량 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에서 사용하는 출력 및 사고 토큰 일별, 프로젝트별, 사용자별로 적용됩니다.

이러한 할당량은 토큰 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 할당량 관리자 (roles/cloudquotas.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 토큰 할당량을 보고 업데이트하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

토큰 할당량을 보고 업데이트하려면 다음 권한이 필요합니다.

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

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

할당량 관리

리소스 사용량에 따라 토큰 할당량 값을 보거나 상향 또는 하향 조정할 수 있습니다.

• 워크로드에 기본 한도보다 많은 용량이 필요한 경우 할당량 상향을 요청할 수 있습니다.
• 예산 초과를 방지하기 위해 사용량에 더 엄격한 한도를 적용하려면 할당량 재정의를 만들어 사용량을 제한하면 됩니다.

일일 토큰 할당량을 보고 업데이트하려면 다음 옵션 중 하나를 선택합니다.

콘솔

1. Google Cloud 콘솔에서 IAM 및 관리자 > 할당량 및 시스템 한도 페이지로 이동합니다.

   할당량 및 시스템 한도로 이동

2. Service: BigQuery API를 입력하여 할당량을 필터링합니다.

3. 할당량 목록에서 특정 할당량(예: 일일 AI 입력 토큰(GenAiInputTokensPerDay))을 검색하거나 이름 열을 정렬하여 AI 토큰 할당량을 목록 상단으로 가져옵니다.

4. more_vert 작업 더보기 > 할당량 수정을 클릭합니다.

5. 할당량을 늘리거나 줄이려면 할당량 변경 창의 새 값 필드에 새 값을 입력한 후 완료를 클릭합니다. 할당량을 낮추면 승인 없이 즉시 적용됩니다.

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 및 관리자 > 할당량 및 시스템 한도 페이지로 이동합니다.

   할당량 및 시스템 한도로 이동

2. Service: BigQuery API를 입력하여 할당량을 필터링합니다.

3. 현재 사용량 백분율 및 현재 사용량 열을 확인하여 일일 AI 입력 토큰(GenAiInputTokensPerDay) 및 일일 AI 출력 토큰(GenAiOutputTokensPerDay) 할당량에 대한 프로젝트의 일일 토큰 소비량을 확인합니다.

4. 시간 경과에 따른 이전 토큰 사용량을 보려면 프로젝트 수준 토큰 할당량 행에서 모니터링 사용량 차트 표시를 클릭합니다.

   사용량 카드에는 구성된 한도, 현재 사용량 비율, 최대 사용량 비율과 함께 선택 가능한 7일, 14일, 30일, 커스텀 기간의 이전 소비 차트가 표시됩니다.

   

5. 선택사항: 토큰 소비가 일일 한도의 지정된 비율에 도달하면 이메일, SMS 또는 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"를 설정합니다.

다음 단계

• AI 함수 비용 최적화에 대해 자세히 알아보세요.
• BigQuery의 생성형 AI 개요 읽어보기
• 할당량 알림 및 모니터링 설정 방법 알아보기