TR ▾

Ana SayfaRehber

Geliştiriciler için LLM Proxy Hata Ayıklama Rehberi

Bir LLM proxy'si, uygulama kodunuz ile büyük dil modeli sağlayıcıları arasında bir çeviri katmanı olarak hareket eder; ancak yanlış yapılandırılmış uç noktalar, akış protokolleri veya bağlam limitleri sessiz hatalara neden olabilir. Bu kılavuz, 404 hatalarını düzeltmekten hız limitlerini işlemeye kadar, proxy hata ayıklamanın özel mekaniklerini ele alır ve istemci kodunuzun güvenilir bir şekilde bağlandığını sağlar.

Geliştiriciler için LLM Proxy Hata Ayıklama Rehberi

Anahtar noktalar

  1. Modelin kapalı olduğunu varsamadan önce temel URL'nizi ve API anahtarı formatınızı doğrulayın.
  2. Akış (SSE) hataları genellikle istemci SDK'sındaki eksik başlıklardan veya uygun olmayan arabellek işlemlerinden kaynaklanır.
  3. Hız limitleri anahtar başına uygulanır; bu nedenle bir anahtarı yeniden oluşturmak kullanım sayacınızı hemen sıfırlamaz.
  4. Bağlam penceresi hataları, birleşik istem ve tamamlama token'ları modelin katı sınırını aştığında oluşur.

Proxy ve Doğrudan API Arasındaki Farkı Anlamak

Doğrudan bir API çağrısından bir LLM proxy'sine geçtiğinizde, isteğinizi çeviren bir ara sunucu devreye sokmuş olursunuz. Doğrudan bir API çağrısı, verileri istemciden doğrudan model sağlayıcısına gönderir. Bir proxy bu isteği keser, kendi mantığını (yönlendirme, önbellekleme veya model seçimi gibi) uygular ve ardından ileter. claude code proxy veya benzeri bir hizmet kullanan geliştiriciler için amaç genellikle yerinde uyumluluktur: base_url ve api_key değerlerini değiştirirsiniz, ancak mevcut kodunuzu olduğu gibi korursunuz.

Karşılık olarak gecikme süresi vardır. Her proxy ek bir adım ekler. Proxy iyi optimize edilmemişse, ilk token süresinde (TTFB) artış görebilirsiniz. Ayrıca proxy'ler başlıkları veya gövde yapılarını hafifçe değiştirebilir. Her zaman proxy'nin istemcinizin beklediği tam OpenAI uyumlu şemayı desteklediğinden emin olun. Bir bağlantı sorununu hata ayıklıyorsanız, proxy'nin gerçekten çevrimiçi olduğunu ve sadece yanlış yapılandırılmadığını doğrulayın.

Birden fazla sağlayıcı arasında yönlendirme yapan genel bir geçit aksine, claudecodeproxyapi.com gibi özel bir proxy tek bir sansürsüz modele odaklanır. Bu, model yönlendirme özelliklerine sahip olmayacağınız anlamına gelir, ancak bu belirli mimari için öngörülebilir performans elde edersiniz.

'404 Not Found' Hatalarını Düzeltme

Bir LLM proxy'den gelen 404 hatası genellikle bozuk bir temel URL veya yanlış bir uç nokta yolu gösterir. En yaygın hata, ekstra bir /chat/completions eklemek veya /v1 önekini eksik bırakmaktır. Örneğin, https://api.claudecodeproxyapi.com/chat/completions kullanmak yerine https://api.claudecodeproxyapi.com/v1/chat/completions kullanmak başarısız olur.

  • Temel URL'yi kontrol edin: Proxy sağlayıcınız tarafından sağlanan tam URL'yi kullandığınızdan emin olun. Standart bir kalıp izlediğini varsaymayın.
  • Uç noktayı doğrulayın: Çoğu OpenAI uyumlu proxy POST /v1/chat/completions kullanır. Bazı eski veya özel proxy'ler eski metin modelleri için POST /completions kullanabilir.
  • Yanıt gövdesini inceleyin: 404 yanıtı genellikle eksik rotayı açıklayan bir JSON hata mesajı içerir.

