Gemini API'yi çağırırken ortaya çıkan yaygın sorunları teşhis edip çözmek için bu kılavuzdan yararlanabilirsiniz. Gemini API arka uç hizmetinden veya istemci SDK'larından kaynaklanan sorunlarla karşılaşabilirsiniz. İstemci SDK'larımız aşağıdaki depolarda açık kaynaklı olarak sunulur:
API anahtarıyla ilgili sorunlarla karşılaşırsanız API anahtarı kurulum kılavuzuna göre API anahtarınızı doğru şekilde ayarladığınızı doğrulayın.
Hata kodları
HTTP durum kodları, oluşturma engelleme kodları ve içerik hata kodları dahil olmak üzere tüm hata kodlarının tam listesi için API hataları sayfasını inceleyin.
Yeniden deneme stratejisi
İsteğinizi yeniden denemeniz gerektiğini belirten bir hata alırsanız (ör. 429 RESOURCE_EXHAUSTED veya 503 UNAVAILABLE) eksponansiyel geri yükleme stratejisi uygulamanızı öneririz. Bu durumda, ilk yeniden denemeden önce kısa bir süre beklersiniz ve ardından sonraki yeniden denemeler arasındaki bekleme süresini kademeli olarak artırırsınız.
Gemini API'nin resmi istemci SDK'ları (ör. Python SDK), zaman aşımı, ağ sorunları ve sıklık sınırlamaları (429 ve 5xx durum kodları) gibi geçici hataları işlemek için varsayılan olarak eksponansiyel geri yükleme ile otomatik yeniden deneme mantığı içerir. Örneğin, Python SDK'sı geçici hataları yaklaşık 1 saniyelik bir başlangıç gecikmesi ve maksimum 60 saniyelik bir gecikmeyle otomatik olarak dört kez yeniden dener.
Doğrudan REST API istekleri gönderiyorsanız veya yeniden deneme mantığınızı özelleştiriyorsanız başarılı bir istek olasılığını artırmak ve hizmetin aşırı yüklenmesini önlemek için aşağıdaki en iyi uygulamaları izleyin:
- Eksponansiyel geri yükleme kullanın: İlk yeniden denemeden önce kısa bir süre (ör. 1 saniye) bekleyin, ardından gecikmeyi üstel olarak artırın (ör. 2 sn, 4 sn, 8 sn).
- Dalgalanma ekleme: Tüm istemcilerin tam olarak aynı anda yeniden denemesini önlemek için gecikmeye rastgele "dalgalanma" ekleyin.
- Belirli hatalarda yeniden deneme: Yalnızca geçici hatalarda (ör.
429,408veya5xx) yeniden deneyin. Geçersiz API anahtarları, ön ödemeli kredilerin tükenmesi veya hatalı söz dizimi gibi sorunları gösterdikleri için istemci hatalarında (ör.400,402veya403) yeniden denemeyin. - Maksimum yeniden deneme sayısını ayarlama: Sonsuz döngüleri önlemek için maksimum yeniden deneme sayısını tanımlayın.
Model parametresi hataları için API çağrılarınızı kontrol etme
Model parametrelerinizin aşağıdaki değerler içinde olduğunu doğrulayın:
| Model parametresi | Değerler (aralık) |
| Aday sayısı | 1-8 (tam sayı) |
| Sıcaklık | 0,0-1,0 |
| Maksimum çıkış jetonu sayısı | Kullandığınız model için maksimum parça sayısını belirlemek üzere modeller sayfasını kullanın. |
| TopP | 0,0-1,0 |
Parametre değerlerini kontrol etmenin yanı sıra doğru API sürümünü (ör. /v1 veya /v1beta) ve ihtiyacınız olan özellikleri destekleyen bir model kullandığınızdan emin olun. Örneğin, bir özellik Beta sürümündeyse yalnızca /v1beta API sürümünde kullanılabilir.
Doğru modele sahip olup olmadığınızı kontrol edin
Modeller sayfamızda listelenen desteklenen modellerden birini kullandığınızı doğrulayın.
Düşünebilen modellerde daha yüksek gecikme süresi veya jeton kullanımı
Daha yüksek gecikme süresi veya jeton kullanımı, genellikle Gemini 3.x modellerinde düşünme özelliğinin varsayılan olarak etkin olmasından kaynaklanır. Desteği sonlandırılan Gemini 2.5 modelleri de varsayılan olarak düşünme özelliğini kullanır.
Düşünme modelleri, kaliteyi artırmak için dahili akıl yürütme jetonları oluşturur. Bu muhakeme süreci hem yanıt gecikmesini hem de toplam jeton tüketimini artırır.
Daha düşük gecikme süresine öncelik veriyorsanız veya maliyetleri en aza indirmeniz gerekiyorsa düşünme seviyesini düşürebilir ya da düşünme özelliğini kapatabilirsiniz.
Yapılandırma ayrıntıları ve kod örnekleri için düşünme kılavuzuna bakın.
Güvenlik sorunları
API çağrınızdaki bir güvenlik ayarı nedeniyle bir istemin engellendiğini görürseniz istemi, API çağrısında ayarladığınız filtrelere göre inceleyin.
BlockedReason.OTHER simgesini görüyorsanız sorgu veya yanıt, Hizmet Şartları'nı ihlal ediyor ya da başka bir nedenle desteklenmiyor olabilir.
Okuma sorunu
Modelin RECITATION nedeniyle çıkış oluşturmayı durdurduğunu görürseniz bu, model çıkışının belirli verilere benzeyebileceği anlamına gelir. Bu sorunu düzeltmek için istemi / bağlamı mümkün olduğunca benzersiz hale getirmeyi ve daha yüksek bir sıcaklık kullanmayı deneyin.
Tekrar eden jeton sorunu
Tekrarlanan çıkış jetonları görüyorsanız bunları azaltmak veya ortadan kaldırmak için aşağıdaki önerileri deneyin.
| Açıklama | Neden | Önerilen geçici çözüm |
|---|---|---|
| Markdown tablolarında tekrarlanan kısa çizgiler | Model, görsel olarak hizalanmış bir Markdown tablosu oluşturmaya çalıştığı için tablonun içeriği uzun olduğunda bu durum ortaya çıkabilir. Ancak, Markdown'daki hizalama doğru oluşturma için gerekli değildir. |
Modele Markdown tabloları oluşturmayla ilgili belirli yönergeler vermek için isteminize talimatlar ekleyin. Bu yönergelere uygun örnekler verin. Sıcaklığı da ayarlamayı deneyebilirsiniz. Kod veya Markdown tabloları gibi çok yapılandırılmış çıktılar oluşturmak için yüksek sıcaklığın (>= 0,8) daha iyi sonuç verdiği görülmüştür. Aşağıda, bu sorunu önlemek için isteminize ekleyebileceğiniz örnek bir kural grubu verilmiştir:
# 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.
|
| Markdown tablolarında tekrarlanan jetonlar | Tekrarlanan kısa çizgilerde olduğu gibi bu durum da modelin tablonun içeriğini görsel olarak hizalamaya çalışmasından kaynaklanır. Markdown'da hizalama, doğru oluşturma için gerekli değildir. |
|
Yapılandırılmış çıkışta tekrarlanan yeni satırlar (\n)
|
Model girişi, \u veya \t gibi Unicode ya da kaçış dizileri içerdiğinde tekrarlanan yeni satırlara yol açabilir.
|
|
| Yapılandırılmış çıktı kullanırken tekrarlanan metin | Model çıkışındaki alanların sırası, tanımlanan yapılandırılmış şemadan farklı olduğunda metin tekrarlanabilir. |
|
| Tekrarlanan araç çağrıları | Bu durum, model önceki düşüncelerin bağlamını kaybederse ve/veya zorunlu olduğu kullanılamayan bir uç noktayı çağırırsa ortaya çıkabilir. |
Modele, düşünme sürecinde durumu korumasını söyleyin.
Bunu sistem talimatlarınızın sonuna ekleyin:
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.
|
| Yapılandırılmış çıkışın parçası olmayan tekrarlanan metinler | Bu durum, model çözemediği bir istekte takılı kaldığında ortaya çıkabilir. |
|
Engellenen veya çalışmayan API anahtarları
Bu bölümde, Gemini API anahtarınızın engellenip engellenmediğini nasıl kontrol edeceğiniz ve bu durumda ne yapmanız gerektiği açıklanmaktadır.
Anahtarların neden engellendiğini anlama
Bazı API anahtarlarının herkese açık olarak kullanılabildiği bir güvenlik açığı tespit ettik. Verilerinizi korumak ve yetkisiz erişimi önlemek için, sızdırıldığı bilinen bu anahtarların Gemini API'ye erişimini proaktif olarak engelledik.
Anahtarlarınızın etkilenip etkilenmediğini onaylayın
Sızdırıldığı bilinen anahtarlar Gemini API ile kullanılamaz. API anahtarlarınızdan herhangi birinin Gemini API'yi çağırmasının engellenip engellenmediğini görmek ve yeni anahtarlar oluşturmak için Google AI Studio'yu kullanabilirsiniz. Bu anahtarları kullanmaya çalışırken aşağıdaki hatanın döndürüldüğünü de görebilirsiniz:
Your API key was reported as leaked. Please use another API key.
Engellenen API anahtarları için işlem
Google AI Studio'yu kullanarak Gemini API entegrasyonlarınız için yeni API anahtarları oluşturmanız gerekir. Yeni anahtarlarınızın güvende tutulması ve herkese açık olarak gösterilmemesi için API anahtarı yönetimi uygulamalarınızı gözden geçirmenizi önemle tavsiye ederiz.
Güvenlik açığı nedeniyle beklenmedik ücretler
Faturalandırma destek kaydı gönderme Fatura ekibimiz bu konu üzerinde çalışıyor ve en kısa sürede güncellemeleri sizinle paylaşacağız.
Sızdırılan anahtarlar için Google'ın güvenlik önlemleri
API anahtarlarım sızdırılırsa Google, hesabımı bütçe aşımına ve kötüye kullanıma karşı korumaya nasıl yardımcı olacak?
- Google AI Studio'yu kullanarak yeni bir anahtar istediğinizde API anahtarları vermeye başlıyoruz. Bu anahtarlar varsayılan olarak yalnızca Google AI Studio ile sınırlı olacak ve diğer hizmetlerden anahtar kabul etmeyecek. Bu sayede, anahtarların yanlışlıkla çapraz kullanımı önlenir.
- Sızdırılan ve Gemini API ile kullanılan API anahtarlarını varsayılan olarak engelleyerek maliyetlerin ve uygulama verilerinizin kötüye kullanılmasını önlemeye yardımcı oluyoruz.
- API anahtarlarınızın durumunu Google AI Studio'da bulabilirsiniz. API anahtarlarınızın sızdırıldığını tespit ettiğimizde ise hemen harekete geçmeniz için proaktif bir şekilde sizinle iletişime geçeriz.
Model çıktısını iyileştirme
Daha yüksek kaliteli model çıkışları için daha yapılandırılmış istemler yazmayı deneyin. İstem mühendisliği kılavuzu sayfasında, başlamanıza yardımcı olacak bazı temel kavramlar, stratejiler ve en iyi uygulamalar tanıtılmaktadır.
Jeton sınırlarını anlama
Jetonların nasıl sayılacağını ve sınırlarını daha iyi anlamak için Jeton kılavuzumuzu okuyun.
Bilinen sorunlar
- API yalnızca belirli dilleri destekler. Desteklenmeyen dillerde istem gönderildiğinde beklenmedik veya engellenen yanıtlar alınabilir. Güncellemeler için kullanılabilir dilleri inceleyin.
Hata bildir
Sorularınız varsa Google AI geliştirici forumunda tartışmaya katılın.