Menggunakan paket Ditangguhkan

Gunakan paket Deferred untuk menjalankan panggilan model Gemini multi-turn asinkron untuk agen kustom dengan tarif diskon di Gemini Enterprise Agent Platform. Di Interactions API, Agent Platform mengantrekan setiap giliran yang ditangguhkan untuk eksekusi latar belakang dalam target 24 jam dan mempertahankan status selama 7 hari.

Paket Deferred cocok untuk workload agen yang toleran terhadap latensi dan memerlukan kontrol per giliran, seperti berikut:

  • Agen coding dan keamanan multilangkah: Pemindaian kerentanan repositori, migrasi kode otomatis, dan triase regresi.
  • Pipeline dokumen dan riset: Peninjauan desain teknis, backtesting keuangan, dan sintesis multi-dokumen dengan panggilan alat.
  • Evaluasi agen offline: Tolok ukur kualitas berskala besar yang merangkai previous_interaction_id giliran tanpa batasan latensi real-time.

Untuk membandingkan semua model komputasi, lihat Opsi konsumsi. Untuk menjadwalkan agen Agent Development Kit (ADK) atau operasi terkelola di Agen Deep Research Gemini, lihat Penjadwalan agen otonom.

Model dan lokasi yang didukung

Paket Deferred didukung secara eksklusif di endpoint global (locations/global di aiplatform.googleapis.com). Mengirim permintaan dengan service_tier="deferred" ke endpoint regional atau ke endpoint multi-region us atau eu akan menampilkan HTTP 400 ("code": "invalid_request").

Model Gemini mainline berikut mendukung tingkat Deferred di endpoint global:

Jika project Anda memiliki akses daftar yang diizinkan melalui tim akun Google Cloud , Anda juga dapat menggunakan model Cyber berikut:

Sebelum memulai

