Utiliser le niveau différé

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_id sans 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 :

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 :

Avant de commencer

Dans un projet Google Cloud existant pour lequel la facturation est activée, effectuez les étapes de configuration préalables suivantes :

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Installez la Google Cloud CLI.

  3. 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.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante :

    gcloud init
  5. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.

  6. 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
  7. 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.

  8. Installez la Google Cloud CLI.

  9. 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.

  10. Pour initialiser la gcloud CLI, exécutez la commande suivante :

    gcloud init
  11. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.

  12. 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
  13. 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  :

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 exemple my-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 exemple my-agent-project.
  • INTERACTION_ID : ID d'interaction renvoyé lorsque vous avez créé l'appel de modèle différé, par exemple v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud , par exemple my-agent-project.
  • INTERACTION_ID : ID d'interaction renvoyé lorsque vous avez créé l'appel de modèle différé, par exemple v1_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 exemple my-agent-project.
  • PREVIOUS_INTERACTION_ID : ID du tour completed ou requires_action précédent, par exemple v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud , par exemple my-agent-project.
  • PREVIOUS_INTERACTION_ID : ID de l'interaction terminée ou nécessitant une action lors du tour précédent, par exemple v1_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 exemple my-agent-project.
  • INTERACTION_ID : ID d'une interaction queued ou in_progress, par exemple v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud , par exemple my-agent-project.
  • INTERACTION_ID : ID d'une interaction en file d'attente ou en cours à annuler, par exemple v1_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_action ou requires_continuation sont facturés au tarif différé.
  • Tours annulés : un tour que vous annulez alors qu'il est queued n'est pas facturé. Si vous annulez un tour alors qu'il est in_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_id est 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_creations au moment de la création. Jusqu'à 500 concurrent_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.create et 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é :

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)
  • La règle constraints/vertexai.disableAPIStorage est appliquée.
  • interactions.create enchaîne sur un virage queued ou in_progress, ou définit input sur requires_continuation.
  • interactions.delete cible un tour queued ou in_progress.
  • Utilisez un projet qui permet de conserver l'état de l'API.
  • Enchaînez uniquement sur les derniers virages. Sur requires_continuation, transmettez continuation_token et omettez input.
  • Annulez les tours actifs avant de les supprimer.
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")
  • L'appelant ne dispose pas de l'autorisation roles/aiplatform.user.
  • L'appelant ne dispose pas de l'autorisation storage.objects.get sur les entrées gs://.
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.
  • Réessayez après le délai d'en-tête Retry-After avec un intervalle entre les tentatives et une gigue.
  • Demandez des augmentations de quotas ajustables dans Quotas et limites du niveau différé. Les limites de débit quotidiennes sont fixes.
status="failed"
  • Une défaillance du modèle ou de l'outil en amont s'est produite, ou le tour a dépassé la fenêtre d'achèvement de 24 heures.
  • La requête utilise un modèle *-cyber* et le projet ne dispose pas d'un accès à la liste d'autorisation.
  • Inspectez le champ error renvoyé par interactions.get, puis envoyez une nouvelle requête interactions.create.
  • Pour les modèles Cyber, confirmez l'accès à la liste d'autorisation auprès de l'équipe chargée de votre compte Google Cloud .

Étapes suivantes

Consultez les guides et la documentation de référence associés pour les charges de travail Gemini asynchrones et avec état :