使用延迟层级

在 Gemini Enterprise Agent Platform 上,使用 Deferred 层级以折扣价为自定义智能体运行异步、多轮 Gemini 模型调用。在 Interactions API 中,Agent Platform 会将每个延迟的回合排入队列,以便在 24 小时内执行后台操作,并将状态保留 7 天。

延迟层级适合可容忍延迟且需要逐轮控制的智能体工作负载,例如:

  • 多步骤编码和安全智能体:代码库漏洞扫描、自动化代码迁移和回归问题分类。
  • 文档和研究流水线:技术设计审核、财务回测以及通过工具调用进行多文档整合。
  • 离线智能体评估:大规模质量基准,可串联 previous_interaction_id 轮对话,不受实时延迟限制。

如需比较所有计算模型,请参阅使用选项。如需在 Gemini Deep Research Agent 上安排智能体开发套件 (ADK) 智能体或托管式运行,请参阅自主智能体安排。

支持的模型和位置

延迟层级仅在 global 端点(aiplatform.googleapis.com 上的 locations/global)上受支持。向区域端点或 us 或 eu 多区域端点发送包含 service_tier="deferred" 的请求会返回 HTTP 400 ("code": "invalid_request")。

以下主线 Gemini 模型支持 global 端点上的延迟层级:

如果您的项目通过 Google Cloud 客户支持团队获得了许可清单访问权限,您还可以使用以下 Cyber 模型:

准备工作

在已启用结算功能的现有 Google Cloud 项目中,完成以下前提条件设置步骤:

  1. 登录您的 Google 账号。

    如果您还没有 Google 账号,请注册新账号。

  2. 安装 Google Cloud CLI。

  3. 如果您使用的是外部身份提供方 (IdP),则必须先使用联合身份登录 gcloud CLI。

  4. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  5. 验证您是否拥有完成本指南所需的权限。

  6. 启用 Agent Platform API(如果尚未启用):

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    gcloud services enable aiplatform.googleapis.com
  7. 如果您使用的是本地 shell,请为您的用户账号创建本地身份验证凭证:

    gcloud auth application-default login

    如果您使用的是 Cloud Shell,则无需执行此操作。

    如果系统返回身份验证错误,并且您使用的是外部身份提供方 (IdP),请确认您已使用联合身份登录 gcloud CLI。

  8. 安装 Google Cloud CLI。

  9. 如果您使用的是外部身份提供方 (IdP),则必须先使用联合身份登录 gcloud CLI。

  10. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  11. 验证您是否拥有完成本指南所需的权限。

  12. 启用 Agent Platform API(如果尚未启用):

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    gcloud services enable aiplatform.googleapis.com
  13. 如果您使用的是本地 shell,请为您的用户账号创建本地身份验证凭证:

    gcloud auth application-default login

    如果您使用的是 Cloud Shell,则无需执行此操作。

    如果系统返回身份验证错误,并且您使用的是外部身份提供方 (IdP),请确认您已使用联合身份登录 gcloud CLI。

所需的角色

如需获得创建、监控和取消延迟模型调用所需的权限,请让您的管理员为您授予 Google Cloud 项目的以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

安装 Google Gen AI SDK

如果您使用客户端库,请在开发环境中安装或升级 Google Gen AI SDK(@google/genai >= 2.32.0 或 google-genai >= 2.34.0):

Node.js

npm install @google/genai@latest

Python

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

创建和管理延迟的模型调用

在准备工作中设置的环境中运行以下过程。REST 示例使用 gcloud CLI 凭证进行身份验证,而 Google Gen AI SDK 示例使用应用默认凭据 (ADC)。如果调用返回错误,请参阅问题排查。

创建延迟模型调用

通过使用 service_tier="deferred"、background=true 和 store=true 调用 interactions.create 来提交异步回合。省略 stream 或将其设置为 false。在运行示例之前,请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID,例如 my-agent-project。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。

HTTP 方法和网址:

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

请求 JSON 正文:

{
  "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
}

如需发送您的请求,请展开以下选项之一:

响应会返回类似以下内容的 JSON 载荷:

{
  "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");

输出类似于以下内容:

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")

输出类似于以下内容:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

轮询状态并检索 token 用量

当 status 为 queued 或 in_progress 时,使用退避算法轮询 interactions.get。当轮次达到最终状态时,读取 output_text 和 usage。

延迟层级旨在 24 小时内完成 95% 的轮次,但不提供有返还保障的延迟时间 SLA。下表介绍了 Interaction 资源的 status 值:

状态 最后 含义和后续步骤
queued 否 已接受,正在等待容量。使用退避算法轮询 interactions.get。请勿请求 stream=true。
in_progress 否 正在运行。继续轮询 interactions.get,或使用 stream=true 附加 SSE 流。
requires_action 是 该轮对话在模型发出的 function_call 步骤结束。运行该工具,然后使用 previous_interaction_id 创建新一轮对话。
requires_continuation 是 长解码轮次在输出部分内容后停止,并返回 continuation_token。使用 previous_interaction_id 和 continuation_token 恢复,省略 input,并引发 max_output_tokens。
completed 是 轮次已结束。在下一轮中,读取 output_text 和 usage,或将 id 作为 previous_interaction_id 传递。
incomplete 是 该轮对话提前停止,例如在达到 max_output_tokens 时。检查部分 steps 和 usage。
failed 是 该轮对话遇到了运行时错误,或超出了 24 小时的完成期限。该 API 不使用 expired 状态。检查 error,然后提交新请求。
cancelled 是 对 interactions.cancel 的调用在回合完成之前停止了该回合。