Dalam project Google Cloud yang sudah ada dan mengaktifkan penagihan, selesaikan langkah-langkah penyiapan prasyarat berikut:

  1. Login ke Akun Google Anda.

    Jika Anda belum memilikinya, Daftar untuk membuat akun baru.

  2. Instal Google Cloud CLI.

  3. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  4. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

    gcloud init
  5. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.

  6. Aktifkan Agent Platform API, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    gcloud services enable aiplatform.googleapis.com
  7. Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda:

    gcloud auth application-default login

    Anda tidak perlu melakukannya jika menggunakan Cloud Shell.

    Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, pastikan Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

  8. Instal Google Cloud CLI.

  9. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  10. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

    gcloud init
  11. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.

  12. Aktifkan Agent Platform API, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    gcloud services enable aiplatform.googleapis.com
  13. Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda:

    gcloud auth application-default login

    Anda tidak perlu melakukannya jika menggunakan Cloud Shell.

    Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, pastikan Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat, memantau, dan membatalkan panggilan model yang ditangguhkan, minta administrator untuk memberi Anda peran IAM berikut pada project Google Cloud Anda:

  • Membuat, melakukan polling, membatalkan, dan menghapus interaksi yang ditangguhkan: Agent Platform User (roles/aiplatform.user)
  • Memantau interaksi yang ditangguhkan (hanya baca): Agent Platform Viewer (roles/aiplatform.viewer)
  • Membaca file input multimodal dari Cloud Storage (opsional): Storage Object Viewer (roles/storage.objectViewer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menginstal Google Gen AI SDK

Jika Anda menggunakan library klien, instal atau upgrade Google Gen AI SDK (@google/genai >= 2.32.0 atau google-genai >= 2.34.0) di lingkungan pengembangan Anda:

Node.js

npm install @google/genai@latest

Python

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

Membuat dan mengelola panggilan model yang ditangguhkan

Jalankan prosedur berikut di lingkungan yang Anda siapkan di bagian Sebelum memulai. Contoh REST melakukan autentikasi dengan kredensial gcloud CLI Anda, dan contoh Google Gen AI SDK menggunakan Kredensial Default Aplikasi (ADC). Jika panggilan menampilkan error, lihat Memecahkan masalah.

Membuat panggilan model yang ditangguhkan

Kirim giliran asinkron dengan memanggil interactions.create dengan service_tier="deferred", background=true, dan store=true. Hilangkan stream atau tetapkan ke false. Sebelum menjalankan contoh, ganti PROJECT_ID dengan project ID Google Cloud Anda, seperti my-agent-project.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.

Metode HTTP dan URL:

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

Meminta isi 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
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons menampilkan payload JSON yang mirip dengan berikut ini:

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

Outputnya mirip dengan hal berikut ini:

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

Outputnya mirip dengan hal berikut ini:

Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred

Memeriksa status dan mengambil penggunaan token

Lakukan polling interactions.get dengan backoff saat status adalah queued atau in_progress. Saat giliran mencapai status akhir, baca output_text dan usage.

Paket Deferred menargetkan penyelesaian 95% giliran dalam waktu 24 jam tanpa SLA latensi yang didukung kredit. Tabel berikut menjelaskan nilai status dari resource Interaction:

Status Final Arti dan langkah berikutnya
queued Tidak Diterima dan menunggu kapasitas. Lakukan polling interactions.get dengan backoff. Jangan minta stream=true dulu.
in_progress Tidak Berjalan. Lanjutkan polling interactions.get, atau lampirkan streaming SSE dengan stream=true.
requires_action Ya Giliran berakhir pada langkah function_call yang dikeluarkan model. Jalankan alat, lalu buat giliran baru dengan previous_interaction_id.
requires_continuation Ya Giliran dekode panjang berhenti dengan output parsial dan continuation_token. Lanjutkan dengan previous_interaction_id dan continuation_token, hilangkan input, dan naikkan max_output_tokens.
completed Ya Giliran selesai. Baca output_text dan usage, atau berikan id sebagai previous_interaction_id pada giliran berikutnya.
incomplete Ya Giliran berhenti lebih awal, seperti saat mencapai max_output_tokens. Periksa steps dan usage parsial.
failed Ya Giliran mengalami error runtime atau melebihi periode penyelesaian 24 jam. API tidak menggunakan status expired. Periksa error, lalu kirim permintaan baru.
cancelled Ya Panggilan ke interactions.cancel menghentikan giliran sebelum selesai.

Jika giliran dekode panjang berakhir sebagai requires_continuation, lanjutkan dengan memanggil interactions.create dengan previous_interaction_id, continuation_token, background=true, store=true, dan service_tier="deferred". Hilangkan input dan tetapkan max_output_tokens lebih tinggi dari token yang dihasilkan sejauh ini. Untuk mempelajari cara penagihan setiap status akhir, lihat Harga dan penagihan.

Sebelum menjalankan contoh, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • INTERACTION_ID: ID interaksi yang ditampilkan saat Anda membuat panggilan model yang ditangguhkan, seperti v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • INTERACTION_ID: ID interaksi yang ditampilkan saat Anda membuat panggilan model yang ditangguhkan, seperti v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

Metode HTTP dan URL:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons menampilkan payload JSON yang mirip dengan berikut ini:

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

Outputnya mirip dengan hal berikut ini:

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

Outputnya mirip dengan hal berikut ini:

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

Opsional: Melakukan streaming output saat panggilan berjalan

Setelah interactions.get melaporkan status="in_progress", Anda dapat melampirkan aliran data Server-Sent Events (SSE) dengan stream=true dan melanjutkan koneksi yang terputus dengan last_event_id:

REST

Tambahkan ?stream=true ke URL interactions.get. Saat menghubungkan kembali, tambahkan juga &last_event_id=EVENT_ID, dengan mengganti EVENT_ID dengan ID peristiwa terakhir yang diterima.

Node.js

Lakukan iterasi pada await ai.interactions.get(interactionId, { stream: true, last_event_id: lastEventId }), catat event.event_id, dan baca event.delta?.text pada peristiwa step.delta.

Python

Lakukan iterasi pada client.interactions.get(interaction_id, stream=True, last_event_id=last_event_id), catat event.event_id, dan baca event.delta.text pada peristiwa step.delta.

Untuk mengetahui informasi selengkapnya tentang streaming dan koneksi ulang SSE, lihat panduan developer Interactions API.

Membuat rantai alur kerja multi-giliran yang ditangguhkan

Lanjutkan percakapan multi-turn atau tampilkan hasil eksekusi alat dengan meneruskan id interaksi completed atau requires_action di previous_interaction_id. Kolom cakupan giliran seperti tools, system_instruction, dan generation_config tidak diteruskan secara otomatis, jadi teruskan pada setiap giliran yang memerlukannya. Giliran yang dirantai tetap memenuhi syarat untuk cache konteks implisit, meskipun awalan yang di-cache mungkin akan habis masa berlakunya selama menunggu antrean beberapa jam. Untuk skema langkah tool-result, lihat panduan developer Interactions API.

Sebelum menjalankan contoh, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • PREVIOUS_INTERACTION_ID: ID giliran completed atau requires_action sebelumnya, seperti v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • PREVIOUS_INTERACTION_ID: ID interaksi yang telah selesai atau memerlukan tindakan dari giliran sebelumnya, seperti v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

Metode HTTP dan URL:

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

Meminta isi 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
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons menampilkan payload JSON yang mirip dengan berikut ini:

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

Outputnya mirip dengan hal berikut ini:

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

Outputnya mirip dengan hal berikut ini:

Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)

