Priority PayGo

Il pagamento a consumo prioritario (Priority PayGo) è un'opzione di consumo che offre prestazioni più coerenti rispetto al pagamento a consumo standard senza l'impegno iniziale del throughput di cui è stato eseguito il provisioning.

Quando utilizzi PayGo prioritario, ti viene addebitato un costo per l'utilizzo dei token a una tariffa superiore rispetto a PayGo standard. Per informazioni sui prezzi, consulta la pagina Prezzi di Vertex AI.

Quando utilizzare la priorità PayGo

Priority PayGo è ideale per i carichi di lavoro sensibili alla latenza e critici con modelli di traffico fluttuanti o imprevedibili. Di seguito sono riportati alcuni esempi di casi d'uso:

  • Assistenti virtuali rivolti ai clienti

  • Elaborazione di documenti e dati sensibili alla latenza

  • Workflow agentici e interazioni tra agenti

  • Simulazioni di ricerca

Modelli e posizioni supportati

I seguenti modelli supportano Priority PayGo solo nell'endpoint global. Priority PayGo non supporta gli endpoint regionali o multiregionali.

Utilizzare Priority PayGo

Per inviare richieste all'API Gemini in Vertex AI utilizzando Priority PayGo, devi includere l'intestazione X-Vertex-AI-LLM-Shared-Request-Type nella richiesta. Puoi utilizzare Priority PayGo in due modi:

  • Utilizza la quota di throughput riservato (se disponibile) e il Pay as you go prioritario.

  • Utilizza solo Priority PayGo.

Utilizza Priority PayGo quando utilizzi il throughput riservato come impostazione predefinita

Per utilizzare la quota di throughput di cui è stato eseguito il provisioning prima di utilizzare Priority PayGo, includi l'intestazione X-Vertex-AI-LLM-Shared-Request-Type: priority nelle richieste, come mostrato negli esempi seguenti.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con Vertex AI: 

# 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_VERTEXAI=True

Inizializza il client GenAI per utilizzare Priority PayGo. Dopo aver eseguito questo passaggio, non dovrai apportare ulteriori modifiche al codice per interagire con l'API Gemini utilizzando Priority PayGo sullo stesso client.

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

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Priority PayGo. Per un elenco dei modelli che supportano Priority PayGo, vedi Versioni del modello.
  • PROMPT_TEXT: le istruzioni di testo da includere nel prompt. 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" }
    }
  }'

Dovresti ricevere una risposta JSON simile alla seguente.

{
  "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
  }
}
Nell'URL di questo esempio, tieni presente quanto segue:
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo essere stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti in streaming la risposta mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-2.0-flash). Questo esempio potrebbe supportare anche altri modelli.

Utilizzare solo Priority PayGo

Per utilizzare solo Priority PayGo, includi le intestazioni X-Vertex-AI-LLM-Request-Type: shared e X-Vertex-AI-LLM-Shared-Request-Type: priority nelle richieste, come mostrato negli esempi seguenti.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con Vertex AI: 

# 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_VERTEXAI=True

Inizializza il client GenAI per utilizzare Priority PayGo. Dopo aver eseguito questo passaggio, non dovrai apportare ulteriori modifiche al codice per interagire con l'API Gemini utilizzando Priority PayGo sullo stesso client.

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Priority PayGo. Per un elenco dei modelli che supportano Priority PayGo, vedi Versioni del modello.
  • PROMPT_TEXT: le istruzioni di testo da includere nel prompt. 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" }
    }
  }'

Dovresti ricevere una risposta JSON simile alla seguente.

{
  "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
  }
}
Nell'URL di questo esempio, tieni presente quanto segue:
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo essere stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti in streaming la risposta mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-2.0-flash). Questo esempio potrebbe supportare anche altri modelli.

Verificare l'utilizzo di Priority PayGo

Puoi verificare se una richiesta ha utilizzato Priority PayGo dal tipo di traffico nella risposta, come mostrato negli esempi riportati di seguito.

Python

Puoi verificare se Priority PayGo è stato utilizzato per una richiesta dal campo traffic_type nella risposta. Se la tua richiesta è stata elaborata utilizzando Priority PayGo, il campo traffic_type è impostato su ON_DEMAND_PRIORITY.

sdk_http_response=HttpResponse(
  headers=
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=nishReason.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=ty.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=ty.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=fficType.ON_DEMAND_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

Puoi verificare se Priority PayGo è stato utilizzato per una richiesta dal campo trafficType nella risposta. Se la tua richiesta è stata elaborata utilizzando Priority PayGo, il campo trafficType è impostato su 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
  }
}

Limiti di rampa

Priority PayGo imposta i limiti di aumento a livello di organizzazione. I limiti di aumento graduale contribuiscono a fornire prestazioni prevedibili e coerenti. Il limite iniziale dipende dal modello, come segue:

  • Modelli Gemini Flash e Flash-Lite:4 milioni di token/min.
  • Modelli Gemini Pro: 1 milione di token/min.

Il limite di rampa aumenta del 50% ogni 10 minuti di utilizzo sostenuto.

Se una richiesta supera il limite di aumento e il sistema è sovraccarico a causa di un volume di traffico elevato, la richiesta viene declassata a Standard PayGo e viene addebitata alle tariffe Standard PayGo.

Per ridurre al minimo i downgrade, aumenta l'utilizzo in modo incrementale per rimanere entro il limite. Se hai ancora bisogno di prestazioni migliori, valuta la possibilità di acquistare una quota di throughput con provisioning aggiuntiva.

Puoi verificare se una richiesta è stata declassata dalla risposta. Per le richieste di downgrade a PayGo standard, il tipo di traffico è impostato su ON_DEMAND. Per saperne di più, consulta Verificare l'utilizzo di Priority PayGo.

Passaggi successivi