Panduan pemecahan masalah

Gunakan panduan ini untuk membantu Anda mendiagnosis dan menyelesaikan masalah umum yang muncul saat Anda memanggil Gemini API. Anda mungkin mengalami masalah dari layanan backend Gemini API atau SDK klien. SDK klien kami bersifat open source di repositori berikut:

Jika Anda mengalami masalah kunci API, pastikan Anda telah menyiapkan kunci API dengan benar sesuai panduan penyiapan kunci API.

Kode error

Untuk referensi lengkap semua kode error, termasuk kode status HTTP, kode yang memblokir pembuatan, dan kode error konten, lihat halaman error API.

Strategi percobaan ulang

Jika Anda menerima error yang menunjukkan bahwa Anda harus mencoba lagi permintaan Anda (seperti 429 RESOURCE_EXHAUSTED atau 503 UNAVAILABLE), sebaiknya terapkan strategi backoff eksponensial. Artinya, Anda menunggu sebentar sebelum percobaan ulang pertama, lalu secara bertahap meningkatkan waktu tunggu antara percobaan ulang berikutnya.

SDK klien resmi untuk Gemini API, seperti Python SDK, menyertakan logika percobaan ulang otomatis dengan backoff eksponensial secara default untuk menangani error sementara seperti waktu tunggu habis, masalah jaringan, dan batas frekuensi (429 dan kode status 5xx). Misalnya, Python SDK otomatis mencoba lagi error sementara hingga empat kali dengan penundaan awal sekitar 1 detik dan penundaan maksimum 60 detik.

Jika Anda membuat permintaan REST API langsung atau menyesuaikan logika percobaan ulang, ikuti praktik terbaik ini untuk meningkatkan kemungkinan permintaan berhasil dan mencegah layanan kewalahan:

  • 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: Tambahkan "jitter" acak ke penundaan untuk membantu mencegah semua klien mencoba lagi pada waktu yang sama.
  • Coba lagi pada error tertentu: Hanya coba lagi pada error sementara (seperti 429, 408, atau 5xx). Jangan coba lagi pada error klien (seperti 400 atau 403) karena error tersebut menunjukkan masalah seperti kunci API yang tidak valid atau sintaksis yang buruk.
  • Tetapkan percobaan ulang maksimum: Tentukan jumlah maksimum upaya percobaan ulang untuk mencegah loop tak terbatas.

Memeriksa panggilan API untuk error parameter model

Pastikan parameter model Anda berada dalam nilai berikut:

Parameter model Nilai (rentang)
Jumlah kandidat 1-8 (bilangan bulat)
Suhu 0.0-1.0
Token output maks Gunakan halaman model untuk menentukan jumlah maksimum token untuk model yang Anda gunakan.
TopP 0.0-1.0

Selain memeriksa nilai parameter, pastikan Anda menggunakan versi API yang benar (misalnya, /v1 atau /v1beta) dan model yang mendukung fitur yang Anda butuhkan. Misalnya, jika fitur berada dalam rilis Beta, fitur tersebut hanya akan tersedia di versi API /v1beta.

Memeriksa apakah Anda memiliki model yang tepat

Pastikan Anda menggunakan model yang didukung yang tercantum di halaman model kami.

Latensi atau penggunaan token yang lebih tinggi dengan model 2.5

Jika Anda mengamati latensi atau penggunaan token yang lebih tinggi dengan model 2.5 Flash dan Pro, hal ini dapat terjadi karena model tersebut dilengkapi dengan pemikiran yang diaktifkan secara default untuk meningkatkan kualitas. Jika Anda memprioritaskan kecepatan atau perlu meminimalkan biaya, Anda dapat menyesuaikan atau menonaktifkan pemikiran.

Lihat halaman penalaran untuk panduan dan kode contoh.

Masalah keamanan

Jika Anda melihat perintah diblokir karena setelan keamanan dalam panggilan API, tinjau perintah tersebut terkait filter yang Anda tetapkan dalam panggilan API.

Jika Anda melihat BlockedReason.OTHER, kueri atau respons mungkin melanggar persyaratan layanan atau tidak didukung.

Masalah pengucapan

Jika Anda melihat model berhenti menghasilkan output karena alasan PENGUCAPAN, berarti output model mungkin menyerupai data tertentu. Untuk memperbaikinya, coba buat perintah / konteks seunik mungkin dan gunakan suhu yang lebih tinggi.

Masalah token berulang

Jika Anda melihat token output berulang, coba saran berikut untuk membantu mengurangi atau menghapusnya.

Deskripsi Penyebab Solusi yang disarankan
Tanda hubung berulang dalam tabel Markdown Hal ini dapat terjadi jika konten tabel panjang karena model mencoba membuat tabel Markdown yang selaras secara visual. Namun, perataan dalam Markdown tidak diperlukan untuk rendering yang benar.

Tambahkan petunjuk dalam perintah Anda untuk memberikan panduan khusus kepada model dalam membuat tabel Markdown. Berikan contoh yang mengikuti panduan tersebut. Anda juga dapat mencoba menyesuaikan suhu. Untuk membuat kode atau output yang sangat terstruktur seperti tabel Markdown, temperatur tinggi terbukti berfungsi lebih baik (>= 0,8).