Membatalkan panggilan model yang ditangguhkan

Untuk menghentikan interaksi yang ditangguhkan yang status-nya adalah queued atau in_progress, panggil interactions.cancel. Memanggil interactions.cancel pada interaksi dalam status lain akan menampilkan HTTP 409 ("code": "aborted"). Untuk mempelajari pengaruh pembatalan terhadap penagihan, lihat Harga dan penagihan.

Sebelum menjalankan contoh, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • INTERACTION_ID: ID interaksi queued atau in_progress, seperti v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda, seperti my-agent-project.
  • INTERACTION_ID: ID interaksi dalam antrean atau yang sedang berlangsung untuk dibatalkan, seperti v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

Metode HTTP dan URL:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons menampilkan payload JSON yang mirip dengan berikut ini:

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

Outputnya adalah sebagai berikut:

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

Outputnya adalah sebagai berikut:

Status: cancelled

Harga, kuota, dan kontrol keamanan

Tinjau aturan penagihan, kuota, batas payload, dan kontrol keamanan sebelum Anda menjalankan workload produksi di paket Deferred.

Penetapan harga dan penagihan

Panggilan model yang ditangguhkan ditagih dengan diskon 50% dibandingkan dengan tarif Bayar sesuai penggunaan standar untuk token input, output, dan token penalaran. Penagihan mengikuti aturan berikut:

  • Penumpukan diskon: Diskon yang ditangguhkan ditumpuk dengan diskon kontrak dan diskon token cache konteks implisit, yang diterapkan di atas tarif yang di-cache.
  • Tidak ada penggantian ke tarif standar: Permintaan yang ditangguhkan tidak pernah melimpah atau diturunkan ke PayGo Standar, sehingga tidak ditagih dengan tarif on-demand tanpa diskon.
  • Penagihan berdasarkan panggilan model: Setiap panggilan model yang dilakukan oleh giliran akan ditagih. Giliran yang berakhir sebagai completed, incomplete, requires_action, atau requires_continuation akan ditagih dengan tarif yang ditangguhkan.
  • Giliran yang dibatalkan: Giliran yang Anda batalkan saat queued tidak akan ditagih. Jika Anda membatalkan giliran saat statusnya in_progress, panggilan model yang sudah dimulai akan ditagih, termasuk panggilan yang terganggu di tengah pembuatan.
  • Giliran gagal: Giliran panggilan tunggal yang berakhir sebagai failed, termasuk giliran yang melebihi periode penyelesaian 24 jam, tidak akan ditagih. Dalam loop alat sisi server multi-langkah, panggilan model yang selesai sebelum kegagalan akan ditagih, tetapi panggilan yang gagal tidak akan ditagih.
  • Giliran berantai: Setiap giliran dalam rantai previous_interaction_id ditagih secara terpisah. Membatalkan giliran berikutnya, atau giliran berikutnya yang gagal, tidak akan mengubah biaya untuk giliran sebelumnya.

Untuk mengetahui tarif token per model, lihat halaman harga Agent Platform.

Kuota, batas payload, dan retensi