If you are using a standard SDK like OpenAI's Python or Node client, ensure you are not manually constructing the URL if the SDK expects just the base. Double-check that your proxy supports the /v1 prefix. If the error persists, try a simple curl request to isolate whether the issue is in your code or the proxy itself.

Akış (SSE) Sorunlarını Giderme

Server-Sent Events (SSE) üzerinden akış, tam tamamlamayı beklemek yerine token token yanıtlar almanızı sağlar. Bu, sohbet arayüzleri için kritiktir. Akış başarısız olursa uygulamanız asılı kalabilir veya tüm yanıtı tek seferde görüntüleyebilir.

  • Başlıkları kontrol edin: İsteğinizin Accept: text/event-stream ve Content-Type: application/json başlıklarını içerdiğinden emin olun. Bazı proxy'ler bunları açıkça gerektirir.
  • Akışı doğru şekilde işleyin: SDK'nızın yerleşik akış desteğini kullanın. SSE verilerinin manuel ayrıştırılması, data: [DONE] gibi sınır olaylarını kaçırmanız durumunda hata yapmaya açıktır.
  • Hata ayıklama: Akış erken kesilirse, ağ kesintilerini veya proxy zaman aşımı ayarlarını kontrol edin.

Akış desteği olan bir claude code proxy için, istemcinizin kısmi yanıtları işleyecek şekilde yapılandırıldığından emin olun. Doğrudan API'den bir proxy'ye geçtiğinizde, proxy'nin gerçekten SSE'yi uyguladığını doğrulayın. Tüm proxy'ler bunu desteklemez ve bazıları akış istenmediğinde standart JSON yanıtlarına geri dönebilir.

Hız Limitlerini Yönetme (300 RPM)

Hız limitleri kötüye kullanımı önler ve adil kaynak kullanımını sağlar. Yaygın bir kafa karışıklığı, hız limitlerinin genellikle hesabınızdan çok API anahtarınızla ilişkili olmasıdır. Tek bir anahtarınız varsa, o anahtarın kota sınırına tabi olursunuz.

claudecodeproxyapi.com için sınır, anahtar başına dakikada 300 istektir. Bu değeri aşarsanız, 429 Çok Fazla İstek hatası alırsınız. Bunu çözmek için:

  • Üstel geri çekilme uygulayın: Başarısız istekleri artan gecikmelerle yeniden deneyin.
  • Retry-After başlığını kontrol edin: Bu başlık, yeniden deneme yapmadan önce ne kadar beklemeniz gerektiğini sıklıkla belirtir.
  • Anahtarınızı yeniden oluşturun: Anahtarınızı yeniden oluşturabildiğinizi unutmayın, ancak bunun hız limiti sayacınızı hemen sıfırlamadığını belirtin. Yeni anahtar, kısa bir süre için eski anahtarın kullanım geçmişini devralır.

Hesap başına birden fazla anahtar sunan bazı sağlayıcıların aksine, bu hizmet hesabı başına tek bir anahtar sağlar. Daha yüksek iş yükü için istemci tarafında kuyruk yönetimi uygulamanız veya mevcutse planınızı yükseltmeniz gerekebilir.

Bağlam Penceresi Aşım Hataları

Bağlam penceresi, modelin tek bir istekte işleyebileceği maksimum token sayısını (istem + tamamlama) ifade eder. İsteminiz bu limiti aşarsa API bir hata döndürür. claudecodeproxyapi.com için bağlam penceresi 100.000 token'dır.

  • Token kullanımını hesaplayın: İsteminizdeki ve beklenen yanıtızdaki tokenları saymak için bir tokenizasyon kütüphanesi kullanın. Temkinli olun; yanıtınızın bağlam penceresinin %10-20'sini alacağını tahmin edin.
  • Uzun girdileri kısaltın: Büyük belgeler gönderiyorsanız, bunları en alakalı bölümlere kısaltın.
  • Sistem mesajlarını kontrol edin: Sistem istemleri ve fonksiyon tanımları bağlam penceresine dahil edilir. Boyutlarını hafife almayın.

