Utilisez le niveau différé pour exécuter des appels de modèle Gemini asynchrones et multitours pour des agents personnalisés à un tarif réduit sur Gemini Enterprise Agent Platform. Sur l'API Interactions, Agent Platform met en file d'attente chaque tour différé pour une exécution en arrière-plan dans un délai cible de 24 heures et conserve l'état pendant sept jours.
Le niveau différé convient aux charges de travail d'agent tolérantes à la latence qui nécessitent un contrôle par tour, comme les suivantes :
- Agents de codage et de sécurité en plusieurs étapes : analyses des failles des dépôts, migrations de code automatisées et tri des régressions.
- Pipelines de documents et de recherche : examens de conception technique, backtesting financier et synthèse multi-documents avec appel d'outils.
- Évaluations d'agents hors connexion : benchmarks de qualité à grande échelle qui enchaînent les tours
previous_interaction_idsans contraintes de latence en temps réel.
Pour comparer tous les modèles de calcul, consultez Options de consommation. Pour programmer des agents Agent Development Kit (ADK) ou des exécutions gérées sur l'agent Gemini Deep Research, consultez Programmation d'agents autonomes.
Modèles et emplacements compatibles
Le niveau différé n'est compatible qu'avec le point de terminaison global (locations/global sur aiplatform.googleapis.com). L'envoi d'une requête avec service_tier="deferred" à un point de terminaison régional ou aux points de terminaison multirégionaux us ou eu renvoie l'erreur HTTP 400 ("code": "invalid_request").
Les modèles Gemini principaux suivants sont compatibles avec le niveau différé sur le point de terminaison 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)
Si votre projet dispose d'un accès à la liste d'autorisation via votre équipe chargée du compte Google Cloud , vous pouvez également utiliser les modèles Cyber suivants :
- Gemini 4 Carbon pour la cybersécurité (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Avant de commencer
Dans un projet Google Cloud existant pour lequel la facturation est activée, effectuez les étapes de configuration préalables suivantes :
-
Connectez-vous à votre compte Google.
Si vous n'en possédez pas déjà un, vous devez en créer un.
-
Installez la Google Cloud CLI.
-
Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.
-
Pour initialiser la gcloud CLI, exécutez la commande suivante :
gcloud init -
Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.
Activez l'API Agent Platform si ce n'est pas déjà fait :
Rôles requis pour activer les API
Pour activer des API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.gcloud services enable aiplatform.googleapis.com
-
Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur :
gcloud auth application-default login
Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.
Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.
-
Installez la Google Cloud CLI.
-
Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.
-
Pour initialiser la gcloud CLI, exécutez la commande suivante :
gcloud init -
Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.
Activez l'API Agent Platform si ce n'est pas déjà fait :
Rôles requis pour activer les API
Pour activer des API, vous devez disposer de l'autorisation
serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.gcloud services enable aiplatform.googleapis.com
-
Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur :
gcloud auth application-default login
Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.
Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.
Rôles requis
Pour obtenir les autorisations nécessaires pour créer, surveiller et annuler des appels de modèle différés, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet Google Cloud :
-
Créer, interroger, annuler et supprimer des interactions différées : Utilisateur Agent Platform (
roles/aiplatform.user) -
Surveiller les interactions différées (lecture seule) : Lecteur Agent Platform (
roles/aiplatform.viewer) -
Lire des fichiers d'entrée multimodaux à partir de Cloud Storage (facultatif) : Lecteur des objets de l'espace de stockage (
roles/storage.objectViewer)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
Installer le SDK Google Gen AI
Si vous utilisez une bibliothèque cliente, installez ou mettez à niveau le SDK Google Gen AI (@google/genai >= 2.32.0 ou google-genai >= 2.34.0) dans votre environnement de développement :
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
Créer et gérer des appels de modèle différés
Exécutez les procédures suivantes dans l'environnement que vous avez configuré dans la section Avant de commencer. Les exemples REST s'authentifient avec vos identifiants gcloud CLI, et les exemples du SDK Google Gen AI utilisent les Identifiants par défaut de l'application (ADC). Si un appel renvoie une erreur, consultez la section Dépannage.
Créer un appel de modèle différé
Envoyez un tour asynchrone en appelant interactions.create avec service_tier="deferred", background=true et store=true. Omettez stream ou définissez-le sur false. Avant d'exécuter un exemple, remplacez PROJECT_ID par l'ID de votre projet Google Cloud , par exemple my-agent-project.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.
Méthode HTTP et URL :
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Corps JSON de la requête :
{
"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
}
Pour envoyer votre requête, développez l'une des options suivantes :
La réponse renvoie une charge utile JSON semblable à celle-ci :
{
"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");
Le résultat ressemble à ce qui suit :
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")
Le résultat ressemble à ce qui suit :
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Interroger l'état et récupérer l'utilisation des jetons
Interrogez interactions.get avec intervalle exponentiel entre les tentatives tant que status est queued ou in_progress. Lorsque le tour atteint un état final, lisez output_text et usage.
Le niveau différé vise à effectuer 95 % des tours en 24 heures, sans SLA de latence basé sur des crédits. Le tableau suivant décrit les valeurs status d'une ressource Interaction :
| État | Version finale | Signification et étape suivante |
|---|---|---|
queued |
Non | Acceptée et en attente de capacité. Interrogez interactions.get avec un intervalle entre les tentatives. Ne demandez pas encore stream=true. |
in_progress |
Non | En cours d'exécution. Continuez à interroger interactions.get ou associez un flux SSE à stream=true. |
requires_action |
Oui | Le tour s'est terminé sur une étape function_call émise par le modèle. Exécutez l'outil, puis créez un tour avec previous_interaction_id. |
requires_continuation |
Oui | Un tour de décodage long s'est arrêté avec une sortie partielle et un continuation_token. Reprenez avec previous_interaction_id et continuation_token, omettez input et augmentez max_output_tokens. |
completed |
Oui | Le tour est terminé. Lisez output_text et usage, ou passez id en tant que previous_interaction_id au tour suivant. |
incomplete |
Oui | Le tour s'est arrêté prématurément, par exemple lorsqu'il a atteint max_output_tokens. Inspectez les fichiers partiels steps et usage. |
failed |
Oui | Le tour a rencontré une erreur d'exécution ou a dépassé le délai de 24 heures. L'API n'utilise pas d'état expired. Inspectez error, puis envoyez une nouvelle demande. |
cancelled |
Oui | Un appel à interactions.cancel a arrêté le tour avant qu'il ne se termine. |
Si un tour de décodage long se termine par requires_continuation, reprenez-le en appelant interactions.create avec previous_interaction_id, continuation_token, background=true, store=true et service_tier="deferred". Omettez input et définissez max_output_tokens sur une valeur supérieure à celle des jetons générés jusqu'à présent. Pour savoir comment chaque état final est facturé, consultez Tarifs et facturation.
Avant d'exécuter un exemple, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.INTERACTION_ID: ID d'interaction renvoyé lorsque vous avez créé l'appel de modèle différé, par exemplev1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.INTERACTION_ID: ID d'interaction renvoyé lorsque vous avez créé l'appel de modèle différé, par exemplev1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Méthode HTTP et URL :
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
Pour envoyer votre requête, développez l'une des options suivantes :
La réponse renvoie une charge utile JSON semblable à celle-ci :
{
"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",
);
Le résultat ressemble à ce qui suit :
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",
)
Le résultat ressemble à ce qui suit :
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
Facultatif : Diffuser la sortie pendant l'exécution d'un appel
Une fois que interactions.get a signalé status="in_progress", vous pouvez associer un flux d'événements envoyés par le serveur (SSE) à stream=true et reprendre les connexions interrompues avec last_event_id :
REST
Ajoutez ?stream=true à l'URL interactions.get. Lors de la reconnexion, ajoutez également &last_event_id=EVENT_ID, en remplaçant EVENT_ID par l'ID du dernier événement reçu.
Node.js
Effectuez une itération sur await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId }), enregistrez event.event_id et lisez event.delta?.text sur les événements step.delta.
Python
Effectuez une itération sur client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id), enregistrez event.event_id et lisez event.delta.text sur les événements step.delta.
Pour en savoir plus sur le streaming et la reconnexion SSE, consultez le guide du développeur de l'API Interactions.
Enchaîner des workflows différés multitours
Poursuivez une conversation multitour ou renvoyez les résultats de l'exécution de l'outil en transmettant le id d'une interaction completed ou requires_action dans previous_interaction_id. Les champs limités au tour, tels que tools, system_instruction et generation_config, ne sont pas reportés automatiquement. Transmettez-les donc à chaque tour qui en a besoin. Les tours enchaînés restent éligibles à la mise en cache implicite du contexte, bien que les préfixes mis en cache puissent expirer lors des attentes de plusieurs heures dans la file d'attente. Pour connaître les schémas d'étape de résultat d'outil, consultez le guide du développeur de l'API Interactions.
Avant d'exécuter un exemple, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.PREVIOUS_INTERACTION_ID: ID du tourcompletedourequires_actionprécédent, par exemplev1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.PREVIOUS_INTERACTION_ID: ID de l'interaction terminée ou nécessitant une action lors du tour précédent, par exemplev1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
Méthode HTTP et URL :
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Corps JSON de la requête :
{
"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
}
Pour envoyer votre requête, développez l'une des options suivantes :
La réponse renvoie une charge utile JSON semblable à celle-ci :
{
"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})`);
Le résultat ressemble à ce qui suit :
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})")
Le résultat ressemble à ce qui suit :
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Annuler un appel de modèle différé
Pour arrêter une interaction différée dont l'état (status) est queued ou in_progress, appelez interactions.cancel. L'appel de interactions.cancel sur une interaction dans un autre état renvoie l'erreur HTTP 409 ("code": "aborted"). Pour savoir comment l'annulation affecte la facturation, consultez Tarifs et facturation.
Avant d'exécuter un exemple, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.INTERACTION_ID: ID d'une interactionqueuedouin_progress, par exemplev1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
PROJECT_ID: ID de votre projet Google Cloud , par exemplemy-agent-project.INTERACTION_ID: ID d'une interaction en file d'attente ou en cours à annuler, par exemplev1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
Méthode HTTP et URL :
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
Pour envoyer votre requête, développez l'une des options suivantes :
La réponse renvoie une charge utile JSON semblable à celle-ci :
{
"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}`);
Le résultat est le suivant :
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}")
Le résultat est le suivant :
Status: cancelled
Tarifs, quotas et contrôles de sécurité
Examinez les règles de facturation, les quotas, les limites de charge utile et les contrôles de sécurité avant d'exécuter des charges de travail de production sur le niveau différé.
Tarification et facturation
Les appels de modèle différés sont facturés avec une remise de 50 % par rapport aux tarifs de paiement à l'usage standards pour les jetons d'entrée, de sortie et de raisonnement. La facturation suit les règles suivantes :
- Cumul des remises : la remise différée se cumule avec les remises contractuelles et les remises sur les jetons de mise en cache de contexte implicite, en s'appliquant en plus du tarif mis en cache.
- Pas de basculement vers les tarifs standards : les requêtes différées ne sont jamais transférées ni rétrogradées vers le paiement à l'usage standard. Elles ne sont donc pas facturées aux tarifs à la demande sans remise.
- Facturation par appel de modèle : chaque appel de modèle effectué par un tour est facturé.
Les tours qui se terminent par
completed,incomplete,requires_actionourequires_continuationsont facturés au tarif différé. - Tours annulés : un tour que vous annulez alors qu'il est
queuedn'est pas facturé. Si vous annulez un tour alors qu'il estin_progress, les appels de modèle qui ont déjà commencé sont facturés, y compris un appel interrompu en cours de génération. - Tours ayant échoué : les tours à appel unique qui se terminent par
failed, y compris ceux qui dépassent la période d'achèvement de 24 heures, ne sont pas facturés. Dans une boucle d'outil côté serveur en plusieurs étapes, les appels de modèle terminés avant un échec sont facturés, mais pas l'appel ayant échoué. - Tours enchaînés : chaque tour d'une chaîne
previous_interaction_idest facturé séparément. L'annulation d'un tour ultérieur ou l'échec d'un tour ultérieur ne modifie pas les frais des tours précédents.
Pour connaître les tarifs des jetons par modèle, consultez la page des tarifs d'Agent Platform.
Quotas, limites de charge utile et conservation
Le niveau différé ne dispose pas de son propre quota d'appels de modèle. Les appels différés partagent le quota de paiement à l'usage Flex (flex_requests_per_minute_per_project_per_base_model, 3 000 RPM), qui est vérifié à chaque appel de modèle après que interactions.create a renvoyé queued. Les principaux quotas de projet et limites du système sont les suivants :
- Quotas de création et de simultanéité : jusqu'à 100 RPM ou illimité pour
stateful_genai_interaction_creationsau moment de la création. Jusqu'à 500concurrent_interaction_generations, selon votre niveau de quota. - Débit avec état quotidien (fixe) : 240 Gio par jour écrits et 480 Gio par jour lus par projet.
- Limites de charge utile et de conservation : jusqu'à 9, 75 Mio de corps HTTP non compressé par appel
interactions.createet conservation de l'état pendant sept jours. Les chaînes peuvent accepter jusqu'à 100 URI Cloud Storage (gs://) distincts.
Pour obtenir le tableau complet des quotas et les instructions de la console, consultez Quotas et limites du niveau différé.
Commandes de sécurité et de conformité
Étant donné que le niveau différé met en file d'attente et conserve l'état sur le point de terminaison global, vérifiez que les contrôles de gouvernance compatibles correspondent à vos exigences de conformité :
- Contrôles compatibles : VPC Service Controls (VPC-SC ; les outils
mcp_serverexternes ne sont pas autorisés dans un périmètre), Access Transparency (AXT), Cloud Audit Logs et FedRAMP High. - Contrôles non compatibles : conservation des données nulle sans état (
store=falseet l'application deconstraints/vertexai.disableAPIStoragerenvoient tous deux HTTP400avec"code": "invalid_request"), clés de chiffrement gérées par le client (CMEK), résidence des données, DoD IL5 et ITAR.
Pour obtenir la matrice complète des fonctionnalités, consultez Contrôles de sécurité pour l'IA générative.
Résoudre les problèmes
Le tableau suivant décrit les erreurs courantes sur le niveau différé et comment les résoudre :
| Erreur ou état | Causes courantes | Solution |
|---|---|---|
400 (error.code: "invalid_request" ; point de terminaison, options ou modèle) |
Point de terminaison non-global, modèle non compatible, ou options background, store ou stream non valides sur interactions.create. |
Ciblez locations/global avec un modèle compatible, définissez background=true et store=true, et omettez stream=true. |
400 (error.code: "invalid_request" ; charge utile, URI ou outils) |
Le corps non compressé dépasse 9, 75 Mio, la chaîne dépasse 100 URI gs:// ou les outils mcp_server externes dans VPC-SC. |
Transmettez les fichiers volumineux en tant qu'URI gs:// (au maximum 100 par chaîne) et omettez les outils mcp_server externes dans VPC-SC. |
400 (error.code: "invalid_request" le interactions.create ; status: "FAILED_PRECONDITION" le interactions.delete) |
|
|
401 (status: "UNAUTHENTICATED" ou error.code: "authentication") |
Vos identifiants gcloud CLI (exemples REST) ou ADC (exemples du SDK Google Gen AI) sont manquants ou ont expiré. | Pour obtenir des exemples REST, exécutez gcloud auth login. Pour obtenir des exemples de SDK Google Gen AI, exécutez gcloud auth application-default login. puis réessayez d'envoyer la requête. |
403 (status: "PERMISSION_DENIED" ou error.code: "permission_denied") |
|
Accordez l'autorisation roles/aiplatform.user. Pour les entrées Cloud Storage, accordez également roles/storage.objectViewer. |
404 (error.code: "not_found" ; status: "NOT_FOUND" le interactions.delete) |
L'interaction ou previous_interaction_id n'existe pas ou a été supprimée. Il peut également appartenir à un point de terminaison non-global ou être plus ancien que la période de conservation de sept jours. |
Vérifiez l'ID d'interaction sur le point de terminaison global. Si le tour parent a expiré, démarrez une nouvelle chaîne sans previous_interaction_id. |
409 (error.code: "aborted") |
interactions.cancel cible une interaction qui est déjà dans un état final : requires_action, requires_continuation, completed, incomplete, failed ou cancelled. |
Vérifiez d'abord status avec interactions.get. Vous ne pouvez annuler que les interactions queued et in_progress. |
429 (error.code: "too_many_requests") |
Le projet a dépassé un quota par projet, tel que le taux de création d'interactions, les générations d'interactions simultanées ou le débit avec état quotidien. |
|
status="failed" |
|
|
Étapes suivantes
Consultez les guides et la documentation de référence associés pour les charges de travail Gemini asynchrones et avec état :
- Comparez les modèles de calcul dans Options de consommation.
- Créez des applications multitours avec état dans le guide du développeur de l'API Interactions.
- Planifiez des agents ADK et des exécutions de recherche gérées dans Planification d'agents autonomes.
- Explorez les schémas de méthode dans la documentation de référence de l'API Interactions.