Grok 4.6 API İsteklerini Test Etme ve Hata Ayıklama (Akış, Araç Çağrıları, Hatalar)

Grok 4.6, uzun süre çalışan ajanlar için tasarlanmıştır; bu da entegrasyonunuzun hata modlarının, hata ayıklanması en zor yerlerde ortaya çıktığı anlamına gelir: token ortasında takılan akışlı yanıtlar, neredeyse ayrıştırılan araç çağrısı yükleri ve yalnızca üretim yükü altında etkili olan hız sınırları. xAI'nin belgeleri, API'nin neyi kabul ettiğini belirtir. Sıralama arama sonuçlarındaki hiçbir şey, bunu nasıl test edeceğinizi söylemez. Bu kılavuz, iş akışını kapsar: istekleri doğrulamak, akışları incelemek, araç çağrılarını hata ayıklamak, hataları işlemek ve CI'nizin token yakmaması için Grok yanıtlarını taklit etmek.

Buradaki her şey, LLM API hata ayıklamasının, SSE renderlamanın, ortam kapsamlı sırların, yanıt onaylarının ve sahte sunucuların zor kısımlarını tek bir yerde hallettiği için çalışma ortamı olarak Apidog'u kullanır. Eğer bunu manuel olarak kuruyorsanız, kavramlar aktarılır; ancak ekran görüntülerindeki tıklamalar aktarılmaz.

düğme

ÖZET

• https://api.x.ai/v1 ve XAI_API_KEY'nizi bir değişken olarak kullanarak bir Apidog ortamı kurun, anahtarları asla kaydedilmiş isteklere sabit kodlamayın.
• Akışı görsel olarak hata ayıklayın: Apidog, SSE parçalarını gerçek zamanlı olarak renderlar, böylece duraklamalar ve kesintiler belirgin hale gelir.
• Araç çağrıları metinden daha sık başarısız olur: tool_calls[].function.arguments'ın JSON olarak ayrıştırıldığından ve her çalıştırmada şemanızla eşleştiğinden emin olun.
• 429'u üstel geri çekilmeyle ve 5xx'i sınırlı yeniden denemelerle ele alın; her yanıtta usage'ı günlüğe kaydedin.
• CI'da Grok uç noktasını taklit edin. Ajan döngüleri görev başına düzinelerce çağrı yapar, canlı API'ye karşı test yapmak yavaş, tutarsız ve pahalıdır.
• Hata ayıklama isteklerinizi otomatik test senaryolarına dönüştürün ve her dağıtımda çalıştırın.

Önce düzgün bir çalışma alanı kurun

Ad-hoc curl komutları ilk bir "merhaba dünya" için iyidir; ancak başarısız bir isteğin üç varyasyonunu karşılaştırdığınız anda işe yaramaz hale gelirler. İki dakikalık kurulum kendini amorti eder:

1. Apidog'da bir proje (örneğin, "Grok 4.6 Entegrasyonu") ve xai-dev adında bir ortam oluşturun.
2. Ortam değişkenleri ekleyin: base_url = https://api.x.ai/v1 ve api_key = <anahtarınız> (gizli olarak işaretlenmiş).
3. {{base_url}}/chat/completions adresine Authorization: Bearer {{api_key}} başlığıyla bir POST isteği oluşturun.
4. Ortamı üretim anahtarıyla xai-prod olarak kopyalayın. Aynı istekler, farklı kapsam; geliştirme deneyleri yanlışlıkla üretim kotasını aşamaz.

Henüz bir anahtar oluşturmadıysanız, Grok 4.6 API hızlı başlangıç kılavuzumuz, console.x.ai kurulumunu ve curl, Python ve JavaScript'teki ilk istekleri adım adım anlatır.

Modeli suçlamadan önce istekleri doğrulayın

Bir istek yanlış davrandığında, önce sıkıcı nedenler gelir. Bunları sırayla kontrol edin:

• Model Kimliği. Yerel API'de grok-4-6; satıcılar farklılık gösterir (OpenRouter x-ai/grok-4.6 kullanır). Buradaki bir 404, bir kesinti değil, bir kimlik sorunudur.
• Parametre aralıkları. Geçersiz bir temperature veya bağlamda kalan kısmı aşan bir max_tokens, genellikle doğru bir hata mesajıyla birlikte 400 döndürür. Başka bir şeyi değiştirmeden önce okuyun.
• Mesaj yapısı. messages dizisi mantıklı bir şekilde değişmeli; başıboş boş içerikli bir mesaj veya yinelenen bir sistem istemi, hiç hata vermeden kalitesi düşmüş bir çıktı üretir ki bu en kötü türden bir hatadır.
• Bağlam aritmetiği. Grok 4.6'nın penceresi 500K tokendır, cömert ancak sınırlıdır. Uzun ajan transkriptleri artı büyük bir max_tokens rezervasyonu pencereyi aşabilir ve hata, bir hata yerine sessiz kesinti olarak ortaya çıkar. usage'dan istem token sayılarını günlüğe kaydedin ve tavana yaklaştıklarında uyarı verin.