Bir bağlam penceresi hatasıyla karşılaşırsanız, giriş boyutunu azaltın veya sağlayıcı daha büyük bir bağlam seçeneği sunuyorsa modelin sınırını artırın. Unutmayın ki sınır, tek bir istekte gönderilen toplam token sayısına uygulanır, sadece giriş metnine değil.

Kimlik Doğrulama ve Anahtar Yeniden Oluşturma

Kimlik doğrulama genellikle Authorization: Bearer başlığı aracılığıyla geçirilen bir API anahtarı ile yapılır. 401 Yetkisiz erişim hatası alırsanız, anahtarınızın doğru olduğundan ve süresinin dolmadığından emin olun.

Çoğu proxy API anahtarınızı yeniden oluşturmanıza olanak tanır. Bir anahtarı yeniden oluşturduğunuzda:

  • Eski anahtar iptal edilir: Eski anahtarı kullanan istekler hemen başarısız olur.
  • Yeni bir anahtar oluşturulur: Ortam değişkenlerinizi veya yapılandırma dosyalarınızı yeni anahtarı kullanacak şekilde güncelleyin.
  • Kullanım geçmişi korunur: Bir anahtarı yeniden oluşturduğunuzda faturalandırma ve kullanım istatistikleriniz sıfırlanmaz.

claudecodeproxyapi.com için anahtarınızı panelden istediğiniz zaman yeniden oluşturabilirsiniz. Bu, anahtarınızın sızdığından şüpheleniyorsanız kullanışlıdır. Yenileme yapmadan önce anahtarı kullanan tüm istemcileri güncellediğinizden emin olun, aksi takdirde kesinti yaşarlar.

Fonksiyon Çağırma Hatalarının Ayıklanması

Fonksiyon çağırma (fonksiyon çağırma), modelin kodunuzdan belirli eylemler talep etmesini sağlar. Fonksiyon çağırma başarısız olursa, model istenen işlevi çalıştırmayabilir veya kodunuz işlev argümanlarını ayrıştırmada başarısız olabilir.

  • Fonksiyon şemasını doğrulayın: Fonksiyon tanımlarınızın proxy'nin beklediği şemayla eşleştiğinden emin olun. Eşleşmeyen parametre türleri veya eksik gerekli alanlar başarısızlıklara neden olabilir.
  • Kısmi yanıtları işleyin: Akış sırasında araç çağrıları parça parça gelebilir. İstemcinizin bu parçaları tam bir fonksiyon çağrısında birleştirebildiğinden emin olun.
  • Hata mesajlarını kontrol edin: Model bir aracı çağıramazsa, API yanıtı genellikle nedenini açıklayan bir hata mesajı içerir (örneğin, argümanlarda geçersiz JSON).

Araç çağırma desteği olan bir claude code proxy için, istemcinizin araç yanıt formatını işleyecek şekilde yapılandırıldığından emin olun. Doğrudan API'den geçtiğinizde, proxy'nin aynı araç çağırma şemasını desteklediğini doğrulayın. Bazı proxy'ler araç çağırma özelliğini etkinleştirmek için ek yapılandırma gerektirebilir.

İstek Gövdesi Boyutu Sınırlarının Yönetimi

Çoğu API, aşırı kaynak kullanımını önlemek için istek gövdesinin boyutuna bir sınır getirir. İstek gövdeniz bu limiti aşarsa API, 413 Gövde Çok Büyük hatasını döndürür.

claudecodeproxyapi.com için istek gövdesi limiti 8 MB'dir. Bu sınır, başlıkları ve JSON gövdesini de içeren tüm HTTP isteğine uygulanır. Bunu yönetmek için:

  • Büyük girdileri sıkıştırın: Büyük dosyalar gönderiyorsanız, göndermeden önce sıkıştırmayı düşünün.
  • Gönderi boyutunu azaltın: JSON isteğinizden gereksiz alanları kaldırın. Yalnızca API tarafından gerekli olan parametreleri gönderin.
  • İstek boyutunu izleyin: Limiti ne zaman aştığınızı belirlemek için isteklerinizin boyutunu günlüğe kaydedin.