如果长解码回合以 requires_continuation 结束,请使用 previous_interaction_id、continuation_token、background=true、store=true 和 service_tier="deferred" 调用 interactions.create,以恢复该回合。省略 input,并将 max_output_tokens 设置为高于目前生成的 token 数。如需了解每种最终状态的结算方式,请参阅价格和结算。

在运行示例之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • INTERACTION_ID:创建延迟模型调用时返回的互动 ID,例如 v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • INTERACTION_ID:创建延迟模型调用时返回的互动 ID,例如 v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0。

HTTP 方法和网址:

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

如需发送您的请求,请展开以下选项之一:

响应会返回类似以下内容的 JSON 载荷:

{
  "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",
);

输出类似于以下内容:

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",
)

输出类似于以下内容:

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

可选:在调用运行时流式传输输出

在 interactions.get 报告 status="in_progress" 后,您可以使用 stream=true 附加服务器发送事件 (SSE) 流,并使用 last_event_id 恢复断开的连接:

REST

将 ?stream=true 附加到 interactions.get 网址。重新连接时,还要附加 &last_event_id=EVENT_ID,并将 EVENT_ID 替换为上次收到的事件 ID。

Node.js

在 step.delta 事件中,迭代 await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId })、记录 event.event_id 并读取 event.delta?.text。

Python

在 step.delta 事件中,迭代 client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id)、记录 event.event_id 并读取 event.delta.text。

如需详细了解 SSE 流式传输和重新连接,请参阅 Interactions API 开发者指南。

串联多轮延迟工作流

通过在 previous_interaction_id 中传递 completed 或 requires_action 交互的 id,继续多轮对话或返回工具执行结果。tools、system_instruction 和 generation_config 等轮次级字段不会自动沿用,因此请在每个需要这些字段的轮次中传递它们。链式轮次仍可使用隐式上下文缓存,但缓存的前缀可能会在长达数小时的队列等待中过期。如需了解工具结果步骤架构,请参阅 Interactions API 开发者指南。

在运行示例之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • PREVIOUS_INTERACTION_ID:前一个 completed 或 requires_action 回合的 ID,例如 v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • PREVIOUS_INTERACTION_ID:上一轮中已完成或需要采取行动的互动 ID,例如 v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0。

HTTP 方法和网址:

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

请求 JSON 正文:

{
  "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
}

如需发送您的请求,请展开以下选项之一:

响应会返回类似以下内容的 JSON 载荷:

{
  "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})`);

输出类似于以下内容:

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})")

输出类似于以下内容:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

取消延迟的模型调用

如需停止 status 为 queued 或 in_progress 的延迟互动,请调用 interactions.cancel。对处于任何其他状态的互动调用 interactions.cancel 会返回 HTTP 409 ("code": "aborted")。如需了解取消操作对结算有何影响,请参阅价格和结算。

在运行示例之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • INTERACTION_ID:queued 或 in_progress 互动的 ID,例如 v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目 ID,例如 my-agent-project。
  • INTERACTION_ID:要取消的已加入队列或正在进行的互动的 ID,例如 v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ。

HTTP 方法和网址:

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

如需发送您的请求,请展开以下选项之一:

响应会返回类似以下内容的 JSON 载荷:

{
  "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}`);

输出如下所示:

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}")

输出如下所示:

Status: cancelled

价格、配额和安全控制

在延迟层级上运行生产工作负载之前,请先查看结算规则、配额、载荷限制和安全控制措施。

价格和结算

与标准随用随付费率相比,延迟模型调用的输入、输出和思考 token 费用可享受 50% 的折扣。结算遵循以下规则:

  • 折扣叠加:延期折扣可与合约折扣和隐式上下文缓存 token 折扣叠加,在缓存费率的基础上应用。
  • 不会回退到标准费率:延迟请求绝不会溢出或降级到标准随用随付,因此不会按无折扣的按需费率计费。
  • 按模型调用计费:系统会针对一轮对话中的每次模型调用进行计费。 以 completed、incomplete、requires_action 或 requires_continuation 结束的轮次按延迟费率计费。
  • 已取消的回合:如果您在回合处于 queued 状态时取消该回合,则系统不会向您收取费用。如果您在轮次处于 in_progress 状态时取消该轮次,则系统会对已开始的模型调用(包括在生成过程中中断的调用)计费。
  • 失败的回合:以 failed 结束的单次调用回合(包括超出 24 小时完成窗口的回合)不会计费。在多步服务器端工具循环中,失败前完成的模型调用会产生费用,但失败的调用不会。
  • 链式轮次:previous_interaction_id 链中的每个轮次单独计费。取消后续回合或后续回合失败不会改变先前回合的费用。