Paket Deferred tidak memiliki kuota panggilan modelnya sendiri. Panggilan yang ditangguhkan menggunakan kuota bayar sesuai penggunaan Flex (flex_requests_per_minute_per_project_per_base_model, 3.000 RPM), yang diperiksa pada setiap panggilan model setelah interactions.create menampilkan queued. Kuota project dan batas sistem utama mencakup hal berikut:

  • Kuota pembuatan dan konkurensi: Hingga 100 RPM atau tidak terbatas untuk stateful_genai_interaction_creations pada waktu pembuatan. Hingga 500 concurrent_interaction_generations, bergantung pada tingkat kuota Anda.
  • Throughput stateful harian (tetap): 240 GiB per hari ditulis dan 480 GiB per hari dibaca per project.
  • Batas payload dan retensi: Isi HTTP yang tidak dikompresi hingga 9,75 MiB per panggilan interactions.create, dan retensi status 7 hari. Rantai mendukung hingga 100 URI Cloud Storage (gs://) yang berbeda.

Untuk mengetahui tabel kuota lengkap dan petunjuk konsol, lihat Kuota dan batas paket yang ditangguhkan.

Kontrol keamanan dan kepatuhan

Karena tingkat Deferred mengantrekan dan mempertahankan status di endpoint global, pastikan kontrol tata kelola yang didukungnya sesuai dengan persyaratan kepatuhan Anda:

  • Kontrol yang didukung: Kontrol Layanan VPC (VPC-SC; alat mcp_server eksternal tidak diizinkan di dalam perimeter), Transparansi Akses (AXT), Cloud Audit Logs, dan FedRAMP High.
  • Kontrol yang tidak didukung: Stateless zero data retention (store=false dan penerapan constraints/vertexai.disableAPIStorage keduanya menampilkan HTTP 400 dengan "code": "invalid_request"), Kunci enkripsi yang dikelola pelanggan (CMEK), Residensi data, DoD IL5, dan ITAR.

Untuk mengetahui matriks fitur lengkap, lihat Kontrol keamanan untuk AI Generatif.

Memecahkan masalah

Tabel berikut menjelaskan error umum pada paket Ditangguhkan dan cara mengatasinya:

Error atau status Penyebab umum Resolusi
400 (error.code: "invalid_request"; endpoint, flag, atau model) Endpoint non-global, model yang tidak didukung, atau flag background, store, atau stream yang tidak valid di interactions.create. Targetkan locations/global dengan model yang didukung, tetapkan background=true dan store=true, serta hapus stream=true.
400 (error.code: "invalid_request"; payload, URI, atau alat) Isi yang tidak dikompresi melebihi 9,75 MiB, rantai melebihi 100 URI gs://, atau alat mcp_server eksternal di dalam VPC-SC. Teruskan file besar sebagai URI gs:// (maksimal 100 per rantai), dan hilangkan alat mcp_server eksternal di dalam VPC-SC.
400 (error.code: "invalid_request" di interactions.create; status: "FAILED_PRECONDITION" di interactions.delete)
  • Kebijakan constraints/vertexai.disableAPIStorage diterapkan.
  • interactions.create berantai ke belokan queued atau in_progress, atau menetapkan input di requires_continuation.
  • interactions.delete menargetkan belokan queued atau in_progress.
  • Gunakan project yang memungkinkan persistensi status API.
  • Rantai hanya pada giliran terakhir. Di requires_continuation, teruskan continuation_token dan hapus input.
  • Batalkan giliran aktif sebelum Anda menghapusnya.
401 (status: "UNAUTHENTICATED" atau error.code: "authentication") Kredensial gcloud CLI (contoh REST) atau ADC (contoh Google Gen AI SDK) Anda tidak ada atau sudah tidak berlaku. Untuk contoh REST, jalankan gcloud auth login. Untuk contoh Google Gen AI SDK, jalankan gcloud auth application-default login. Kemudian, coba lagi permintaan tersebut.
403 (status: "PERMISSION_DENIED" atau error.code: "permission_denied")
  • Pemanggil tidak memiliki roles/aiplatform.user.
  • Pemanggil tidak memiliki storage.objects.get pada input gs://.
Pemberian roles/aiplatform.user. Untuk input Cloud Storage, berikan juga roles/storage.objectViewer.
404 (error.code: "not_found"; status: "NOT_FOUND" pada interactions.delete) Interaksi atau previous_interaction_id tidak ada atau telah dihapus. Data tersebut mungkin juga milik endpoint non-global atau lebih lama dari periode retensi data 7 hari. Periksa ID interaksi di endpoint global. Jika giliran induk sudah tidak berlaku, mulai rantai baru tanpa previous_interaction_id.
409 (error.code: "aborted") interactions.cancel menargetkan interaksi yang sudah dalam status akhir: requires_action, requires_continuation, completed, incomplete, failed, atau cancelled. Periksa status dengan interactions.get terlebih dahulu. Anda hanya dapat membatalkan interaksi queued dan in_progress.
429 (error.code: "too_many_requests") Project ini melampaui kuota per project, seperti rasio pembuatan interaksi, pembuatan interaksi serentak, atau throughput stateful harian.
  • Coba lagi setelah penundaan header Retry-After dengan backoff dan jitter.
  • Minta penambahan kuota yang dapat disesuaikan di Kuota dan batas paket Deferred. Batas throughput harian bersifat tetap.
status="failed"
  • Terjadi kegagalan model atau alat upstream, atau giliran melebihi periode penyelesaian 24 jam.
  • Permintaan menggunakan model *-cyber*, dan project tidak memiliki akses daftar yang diizinkan.
  • Periksa kolom error yang ditampilkan interactions.get, lalu kirim permintaan interactions.create baru.
  • Untuk model Cyber, konfirmasi akses daftar yang diizinkan dengan tim akun Google Cloud Anda.

Langkah berikutnya

Pelajari panduan dan dokumentasi referensi terkait untuk workload Gemini asinkron dan stateful: