Hata yönetimi, hız sınırlama ve kota yönetimi

Üretim uygulamalarında ve yapay zeka aracıları içinde Developer Knowledge API veya Developer Knowledge MCP sunucusunu sorgularken yüksek performans elde etmek için hata işleme ve kota yönetimi olmalıdır.

Bu kılavuzda şunları öğreneceksiniz:

  • HTTP 429 yanıtları için jitter ile kesilmiş eksponansiyel geri yüklemeyi uygulayın.
  • Standart gRPC hata kodlarını (INVALID_ARGUMENT, PERMISSION_DENIED, RESOURCE_EXHAUSTED) işleyin.
  • MCP bağlantı zaman aşımlarını ve yeniden deneme mantığını yönetin.
  • Kota yönetimi ve önbelleğe alma ile ilgili en iyi uygulamaları kullanın.

HTTP 429 sıklık sınırlaması ve eksponansiyel geri yükleme

İstek oranları varsayılan API kotasını aştığında hizmet, HTTP 429 Too Many Requests hatası döndürür. Uygulamalar, hizmetin aşırı yüklenmesini önlemek için jitter ile kesilmiş eksponansiyel geri yükleme kullanarak yeniden deneme mantığı uygulamalıdır.

Kısaltılan eksponansiyel geri yükleme

Yeniden deneme gecikmelerini hesaplamak için aşağıdaki formülü kullanın:

retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)

Yeniden deneme gecikmelerini hesaplamak için aşağıdaki parametreleri kullanın:

  • initial_delay: İlk yeniden deneme gecikmesi (örneğin, 1,0 saniye).
  • max_delay: Maksimum geri çekilme sınırı (örneğin, 32,0 saniye).
  • attempt: Mevcut yeniden deneme sayısı (0, 1, 2, ...).
  • jitter: İş parçacığı senkronizasyonunda ani artışları (thundering herd problemi) önlemek için 0 ile 1,0 saniye arasında rastgele bir değer.

gRPC hata işleme

Hizmete gRPC üzerinden erişen uygulamalar, standart grpc.StatusCode değerlerini incelemelidir.

Standart gRPC durum kodları

Aşağıdaki tabloda, hizmet tarafından döndürülen standart gRPC durum kodları ve önerilen istemci işleme listelenmektedir:

gRPC durum kodu HTTP durumu Temel neden Önerilen işlem
INVALID_ARGUMENT 400 Bad Request Yanlış biçimlendirilmiş sorgu dizesi, geçersiz parametre biçimi veya geçersiz alan maskesi. Tekrar denemeyin. İsteği tekrarlamadan önce istek parametrelerini düzeltin.
UNAUTHENTICATED 401 Unauthorized Eksik, süresi dolmuş veya hatalı biçimlendirilmiş API anahtarı ya da OAuth Bearer jetonu. Tekrar denemeyin. Kimlik bilgilerini yenileyin veya geçerli bir API anahtarı oluşturun.
PERMISSION_DENIED 403 Forbidden API anahtarında izin eksik veya projede Developer Knowledge API devre dışı. Tekrar denemeyin. Google Cloud Console'da API'nin etkinleştirildiğini doğrulayın.
NOT_FOUND 404 Not Found Belirtilen parent belge yolu mevcut değil. İstenen dokümanlardan herhangi biri bulunamazsa BatchGetDocuments atomik olarak başarısız olur. Tekrar denemeyin. Belge kaynağı adını doğrulayın.
RESOURCE_EXHAUSTED 429 Too Many Requests Sıklık sınırı veya proje kotası sınırı aşıldı. Eksponansiyel geri yükleme ve jitter ile yeniden deneyin.
UNAVAILABLE 503 Service Unavailable Geçici ağ bağlantısı kesilmesi veya sunucunun yeniden başlatılması. Eksponansiyel geri yüklemeyle yeniden deneyin.
DEADLINE_EXCEEDED 504 Gateway Timeout İstek, tamamlanmadan önce yapılandırılmış TBG son tarihini aştı. İstemci RPC zaman aşımı artırılarak yeniden deneyin.

MCP bağlantısı zaman aşımı ve hata yönetimi

Developer Knowledge MCP sunucusu, HTTPS üzerinden (HTTP POST veya sunucu tarafından gönderilen etkinlikler kullanılarak) erişilen, https://developerknowledge.googleapis.com/mcp adresinde barındırılan uzak bir hizmettir. Yapay zeka sunucuları ve aracıları, bağlantı zaman aşımlarını ve araç hatalarını düzgün bir şekilde yönetmelidir.

Araç yürütme zaman aşımları

Bir aracı search_documents, get_documents veya answer_query işlevini çağırdığında, ağ bağlantılarında gecikme olursa araç çağrıları zaman aşımı sürelerini (örneğin, 30 saniye) aşabilir.

Araç yürütme zaman aşımlarını işlemek için:

  • İstemci zaman aşımlarını yapılandırın: MCP ana makine istemci yapılandırmanızda araç yürütme zaman aşımlarını 30-60 saniye olarak ayarlayın.
  • Ağ kesintilerini ele alma: Geçici ağ düşüşleri veya HTTP 503 yanıtları yaşandığında başarısız HTTP isteklerini eksponansiyel geri yükleme ile yeniden deneyin.
  • Hata mesajlarını inceleme: Geçersiz bağımsız değişkenleri kota tükenmesinden ayırt etmek için standart JSON-RPC hata mesajlarını veya HTTP hata durum kodlarını ayrıştırın.

Kota yönetimiyle ilgili en iyi uygulamalar

API kullanımını en iyi şekilde sürdürmek ve beklenmedik sıklık sınırlarından kaçınmak için aşağıdaki en iyi uygulamalardan yararlanın:

  1. Alınan doküman içeriğini önbelleğe alma: Aynı sayfalara sık sık erişen uygulamalar oluştururken getirilen Markdown belgelerini yerel olarak veya bir önbellekte (ör. Redis) depolayın.
  2. Toplu alma işlemini kullanın: Birden fazla sıralı documents.get isteği yürütmek yerine documents.batchGet kullanın.
  3. Sorgu alanlarını optimize edin: Alan maskelerini (fields=results(parent,content)) kullanarak yalnızca gerekli yanıt alanlarını isteyin.
  4. Kota tüketimini izleme: Google Cloud Console API kontrol panelinde API istek hızlarını takip edin.

İlgili içerik