Flex PayGo

Flex pay-as-you-go (Flex PayGo) è un'opzione conveniente per accedere ai modelli Gemini per carichi di lavoro non critici che possono tollerare tempi di risposta più lunghi e una limitazione più elevata. Flex PayGo offre uno sconto del 50% rispetto a Standard PayGo.

Quando utilizzare Flex PayGo

Flex PayGo è ideale per le attività sincrone, tolleranti alla latenza e non critiche che non sono sensibili al fattore tempo. Di seguito sono riportati alcuni esempi di casi d'uso:

  • Analisi offline di testo, documenti, immagini, file audio e video

  • Valutazione delle qualità del modello

  • Annotazione ed etichettatura dei dati

  • Traduzione di documenti

  • Creazione di un catalogo prodotti

Modelli e posizioni supportati

I seguenti modelli Gemini in anteprima supportano Flex PayGo solo nell'endpoint global. Flex PayGo non supporta gli endpoint regionali o multiregionali.

Utilizzare Flex PayGo

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

  • Utilizza la quota di throughput riservato (se disponibile) e poi utilizza Flex PayGo.

  • Utilizza solo Flex PayGo.

Tieni presente che le richieste che utilizzano Flex PayGo hanno una latenza maggiore rispetto a PayGo standard. Il timeout predefinito è 20 minuti, che puoi ignorare (in millisecondi) utilizzando il parametro timeout. Il valore massimo consentito è 30 minuti.

Utilizzare Flex PayGo quando si utilizza il throughput con provisioning come impostazione predefinita

Per utilizzare qualsiasi quota di throughput di cui è stato eseguito il provisioning disponibile prima di utilizzare Flex PayGo, includi l'intestazione X-Vertex-AI-LLM-Shared-Request-Type: flex 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 Flex PayGo. Dopo aver eseguito questo passaggio, non dovrai apportare ulteriori modifiche al codice per interagire con l'API Gemini utilizzando Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

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, effettua le seguenti sostituzioni:

  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Flex PayGo. Per un elenco dei modelli che supportano Flex 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-Server-Timeout: 600" \  # Timeout in milliseconds
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "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.

Utilizza solo Flex PayGo

Per utilizzare solo Flex PayGo, includi le intestazioni X-Vertex-AI-LLM-Request-Type: shared e X-Vertex-AI-LLM-Shared-Request-Type: flex 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 Flex PayGo. Dopo aver eseguito questo passaggio, non dovrai apportare ulteriori modifiche al codice per interagire con l'API Gemini utilizzando Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

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

  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Flex PayGo. Per un elenco dei modelli che supportano Flex 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-Server-Timeout: 600" \  # Timeout in milliseconds
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "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 Flex PayGo

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

Python

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

sdk_http_response=HttpResponse(
  headers=
) 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_FLEX: 'ON_DEMAND_FLEX'>
) automatic_function_calling_history=[] parsed=None

REST

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

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

Quota aggiuntiva per Flex PayGo

Oltre alle quote disponibili per le richieste di generazione di contenuti (inclusa la quota di throughput di cui è stato eseguito il provisioning per il traffico di overflow), le richieste che utilizzano Flex PayGo sono soggette alla seguente quota:

Descrizione QPM per ogni modello di base in un progetto
Quota per ogni modello di base in un progetto che richiede l'utilizzo di Flex PayGo 3000

Passaggi successivi