Utilizza il livello Posticipato

Utilizza il livello Differito per eseguire chiamate asincrone e multi-turno al modello Gemini per agenti personalizzati a una tariffa scontata su Gemini Enterprise Agent Platform. Nell'API Interactions, la piattaforma degli agenti mette in coda ogni turno differito per l'esecuzione in background entro un target di 24 ore e conserva lo stato per 7 giorni.

Il livello Deferred è adatto ai workload agentici tolleranti alla latenza che richiedono un controllo per turno, ad esempio:

  • Agenti di programmazione e sicurezza in più passaggi: analisi delle vulnerabilità dei repository, migrazioni automatiche del codice e triage delle regressioni.
  • Pipeline di documenti e ricerche: revisioni di progetti tecnici, backtesting finanziario e sintesi di più documenti con chiamate agli strumenti.
  • Valutazioni offline degli agenti: benchmark di qualità su larga scala che concatenano previous_interaction_id turni senza vincoli di latenza in tempo reale.

Per confrontare tutti i modelli di computing, consulta Opzioni di consumo. Per pianificare gli agenti dell'Agent Development Kit (ADK) o le esecuzioni gestite sull'agente Gemini Deep Research, consulta Pianificazione degli agenti autonomi.

Modelli e località supportati

Il livello Deferred è supportato esclusivamente sull'endpoint global (locations/global su aiplatform.googleapis.com). L'invio di una richiesta con service_tier="deferred" a un endpoint regionale o agli endpoint multiregionali us o eu restituisce HTTP 400 ("code": "invalid_request").

I seguenti modelli Gemini principali supportano il livello differito sull'endpoint global:

Se il tuo progetto ha accesso alla lista consentita tramite il team dedicato all'account Google Cloud , puoi utilizzare anche i seguenti modelli Cyber:

Prima di iniziare