Apidog'un istek doğrulaması, yapısal hataları (yanlış türler, eksik zorunlu alanlar) istek makinenizden ayrılmadan önce yakalar, bu da ilk iki kategorideki döngüyü sıfır gidiş-dönüşe indirir.

Kör olmadan akış hata ayıklaması yapın

Grok 4.6 yanıtları sunucu tarafından gönderilen olaylar olarak akar ve ajans yanıtları uzundur, binlerce token normaldir. Neredeyse her akış hatasını açıklayan üç hata modeli vardır:

1. Duraklama. Tokenlar yanıtın ortasında gelmeyi durdurur. Bir terminalde bu, modelin düşündüğünden ayırt edilemez. Apidog'un SSE görünümünde, parçaların gelmeyi durdurup durmadığını (sunucu/ağ tarafı) veya uygulamanız render etmeyi durdururken gelmeye devam edip etmediğini (istemci tarafı) görebilirsiniz. Bu ayrım genellikle hata ayıklama süresini yarıya indirir.
2. Sessiz kesinti. Akış düzgün ama erken sona erer. Son parçanın finish_reason'ını kontrol edin: length, max_tokens'a ulaştığınız anlamına gelir, bu yüzden artırın; Grok 4.6 tasarımsal olarak uzun, çok adımlı yanıtlar yazar. stop, modelin gerçekten bittiği anlamına gelir.
3. Proxy sorunu. Yerel olarak çalışır, hazırlık ortamında takılır. Ters proxy'ler varsayılan olarak SSE'yi arabelleğe alır; nginx'in akış yolu için proxy_buffering off'a ihtiyacı vardır. Apidog'dan aynı isteği her iki ortama karşı test ederek onaylayın; eğer makinenizden akış sağlanıyor ancak ağ geçidinizden sağlanmıyorsa, sorun xAI değil altyapıdır.

Araç çağrıları: ajan entegrasyonlarının gerçekten bozulduğu yer

Grok 4.6'nın ajan odaklılığı, fonksiyon çağırmayı taşıyıcı özellik haline getirir ve araç çağrısı yönetimi, her LLM sağlayıcısında en çok üretim olayını gördüğümüz yerdir. Hata modları:

• Ayrıştırılamayan argümanlar. tool_calls[].function.arguments bir JSON dizesi olarak gelir. Modeller zaman zaman neredeyse JSON, sondaki virgüller, kaçırılmamış tırnak işaretleri, özellikle uzun bağlamlarda yayınlayabilir. Ayrıştırmayı bir try/catch içine alın ve hataları sayın; artan bir ayrıştırma hatası oranı, isteminizin veya şemanızın bir şeyleri değiştirdiğine dair erken bir uyarıdır.
• Geçerli JSON, yanlış biçim. Argümanlar ayrıştırılır ancak şemanızı ihlal eder: eksik zorunlu alan, sayı yerine dize. Yalnızca geliştirmede değil, her zaman şemaya karşı doğrulayın.
• Halüsinasyon gören araçlar. Nadir ama gerçek: hiç tanımlamadığınız bir fonksiyona çağrı. Bilinmeyen araç adlarını açıkça reddedin, bir KeyError'ın döngüyü bozmasına izin vermeyin.
• Akış birleştirme hataları. Akışlı yanıtlarda, araç çağrısı argümanları parçalar arasında parçalanmış olarak gelir ve ayrıştırmadan önce birleştirilmelidir. Erken ayrıştırma "model bozuk JSON üretiyor" gibi görünür ancak aslında sizin birleştirme kodunuzdur.

Apidog'da, yanıtı araç çağrıları içeren bir isteği kaydedin, ardından onaylar ekleyin: araç adının izin verilen kümenizde olduğundan, argüman dizesinin ayrıştırıldığından ve ayrıştırılan nesnenin doğrulandığından emin olun. On kez çalıştırın, LLM'nin deterministik olmaması, %10'luk bir hata oranının tek çalıştırmalarda kolayca gizlenmesi anlamına gelir. Yığınınız ham fonksiyon çağrısı yerine MCP sunucularını içeriyorsa, aynı disiplin geçerlidir; MCP sunucularını Apidog ile test etme kılavuzumuza bakın.

Hatalar, yeniden denemeler ve hız sınırları

Bir üretim Grok entegrasyonu, bu tablonun her satırı için bir politikaya ihtiyaç duyar:

Grok'a özgü iki not. Birincisi, lansman haftaları yük anlamına gelir: geçici 429'lar ve 5xx'ler, bunun gibi bir sürümden sonraki günlerde daha yaygındır, bu nedenle paydaşlara demodan önce geri çekilme mekanizmasının yerinde olması gerekir. İkincisi, her yanıttaki usage nesnesini günlüğe kaydedin. Milyon token başına 2$/6$ maliyetle fatura uygun olsa da, ajan döngüleri her şeyi çarpar, bir istem değişikliğinden kaynaklanan maliyet regresyonları faturalarda görünmeden günler önce token günlüklerinde ortaya çıkar. Grok fiyatlandırma analizimiz maliyet modelini ayrıntılı olarak kapsar.