如需了解每个模型的 token 费率,请参阅 Agent Platform 价格页面。

配额、载荷限制和保留

延迟层级没有自己的模型调用配额。延迟调用会共享 Flex 随用随付配额(flex_requests_per_minute_per_project_per_base_model,3,000 RPM),在 interactions.create 返回 queued 后,系统会在每次模型调用时检查该配额。关键项目配额和系统限制包括:

  • 创建和并发配额:创建时,stateful_genai_interaction_creations 的 RPM 上限为 100 或无限制。最多 500 个concurrent_interaction_generations,具体取决于您的配额层级。
  • 每日有状态吞吐量(固定):每个项目每天写入 240 GiB,读取 480 GiB。
  • 载荷和保留限制:每次 interactions.create 调用最多可传输 9.75 MiB 未压缩的 HTTP 正文,状态保留期为 7 天。链最多支持 100 个不同的 Cloud Storage (gs://) URI。

如需查看完整的配额表和控制台说明,请参阅延迟层级配额和限制。

安全与合规控制

由于延迟层会在 global 端点上将状态加入队列并保留,因此请验证其支持的治理控制措施是否符合您的合规性要求:

  • 支持的控制措施:VPC Service Controls(VPC-SC;边界内不允许使用外部 mcp_server 工具)、Access Transparency (AXT)、Cloud Audit Logs 和 FedRAMP High。
  • 不受支持的控制措施:无状态零数据保留(store=false和强制执行 constraints/vertexai.disableAPIStorage 都会返回 HTTP 400 和 "code": "invalid_request")、客户管理的加密密钥 (CMEK)、数据驻留、DoD IL5 和 ITAR。

如需查看完整的功能矩阵,请参阅针对生成式 AI 的安全控制措施。

问题排查

下表介绍了延迟层级中的常见错误以及解决方法:

错误或状态 常见原因 解决方法
400(error.code: "invalid_request";端点、标志或模型) 非 global 端点、不受支持的模型,或 interactions.create 上存在无效的 background、store 或 stream 标志。 使用支持的模型定位 locations/global,设置 background=true 和 store=true,并省略 stream=true。
400(error.code: "invalid_request";载荷、URI 或工具) 未压缩的正文超过 9.75 MiB、链超过 100 个 gs:// URI,或 VPC-SC 内部存在外部 mcp_server 工具。 以 gs:// URI 的形式传递大文件(每个链最多 100 个),并省略 VPC-SC 中的外部 mcp_server 工具。
400(interactions.create:error.code: "invalid_request";interactions.delete:status: "FAILED_PRECONDITION")
  • 强制执行 constraints/vertexai.disableAPIStorage 政策。
  • interactions.create 链接到 queued 或 in_progress 转弯,或在 requires_continuation 上设置 input。
  • interactions.delete 针对 queued 或 in_progress 转向。
  • 使用允许 API 状态持久化的项目。
  • 仅在最后一次转弯时进行链式操作。在 requires_continuation 上,传递 continuation_token 并省略 input。
  • 请先取消有效轮次,然后再将其删除。
401(status: "UNAUTHENTICATED" 或 error.code: "authentication") 您的 gcloud CLI 凭证(REST 示例)或 ADC(Google Gen AI SDK 示例)缺失或已过期。 对于 REST 示例,请运行 gcloud auth login。对于 Google Gen AI SDK 示例,请运行 gcloud auth application-default login。然后重试请求。
403(status: "PERMISSION_DENIED" 或 error.code: "permission_denied")
  • 调用方没有 roles/aiplatform.user。
  • 调用方对 gs:// 输入没有 storage.objects.get 权限。
授予 roles/aiplatform.user。对于 Cloud Storage 输入,还需授予 roles/storage.objectViewer。
404(error.code: "not_found";interactions.delete status: "NOT_FOUND") 互动或previous_interaction_id不存在或已被删除。它也可能属于非 global 端点,或者已超过 7 天的保留期限。 检查 global 端点上的互动 ID。如果父级对话轮次已过期,请在不使用“previous_interaction_id”的情况下发起新对话链。
409 (error.code: "aborted") interactions.cancel 针对已处于最终状态的互动:requires_action、requires_continuation、completed、incomplete、failed 或 cancelled。 请先通过 interactions.get 检查 status。您只能取消 queued 和 in_progress 互动。
429 (error.code: "too_many_requests") 项目超出了每项目配额,例如互动创建速率、并发互动生成次数或每日有状态吞吐量。
  • 在 Retry-After 标头延迟时间后,使用退避和抖动重试。
  • 在延迟层级配额和限制中申请增加可调整的配额。每日吞吐量限制是固定的。
status="failed"
  • 上游模型或工具发生故障,或者对话轮次超出了 24 小时的完成时间范围。
  • 请求使用了 *-cyber* 模型,但项目没有许可清单访问权限。
  • 检查 interactions.get 返回的 error 字段,然后提交新的 interactions.create 请求。
  • 对于 Cyber 模型,请与您的 Google Cloud 客户支持团队确认许可清单访问权限。

后续步骤

探索有关异步和有状态 Gemini 工作负载的相关指南和参考文档: