使用延遲級別

在 Gemini Enterprise Agent Platform,使用延遲級別,以折扣費率為自訂代理執行非同步、多輪 Gemini 模型呼叫。在 Interactions API 中,Agent Platform 會將每個延遲的回合排入佇列,在 24 小時內於背景執行,並保留狀態 7 天。

延遲層級適用於可容忍延遲、需要逐輪控制的代理工作負載,例如:

  • 多步驟程式設計和安全防護代理:存放區安全漏洞掃描、自動化程式碼遷移,以及迴歸分類。
  • 文件和研究管道:技術設計審查、財務回測,以及透過工具呼叫彙整多份文件。
  • 離線代理評估:大規模品質基準,可串連 previous_interaction_id 回合,不受即時延遲限制。

如要比較所有運算模型,請參閱「用量選項」。如要排定 Agent Development Kit (ADK) 代理或 Gemini Deep Research 代理的代管執行作業,請參閱「自主代理排程」。

支援的模型和位置

延遲級別僅支援 global 端點 (aiplatform.googleapis.com 上的 locations/global)。如果將含有 service_tier="deferred" 的要求傳送至區域端點,或 us 或 eu 多區域端點,則會傳回 HTTP 400 ("code": "invalid_request")。

下列主流 Gemini 模型支援 global 端點的延遲級別:

如果專案已透過 Google Cloud 帳戶團隊取得許可清單存取權,您也可以使用下列 Cyber 模型:

事前準備

在已啟用計費功能的現有 Google Cloud 專案中,完成下列必要設定步驟:

  1. 登入 Google 帳戶。

    如果還沒有帳戶,請註冊新帳戶。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令,初始化 gcloud CLI:

    gcloud init
  5. 確認您具備完成本指南所需的權限。

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

    啟用 API 所需的角色

    如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    gcloud services enable aiplatform.googleapis.com
  7. 如果您使用的是本機殼層,請為使用者帳戶建立本機驗證憑證:

    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 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    gcloud services enable aiplatform.googleapis.com
  13. 如果您使用的是本機殼層,請為使用者帳戶建立本機驗證憑證:

    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

輪詢狀態並擷取權杖用量

當 status 為 queued 或 in_progress 時,使用輪詢 interactions.get 搭配輪詢。當回合達到最終狀態時,請讀取 output_text 和 usage。

延遲級別的目標是在 24 小時內完成 95% 的回合,不提供抵免額支援的延遲服務水準協議。下表說明 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 結束,請呼叫 interactions.create,並傳入 previous_interaction_id、continuation_token、background=true、store=true 和 service_tier="deferred",以恢復回合。省略 input,並將 max_output_tokens 設為高於目前產生的權杖數量。如要瞭解各項最終狀態的計費方式,請參閱「定價和計費」。

執行範例前,請先替換下列項目:

  • 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

疊代 await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId })、記錄 event.event_id,並在 step.delta 事件中讀取 event.delta?.text。

Python

疊代 client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id)、記錄 event.event_id,並在 step.delta 事件中讀取 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

定價、配額和安全控管機制

在延遲級別執行正式環境工作負載前,請先詳閱計費規則、配額、酬載限制和安全控管措施。

價格與計費

與標準即付即用費率相比,延遲模型呼叫的輸入、輸出和思考詞元費用可享 50% 折扣。計費規則如下:

  • 折扣累加:延遲折扣會與合約折扣和隱含脈絡快取詞元折扣累加,並在快取費率之上套用。
  • 不會降級為標準費率:延遲要求不會溢出或降級為標準 PayGo,因此不會以未折扣的隨選費率計費。
  • 依模型呼叫計費:系統會針對每個回合的模型呼叫計費。以 completed、incomplete、requires_action 或 requires_continuation 結束的回合,會以延遲費率計費。
  • 取消的回合:在queued狀態下取消的回合不會計費。如果在in_progress期間取消回合,系統會針對已啟動的模型呼叫收費,包括在生成過程中中斷的呼叫。
  • 失敗的回合:以 failed 結束的單次通話回合 (包括超過 24 小時完成時間的回合) 不會計費。在多步驟伺服器端工具迴圈中,失敗前完成的模型呼叫會計費,但失敗的呼叫不會計費。
  • 鏈結回合:previous_interaction_id 鏈結中的每個回合都會單獨計費。取消後續回合或後續回合失敗,不會影響先前回合的費用。

如要瞭解各模型的詞元費率,請參閱 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 端點上排入佇列並保留狀態,請確認其支援的管理控制項符合您的法規遵循要求:

如需完整的功能矩陣,請參閱「生成式 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";status: "NOT_FOUND",interactions.delete) 互動或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 工作負載的相關指南和參考文件: