Gemini API'yi çağırırken ortaya çıkan yaygın sorunları teşhis edip çözmenize yardımcı olması için bu kılavuzu kullanın. Gemini API arka uç hizmeti veya istemci SDK'ları ile ilgili sorunlarla karşılaşabilirsiniz. Müşteri SDK'larımız aşağıdaki depolarda açık kaynaklıdır:
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 engellendi kodları ve içerik hata kodları dahil olmak üzere tüm hata kodlarının eksiksiz bir referansı için API hataları sayfasına bakın.
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 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şımları, ağ sorunları ve sıklık sınırları (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, geçici hataları yaklaşık 1 saniyelik başlangıç gecikmesi ve maksimum 60 saniyelik gecikmeyle otomatik olarak en fazla 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ı 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 bekleyin (örneğin, 1 saniye), ardından gecikmeyi üstel olarak artırın (örneğin, 2 sn, 4 sn, 8 sn).
- Titreme ekleme: Tüm istemcilerin tam olarak aynı anda yeniden denemesini önlemek için gecikmeye rastgele "titreme" 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ı tanımlayın.
API çağrılarınızda model parametresi hataları olup olmadığını kontrol edin
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 modelin maksimum jeton sayısını belirlemek için 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 bir modeli 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 düşünme yöntemini kullanır.
Düşünen modeller, 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.
Gecikmeyi azaltmaya öncelik veriyorsanız veya maliyetleri en aza indirmeniz gerekiyorsa düşünme düzeyini düşürebilir ya da düşünmeyi devre dışı bırakabilirsiniz.
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 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 şekilde desteklenmiyor olabilir.
Okuma sorunu
Modelin, RECITATION (Tekrar) nedeniyle çıkış oluşturmayı durdurduğunu görüyorsanız 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 getirmeye çalışın ve daha yüksek bir sıcaklık kullanın.
Tekrarlayan jeton sorunu
Çıkış jetonlarının tekrarlandığını görüyorsanız bunları azaltmak veya tamamen kaldırmak için aşağıdaki önerileri deneyin.
| Açıklama | Neden | Önerilen geçici çözüm |
|---|---|---|
| Markdown tablolarında tekrarlanan tireler | Model, görsel olarak hizalanmış bir Markdown tablosu oluşturmaya çalıştığı için bu durum, tablonun içeriği uzun olduğunda ortaya çıkabilir. Ancak, Markdown'daki hizalama doğru oluşturma için gerekli değildir. |
Modelin Markdown tabloları oluşturması için isteminize talimatlar ekleyin. Bu yönergelere uygun örnekler verin. Sıcaklığı da ayarlamayı deneyebilirsiniz. Kod oluşturma veya Markdown tabloları gibi çok yapılandırılmış çıkışlar için yüksek sıcaklık değerlerinin daha iyi sonuç verdiği görülmüştür (>= 0,8). Bu sorunu önlemek için isteminize ekleyebileceğiniz yönergelerle ilgili örnekleri aşağıda bulabilirsiniz:
# 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. Doğru oluşturma için Markdown'da hizalama gerekmez. |
|
Yapılandırılmış çıkışta tekrar eden 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 tekrar edebilir. |
|
| Tekrarlanan araç çağrıları | Bu durum, modelin önceki düşüncelerin bağlamını kaybetmesi ve/veya kullanılamayan bir uç noktayı çağırmaya zorlanması durumunda ortaya çıkabilir. |
Modele, düşünce sürecinde durumu koruması talimatını verin.
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ış çıktının parçası olmayan tekrarlayan metinler | Bu durum, modelin çözemediği bir isteğe takılması halinde ortaya çıkabilir. |
|
Engellenmiş 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üvenli bir şekilde saklanmasını ve herkese açık olmamasını sağlamak 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önderin. Fatura ekibimiz bu konu üzerinde çalışıyor ve en kısa sürede güncellemeleri sizinle paylaşacağız.
Sızdırılan anahtarlarla ilgili Google'ın güvenlik önlemleri
API anahtarlarım sızdırılırsa Google, hesabımın maliyet aşımı ve kötüye kullanıma karşı güvenliğini sağlamama nasıl yardımcı olacak?
- Google AI Studio'yu kullanarak yeni bir anahtar istediğinizde API anahtarları vermeye geçiyoruz. Bu anahtarlar varsayılan olarak yalnızca Google AI Studio ile sınırlı olacak ve diğer hizmetlerden gelen anahtarları kabul etmeyecek. Bu sayede, anahtarların yanlışlıkla çapraz kullanımını önleyebilirsiniz.
- Sızdırılan ve Gemini API ile kullanılan API anahtarlarını varsayılan olarak engelliyoruz. Böylece maliyetin 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 olarak sizinle iletişime geçeriz.
Model çıktısını iyileştirme
Daha kaliteli model çıkışları için daha yapılandırılmış istemler yazmayı deneyin. İstem mühendisliği rehberi 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ıldığını ve sınırlarını daha iyi anlamak için Jeton kılavuzumuzu inceleyin.
Bilinen sorunlar
- API yalnızca belirli dilleri destekler. Desteklenmeyen dillerde istem göndermek beklenmedik veya hatta engellenen yanıtlar üretebilir. Güncellemeler için kullanılabilir dilleri inceleyin.
Hata bildir
Sorularınız varsa Google Yapay Zeka geliştirici forumunda tartışmaya katılın.