Bağlam Penceresi Limitlerini Anlamak
API hatalarının en sık nedenlerinden biri bağlam penceresini aşmaktır. Bağlam penceresi, modelin tek bir istekte işleyebileceği maksimum token sayısını tanımlar. Birleşik token sayınız bu limiti aşarsa API genellikle hata döndürür veya yanıtınızı öngörülemez şekilde keser.
Örneğin, 100.000 token'lık bağlam penceresine sahip bir sansürsüz Qwen modeli kullanıyorsanız, konuşma geçmişiniz ile yeni isteminizin toplamının bu eşiği aşmadığından emin olmalısınız. Çoğu geliştirici, uzun süreli oturumların kümülatif token sayısını takip etmez; bu da limit aşıldığında ani entegrasyon hatalarına yol açar.
- Token kullanımını takip edin: Tokenları doğru saymak için modelin tokeniser'ı ile tutarlı bir tokeniser kütüphanesi kullanın.
- Geçmişi kısaltın: Bağlam penceresi dolduğunda eski mesajları silmek için mantık uygulayın.
- Limitleri izleyin: Sağlanıyorsa kalan bağlam kapasitesi için API yanıt başlıklarını kontrol edin.
Bu limitleri göz ardı etmek sadece hatalara neden olmaz; model kalabalık bir pencerede ilgili bilgiye odaklanmaya çalışırken yanıt kalitesini de düşürebilir.
Akış Yanıtlarını Doğru Şekilde İşleme
Akış (streaming), modern LLM API'leri için standart bir özelliktir ve size parçaları oluşturulurken kısmi yanıtlar almanızı sağlar. Ancak, birçok geliştirici yanlışlıkla akışın her parça için tam bir JSON nesnesi döndürdüğünü varsayar. Gerçekte akış, her biri kısmi bir JSON parçası içeren bir dizi Sunucu Tarafından Gönderilen Olay (SSE) döndürür.
SSE desteği olmayan standart bir HTTP istemcisi kullanıyorsanız, ham metin akışını ayrıştırmanız gerekebilir; data: satırlarına göre bölme yapmalı ve her JSON nesnesini ayrı ayrı ayrıştırmalısınız. Bunu doğru şekilde işlemezseniz bozuk JSON hataları veya kesik metinlerle karşılaşabilirsiniz.
Ayrıca, önceki içeriği yerine koymak yerine artımlı metin ekleyecek şekilde tasarlanmış bir UI veya istemci kütüphaneniz olduğundan emin olun. Akış, token sayımını da etkiler; hız limitleri ve bütçe kısıtlamaları içinde kalmak için tokenları geldikçe saymalısınız.
İstemlerde Yaygın Biçimlendirme Hataları
LLM'ler istem biçemine duyarlıdır. Beklenen yapıdan küçük sapmalar bile, özellikle araç çağırma kullanırken kötü performans veya ayrıştırma hatalarına yol açabilir. Örneğin, fonksiyon çağırma kullanıyorsanız model belirli JSON şemaları bekler. İsteminizde ekstra boşluklar, eksik virgüller veya yanlış anahtar adları varsa model geçerli araç çağrıları oluşturamayabilir.
- Şablonlar kullanın: Manuel biçimlendirme hatalarını azaltmak için tutarlı bir istem şablonu kütüphanesi benimseyin.
- JSON'ı doğrulayın: İşlemeden önce her zaman çıktı JSON'unu beklenen şemanızla doğrulayın.
- Kenar durumları test edin: Sağlamlığı sağlamak için özel karakterler, yeni satırlar ve değişen uzunluklarla istemleri test edin.
Bir sansürsüz Qwen modeli ile entegrasyon yaparken, istem formatınızın modelin eğitim verisi yapısıyla eşleştiğinden emin olun. Uyuşmayan formatlar, modelin talimatları yok saymasına veya hatalı biçimli çıktı üretmesine neden olabilir.
Hız Limitleme ve Ani Trafik
API'ler, kötüye kullanımı önlemek ve kararlı performans sağlamak için hız limitlerini uygular. Yaygın bir hata, dakikadaki limiti aşan istek dalgalanmaları göndermek ve buna takiben gelen isteklerin 429 Too Many Requests hatıyla başarısız olmasıdır. Geliştiriciler, genellikle düşük trafik hacimleriyle test yapıp ölçeklendirme sırasında istek stratejilerini ayarlamadıkları için bunu gözden kaçırır.
Örneğin API dakika başına 300 isteklere izin veriyorsa, tek bir dakikada 301 istek göndermek son isteğin başarısız olmasına neden olur. Bunu önlemek için istemci kütüphanenizde üstel geri çekilme uygulayın. Bu strateji, her başarısızlıktan sonra yeniden denemeler arasındaki süreyi artırarak daha fazla tıkanıklığı önler.
Ayrıca istek desenlerinizi izleyin. Büyük toplu işler işlerken, hepsini aynı anda göndermek yerine istekleri zaman içinde yaymayı düşünün. Bu tutarlı performans sağlar ve katı limitlere takılmayı önler.
Token Sayım Hesaplamaları
Token sayımı genellikle hafife alınır. Geliştiriciler sıkça token yerine karakter veya kelime sayarlar. Tokenizer'lar metni alt kelimelere böler; bu nedenle tek bir kelime birden fazla token olarak sayılabilir.
Örneğin, uncensored kelimesi, tokenizere bağlı olarak birden fazla token olarak sayılabilir. Doğru sayımlar için her zaman API sağlayıcısının sağladığı resmi tokenizörü kullanın. Bu, maliyetleri hesaplamak için kritiktir çünkü fiyatlandırma genellikle 1M token başına belirlenir.
- Resmi tokenizer'ları kullanın: Token başına 4 karakter gibi tahminlerden kaçının.
- Giriş ve çıktıyı sayın: Hem istem hem de tamamlama tokenlarının faturalandırıldığını unutmayın.
- Kullanımı izleyin: Sürpriz ücretlerden kaçınmak için yüksek token kullanımı için uyarı kurun.
Doğru token sayımı, kritik operasyonlar sırasında hizmet kesintilerini önleyerek bütçe ve bağlam limitleri içinde kalmanızı sağlar.
Araç Çağırma Yapılandırma Sorunları
Araç çağırma, modelin harici fonksiyonları çağırmasını sağlar ancak hassas yapılandırma gerektirir. Yaygın bir hata, API isteğinde tanımlanan fonksiyon şemasını kodunuzdaki gerçek fonksiyon uygulamasıyla eşleştirmemektir. Şema, fonksiyonunuzun imzasıyla eşleşmeyen bir parametre türü belirtirse model geçersiz argümanlar üretebilir.
Başka bir sorun, fonksiyon çağırma sonuçlarını sonraki isteme eklemeyi unutmaktır. Model son yanıtı oluşturmak için aracın çıktısına ihtiyaç duyar. Bu adımı atlaması modelin uydurma yapmasına neden olabilir.
Araç tanımlarınızın açık, açıklayıcı adlara ve parametrelere sahip olduğundan emin olun. Modelin fonksiyonları doğru şekilde yorumlayıp çalıştırabildiğinden emin olmak için araç çağırma akışını çeşitli girdilerle kapsamlı bir şekilde test edin. Bu özellikle farklı eğitim veri dağılımlarına sahip olan sansürsüz Qwen gibi açık ağırlıklı modeller kullanılırken önemlidir.
Kimlik Doğrulama Başlığı Hataları
Kimlik doğrulama, API erişiminiz için savunmanın ilk çizgisidir. Yaygın bir hata, yanlış başlık formatının kullanılmasıdır. Çoğu OpenAI uyumlu API, yetkilendirme başlığınınAuthorization: Bearer YOUR_API_KEY formatında olmasını bekler. API-Key veya diğer varyantların kullanılması 401 Unauthorized hatalarına yol açabilir.Başka bir sorun, API anahtarını başlık yerine sorgu dizgesinde geçirmektir. Bu daha az güvenlidir ve tüm istemcilerle çalışmayabilir. Daha iyi güvenlik ve uyumluluk için her zaman başlık yöntemini tercih edin.
- Başlık formatını doğrulayın: Gerekli başlık formatını API dokümantasyonunda iki kez kontrol edin.
- Güvenli anahtar depolama: API anahtarlarını kod içinde değil, ortam değişkenlerinde saklayın.
- Anahtarları yenileyin: Bir anahtarın ele geçirilmesi durumunda riski en aza indirmek için anahtarları periyodik olarak yeniden oluşturun.
Doğru kimlik doğrulama, isteklerinizin tanınmasını ve doğru şekilde işlenmesini sağlar; gereksiz yeniden denemeleri ve hataları önler.
Hata Yanıtı Yorumlama
API hataları hata ayıklama için değerli ipuçları sağlar ancak sıklıkla yanlış yorumlanır. 400 Bad Request hatası genellikle geçersiz JSON veya eksik gerekli alanlar gibi girdi verisiyle ilgili bir sorunu belirtir. 401 Unauthorized hatası kimlik doğrulama sorunlarına işaret ederken, 429 Too Many Requests hatası hız limiti ihlallerini bildirir.
Hata mesajını dikkatlice okuyun. Sıklıkla hataya neden olan alanı veya ihlal edilen kısıtlamayı içeren ayrıntılar içerir. Örneğin, bir hata mesajı "Invalid value: 'function'" gibi bir ifade içerebilir; bu, bir mesajdaki role alanının yanlış olduğunu gösterir.
Hataları tutarlı bir şekilde günlüğe kaydedin ve istem yükü ve başlıklar gibi bağlamı dahil edin. Bu, sorunları daha sonra yeniden üretmek ve teşhis etmek için daha kolay hale getirir. Geçici hataları görmezden gelmeyin; geçici ağ veya sunucu sorunlarını işlemek için üstel geri çekilme ile yeniden deneme mantığı uygulayın.
