우선순위 사용한 만큼만 지불

우선순위 사용한 만큼만 지불 (우선순위 PayGo)은 프로비저닝된 처리량의 선불 약정 없이 표준 PayGo보다 더 일관된 성능을 제공하는 소비 옵션입니다.

우선순위 PayGo를 사용하면 표준 PayGo보다 높은 요율로 토큰 사용량에 따라 요금이 청구됩니다. 가격 책정에 대한 자세한 내용은 Gemini Enterprise Agent Platform 가격 책정 페이지를 참고하세요.

우선순위 PayGo를 사용하는 경우

우선순위 PayGo는 트래픽 패턴이 변동하거나 예측 불가능한 업무상 중요한 워크로드에 적합합니다. 사용 사례 예시는 다음과 같습니다.

  • 고객 대면 가상 어시스턴트
  • 에이전트형 워크플로 및 교차 에이전트 상호작용
  • 연구 시뮬레이션

지원되는 모델 및 위치

다음 모델은 global 엔드포인트에서만 우선순위 PayGo를 지원합니다. 우선순위 PayGo는 리전 또는 멀티 리전 엔드포인트를 지원하지 않습니다.

우선순위 PayGo 사용

우선순위 PayGo를 사용하여 Gemini API에 요청을 전송하려면 요청에 X-Vertex-AI-LLM-Shared-Request-Type 헤더를 포함해야 합니다. 우선순위 PayGo는 두 가지 방법으로 사용할 수 있습니다.

  • 프로비저닝된 처리량 할당량 (사용 가능한 경우)을 사용하고 우선순위 PayGo로 오버플로합니다.

  • 우선순위 PayGo만 사용합니다.

프로비저닝된 처리량을 기본값으로 사용하는 동안 우선순위 PayGo 사용

우선순위 PayGo를 사용하기 전에 사용 가능한 프로비저닝된 처리량 할당량을 활용하려면 다음 샘플과 같이 요청에 X-Vertex-AI-LLM-Shared-Request-Type: priority 헤더를 포함합니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

우선순위 PayGo를 사용하도록 GenAI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 우선순위 PayGo를 사용하여 Gemini API와 상호작용하기 위해 코드를 추가로 조정할 필요가 없습니다.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

다음과 비슷한 JSON 응답이 수신됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 응답이 완전히 생성된 후 반환되도록 요청하려면 generateContent 메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면 streamGenerateContent 메서드를 사용하여 생성되는 응답을 스트리밍합니다.
  • 멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다 (예: gemini-3.5-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.

우선순위 PayGo만 사용

우선순위 PayGo만 사용하려면 다음 샘플과 같이 요청에 X-Vertex-AI-LLM-Request-Type: shared 및 X-Vertex-AI-LLM-Shared-Request-Type: priority 헤더를 포함합니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

우선순위 PayGo를 사용하도록 GenAI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 우선순위 PayGo를 사용하여 Gemini API와 상호작용하기 위해 코드를 추가로 조정할 필요가 없습니다.

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "priority"
      },
  )
)

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

다음과 비슷한 JSON 응답이 수신됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 응답이 완전히 생성된 후 반환되도록 요청하려면 generateContent 메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면 streamGenerateContent 메서드를 사용하여 생성되는 응답을 스트리밍합니다.
  • 멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다 (예: gemini-3.5-flash). 이 샘플은 다른 모델도 지원할 수 있습니다.

우선순위 PayGo 사용량 확인

다음 예와 같이 응답의 트래픽 유형에서 요청이 우선순위 PayGo를 사용했는지 확인할 수 있습니다.

Python

응답의 traffic_type 필드에서 요청에 우선순위 PayGo가 사용되었는지 확인할 수 있습니다. 우선순위 PayGo를 사용하여 요청이 처리된 경우 traffic_type 필드는 ON_DEMAND_PRIORITY로 설정됩니다.

sdk_http_response=HttpResponse(
  headers=<dict len=9>
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=<FinishReason.STOP: 'STOP'>
)] create_time=datetime.datetime(2025, 12, 3, 20, 32, 55, 916498, tzinfo=TzInfo(0)) model_version='gemini-2.5-flash' prompt_feedback=None response_id='response_id' usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=1408,
  candidates_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=<TrafficType.ON_DEMAND_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

응답의 trafficType 필드에서 요청에 우선순위 PayGo가 사용되었는지 확인할 수 있습니다. 우선순위 PayGo를 사용하여 요청이 처리된 경우 trafficType 필드는 ON_DEMAND_PRIORITY로 설정됩니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}

처리량 한도

우선순위 PayGo는 각 모델에 대해 조직 수준에서 기준 처리량 한도를 제공합니다.

  • Gemini Pro 모델: 분당 10,000,000개의 토큰
  • Gemini Flash 및 Flash-Lite 모델: 분당 50,000,000개의 토큰

이러한 한도는 조직에서 즉시 사용할 수 있습니다. 증가 기간이 없으며 한도에 도달하기 전에 지속적인 사용량을 빌드할 필요가 없습니다. 표준 PayGo와 마찬가지로 모델 제품군에 표시된 처리량 한도는 해당 제품군 내의 각 모델에 독립적으로 적용됩니다.

한도를 초과하는 트래픽은 자동으로 다운그레이드되지 않습니다. 용량이 있는 경우 Agent Platform은 우선순위로 해당 트래픽을 계속 처리하며 우선순위 PayGo 요율로 청구됩니다. 요청은 우선순위로 처리할 수 있는 여유 용량이 없고 해당 요청이 표준 PayGo 요율로 청구되는 경우에만 표준 PayGo로 다운그레이드됩니다.

응답에서 요청이 다운그레이드되었는지 확인할 수 있습니다. 표준 PayGo로 다운그레이드된 요청의 경우 트래픽 유형이 ON_DEMAND로 설정됩니다. 자세한 내용은 우선순위 PayGo 사용량 확인을 참고하세요.

다운그레이드 가능성을 줄이려면 급격한 초 단위 스파이크를 전송하는 대신 매분 트래픽을 분산합니다. 워크로드에 더 높은 한도가 필요한 경우 영업팀에 문의하세요. 보장된 전용 용량이 필요한 워크로드의 경우 프로비저닝된 처리량을 참고하세요.

다음 단계