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

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

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

우선 PayGo를 사용해야 하는 경우

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

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

지원되는 모델 및 위치

일반적으로 우선 PayGo는 global, us, eu 엔드포인트에서 지원됩니다. 하지만 일부 모델 (예: Gemini 2.5 모델)은 세 엔드포인트를 모두 지원하지 않을 수 있습니다. Google 모델에서 연결된 개별 모델 페이지를 확인하여 우선순위 종량제 사용 시 지원되는 엔드포인트를 확인하세요.

다음 모델은 우선순위 PayGo를 지원합니다.

우선 PayGo 사용

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

  • 프로비저닝된 처리량 할당량 (사용 가능한 경우)을 사용하고 우선적 PayGo로 유출됩니다.

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

다음 샘플에서는 global 엔드포인트를 사용합니다. 대신 멀티 리전 엔드포인트로 요청을 보내려면 global을 us 또는 eu로 바꿉니다. REST 요청의 경우 aiplatform.googleapis.com 호스트 이름을 aiplatform.us.rep.googleapis.com 또는 aiplatform.eu.rep.googleapis.com로 바꿔야 합니다. 자세한 내용은 다중 리전 엔드포인트를 참고하세요.

프로비저닝된 처리량을 기본값으로 사용하는 동안 우선적 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를 사용하도록 생성형 AI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 우선순위 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를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

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

  • PROJECT_ID: 프로젝트 ID .
  • MODEL_ID: 우선순위 PayGo를 초기화할 모델의 모델 ID입니다. 우선순위 PayGo를 지원하는 모델 목록은 모델 버전을 참고하세요.
  • PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.
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를 사용하도록 생성형 AI 클라이언트를 초기화합니다. 이 단계를 수행한 후에는 동일한 클라이언트에서 우선순위 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

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

  • PROJECT_ID: 프로젝트 ID .
  • MODEL_ID: 우선순위 PayGo를 초기화할 모델의 모델 ID입니다. 우선순위 PayGo를 지원하는 모델 목록은 모델 버전을 참고하세요.
  • PROMPT_TEXT: 프롬프트에 포함할 텍스트 안내입니다. JSON.
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 필드에서 요청에 Priority 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 필드에서 요청에 Priority 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
  }
}

처리량 한도

우선적으로 사용한 만큼만 지불하는 옵션은 각 모델에 대해 조직 수준에서 기준 처리량 한도를 제공합니다.

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

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

한도를 초과하는 트래픽은 자동으로 다운그레이드되지 않습니다. 용량이 확보되면 Agent Platform은 우선순위로 해당 트래픽을 계속 서빙하며 우선순위 사용한 만큼만 지불 요금으로 청구됩니다. 요청은 우선순위로 처리할 여유 용량이 없는 경우에만 표준 PayGo로 다운그레이드되며, 이러한 요청에는 표준 PayGo 요금이 청구됩니다.

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

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

다음 단계