In un progetto Google Cloud esistente con fatturazione abilitata, completa i seguenti passaggi di configurazione dei prerequisiti:

  1. Accedi al tuo Account Google.

    Se non ne hai già uno, registrati per creare un nuovo account.

  2. Installa Google Cloud CLI.

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando:

    gcloud init
  5. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.

  6. Abilita l'API Agent Platform, se non è già abilitata:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    gcloud services enable aiplatform.googleapis.com
  7. Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:

    gcloud auth application-default login

    Non è necessario farlo se utilizzi Cloud Shell.

    Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

  8. Installa Google Cloud CLI.

  9. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  10. Per inizializzare gcloud CLI, esegui questo comando:

    gcloud init
  11. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.

  12. Abilita l'API Agent Platform, se non è già abilitata:

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    gcloud services enable aiplatform.googleapis.com
  13. Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:

    gcloud auth application-default login

    Non è necessario farlo se utilizzi Cloud Shell.

    Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare, monitorare e annullare le chiamate ai modelli differite, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto Google Cloud :

  • Creare, eseguire il polling, annullare ed eliminare le interazioni differite: Agent Platform User (roles/aiplatform.user)
  • Monitora le interazioni differite (sola lettura): Agent Platform Viewer (roles/aiplatform.viewer)
  • Leggi i file di input multimodali da Cloud Storage (facoltativo): Storage Object Viewer (roles/storage.objectViewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installa l'SDK Google Gen AI

Se utilizzi una libreria client, installa o esegui l'upgrade dell'SDK Google Gen AI (@google/genai >= 2.32.0 o google-genai >= 2.34.0) nel tuo ambiente di sviluppo:

Node.js

npm install @google/genai@latest

Python

pip install --upgrade "google-genai>=2.34.0"

Crea e gestisci le chiamate al modello differite

Esegui le seguenti procedure nell'ambiente che hai configurato in Prima di iniziare. Gli esempi REST si autenticano con le tue credenziali gcloud CLI, mentre gli esempi dell'SDK Google Gen AI utilizzano Credenziali predefinite dell'applicazione (ADC). Se una chiamata restituisce un errore, consulta Risolvi i problemi.

Crea una chiamata al modello differita

Invia un turno asincrono chiamando interactions.create con service_tier="deferred", background=true e store=true. Ometti stream o impostalo su false. Prima di eseguire un esempio, sostituisci PROJECT_ID con l'ID progetto Google Cloud , ad esempio my-agent-project.

REST

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

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions

Corpo JSON della richiesta:

{
  "model": "gemini-4-argon",
  "input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

Per inviare la richiesta, espandi una di queste opzioni:

La risposta restituisce un payload JSON simile al seguente:

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

async function createDeferredInteraction(projectId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  const interaction = await ai.interactions.create({
    model: "gemini-4-argon",
    input:
      "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
    service_tier: "deferred",
    background: true,
    store: true,
  });

  console.log(`Interaction ID: ${interaction.id}`);
  console.log(`Status: ${interaction.status}`);
  console.log(`Service tier: ${interaction.service_tier}`);
  return interaction.id ?? "";
}

await createDeferredInteraction("PROJECT_ID");

L'output è simile al seguente:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Python

from google import genai

def create_deferred_interaction(project_id: str) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    interaction = client.interactions.create(
        model="gemini-4-argon",
        input=(
            "In two sentences, explain how a circuit breaker differs from "
            "exponential backoff in a distributed microservice architecture."
        ),
        service_tier="deferred",
        background=True,
        store=True,
    )

    print(f"Interaction ID: {interaction.id}")
    print(f"Status: {interaction.status}")
    print(f"Service tier: {interaction.service_tier}")
    return interaction.id or ""

create_deferred_interaction("PROJECT_ID")

L'output è simile al seguente:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Esegui il polling dello stato e recupera l'utilizzo dei token

Esegui il polling di interactions.get con backoff mentre status è queued o in_progress. Quando il turno raggiunge uno stato finale, leggi output_text e usage.

Il livello Deferred mira a completare il 95% dei turni entro 24 ore senza uno SLA di latenza supportato da credito. La tabella seguente descrive i valori status di una risorsa Interaction:

Stato Finale Significato e passaggio successivo
queued No Accettata e in attesa di capacità. Esegui il polling di interactions.get con backoff. Non richiedere ancora stream=true.
in_progress No In esecuzione. Continua a eseguire il polling di interactions.get o collega uno stream SSE con stream=true.
requires_action Sì Il turno è terminato con un passaggio function_call emesso dal modello. Esegui lo strumento, quindi crea un nuovo turno con previous_interaction_id.
requires_continuation Sì Un turno di decodifica lungo è stato interrotto con un output parziale e un continuation_token. Riprendi con previous_interaction_id e continuation_token, ometti input e aumenta max_output_tokens.
completed Sì Il turno è terminato. Leggi output_text e usage o passa id come previous_interaction_id al turno successivo.
incomplete Sì Il turno è stato interrotto in anticipo, ad esempio quando ha raggiunto max_output_tokens. Esamina i steps e i usage parziali.
failed Sì Il turno ha riscontrato un errore di runtime o ha superato la finestra di completamento di 24 ore. L'API non utilizza uno stato expired. Controlla error, quindi invia una nuova richiesta.
cancelled Sì Una chiamata a interactions.cancel ha interrotto il turno prima del completamento.

Se un turno di decodifica lunga termina come requires_continuation, riprendilo chiamando interactions.create con previous_interaction_id, continuation_token, background=true, store=true e service_tier="deferred". Ometti input e imposta max_output_tokens su un valore superiore ai token generati finora. Per scoprire come viene fatturato ogni stato finale, consulta Prezzi e fatturazione.

Prima di eseguire un esempio, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • INTERACTION_ID: l'ID interazione restituito quando hai creato la chiamata al modello differita, ad esempio v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

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

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • INTERACTION_ID: l'ID interazione restituito quando hai creato la chiamata al modello differita, ad esempio v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

Metodo HTTP e URL:

GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID

Per inviare la richiesta, espandi una di queste opzioni:

La risposta restituisce un payload JSON simile al seguente:

{
  "id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "status": "completed",
  "service_tier": "deferred",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 27,
    "total_output_tokens": 41,
    "total_tokens": 68
  }
}

Node.js

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

const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForDeferredInteraction(projectId, interactionId) {
  const ai = new GoogleGenAI({
    enterprise: true,
    project: projectId,
    location: "global",
  });

  let delayMs = 5000;
  let current = await ai.interactions.get(interactionId);

  while (PENDING_STATES.has(current.status)) {
    await sleep(delayMs);
    delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
    current = await ai.interactions.get(interactionId);
  }

  console.log(`Status: ${current.status}`);
  if (current.status === "failed") {
    throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
  }
  if (current.output_text) {
    console.log(current.output_text);
  }
  if (current.usage) {
    console.log(`Input tokens: ${current.usage.total_input_tokens}`);
    console.log(`Output tokens: ${current.usage.total_output_tokens}`);
    console.log(`Total tokens: ${current.usage.total_tokens}`);
  }
  return current.output_text ?? "";
}

await waitForDeferredInteraction(
  "PROJECT_ID",
  "INTERACTION_ID",
);

L'output è simile al seguente:

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

Python

import time
from google import genai

PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0

def wait_for_deferred_interaction(
    project_id: str,
    interaction_id: str,
) -> str:
    client = genai.Client(
        enterprise=True,
        project=project_id,
        location="global",
    )

    delay_seconds = 5.0
    current = client.interactions.get(interaction_id)

    while current.status in PENDING_STATES:
        time.sleep(delay_seconds)
        delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
        current = client.interactions.get(interaction_id)

    print(f"Status: {current.status}")
    if current.status == "failed":
        raise RuntimeError(f"Deferred turn failed: {current.error}")
    if current.output_text:
        print(current.output_text)
    if current.usage:
        print(f"Input tokens: {current.usage.total_input_tokens}")
        print(f"Output tokens: {current.usage.total_output_tokens}")
        print(f"Total tokens: {current.usage.total_tokens}")
    return current.output_text or ""

wait_for_deferred_interaction(
    "PROJECT_ID",
    "INTERACTION_ID",
)

L'output è simile al seguente:

Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68

(Facoltativo) Trasmetti l'output in streaming durante l'esecuzione di una chiamata

Dopo che interactions.get segnala status="in_progress", puoi collegare uno stream Server-Sent Events (SSE) con stream=true e riprendere le connessioni interrotte con last_event_id:

REST

Aggiungi ?stream=true all'URL interactions.get. Durante la riconnessione, aggiungi anche &last_event_id=EVENT_ID, sostituendo EVENT_ID con l'ultimo ID evento ricevuto.

Node.js

Esegui l'iterazione su await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId }), registra event.event_id e leggi event.delta?.text sugli eventi step.delta.

Python

Esegui l'iterazione su client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id), registra event.event_id e leggi event.delta.text sugli eventi step.delta.

Per saperne di più sullo streaming e sulla riconnessione SSE, consulta la guida per gli sviluppatori dell'API Interactions.

Concatenare workflow differiti multi-turno

Continua una conversazione multi-turn o restituisci i risultati dell'esecuzione dello strumento passando il id di un'interazione completed o requires_action in previous_interaction_id. I campi con ambito di turno, come tools, system_instruction e generation_config, non vengono trasferiti automaticamente, quindi trasmettili a ogni turno che li richiede. I turni concatenati rimangono idonei per la memorizzazione nella cache del contesto implicito, anche se i prefissi memorizzati nella cache potrebbero scadere durante le attese in coda di più ore. Per gli schemi dei passaggi dei risultati degli strumenti, consulta la guida per gli sviluppatori dell'API Interactions.

Prima di eseguire un esempio, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • PREVIOUS_INTERACTION_ID: l'ID del turno completed o requires_action precedente, ad esempio v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

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

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • PREVIOUS_INTERACTION_ID: l'ID interazione completato o per cui è richiesta un'azione del turno precedente, ad esempio v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions

Corpo JSON della richiesta:

{
  "model": "gemini-4-argon",
  "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
  "input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  "service_tier": "deferred",
  "background": true,
  "store": true
}

Per inviare la richiesta, espandi una di queste opzioni:

La risposta restituisce un payload JSON simile al seguente:

{
  "id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "model": "gemini-4-argon",
  "previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
  "status": "queued",
  "service_tier": "deferred",
  "steps": []
}

Node.js

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: "PROJECT_ID",
  location: "global",
});

