Priority PayGo

Il pagamento a consumo prioritario (PayGo prioritario) è un'opzione di consumo che offre prestazioni più costanti rispetto a PayGo standard senza l'impegno iniziale di Throughput riservato.

Quando utilizzi Priority PayGo, ti viene addebitato un costo per l'utilizzo dei token a una tariffa superiore rispetto a Standard PayGo. Per informazioni sui prezzi, consulta la pagina dei prezzi di Gemini Enterprise Agent Platform.

Quando utilizzare Priority PayGo

Priority PayGo è ideale per i workload aziendali critici con modelli di traffico fluttuanti o imprevedibili. Di seguito sono riportati alcuni esempi di casi d'uso:

  • Assistenti virtuali per i clienti
  • Agentic Workflows e interazioni tra agenti
  • Simulazioni di ricerca

Modelli e località supportati

In generale, Priority PayGo è supportato sugli endpoint global, us e eu. Tuttavia, alcuni modelli (come i modelli Gemini 2.5) potrebbero non supportare tutti e tre gli endpoint. Controlla le singole pagine dei modelli collegate da Modelli Google per vedere quali endpoint sono supportati quando utilizzi Priority PayGo.

I seguenti modelli supportano Priority PayGo:

Utilizza Priority PayGo

Per inviare richieste all'API Gemini 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 passa a PayGo prioritario.

  • Utilizza solo PayGo prioritario.

Gli esempi seguenti utilizzano l'endpoint global. Per inviare le richieste a un endpoint multiregionale, sostituisci global con us o eu. Per le richieste REST, devi anche sostituire il nome host aiplatform.googleapis.com con aiplatform.us.rep.googleapis.com o aiplatform.eu.rep.googleapis.com. Per maggiori informazioni, consulta Endpoint multiregionali.

Utilizza PayGo prioritario mentre utilizzi Throughput riservato come predefinito

Per utilizzare qualsiasi quota di Throughput riservato disponibile prima di utilizzare Priority PayGo, includi l'intestazione X-Vertex-AI-LLM-Shared-Request-Type: priority nelle tue 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 Google 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_ENTERPRISE=True

Inizializza il client di AI generativa 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 testuale. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

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

  • PROJECT_ID: il tuo ID progetto. .
  • MODEL_ID: l'ID del modello per cui vuoi inizializzare PayGo con priorità. Per un elenco dei modelli che supportano Priority PayGo, consulta Versioni dei modelli.
  • 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
  }
}
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo che è stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti la risposta in streaming mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-3.5-flash). Questo esempio potrebbe supportare anche altri modelli.

Utilizza solo PayGo prioritario

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 tue 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 Google 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_ENTERPRISE=True

Inizializza il client di AI generativa 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 seguenti sostituzioni:

  • PROJECT_ID: il tuo ID progetto. .
  • MODEL_ID: l'ID del modello per cui vuoi inizializzare PayGo con priorità. Per un elenco dei modelli che supportano Priority PayGo, consulta Versioni dei modelli.
  • 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
  }
}
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo che è stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti la risposta in streaming mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-3.5-flash). Questo esempio potrebbe supportare anche altri modelli.

Verifica l'utilizzo di Priority PayGo

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

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=<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

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 throughput

PayGo prioritario fornisce un limite di throughput di base a livello di organizzazione per ogni modello:

  • Modelli Gemini Pro: 10.000.000 di token al minuto
  • Modelli Gemini Flash e Flash-Lite: 50.000.000 di token al minuto

Questi limiti sono disponibili immediatamente per la tua organizzazione. Non è previsto un periodo iniziale e non è necessario creare un utilizzo sostenuto prima di poterli raggiungere. Analogamente a PayGo standard, il limite di throughput mostrato per una famiglia di modelli si applica in modo indipendente a ogni modello all'interno di quella famiglia.

Il traffico che supera il limite non viene eseguito automaticamente il downgrade. Quando la capacità è disponibile, Agent Platform continua a gestire il traffico con priorità e viene fatturato alle tariffe PayGo prioritario. Il downgrade delle richieste a PayGo standard viene eseguito solo quando non è disponibile capacità di riserva per gestirle con priorità e queste richieste vengono fatturate alle tariffe di PayGo standard.

Puoi verificare se è stato eseguito il downgrade di una richiesta dalla risposta. Per le richieste sottoposte a downgrade a Standard PayGo, il tipo di traffico è impostato su ON_DEMAND. Per saperne di più, consulta Verifica l'utilizzo di Priority PayGo.

Per ridurre la probabilità di un downgrade, distribuisci il traffico in modo uniforme nel corso di ogni minuto, anziché inviare picchi improvvisi a livello di secondo. Se il tuo workload richiede un limite più elevato, contatta il team di vendita. Per i workload che richiedono una capacità dedicata e garantita, consulta Throughput riservato.

Passaggi successivi