Bu sınırı sık sık aşıyorsanız, büyük görevleri daha küçük isteklere bölmeyi veya daha büyük yükleri destekleyen bir proxy kullanmayı düşünün.

Sonraki Adımlar ve Destek

Bu sorun giderme adımlarını izlediyseniz ve hala sorun yaşıyorsanız, aşağıdaki sonraki adımları göz önünde bulundurun:

  • Proxy'nin durum sayfasını kontrol edin: Bazı sağlayıcılar hizmetleri için gerçek zamanlı durum güncellemeleri yayınlar.
  • API dokümantasyonunu gözden geçirin: API'nin en son sürümünü kullandığınızdan ve istemcinizin güncel olduğundan emin olun.
  • Destek ile iletişime geçin: Sorun devam ederse, istek kimliğiniz ve hata günlüklerinizle birlikte proxy sağlayıcısının destek ekibiyle iletişime geçin.

claudecodeproxyapi.com için web sitemizde ek kaynaklar ve dokümantasyon bulabilirsiniz. Aylık ücreti olmayan ön ödemeli kredi sistemimiz sunuyoruz; bu da sansürsüz modelimizi uygulamalarınıza test etmenizi ve entegre etmenizi kolaylaştırır.

Sorular ve cevaplar

LLM proxy'si ile LLM gateway'i arasındaki fark nedir?

Bir LLM proxy'si genellikle şeffaf bir katman olarak hareket eder ve istekleri tek bir modele veya sabit bir model kümesine iletir. Bir LLM gateway'i genellikle gelişmiş yönlendirme mantığı içerir; bu da size maliyete, gecikmeye veya yeteneğe göre farklı modellere istek gönderme imkanı tanır. Proxy'ler daha basittir ve genellikle tek model kullanım durumları için daha iyi performans sunar; gateway'ler çok modellerli mimariler için daha fazla esneklik sağlar.

claudecodeproxyapi.com hesabı başına birden fazla API anahtarı destekliyor mu?

Hayır, claudecodeproxyapi.com hesabı başına bir API anahtarı sağlar. Anahtarı istediğiniz zaman yeniden oluşturabilirsiniz, ancak tek bir hesap altında aynı anda birden fazla aktif anahtarınız olamaz. Daha yüksek bir aktarım hızına ihtiyacınız varsa, istemci tarafında kuyruk yönetimi uygulamanız veya mevcut bir plan yükseltmeniz gerekebilir.

Bir LLM proxy'sinden akış yanıtlarını nasıl işlerim?

Akış yanıtlarını işlemek için istemcinizin Accept: text/event-stream başlığını istediğinden emin olun. SDK'nızın yerleşik akış desteğini kullanarak Sunucu Tarafı Olayları (SSE) verilerini işleyin. Bu, token token yanıtlar almanızı sağlar ve sohbet arayüzleri için kullanıcı deneyimini iyileştirir. Akış başarısız olursa, proxy'nin SSE'yi desteklediğinden ve istemcinizin olay akışını doğru şekilde ayrıştırdığından emin olun.

Bağlam penceresi sınırını aşarsam ne olur?

İsteğiniz bağlam penceresi limitini (claudecodeproxyapi.com için 100.000 token) aşarsa API bir hata döndürür. Uzun belgeleri kısaltarak veya isteminizdeki token sayısını azaltarak girdi boyutunu azaltmalısınız. Tokenları doğru şekilde saymak ve isteklerinizin limit içinde kalmasını sağlamak için bir tokenizasyon kütüphanesi kullanmayı düşünün.

Anahtarınız tek bir formun uzağında

Bir hesap oluşturun, anahtarı kopyalayın, temel URL'yi değiştirin. Kurulumun tamamı bu kadar.