Berikut adalah contoh kumpulan panduan yang dapat Anda tambahkan ke perintah untuk mencegah masalah ini: 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Token berulang dalam tabel Markdown Mirip dengan tanda hubung berulang, hal ini terjadi saat model mencoba menyelaraskan konten tabel secara visual. Perataan dalam Markdown tidak diperlukan untuk rendering yang benar.
  • Coba tambahkan petunjuk seperti berikut ke perintah sistem Anda: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Coba sesuaikan suhu. Suhu yang lebih tinggi (>= 0,8) umumnya membantu menghilangkan pengulangan atau duplikasi dalam output.
Baris baru berulang (\n) dalam output terstruktur Jika input model berisi urutan escape atau unicode seperti \u atau \t, hal ini dapat menyebabkan baris baru berulang.
  • Periksa dan ganti urutan escape yang dilarang dengan karakter UTF-8 dalam perintah Anda. Misalnya, \u urutan escape dalam contoh JSON Anda dapat menyebabkan model menggunakannya dalam outputnya juga.
  • Berikan petunjuk kepada model tentang escape yang diizinkan. Tambahkan petunjuk sistem seperti ini: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Teks berulang saat menggunakan output terstruktur Jika output model memiliki urutan kolom yang berbeda dengan skema terstruktur yang ditentukan, hal ini dapat menyebabkan teks berulang.
  • Jangan tentukan urutan kolom dalam perintah Anda.
  • Jadikan semua kolom output wajib diisi.
Panggilan alat berulang Hal ini dapat terjadi jika model kehilangan konteks pemikiran sebelumnya dan/atau memanggil endpoint yang tidak tersedia yang terpaksa dipanggil. Berikan petunjuk kepada model untuk mempertahankan status dalam proses pemikirannya. Tambahkan hal ini ke akhir petunjuk sistem Anda: 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
Teks berulang yang bukan bagian dari output terstruktur Hal ini dapat terjadi jika model mengalami masalah pada permintaan yang tidak dapat diselesaikan.
  • Jika pemikiran diaktifkan, hindari memberikan perintah eksplisit tentang cara untuk memikirkan masalah dalam petunjuk. Cukup minta output akhir output.
  • Coba suhu yang lebih tinggi >= 0,8.
  • Tambahkan petunjuk seperti "Singkat", "Jangan ulangi", atau "Berikan jawaban sekali".

Kunci API yang diblokir atau tidak berfungsi

Bagian ini menjelaskan cara memeriksa apakah kunci Gemini API Anda diblokir dan apa yang harus dilakukan.

Memahami alasan kunci diblokir

Kami telah mengidentifikasi kerentanan yang menyebabkan beberapa kunci API mungkin terekspos secara publik. Untuk melindungi data Anda dan mencegah akses yang tidak sah, kami telah secara proaktif memblokir kunci yang diketahui bocor ini agar tidak dapat mengakses Gemini API.

Mengonfirmasi apakah kunci Anda terpengaruh

Jika kunci Anda diketahui bocor, Anda tidak dapat lagi menggunakan kunci tersebut dengan Gemini API. Anda dapat menggunakan Google AI Studio untuk melihat apakah ada kunci API Anda yang diblokir agar tidak dapat memanggil Gemini API dan membuat kunci baru. Anda mungkin juga melihat error berikut yang ditampilkan saat mencoba menggunakan kunci ini:

Your API key was reported as leaked. Please use another API key.

Tindakan untuk kunci API yang diblokir

Anda harus membuat kunci API baru untuk integrasi Gemini API menggunakan Google AI Studio. Sebaiknya tinjau praktik pengelolaan kunci API Anda untuk memastikan kunci baru Anda tetap aman dan tidak terekspos secara publik.

Tagihan yang tidak terduga karena kerentanan

Ajukan kasus dukungan penagihan. Tim penagihan kami sedang menangani masalah ini, dan kami akan menyampaikan informasi terbaru sesegera mungkin.

Langkah-langkah keamanan Google untuk kunci yang bocor

Bagaimana Google akan membantu mengamankan akun saya dari pembengkakan biaya dan penyalahgunaan jika kunci API saya bocor?

  • Kami akan mulai menerbitkan kunci API saat Anda meminta kunci baru menggunakan Google AI Studio yang secara default akan dibatasi hanya untuk Google AI Studio dan tidak menerima kunci dari layanan lain. Hal ini akan membantu mencegah penggunaan kunci yang tidak disengaja.
  • Kami akan memblokir kunci API yang bocor dan digunakan dengan Gemini API secara default, sehingga membantu mencegah penyalahgunaan biaya dan data aplikasi Anda.
  • Anda dapat menemukan status kunci API Anda di Google AI Studio dan kami akan berupaya berkomunikasi secara proaktif saat kami mengidentifikasi kunci API Anda bocor untuk tindakan segera.

Meningkatkan output model

Untuk output model berkualitas lebih tinggi, coba tulis perintah yang lebih terstruktur. Halaman panduan rekayasa perintah memperkenalkan beberapa konsep dasar, strategi, dan praktik terbaik untuk membantu Anda memulai.

Memahami batas token

Baca panduan Token kami untuk lebih memahami cara menghitung token dan batasnya.

Masalah umum

  • API hanya mendukung sejumlah bahasa tertentu. Mengirimkan perintah dalam bahasa yang tidak didukung dapat menghasilkan respons yang tidak terduga atau bahkan diblokir. Lihat bahasa yang tersedia untuk mengetahui informasi terbaru.

Laporkan bug

Bergabunglah dalam diskusi di forum developer Google AI jika Anda memiliki pertanyaan.