const followUp = await ai.interactions.create({
  model: "gemini-4-argon",
  previous_interaction_id: "PREVIOUS_INTERACTION_ID",
  input:
    "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
  service_tier: "deferred",
  background: true,
  store: true,
});

console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);

L'output è simile al seguente:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

follow_up = client.interactions.create(
    model="gemini-4-argon",
    previous_interaction_id="PREVIOUS_INTERACTION_ID",
    input=(
        "Draft a one-paragraph rollout checklist for adding a circuit "
        "breaker to a payment gateway client without causing false trips."
    ),
    service_tier="deferred",
    background=True,
    store=True,
)

print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")

L'output è simile al seguente:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Annulla una chiamata al modello differita

Per interrompere un'interazione differita il cui status è queued o in_progress, chiama interactions.cancel. La chiamata di interactions.cancel su un'interazione in qualsiasi altro stato restituisce HTTP 409 ("code": "aborted"). Per scoprire in che modo l'annullamento influisce sulla fatturazione, consulta Prezzi e fatturazione.

Prima di eseguire un esempio, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • INTERACTION_ID: l'ID di un'interazione queued o in_progress, ad esempio v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

REST

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

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • INTERACTION_ID: l'ID di un'interazione in coda o in corso da annullare, ad esempio v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

Metodo HTTP e URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel

