Strategi percobaan ulang

Library klien Google Gen AI SDK menyertakan logika coba lagi otomatis dengan backoff eksponensial untuk menangani error sementara seperti waktu tunggu habis, masalah jaringan, dan batas kecepatan (kode status HTTP 429 dan 5xx). Misalnya, Python SDK secara otomatis mencoba lagi error sementara hingga empat kali dengan penundaan awal sekitar 1 detik dan penundaan maksimum 60 detik. Meskipun SDK menangani hal ini secara default, Anda dapat mengonfigurasi perilaku ini agar lebih sesuai dengan workload spesifik Anda.

Menentukan kapan harus mencoba lagi

Sebelum menerapkan strategi coba lagi kustom, pertimbangkan bagaimana pemilihan endpoint, model pembayaran, dan beban kerja memengaruhi kebutuhan Anda.

Memilih endpoint yang tepat

  • Endpoint global: Direkomendasikan untuk ketersediaan. Endpoint global merutekan traffic secara dinamis, yang dapat mengurangi kebutuhan untuk percobaan ulang sisi klien yang disebabkan oleh masalah kapasitas regional.
  • Endpoint regional: Dibatasi ke lokasi tertentu. Jika region kelebihan beban, percobaan ulang langsung mungkin gagal; pertimbangkan strategi failover sebagai gantinya.

Menyesuaikan untuk model pembayaran Anda

  • Bayar sesuai penggunaan standar: Menggunakan resource bersama. Gunakan backoff eksponensial untuk menangani error sementara batas kecepatan (429) yang disebabkan oleh lonjakan traffic.
  • Bayar sesuai penggunaan Flex: Dirancang untuk pemrosesan yang lebih lambat dan berprioritas lebih rendah. Jangan mencoba ulang secara agresif. Sebagai gantinya, tingkatkan waktu tunggu permintaan Anda (misalnya, hingga 30 menit) untuk memberi waktu kepada sistem dalam menyelesaikan tugas.
  • Bayar sesuai penggunaan prioritas: Dirancang untuk workload yang sensitif terhadap latensi dan memiliki keandalan tinggi tanpa komitmen di muka dari Throughput yang Disediakan. Jika Anda menerima error 429 di tingkat ini, coba lagi dengan backoff eksponensial, tetapi pastikan Anda tidak melebihi kuota.
  • Throughput yang Disediakan: Menggunakan kapasitas khusus. Error yang sering terjadi biasanya menunjukkan bahwa Anda telah melampaui kapasitas yang dibeli, sehingga menambahkan percobaan ulang mungkin tidak menyelesaikan masalah yang mendasarinya.

Menentukan toleransi latensi

  • Real-time (misalnya, chat): Gagal dengan cepat. Batasi jumlah upaya percobaan ulang agar pengguna tidak menunggu respons tanpa batas waktu.
  • Inferensi Batch: Jangan coba lagi item satu per satu. Layanan Batch secara otomatis menangani percobaan ulang untuk setiap permintaan dalam tugas guna mencapai rasio penyelesaian yang tinggi. Satu-satunya tanggung jawab Anda adalah berhasil mengirimkan tugas satu kali. Untuk mengetahui informasi selengkapnya, lihat Prediksi batch.

Mengidentifikasi error yang dapat dicoba lagi

Ada dua faktor utama yang menentukan apakah sebuah permintaan aman untuk dicoba ulang:

Respons

Kode error atau respons yang diterima menunjukkan apakah masalah bersifat sementara atau permanen. Respons yang terkait dengan masalah sementara umumnya dapat dicoba ulang. Fitur tersebut meliputi:

  • Kode HTTP: 408 (Waktu Permintaan Habis), 429 (Terlalu Banyak Permintaan), dan 5xx (Error Server).
  • Masalah Jaringan: Waktu tunggu soket dan TCP terputus.

Untuk mengetahui informasi selengkapnya, lihat Error API.

Idempotensi

Permintaan idempoten dapat dieksekusi berulang kali tanpa mengubah status akhir resource. Pertimbangkan hal berikut saat menentukan keidempotenan:

  • Selalu idempoten: Operasi daftar (tidak mengubah resource), permintaan get, permintaan jumlah token, dan permintaan penyematan.
  • Tidak pernah idempoten: Operasi yang membuat resource unik setiap kali berhasil, seperti membuat model yang di-tuning baru.
  • Nuansa AI generatif: Meskipun generateContent tidak sepenuhnya bersifat idempoten karena sifat stokastik model generatif, umumnya aman untuk mencoba lagi jika terjadi error sementara karena tidak mengubah status sisi server.

