Strategi percobaan ulang

Library klien Google Gen AI SDK menyertakan logika percobaan ulang otomatis dengan backoff eksponensial untuk menangani error sementara seperti waktu tunggu habis, masalah jaringan, dan batas kapasitas (kode status HTTP 429 dan 5xx). Misalnya, Python SDK otomatis mencoba ulang 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 tertentu.

Menentukan kapan harus mencoba ulang

Sebelum menerapkan strategi percobaan ulang kustom, pertimbangkan bagaimana pemilihan endpoint, model pembayaran, dan workload memengaruhi kebutuhan Anda.

Memilih endpoint yang tepat

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

Menyesuaikan model pembayaran

  • **Bayar sesuai penggunaan standar**: Menggunakan resource bersama. Gunakan backoff eksponensial untuk menangani error batas kapasitas sementara (429) yang disebabkan oleh lonjakan traffic.
  • **Bayar sesuai penggunaan fleksibel**: Dirancang untuk pemrosesan yang lebih lambat dan berprioritas lebih rendah. Jangan mencoba ulang secara agresif; sebagai gantinya, tingkatkan waktu tunggu permintaan Anda (misalnya, menjadi 30 menit) untuk memberi sistem waktu menyelesaikan tugas.
  • Bayar sesuai penggunaan prioritas: Dirancang untuk workload yang sensitif terhadap latensi dan memiliki keandalan tinggi tanpa komitmen awal Throughput yang Disediakan. Jika Anda menerima error 429 di tingkat ini, coba ulang dengan backoff eksponensial, tetapi pastikan Anda tidak melebihi kuota.
  • Throughput yang Disediakan: Menggunakan kapasitas yang dicadangkan. Error yang sering terjadi biasanya menunjukkan bahwa Anda telah melebihi 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 mencoba ulang setiap item. Layanan Batch otomatis menangani percobaan ulang untuk setiap permintaan dalam tugas untuk mengupayakan tingkat penyelesaian yang tinggi. Satu-satunya tanggung jawab Anda adalah mengirimkan tugas sekali saja. Untuk mengetahui informasi selengkapnya, lihat Prediksi batch.

Mengidentifikasi error yang dapat dicoba ulang

Ada dua faktor utama yang menentukan apakah 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 Tunggu 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 dijalankan berulang kali tanpa mengubah status akhir resource. Pertimbangkan hal berikut saat menentukan idempotensi:

  • Selalu idempoten: Operasi daftar (tidak mengubah resource), permintaan get, permintaan jumlah token, dan permintaan embedding.
  • Tidak pernah idempoten: Operasi yang membuat resource unik setiap kali berhasil, seperti membuat model yang disesuaikan baru.
  • Nuansa AI Generatif: Meskipun generateContent tidak sepenuhnya idempoten karena sifat stokastik model generatif, umumnya aman untuk dicoba ulang 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 ke backoff (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,
        )
    )
)

Bayar Sesuai Penggunaan Fleksibel

Untuk Bayar Sesuai Penggunaan Fleksibel, waktu tunggu default adalah 10 menit karena pemrosesan yang lebih lambat dan percobaan ulang yang transparan. Pengguna dapat meningkatkan waktu tunggu ini menjadi 30 menit untuk mendapatkan tingkat 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 ulang pada waktu yang sama.
  • Coba ulang jika terjadi error tertentu: Hanya coba ulang jika terjadi error sementara (429, 408, 5xx).
  • Tetapkan percobaan ulang maksimum: Tentukan jumlah maksimum upaya percobaan ulang untuk mencegah loop tak terbatas.
  • 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 ulang tanpa backoff: Mencoba ulang segera dapat menyebabkan kegagalan berjenjang dan membebani layanan.
  • Mencoba ulang error yang tidak dapat dicoba ulang: Jangan mencoba ulang error klien (4xx selain 429/408) karena error tersebut menunjukkan masalah seperti kunci API yang tidak valid atau sintaksis yang buruk.
  • Mencoba ulang operasi non-idempoten tanpa syarat: Menjalankan operasi yang tidak idempoten berulang kali dapat menyebabkan efek samping, seperti resource duplikat.
  • Mengabaikan batas percobaan ulang: Mencoba ulang tanpa batas waktu dapat menyebabkan kehabisan resource; selalu tetapkan jumlah maksimum upaya.

Langkah berikutnya