Per inviare la richiesta, espandi una di queste opzioni:

La risposta restituisce un payload JSON simile al seguente:

{
  "id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
  "model": "gemini-4-argon",
  "status": "cancelled",
  "service_tier": "deferred"
}

Node.js

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: "PROJECT_ID",
  location: "global",
});

const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);

L'output è il seguente:

Status: cancelled

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")

L'output è il seguente:

Status: cancelled

Prezzi, quote e controlli di sicurezza

Esamina le regole di fatturazione, le quote, i limiti di payload e i controlli di sicurezza prima di eseguire i workload di produzione nel livello Deferred.

Prezzi e fatturazione

Le chiamate al modello differite vengono fatturate con uno sconto del 50% rispetto alle tariffe standard con pagamento a consumo per i token di input, output e ragionamento. La fatturazione segue queste regole:

  • Cumulo degli sconti: lo sconto differito si somma agli sconti contrattuali e agli sconti sui token di memorizzazione nella cache del contesto implicita, applicandosi alla tariffa memorizzata nella cache.
  • Nessun fallback alle tariffe standard: le richieste differite non vengono mai trasferite o sottoposte a downgrade a PayGo standard, pertanto non vengono fatturate alle tariffe on demand non scontate.
  • Fatturazione per chiamata al modello: viene fatturata ogni chiamata al modello effettuata da un turno. Le svolte che terminano con completed, incomplete, requires_action o requires_continuation vengono fatturate alla tariffa differita.
  • Turni annullati: un turno che annulli mentre è queued non viene fatturato. Se annulli un turno mentre è in_progress, le chiamate al modello già avviate vengono fatturate, inclusa una chiamata interrotta a metà generazione.
  • Turni non riusciti: i turni di una singola chiamata che terminano come failed, inclusi i turni che superano la finestra di completamento di 24 ore, non vengono fatturati. In un loop di strumenti lato server in più passaggi, le chiamate al modello completate prima di un errore vengono fatturate, ma la chiamata non riuscita no.
  • Turni concatenati: ogni turno di una catena previous_interaction_id viene fatturato separatamente. L'annullamento di un turno successivo o il mancato completamento di un turno successivo non modifica gli addebiti per i turni precedenti.

Per le tariffe dei token per modello, consulta la pagina dei prezzi di Agent Platform.

Quote, limiti di payload e conservazione

