우선순위 추론

Gemini Priority API는 프리미엄 가격으로 지연 시간이 짧고 안정성이 가장 높은 비즈니스에 중요한 워크로드를 위해 설계된 프리미엄 추론 등급입니다. 우선순위 등급 트래픽은 표준 API 및 Flex 등급 트래픽보다 우선순위가 높습니다.

우선순위 추론은 GenerateContent API 및 Interactions API 엔드포인트에서 등급 2 및 등급 3 사용자가 사용할 수 있습니다.

우선순위를 사용하는 방법

우선순위 등급을 사용하려면 요청 본문의 service_tier 필드를 SERVICE_TIER_PRIORITY로 설정합니다. 필드가 생략되면 기본 등급은 표준입니다.

Python

from google import genai

client = genai.Client()

try:
    response = client.models.generate_content(
        model="gemini-3-flash-preview",
        contents="Triage this critical customer support ticket immediately.",
        config={'service_tier': 'SERVICE_TIER_PRIORITY'},
    )

    # Validate for graceful downgrade
    if response.sdk_http_response.headers.get("x-gemini-service-tier") == "standard":
        print("Warning: Priority limit exceeded, processed at Standard tier.")

    print(response.text)

except Exception as e:
    # Standard error handling (e.g., DEADLINE_EXCEEDED)
    print(f"Error during API call: {e}")

JavaScript

자바스크립트에서 다운그레이드는 클라이언트 라이브러리에서 자동으로 처리됩니다. 용량을 초과하면 오류가 발생하거나 표준 등급으로 처리됩니다. 응답 객체는 다운그레이드를 확인하기 위해 헤더를 직접 노출하지 않습니다.

import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

async function main() {
  try {
      const result = await ai.models.generateContent({
          model: "gemini-3-flash-preview",
          contents: "Triage this critical customer support ticket immediately.",
          config: {serviceTier: "priority"},
      });

      // Validate for graceful downgrade
      if (result.sdkHttpResponse.headers.get("x-gemini-service-tier") === "standard") {
          console.log("Warning: Priority limit exceeded, processed at Standard tier.");
      }

      console.log(result.text);

  } catch (e) {
      console.log(`Error during API call: ${e}`);
  }
}

await main();

Go

Go에서 다운그레이드는 클라이언트 라이브러리에서 자동으로 처리됩니다. 용량을 초과하면 오류가 발생하거나 표준 등급으로 처리됩니다. 응답 객체는 다운그레이드를 확인하기 위해 헤더를 직접 노출하지 않습니다.

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    resp, err := client.Models.GenerateContent(
        ctx,
        "gemini-3-flash-preview",
        genai.Text("Triage this critical customer support ticket immediately."),
        &genai.GenerateContentConfig{
            ServiceTier: "priority",
        },
    )
    if err != nil {
        log.Fatalf("Error during API call: %v", err)
    }

    // Validate for graceful downgrade
    if resp.SDKHTTPResponse.Header.Get("x-gemini-service-tier") == "standard" {
        fmt.Println("Warning: Priority limit exceeded, processed at Standard tier.")
    }

    fmt.Println(resp.Text())
}

REST

curl \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-d '{
  "contents": [{
    "parts":[{"text": "Analyze user sentiment in real time"}]
  }],
  "serviceTier": "PRIORITY"
}'

우선순위 추론 작동 방식

우선순위 추론은 요청을 중요도가 높은 컴퓨팅 대기열로 라우팅하여 사용자 대상 애플리케이션에 예측 가능하고 빠른 성능을 제공합니다. 기본 메커니즘은 요청 실패 대신 애플리케이션 안정성을 보장하는 동적 한도를 초과하는 트래픽에 대한 표준 처리에 대한 정상적인 서버 측 다운그레이드입니다.

기능 우선순위 표준 Flex 일괄
가격 책정 표준보다 75~100% 더 높음 정상가 50% 할인 50% 할인
지연 시간 낮음 (초) 초~분 분 (1~15분 목표) 최대 24시간
안정성 높음 (삭제 불가) 높음 / 중간 높음 최선 (삭제 가능) 높음 (처리량)
인터페이스 동기식 동기식 동기식 비동기식

주요 이점

  • 지연 시간 단축: 대화형 사용자 대상 AI 도구의 밀리초-초 응답 시간을 위해 설계되었습니다.
  • 높은 안정성: 트래픽은 중요도가 가장 높게 처리되며 엄격하게 삭제할 수 없습니다.
  • 단계적 성능 저하: 동적 한도를 초과하는 트래픽 급증은 실패 대신 처리를 위해 자동으로 표준 등급으로 다운그레이드되어 서비스 중단을 방지합니다.
  • 낮은 마찰: 표준 및 Flex 등급과 동일한 동기식 generateContent 메서드를 사용합니다.

사용 사례

우선순위 처리는 성능과 안정성이 가장 중요한 비즈니스에 중요한 워크플로에 적합합니다.

  • 대화형 AI 애플리케이션: 사용자가 프리미엄을 지불하고 빠르고 일관된 응답을 기대하는 고객 서비스 챗봇 및 코파일럿
  • 실시간 의사결정 엔진: 실시간 티켓 분류 또는 사기 감지와 같이 안정성이 높고 지연 시간이 짧은 결과가 필요한 시스템
  • 프리미엄 고객 기능: 유료 고객에게 더 높은 서비스 수준 목표 (SLO)를 보장해야 하는 개발자

비율 제한

우선순위 소비는 소비가 전체 대화형 트래픽 비율 제한에 집계되더라도 자체 비율 제한을 유지합니다. 우선순위 추론의 기본 비율 제한은 모델 / 등급의 표준 비율 제한의 0.3배 입니다.

단계적 다운그레이드 로직

정체로 인해 우선순위 한도를 초과하는 경우 오버플로 요청은 503 또는 429 오류로 실패하는 대신 표준 처리로 자동으로 정상적으로 다운그레이드됩니다. 다운그레이드된 요청은 우선순위 프리미엄 요금이 아닌 표준 요금으로 청구됩니다.

클라이언트 책임

  • 응답 모니터링: 개발자는 요청이 standard로 자주 다운그레이드되는지 감지하기 위해 API 응답 본문의 service_tier 값을 모니터링해야 합니다.
  • 재시도: 클라이언트는 표준 오류(예: DEADLINE_EXCEEDED)에 대해 재시도 로직/지수 백오프를 구현해야 합니다.

가격 책정

우선순위 추론은 표준 API보다 75~100% 더 높은 가격으로 책정되며 토큰당 청구됩니다.

지원되는 모델

다음 모델은 우선순위 추론을 지원합니다.

모델 우선순위 추론
Gemini 3.1 Flash-Lite 프리뷰 ✔️
Gemini 3.1 Pro 프리뷰 ✔️
Gemini 3 Flash 프리뷰 ✔️
Gemini 3 Pro Image 프리뷰 ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash Image ✔️
Gemini 2.5 Flash-Lite ✔️

다음 단계

Gemini의 다른 추론 및 최적화 옵션에 대해 알아보세요.