# Yapılandırılmış JSON Çıktısı Bir LLM API Geçişinden Sonra Neden Bozulur? > Yapılandırılmış JSON genellikle bir LLM API geçişinden sonra bozulur çünkü eski ve yeni yığınlar farklı sözleşmeler uygular. Promptu suçlamadan önce istek şemalarını, yanıt modlarını, akış davranışını, araç çağrısı zarflarını, retleri ve doğrulama kurallarını karşılaştırın. Bir geçiş, yalnızca ana bilgisayar adını değiştirmez. Modeli, SDK serileştirmesini, desteklenen şema anahtar sözcüklerini, akış olay sırasını, varsayılan örnekleme değerlerini, güvenlik davranışını ve oluşturulan yükün tam konumunu değiştirebilir. Uygulama kodunda eşdeğer görünen bir istek, bu nedenle tel üzerinde farklı bir sözleşmeyi temsil edebilir. En hızlı teşhis, her iki sağlayıcıdan bir başarısız isteği ve değiştirilmemiş yanıtını kaydetmektir. SDK'nızın sunduğu sarmalayıcı nesneleri değil, gerçek HTTP gövdelerini karşılaştırın. Bu karşılaştırma genellikle bozulmanın üretimden önce mi, üretim sırasında mı yoksa uygulamanız sonucu çıkarıp doğrularken mi meydana geldiğini ortaya koyar. ## Sözdizimi hatalarını sözleşme hatalarından ayırın "JSON bozuldu" birkaç farklı kusuru tanımlayabilir. Bunları tek bir sorun olarak ele almak, gerçek nedeni gizleyen istem düzenlemelerine yol açar. * Bir sözdizimi hatası, bir JSON ayrıştırıcısının okuyamadığı metin üretir. * Bir şema hatası, yanlış anahtarlar, türler, iç içe yapılar veya enum değerleri içeren geçerli JSON üretir. * Bir çıkarma hatası, geçerli yapılandırılmış veriler farklı bir yanıt alanında bulunduğunda ortaya çıkar. * Bir akış hatası, kısmi parçalar tam belgeler olarak ayrıştırıldığında oluşur. * Bir ret veya kesme hatası, beklenen nesneyi bir güvenlik mesajı veya eksik yük ile değiştirir. * Bir araç çağrısı hatası, uygulama asistan metni beklerken argümanları bir araç zarfında döndürür. Bu kategorileri ayrı ayrı günlüğe kaydedin. Bir ayrıştırıcı istisnası, eksik bir zorunlu alan ve API düzeyinde bir `400`, tek bir genel yeniden deneme sayacını paylaşmamalıdır. ## İki istek sözleşmesini karşılaştırın Alan alan bir geçiş matrisiyle başlayın. Benzer görünen adlar her zaman aynı anlama gelmez. | Sözleşme alanı | Eski yığın | Yeni yığın | Test sorusu | |---|---|---|---| | Çıktı modu | JSON nesnesi | Şemaya bağlı nesne | Yalnızca sözdizimini mi yoksa tam şemayı mı garanti eder? | | Şema konumu | Araç parametreleri | Yanıt biçimi | Şema doğru istek alanına mı eklenmiş? | | Katılık | Örtük | Açık bayrak | Katı mod etkinleştirilmeli mi? | | Desteklenmeyen anahtar sözcükler | Yoksayılır | Reddedilir | Birleşimler, biçimler, varsayılanlar veya başvurular kabul ediliyor mu? | | Ek anahtarlar | İzin verilir | Engellenir | `additionalProperties` tutarlı şekilde işleniyor mu? | | Akış | Metin deltaları | Tipli olaylar | Tamamlanmış nesneyi hangi olay içerir? | | Retler | Asistan metni | Özel alan | Çıkarıcı, reddi çıktıdan ayırt edebilir mi? | SDK işlemeden sonra son serileştirilmiş isteği yakalayın. Eski istemci tarafından eklenen varsayılanlar geçiş sırasında kaybolabilir. Tersi de olur: yeni bir SDK, belirgin bir uygulama hatası olmadan bir katı bayrağı ekleyebilir veya bir yanıt biçimi alanını yeniden adlandırabilir. ## İstemi değiştirmeden önce şemayı küçültün Önce mümkün olan en küçük şemayı test edin. Bir zorunlu dize ile başlayın ve isteğe bağlı dallar olmasın. Tamsayıları, dizileri, iç içe nesneleri, enum'ları ve koşullu yapıları tek tek ekleyin. Bu, desteklenmeyen özellikleri, bir üretim istemini tekrar tekrar yazmaktan çok daha hızlı izole eder. Örneğin, taşınabilir bir temel şu şekilde görünebilir: ```json { "type": "object", "properties": { "decision": { "type": "string", "enum": ["approve", "review", "reject"] }, "reason": { "type": "string" } }, "required": ["decision", "reason"], "additionalProperties": false } ``` Bu işe yararsa, taşıma ve temel uygulama yolu sağlamdır. Üretim şeması bir özellik eklendikten sonra başarısız olursa, belirsiz bir model kalitesi sorunu yerine belirli bir uyumluluk sorununuz var demektir. ## Yapılandırılmış yükün nerede olduğunu inceleyin Sağlayıcı geçişleri genellikle çıkarma kodunu bozar. Bir yığın JSON'u bir asistan mesajında, bir diğeri ayrıştırılmış bir kolaylık özelliğinde ve bir başkası dizeleştirilmiş araç argümanları olarak döndürebilir. Akış, sıradan metin deltaları yerine bir dizi tipli olay sunabilir. Uygulamanın geri kalanı yanıtı görmeden önce normalleştirilmiş bir iç sonuç oluşturun: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` Geçiş dönemi boyunca `raw`'ı saklayın. Bir model çıktısı kusurunu bir bağdaştırıcı kusurundan ayırt etmek için gereken kanıt budur. Günlükleri saklamadan önce hassas içeriği redakte edin ve uygulamanız için uygun bir saklama süresi belirleyin. ## Tamamlanmamış bir akışı ayrıştırmayın Bir JSON belgesi, son baytı gelene kadar genellikle geçersizdir. Her metin deltasını ayrıştırmak, üretim hataları gibi görünen beklenen hatalar üretecektir. Ya tam çıktıyı tamponlayın, ya sağlayıcı tarafından desteklenen artımlı bir JSON ayrıştırıcısı kullanın ya da sonuçlandırılmış yapılandırılmış yanıtı temsil eden belgelenmiş bir olayı tüketin. Akış testiniz mutlu yoldan daha fazlasını kapsamalıdır: * parçalar arasında bölünmüş dizeler; * kaçışlı tırnak işaretleri ve Unicode karakterleri; * çok sayıda öğe içeren diziler; * kapanış süslü parantezinden önce bir bağlantı kesilmesi; * bir ret olayı; * geçerli bir nihai nesne ve ardından kullanım meta verileri; * birden çok deltada iletilen araç argümanları. Bir ağ kesintisini eksik bir üretim olarak ele alın, hatalı biçimlendirilmiş model çıktısı olarak değil. Salt okunur bir sınıflandırma isteği için yeniden deneme güvenli olabilir, ancak sonuç harici bir yan etkiyi tetikliyorsa güvenli olmayabilir. ## İki kez doğrulayın, ancak dikkatli onarın Sağlayıcı bir şemayı zorunlu kılabilir, ancak uygulamanız yine de normalleştirilmiş sonucu güven sınırında doğrulamalıdır. Bu, sizi bağdaştırıcı hatalarından, özellik gerilemelerinden ve sağlayıcının hiç vaat etmediği varsayımlardan korur. Pratik bir sıra şöyledir: 1. HTTP isteğinin başarılı olduğunu doğrulayın. 2. Reddi, kesmeyi veya araç çağrısı tamamlanmasını açıkça algılayın. 3. Tamamlanmış yapılandırılmış yükü çıkarın. 4. Bir kez ayrıştırın. 5. Uygulamanın şema sürümüyle doğrulayın. 6. İş mantığı çalışmadan önce bilinmeyen veya güvenli olmayan değerleri reddedin. Sınırsız bir "bu JSON'u düzelt" döngüsünden kaçının. Bir onarım modeli, sözdizimini geçerli hale getirirken anlamı değiştirebilir. Onarım kabul edilebilirse, bunu tek bir denemeyle sınırlayın, doğrulama hatalarını sağlayın, özgün çıktıyı koruyun ve onarılan nesneyi tekrar doğrulayın. Yüksek etkili eylemler için, durumu incelemeye gönderin. ## Bir geçiş yeniden oynatma paketi oluşturun Üretim trafiğini yönlendirmeden önce, gerçek istek şekillerinden kompakt bir derlem oluşturun. Kişisel veya gizli verileri kaldırın, ardından sözleşmenizin sınırlarını zorlayan durumları ekleyin. | Durum grubu | Neler dahil edilmeli | Geçme koşulu | |---|---|---| | Normal | Yaygın kısa girdiler | Beklenen değerlerle geçerli nesne | | İsteğe bağlı alanlar | Eksik ve mevcut varyantlar | Zorunlu ve isteğe bağlı davranış sözleşmeyle eşleşir | | Belirsiz | Çelişkili veya yetersiz belirtilmiş girdi | Geçerli nesne artı izin verilen bir belirsizlik durumu | | Uzun bağlam | Uygulamanın normal maksimumuna yakın | Kesme yok ve geçerli çıkarma | | Düşmanca | Modelden şemayı yoksaymasını isteyen metin | Şema bozulmadan kalır | | Ret | İzin verilmeyen veya güvenli olmayan istek | Ret, ayrıştırıcı karışıklığı olmadan algılanır | | Akış | Parça sınırları ve bağlantı kesilmeleri | Doğrulamaya yalnızca tamamlanmış yükler ulaşır | Her iki sağlayıcıyı da kararlı parametrelerle çalıştırın ve geçerlilik oranını, anlamsal uyumu, ret oranını, kesme oranını, gecikmeyi ve yeniden deneme sayısını kaydedin. Tam anlamsal eşitlik her zaman beklenmez, ancak şema geçerliliği katı bir kapı olmalıdır. ## Uyumluluğu bir bağdaştırıcının arkasına koyun Sağlayıcı yanıt türlerinin tüm kod tabanına sızmasına izin vermeyin. Küçük bir bağdaştırıcı, istek oluşturma, şema yetenek denetimleri, yanıt çıkarma, bitiş nedenleri, kullanım alanları ve hata normalleştirmesinin sahibi olmalıdır. Uygulamanın geri kalanı tek bir iç arabirimi tüketmelidir. Bir uygulama metin, görüntü ve video modelleri kullandığında, [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) gibi OpenAI uyumlu bir ağ geçidi, tekrarlanan entegrasyon işini azaltabilir. Taşıma katmanındaki uyumluluk yararlıdır, ancak model düzeyinde testi ortadan kaldırmaz. Uyumlu bir uç noktanın arkasındaki her modelin aynı şekilde davrandığını varsaymak yerine, yapılandırılmış çıktı, araçlar, akış ve şema özellikleri için yetenek bayraklarını koruyun. Bağdaştırıcıyı ve şemayı birlikte sürümleyin. Bir şema değiştiğinde, şema sürümünü çıktıyla birlikte saklayın, böylece alt hizmetler hangi sözleşmeyi aldıklarını bilsin. ## Net durdurma koşullarıyla aşamalı bir kullanıma sunma kullanın Çevrimdışı yeniden oynatmayla başlayın, ardından gölge trafik, sonra küçük bir canlı yüzde. Yalnızca toplu başarıya güvenmeyin. %1'lik hatalar ödeme, moderasyon veya yetkilendirme isteklerinde kümeleniyorsa, %99 geçerlilik oranı yine de kabul edilemez olabilir. Testten önce durdurma koşullarını tanımlayın: * herhangi bir güvenli olmayan enum iş mantığına ulaşırsa; * şema geçerlilik oranı mevcut temel çizginin altına düşerse; * ret işleme belirsiz hale gelirse; * kesme, kararlaştırılan eşiğin ötesine yükselirse; * yeniden denemeler maliyeti veya gecikmeyi uygulamanın bütçesinin ötesine çıkarırsa; * ham yanıtlar normalleştirilmiş çıktılarla uzlaştırılamazsa. Mümkün olduğunda acil bir kod dağıtımı yerine yönlendirme yapılandırması aracılığıyla geri alın. Yeni yol hem yoğun yükü hem de nadir girdi sınıflarını atlatana kadar eski bağdaştırıcıyı kullanılabilir tutun. ## Sonuç Bir LLM API geçişinden sonra yapılandırılmış JSON hataları genellikle sözleşme uyuşmazlıkları, çıkarma hataları veya eksik akış mantığıdır; yeni modelin talimatları izleyemediğinin kanıtı değildir. Tel yüklerini karşılaştırın, şemayı küçültün, yanıtları normalleştirin, uygulama sınırında doğrulayın ve trafiği kaydırmadan önce temsili bir derlemi yeniden oynatın. Uyumlu bir API geçişi basitleştirebilir, ancak açık yetenek testleri üretim davranışını korumanın güvenilir yolu olmaya devam eder. ## FAQ ### Aynı JSON istemi neden bir modelde çalışıp diğerinde başarısız oluyor? Prompt ifadesi yalnızca tek bir katmandır. Modeller ve sağlayıcılar yerleşik JSON modları, şema desteği, tokenizasyon, reddetme davranışı ve kısıtlamalara ne kadar sıkı uydukları bakımından farklılık gösterir. ### JSON modu, JSON Schema zorlamasıyla aynı şey mi? Hayır. JSON modu yalnızca sözdizimsel olarak geçerli JSON'u garanti edebilir; şema zorlaması ise anahtarları, türleri, zorunlu alanları ve bazen ek özellikleri de kısıtlar. ### Akış halindeki JSON'u token token ayrıştırmalı mıyım? Genellikle hayır. Yapılandırılmış yükün tamamını tamponlayın veya sağlayıcının belgelendirdiği yapılandırılmış akış olaylarını kullanın, ardından son olaydan sonra doğrulayın. ### OpenAI uyumlu bir API geçiş işini ortadan kaldırabilir mi? Aktarım ve SDK değişikliklerini azaltabilir, ancak yine de modele özgü şema özelliklerini, bitiş nedenlerini, araç çağrısı biçimlerini ve hata davranışını doğrulamanız gerekir. ### Doğrulama başarısız olduğunda ne olmalı? Ham yanıtı yakalayın, hatayı sınıflandırın, yalnızca güvenli geçici durumları yeniden deneyin ve deterministik onarımı, bozuk verileri sessizce kabul etmek yerine sınırlı bir doğrulama adımından geçirin. ### En hızlı üretim öncesi test nedir? Normal, belirsiz, çekişmeli, reddetme, uzun bağlam ve akış isteklerinden oluşan sabit bir derlemi her iki yığına karşı yeniden oynatın ve doğrulanmış çıktıları alan alan karşılaştırın.