Il livello Deferred non ha una propria quota di chiamate al modello. Le chiamate differite condividono la quota di pagamento a consumo di Flex (flex_requests_per_minute_per_project_per_base_model, 3000 RPM), che viene controllata a ogni chiamata del modello dopo che interactions.create restituisce queued. Le quote dei progetti e i limiti di sistema principali includono:

  • Quote di creazione e contemporaneità: fino a 100 RPM o illimitate per stateful_genai_interaction_creations al momento della creazione. Fino a 500 concurrent_interaction_generations, a seconda del livello di quota.
  • Throughput stateful giornaliero (fisso): 240 GiB al giorno scritti e 480 GiB al giorno letti per progetto.
  • Limiti di payload e conservazione: fino a 9, 75 MiB di corpo HTTP non compresso per chiamata interactions.create e conservazione dello stato per 7 giorni. Le catene supportano fino a 100 URI Cloud Storage (gs://) distinti.

Per la tabella completa delle quote e le istruzioni della console, consulta Quote e limiti del livello Deferred.

Controlli di sicurezza e conformità

Poiché il livello Deferred mette in coda e mantiene lo stato sull'endpoint global, verifica che i controlli di governance supportati corrispondano ai tuoi requisiti di conformità:

Per la matrice completa delle funzionalità, consulta Controlli di sicurezza per l'AI generativa.

Risoluzione dei problemi

La tabella seguente descrive gli errori comuni nel livello Differito e come risolverli:

Errore o stato Cause comuni Risoluzione
400 (error.code: "invalid_request"; endpoint, flag o modello) Endpoint non global, modello non supportato o flag background, store o stream non validi su interactions.create. Scegli come target locations/global con un modello supportato, imposta background=true e store=true e ometti stream=true.
400 (error.code: "invalid_request"; payload, URI o strumenti) Il corpo non compresso supera i 9, 75 MiB, la catena supera i 100 URI gs:// o gli strumenti mcp_server esterni all'interno di VPC-SC. Passa i file di grandi dimensioni come URI gs:// (al massimo 100 per catena) e ometti gli strumenti mcp_server esterni all'interno dei Controlli di servizio VPC.
400 (error.code: "invalid_request" il giorno interactions.create; status: "FAILED_PRECONDITION" il giorno interactions.delete)
  • Viene applicata la policy constraints/vertexai.disableAPIStorage.
  • interactions.create si concatena con un turno queued o in_progress oppure imposta input su requires_continuation.
  • interactions.delete ha come target una svolta queued o in_progress.
  • Utilizza un progetto che consenta la persistenza dello stato dell'API.
  • Concatena solo sulle curve finali. Su requires_continuation, passa continuation_token e ometti input.
  • Annulla i turni attivi prima di eliminarli.
401 (status: "UNAUTHENTICATED" o error.code: "authentication") Le tue credenziali gcloud CLI (esempi REST) o ADC (esempi SDK Google Gen AI) sono mancanti o scadute. Per gli esempi REST, esegui gcloud auth login. Per gli esempi dell'SDK Google Gen AI, esegui gcloud auth application-default login. Quindi, riprova a inviare la richiesta.
403 (status: "PERMISSION_DENIED" o error.code: "permission_denied")
  • Il chiamante non dispone di roles/aiplatform.user.
  • Il chiamante non dispone di storage.objects.get sugli input gs://.
Concedi roles/aiplatform.user. Per gli input di Cloud Storage, concedi anche roles/storage.objectViewer.
404 (error.code: "not_found"; status: "NOT_FOUND" il giorno interactions.delete) L'interazione o previous_interaction_id non esiste o è stata eliminata. Potrebbe anche appartenere a un endpoint non global o essere precedente al periodo di conservazione di 7 giorni. Controlla l'ID interazione sull'endpoint global. Se il turno principale è scaduto, avvia una nuova catena senza previous_interaction_id.
409 (error.code: "aborted") interactions.cancel ha come target un'interazione che è già in uno stato finale: requires_action, requires_continuation, completed, incomplete, failed o cancelled. Controlla prima status con interactions.get. Puoi annullare solo le interazioni queued e in_progress.
429 (error.code: "too_many_requests") Il progetto ha superato una quota per progetto, ad esempio la frequenza di creazione delle interazioni, le generazioni di interazioni simultanee o la velocità effettiva stateful giornaliera.
  • Riprova dopo il ritardo dell'intestazione Retry-After con backoff e jitter.
  • Richiedi aumenti delle quote regolabili in Quote e limiti del livello Deferred. I limiti di portata giornalieri sono fissi.
status="failed"
  • Si è verificato un errore del modello o dello strumento upstream oppure il turno ha superato la finestra di completamento di 24 ore.
  • La richiesta utilizza un modello *-cyber* e il progetto non ha accesso alla lista consentita.
  • Esamina il campo error restituito da interactions.get, quindi invia una nuova richiesta interactions.create.
  • Per i modelli Cyber, verifica l'accesso alla lista consentita con il tuo team dedicato all'account Google Cloud .

Passaggi successivi

Esplora le guide e la documentazione di riferimento correlate per i workload Gemini asincroni e stateful: