Flex PayGo

Il pagamento a consumo flessibile (Flex PayGo) è un'opzione conveniente per accedere ai modelli di Gemini per i workload 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, a tolleranza di latenza e non critiche che non sono sensibili al tempo. Di seguito sono riportati alcuni esempi di casi d'uso:

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

  • Valutazione delle qualità del modello

  • Annotazione ed etichettatura dei dati

  • Traduzione di documenti

  • Creazione di un catalogo dei prodotti

Modelli e località supportati

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

Limite del payload della richiesta

Le richieste Flex PayGo hanno un limite di dimensioni totali del payload di 20 MB per le richieste in cui il payload è incluso direttamente nel corpo della richiesta. Per elaborare file più grandi, fornisci un URI Cloud Storage nella richiesta.

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), quindi utilizza Flex PayGo.

  • Utilizza solo Flex PayGo.

Tieni presente che le richieste che utilizzano Flex PayGo hanno una latenza prevista più lunga rispetto a Standard PayGo.

Puoi impostare il timeout della richiesta su un massimo di 30 minuti.

Utilizzare Flex PayGo utilizzando il throughput riservato come impostazione predefinita

Per utilizzare la quota di throughput riservato 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, apporta le sostituzioni seguenti.

  • PROJECT_ID: il tuo ID progetto.
  • MODEL_ID: l'ID modello del modello per il quale 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" \
  -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
  }
}
Tieni presente quanto segue nell'URL per questo esempio:
  • Utilizza il generateContent metodo 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 durante la generazione utilizzando il streamGenerateContent metodo.
  • L'ID modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-2.0-flash). Questo esempio potrebbe supportare anche altri modelli.
  • Quando utilizzi un endpoint API regionale (ad esempio, us-central1), la regione dell'URL dell'endpoint determina dove viene elaborata la richiesta. Qualsiasi località in conflitto nel percorso della risorsa viene ignorata.

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

  • PROJECT_ID: il tuo ID progetto.
  • MODEL_ID: l'ID modello del modello per il quale 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" \
  -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
  }
}
Tieni presente quanto segue nell'URL per questo esempio:
  • Utilizza il generateContent metodo 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 durante la generazione utilizzando il streamGenerateContent metodo.
  • L'ID modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-2.0-flash). Questo esempio potrebbe supportare anche altri modelli.
  • Quando utilizzi un endpoint API regionale (ad esempio, us-central1), la regione dell'URL dell'endpoint determina dove viene elaborata la richiesta. Qualsiasi località in conflitto nel percorso della risorsa viene ignorata.

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 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 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 riservato 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 utilizza Flex PayGo 3000

Passaggi successivi

Risorsa

Quote e limiti relativi specificamente all'AI generativa su Vertex AI.

Risorsa

Quote e limiti relativi alla piattaforma Vertex AI, escluse le limitazioni specifiche del prodotto.

Panoramica

Scopri in che modo Google Cloud limita la quantità di una risorsa che il tuo progetto Google Cloud può utilizzare e come le quote si applicano a una serie di tipi di risorse, inclusi hardware, software e componenti di rete.