CI'da Grok'u taklit edin, canlı API'yi ayrı olarak test edin

LLM test paketlerini hızlı ve uygun fiyatlı tutan disiplin şudur: CI'niz her committe canlı modeli çağırmamalıdır.

30 gerçek Grok çağrısı yapan bir ajan entegrasyon testi gerçek paraya mal olur, bir dakikadan fazla sürer ve sağlayıcı aksadığında rastgele başarısız olur; geliştiriciler bir hafta içinde onu görmezden gelmeyi öğrenir. Endişeleri ayırın:

• Mantık için taklit. Apidog'un akıllı taklit özelliğini kullanarak gerçekçi Grok biçimli yanıtlar sunun: basit bir tamamlama, bir araç çağrısı yanıtı, bir 429, kesilmiş bir akış. Yeniden deneme mantığınız, JSON ayrıştırmanız ve döngü sonlandırma kodunuz her committe saniyeler içinde ve ücretsiz olarak çalıştırılır. Özellikle hata biçimlerini taklit edin; çoğu kod tabanındaki 429 yolu, üretime geçmeden önce hiç çalışmamıştır.
• Programlı canlı testler. Gerçek API paketini her committe değil, her gece veya sürüm öncesinde çalıştırın. Bu, xAI'nin çalışma süresine birleştirme kuyruğunuzu bağlamadan, gerçek sağlayıcı kaymasını, araç çağrısı biçimlendirmesini değiştiren bir model güncellemesini, yeni hız limitlerini yakalar.

Apidog test senaryoları her iki yarıyı da kapsar: CI çalıştırmaları için senaryoyu taklit ortama ve planlı canlı geçiş için xai-dev'e yönlendirin. Aynı onaylar, iki hedef. Testleri terminalden veya bir pipeline'dan yönetiyorsanız, Apidog CLI aynı senaryoları başsız olarak çalıştırır.

Üretim öncesi kontrol listesi

Grok 4.6 trafiği canlıya geçmeden önce, bunların hepsine "evet" yanıtını verebilmelisiniz:

• [ ] API anahtarları ortam kapsamında yaşar, geliştirme ve üretim ayrılmıştır, hiçbiri sürüm kontrolünde değildir
• [ ] Akış, finish_reason: length, duraklamaları ve proxy arabelleğini yönetir
• [ ] Araç çağrısı argümanları her çağrıda savunmacı bir şekilde ayrıştırılır ve şema doğrulaması yapılır
• [ ] 429/5xx yeniden deneme politikası uygulanmış ve taklit yoluyla test edilmiştir
• [ ] Görev başına maliyet sapması konusunda uyarı ile birlikte her istek için usage günlüğe kaydedilir
• [ ] CI, taklitlere karşı çalışır; canlı paket programlı olarak çalışır
• [ ] Bir sonraki model sürümü için tüm paket tek bir komutla yeniden çalıştırılır

Sıkça Sorulan Sorular

• Takılan bir Grok 4.6 akış yanıtını nasıl hata ayıklayabilirim? Apidog'un SSE görünümünde yeniden üretin. Eğer parçalar gelmeyi durdurduysa, sunucu/ağ tarafıdır; proxy'leri ve zaman aşımlarını kontrol edin. Eğer parçalar gelmeye devam ettiyse, istemciniz bunları tüketmeyi durdurmuştur; kodunuzdaki arabelleğe alma ve asenkron işlemeyi inceleyin.
• Grok 4.6 araç çağrıları neden bazen ayrıştırmada başarısız oluyor? Fonksiyon argümanları, zaman zaman hatalı JSON içeren bir JSON dizesi olarak gelir ve akışlı araç çağrıları, ayrıştırmadan önce parçalardan birleştirilmelidir. Savunmacı ayrıştırma ve şema doğrulama her ikisini de yakalar; çok erken birleştirme en yaygın kendi kendine sebep olunan versiyondur.
• Testlerim gerçek Grok API'sini çağırmalı mı? Belirli bir program dahilinde, evet, sağlayıcı kaymasını yakalamak için gecelik veya sürüm öncesi çağrılabilir. Ancak her committe hayır, uç noktayı taklit edin böylece CI hızlı, deterministik ve ücretsiz kalır.
• Bu iş akışı diğer LLM API'leri için de çalışır mı? Evet. Grok'un API'si OpenAI uyumlu olduğu için, her sağlayıcı için farklı bir ortama sahip aynı Apidog proje yapısı, GPT-5.6, Claude ve Grok'u yan yana kapsar ki bu, modeller arası karşılaştırmaları tam olarak nasıl yürüttüğünüzdür.