# LLM API’sini Değiştirmeden Önce Akış ve Araç Çağrısı Uyumluluğu Nasıl Test Edilir? > Bir LLM API geçişini sohbet demosuyla değil, kaydedilmiş sözleşme fixture’larıyla test edin. Metin akışını, zorunlu aracı, parçalı argümanları, çoklu çağrıları, sonuç dönüşünü, iptali, hataları ve kullanım muhasebesini doğrulayın. On dakikalık bir sohbet testi önemli hataları kaçırabilir: yeniden denemede çift çağrı, son akış olayından önce yürütülen JSON, yanlış rolle dönen araç sonucu veya iptalden sonra devam eden yazma işlemi. Yararlı bir geçiş kapısı sabit istekleri gerçek parser ve yürütücüden geçirip yapısal değişmezleri değerlendirir. İlk paket sık çalışacak kadar küçük, modeller arasında karşılaştırılacak kadar deterministik olmalıdır. Amaç zekâyı sıralamak değil, yeni API’nin mevcut ajan döngüsünü güvenli biçimde çalıştırabildiğini kanıtlamaktır. ## İstemcinin bağımlı olduğu sözleşmeyi tanımlayın Sağlayıcıyı test etmeden önce istemcinin ihtiyaç duyduğu davranışı yazın. “OpenAI uyumlu” gibi belirsiz etiketlerden kaçının. | Sözleşme alanı | Gerekli değişmez | Saklanacak kanıt | |---|---|---| | Kimlik doğrulama | Endpoint anahtarı kabul eder | Durum ve request ID | | Metin akışı | Deltalar tek bir son mesaj olur | Sıralı ham olaylar | | Araç akışı | Çağrı yürütmeden önce tamamlanır | Çağrı bufferı ve final olayı | | Korelasyon | Sonuç doğru çağrıya bağlanır | Call ID eşlemesi | | Yeniden deneme | Çağrı en fazla bir kez yürütülür | Idempotency günlüğü | | Kullanım | Sayaçlar vardır veya unavailable işaretlidir | Son yanıt metadatası | Protokol desteği modele özeldir. Atlas Cloud birden fazla istek biçimi sunduğu için test rotasını seçmeden önce güncel [`supported_apis` rehberini](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) kontrol edin. ## Dört deterministik araç oluşturun Farklı hata biçimlerini açığa çıkaran fixture’lar kullanın: * `echo_json`, doğrulanmış argümanları değiştirmeden döndürür. * `read_fixture`, sandbox içindeki bilinen bir dosyayı okur. * `delayed_value`, kontrollü gecikmeden sonra tamamlanır. * `always_error`, sabit ve yapılandırılmış hata döndürür. Her araca `additionalProperties: false` içeren katı bir şema ve çift yürütmeyi görünür kılan benzersiz fixture ID verin. Hava durumu, arama sonucu veya değişen repository’ye bağımlı olmayın. ## Aşamalı uyumluluk matrisi çalıştırın Akıştan önce akışsızı, çoklu çağrıdan önce tek çağrıyı test edin. | Aşama | Prompt davranışı | Geçme koşulu | |---|---|---| | A | Düz metin döndür | Son metin ve stop durumu gelir | | B | `echo_json` zorla | Ad ve geçerli argümanlar gelir | | C | `echo_json` akışını aç | Parçalar bir kez birleşir | | D | İki okuma aracı çağır | İki sonuç doğru eşleşir | | E | Bir araç hatası al | Model düzeltir veya temiz çıkar | | F | Akış ortasında iptal et | Geç araç yürütmesi olmaz | Her aday için aynı şemayı ve semantik isteği kullanın. Native protokol farklı bir zarf gerektiriyorsa yalnızca wire gösterimini uyarlayın. ## Ham olayları SDK’nın altında yakalayın Üst düzey SDK nesneleri üretimde kullanışlıdır ancak geçiş farklarını gizleyebilir. Monotonik sıra numarası, response ID, output index, call ID, olay türü ve sansürlenmiş payload uzunluğu yazan bir debug transport ekleyin. Akışlı işlev argümanları artımlıdır. Çağrı başına birleştirin ve son argüman olayını bekleyin: ```text START -> CALL_OPEN -> ARGUMENT_DELTAS -> CALL_DONE -> VALIDATED -> EXECUTED | | +-> CANCELLED <---+ ``` Geri giden geçişleri ve çift yürütmeyi reddedin. Bağlantı `EXECUTED` sonrasında ancak model sonucu almadan koparsa yazmayı körlemesine tekrarlamak yerine idempotency key kullanın. ## Sonucun tam gidiş-dönüşünü test edin Geçerli bir araç çağrısı sözleşmenin yarısıdır. Sonucu protokolün beklediği mesaj veya öğe türüyle döndürün, ardından modelin sonuçtaki bilinen bir alanı kullanan son yanıt üretmesini isteyin. Büyük, boş ve Unicode sonuçları ile yapılandırılmış hataları test edin. Sonuç bağlama yeniden girmeden önce boyutu sınırlayın. ## Metin yerine değişmezleri karşılaştırın İki model son cevabı farklı ifade ediyor diye paketi başarısız saymayın. Şunları doğrulayın: * Beklenen araç adı seçildi. * Argümanlar JSON Schema doğrulamasını geçti. * Her call ID benzersiz ve doğru eşleşti. * Her araç beklendiği gibi sıfır veya bir kez çalıştı. * Döngü izin verilen çağrı bütçesinde sona erdi. * Son yanıt fixture sonucunu kullandı. Adaya özel snapshotları yalnızca hata ayıklama için saklayın; geçme kriterlerini sağlayıcıdan bağımsız tutun. ## Hata ve iptal vakaları ekleyin Akışı ilk argüman parçasından sonra, çağrı tamamlandığında ve araç yürütüldükten sonra kesin. 429, timeout, hatalı JSON ve bilinmeyen araç adı enjekte edin. İstemcinin güvenli biçimde yeniden deneyip devam ettiğini veya anlamlı hatayla durduğunu doğrulayın. En tehlikeli hata durum değiştiren aracı tekrarlayan belirsiz bir retry’dır. Yazma işlemleri için açık idempotency zorunlu olsun. ## Paketi yayın kapısı yapın Her yapılandırma değişimi için hızlı smoke paketi, SDK veya gateway yükseltmesi için tam matris tutun. Modeli, protokolü, base URL’yi, şema hash’ini, akış bayrağını, istemci sürümünü ve zamanı sonuçla birlikte saklayın. Atlas Cloud akışlı ve akışsız LLM isteklerini destekler ve adayları bir [model kataloğunda](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=test-streaming-tool-call-compatibility-before-changing-llm-apis) sunar. Ortak erişim özdeş yetenek anlamına gelmediği için her seçili modelde aynı kapıyı çalıştırın. ## Sonuç LLM API geçişini durum içeren bir protokol değişimi olarak test edin. Deterministik araçlarla başlayın, ham olayları kaydedin, argümanları yalnızca tamamlandığında birleştirin, araç sonucu gidiş-dönüşünü doğrulayın ve retry ile iptal enjekte edin. Yeni modeli tek bir sohbet yanıtı doğru göründüğü için değil, sözleşme paketi geçtiğinde yayına alın. ## FAQ ### İlk uyumluluk testi neyi kapsamalı? Bir akışsız metin isteği ve zorunlu bir salt okunur araç çağrısıyla başlayın. Böylece endpoint, kimlik doğrulama, şema ve temel yanıt biçimi sorunları ayrılır. ### Ham akış olayları neden kaydedilmeli? SDK yardımcıları olay sırasını ve alan farklılıklarını gizleyebilir. Ham olaylar çağrı kimliklerinin, argüman parçalarının, tamamlanma işaretlerinin, hataların ve kullanımın nasıl geldiğini gösterir. ### Sağlayıcıları aynı metni üretmelerine göre karşılaştırabilir miyim? Genellikle hayır. Geçerli çağrı, zorunlu alan, yürütme sayısı, son durum ve görev sonucu gibi yapısal değişmezleri karşılaştırın. ### Hatalı araç argümanları nasıl test edilir? Modele yapılandırılmış doğrulama hatası döndürün ve güvenli olmayan girdiyi çalıştırmadan, belirlenen çağrı bütçesi içinde düzeltmesini veya çıkmasını doğrulayın. ### Test paketi yazma araçlarını kullanmalı mı? Deterministik salt okunur araçlarla başlayın. Birleştirme, doğrulama, tekilleştirme ve hata kurtarma geçtikten sonra sandbox yazma fixture’ı ekleyin. ### Uyumluluk testleri ne sıklıkta çalıştırılmalı? Her model veya protokol değişiminden önce hızlı bir alt kümeyi, SDK, şema, gateway ya da akış parserı değiştiğinde tüm paketi çalıştırın.