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_idturni 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:
- Gemini 4 Carbon (
gemini-4-carbon) - Gemini 4 Argon (
gemini-4-argon) - Gemini 3.8 Flash (
gemini-3.8-flash) - Gemini 3.7 Flash (
gemini-3.7-flash) - Gemini 3.6 Flash (
gemini-3.6-flash) - Gemini 3.5 Flash-Lite (
gemini-3.5-flash-lite) - Gemini 3.5 Flash (
gemini-3.5-flash) - Gemini 3.1 Flash-Lite (
gemini-3.1-flash-lite) - Gemini 3.1 Pro (
gemini-3.1-pro-preview)
Se il tuo progetto ha accesso alla lista consentita tramite il team dedicato all'account Google Cloud , puoi utilizzare anche i seguenti modelli Cyber:
- Gemini 4 Carbon per la cybersicurezza (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Prima di iniziare
In un progetto Google Cloud esistente con fatturazione abilitata, completa i seguenti passaggi di configurazione dei prerequisiti:
-
Accedi al tuo Account Google.
Se non ne hai già uno, registrati per creare un nuovo account.
-
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Verifica di disporre delle autorizzazioni necessarie per completare questa guida.
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
-
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.
-
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Verifica di disporre delle autorizzazioni necessarie per completare questa guida.
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
-
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 esempiomy-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 esempiomy-agent-project.INTERACTION_ID: l'ID interazione restituito quando hai creato la chiamata al modello differita, ad esempiov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
PROJECT_ID: l'ID progetto Google Cloud , ad esempiomy-agent-project.INTERACTION_ID: l'ID interazione restituito quando hai creato la chiamata al modello differita, ad esempiov1_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 esempiomy-agent-project.PREVIOUS_INTERACTION_ID: l'ID del turnocompletedorequires_actionprecedente, ad esempiov1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
PROJECT_ID: l'ID progetto Google Cloud , ad esempiomy-agent-project.PREVIOUS_INTERACTION_ID: l'ID interazione completato o per cui è richiesta un'azione del turno precedente, ad esempiov1_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 esempiomy-agent-project.INTERACTION_ID: l'ID di un'interazionequeuedoin_progress, ad esempiov1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
PROJECT_ID: l'ID progetto Google Cloud , ad esempiomy-agent-project.INTERACTION_ID: l'ID di un'interazione in coda o in corso da annullare, ad esempiov1_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_actionorequires_continuationvengono fatturate alla tariffa differita. - Turni annullati: un turno che annulli mentre è
queuednon 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_idviene 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_creationsal momento della creazione. Fino a 500concurrent_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.createe 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à:
- Controlli supportati:
Controlli di servizio VPC
(VPC-SC; gli strumenti
mcp_serveresterni non sono consentiti all'interno di un perimetro), Access Transparency (AXT), Cloud Audit Logs e FedRAMP High. - Controlli non supportati: conservazione dei dati zero stateless (
store=falsee l'applicazione forzata diconstraints/vertexai.disableAPIStoragerestituiscono entrambe HTTP400con"code": "invalid_request"), chiavi di crittografia gestite dal cliente (CMEK), residenza dei dati, DoD IL5 e ITAR.
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) |
|
|
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") |
|
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. |
|
status="failed" |
|
|
Passaggi successivi
Esplora le guide e la documentazione di riferimento correlate per i workload Gemini asincroni e stateful:
- Confronta i modelli di computing in Opzioni di consumo.
- Crea applicazioni multi-turn stateful nella guida per gli sviluppatori dell'API Interactions.
- Pianifica gli agenti ADK e le esecuzioni di ricerca gestite in Pianificazione degli agenti autonomi.
- Esplora gli schemi dei metodi nel riferimento API Interactions.