Mengonfigurasi percobaan ulang

Google Gen AI SDK memungkinkan Anda mengonfigurasi perilaku percobaan ulang melalui parameter klien atau HttpRetryOptions.

Parameter utama

  • initial_delay: Penundaan awal dalam detik sebelum percobaan ulang pertama (Default: 1.0).
  • attempts: Jumlah maksimum upaya percobaan ulang (Default: 5).
  • exp_base: Basis untuk perhitungan backoff eksponensial (Default: 2).
  • max_delay: Penundaan maksimum dalam detik antara percobaan ulang (Default: 60).
  • jitter: Faktor untuk menambahkan penundaan acak pada jeda (Default: 1).
  • http_status_codes: Daftar kode status yang memicu percobaan ulang.

Contoh

Konfigurasi tingkat klien

Anda dapat menetapkan opsi secara global saat melakukan inisialisasi klien.

Python

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location="global",
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            initial_delay=1.0,
            attempts=5,
            http_status_codes=[408, 429, 500, 502, 503, 504],
        ),
        timeout=120 * 1000,
    ),
)

Java

import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

HttpOptions httpOptions = HttpOptions.builder()
  .retryOptions(
      HttpRetryOptions.builder()
          .attempts(5)
          .httpStatusCodes(408, 429, 500, 502, 503, 504).build())
  .build();

Client client = Client.builder()
  .project(PROJECT_ID)
  .location("global")
  .vertexAI(true)
  .httpOptions(httpOptions)
  .build();

Konfigurasi tingkat permintaan

Anda juga dapat mengganti setelan untuk satu permintaan menggunakan parameter config.

Python

from google import genai
from google.genai import types

client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Tell me a joke about a rabbit.",
    config=types.GenerateContentConfig(
        http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                initial_delay=1.0,
                attempts=10,
                http_status_codes=[408, 429, 500, 502, 503, 504],
            ),
            timeout=120 * 1000,
        )
    )
)

Flex Pay-as-you-go

Untuk Flex Pay-as-you-go, waktu tunggu default adalah 10 menit karena pemrosesan yang lebih lambat dan percobaan ulang yang transparan. Pengguna dapat meningkatkan durasi ini hingga 30 menit untuk mendapatkan rasio keberhasilan yang lebih baik.

Python

from google import genai
from google.genai import types

client = genai.Client(
  vertexai=True, project=PROJECT_ID, location='global',
  http_options=types.HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex" # Use Flex PayGo
      },
      timeout = 30 * 60 * 1000 # Increase to 30 minutes
  )
)

Praktik terbaik dan anti-pola

Baik Anda menggunakan mekanisme percobaan ulang default, menyesuaikannya, atau menerapkan logika percobaan ulang Anda sendiri, ikuti praktik terbaik ini dan hindari anti-pola umum.

Praktik terbaik

  • Gunakan backoff eksponensial: Tunggu sebentar sebelum percobaan ulang pertama (misalnya, 1 detik), lalu tingkatkan penundaan secara eksponensial (misalnya, 2 detik, 4 detik, 8 detik).
  • Tambahkan jitter: Menambahkan "jitter" acak ke penundaan membantu mencegah semua klien mencoba lagi pada waktu yang sama persis.
  • Coba lagi jika terjadi error tertentu: Hanya coba lagi jika terjadi error sementara (429, 408, 5xx).
  • Tetapkan percobaan ulang maksimum: Tentukan jumlah maksimum upaya percobaan ulang untuk mencegah loop tanpa henti.
  • Pantau dan catat log: Catat detail tentang upaya percobaan ulang, jenis error, dan waktu respons untuk men-debug strategi Anda.

Anti-pola percobaan ulang

  • Mencoba lagi tanpa jeda: Mencoba lagi secara langsung dapat menyebabkan kegagalan beruntun dan membebani layanan.
  • Mencoba lagi error yang tidak dapat dicoba lagi: Jangan mencoba lagi error klien (4xx selain 429/408) karena error tersebut menunjukkan masalah seperti kunci API yang tidak valid atau sintaksis yang salah.
  • Mencoba ulang operasi non-idempoten tanpa syarat: Menjalankan operasi yang tidak idempoten berulang kali dapat menyebabkan efek samping, seperti duplikasi resource.
  • Mengabaikan batas percobaan ulang: Mencoba ulang tanpa batas dapat menyebabkan kehabisan resource; selalu tetapkan jumlah percobaan maksimum.

Langkah berikutnya