İçeriğe geç
TokIQ
Çıktı

LLM'den Güvenilir JSON Alma: Şema, Doğrulama, Retry

LLM'den geçerli JSON almak sadece nazikçe istemekle olmaz. Şema, yapılandırılmış çıktı kipleri, doğrulama ve retry kullan, sık görülen hatalardan kaçın.

TokIQ Editorial4 dk okuma
Bu yazıda
  1. Modeller JSON'u en baştan neden bozuyor?
  2. Adım 1: Çıktıyı prompt'ta kesin biçimde tanımla
  3. Adım 2: API'nin yapılandırılmış çıktı özelliğini kullan
  4. Adım 3: Zorlama olsa bile her şeyi doğrula
  5. Adım 4: Körü körüne değil, hatayla retry yap
  6. Bir JSON yanıtında akıl yürütme nereye konmalı?
  7. Çıktı şemalarında sık tasarım hataları
  8. Yalnızca prompt yazmak hiç yeterli mi?

Bir dil modelinden güvenilir JSON almak için yapıyı bir JSON Schema olarak tanımla, varsa sağlayıcının yapılandırılmış çıktı özelliğini kullan, her cevabı kodda doğrula ve doğrulama başarısız olursa doğrulama hatasıyla retry yap. Sadece prompt ifadesi seni yolun büyük kısmına götürür; güvenilirliğin son birkaç yüzdesi API'den ve kendi doğrulamandan gelir.

Bu ayrım önemli, çünkü kod için "yolun büyük kısmı" yeterli değil. Cevapların %2'sinde patlayan bir ayrıştırıcı, ölçekte birilerinin özelliğinin birkaç dakikada bir bozulması demek.

Modeller JSON'u en baştan neden bozuyor?

Düzeltmeden önce gerçekte neyin ters gittiğini bilmek işe yarar. Karşına çıkma sırasına göre kabaca:

  1. Markdown çitleri. Sohbet modelleri kodu güzel sunmak üzere eğitildiği için model ```json ... ``` döndürür.
  2. Geveze girişler. "Tabii! İstediğin JSON burada:" ve ardından nesne.
  3. Yanlış ya da uydurma anahtarlar. customer_name yerine customerName ya da hiç istemediğin fazladan bir notes alanı.
  4. Yanlış tipler. String olarak "price": "19.99", "count": "three", dizi beklediğin yerde tek bir nesne.
  5. Kesilme. Cevap maksimum token sınırına çarpar ve nesnenin ortasında durur.
  6. Sözdizimi geçerli ama anlamsız içerik. Kusursuz JSON, yanlış içerik: yanlış biçimde bir tarih, halüsinasyonla üretilmiş bir telefon numarası, değer girdide açıkça dururken null.

Yapılandırılmış çıktı özellikleri ilk beşini çoğunlukla ortadan kaldırır. Altıncıyı iyi prompt, grounding ve kontroller dışında hiçbir şey ortadan kaldırmaz.

Adım 1: Çıktıyı prompt'ta kesin biçimde tanımla

Şema zorlaması olsa bile her alanın ne anlama geldiğini açıkladığın yer prompt'tur. Şema due_date'in bir string olduğunu söyler; yalnızca prompt bunun ISO 8601 olması gerektiğini ve göreli tarihlerin e-postanın gönderildiği tarihe göre çözülmesini söyleyebilir.

Zayıf bir prompt:

Bu e-postadaki fatura ayrıntılarını JSON olarak çıkar.

Daha güçlü olanı:

Aşağıdaki e-postadan fatura ayrıntılarını çıkar.

Tam olarak şu anahtarlara sahip tek bir JSON nesnesi döndür:
- "vendor": string, faturayı düzenleyen şirket
- "invoice_number": string, yazıldığı gibi (baştaki sıfırları koru)
- "total": number, fatura para biriminde, para birimi simgesi olmadan
- "currency": string, "USD" ya da "EUR" gibi ISO 4217 kodu
- "due_date": YYYY-MM-DD biçiminde string, belirtilmemişse null

E-postada olmayan bir değer için null kullan. Tahmin etme.
Yalnızca JSON nesnesini döndür; markdown ve açıklama olmasın.

<email>
{{email_text}}
</email>

İki ayrıntı çok şey taşıyor. "Baştaki sıfırları koru", modelin 00417'yi "yardımseverlikle" 417'ye çevirmesini önler. "null kullan, tahmin etme" ise modele meşru bir çıkış yolu verir. Açık bir null seçeneği olmazsa zorunlu alan kısıtı altındaki model, alanı boş bırakmak yerine makul görünen bir değer uydurur.

Adım 2: API'nin yapılandırılmış çıktı özelliğini kullan

Büyük sağlayıcıların çoğu artık çıktıyı bir şemaya kısıtlamanın bir yolunu sunuyor. İsimler ve ayrıntılar farklı ve zamanla değişiyor, o yüzden güncel dokümanlara bak; ama ana seçenekler şöyle:

  • OpenAI'da sözdizimi geçerli JSON'u garanti eden temel bir JSON mode ve strict mode ile bir JSON Schema verdiğin, çıktının buna uymaya kısıtlandığı Structured Outputs var.
  • Google Gemini, yanıt MIME tipini JSON olarak ayarlamana ve bir yanıt şeması vermene izin verir.
  • Anthropic, girdi şemasıyla bir tool tanımlamana ve Claude'un onu çağırmasına izin verir; bu da şemaya uygun argümanlar üretir. Dokümanları yerel yapılandırılmış çıktı desteğini de anlatıyor.

Önemli ayrım JSON mode ile şema zorlaması arasında. JSON mode yalnızca metnin ayrıştırılabileceğini vaat eder. Anahtarların yine yanlış olabilir. Şema zorlaması (çoğunlukla modelin bir sonraki adımda üretebileceği token'ları kısıtlayan constrained decoding ile yapılır) biçimi vaat eder.

Fatura örneği için bir şema:

{
  "type": "object",
  "properties": {
    "vendor": { "type": ["string", "null"] },
    "invoice_number": { "type": ["string", "null"] },
    "total": { "type": ["number", "null"] },
    "currency": { "type": ["string", "null"], "enum": ["USD", "EUR", "GBP", null] },
    "due_date": { "type": ["string", "null"], "description": "YYYY-MM-DD" }
  },
  "required": ["vendor", "invoice_number", "total", "currency", "due_date"],
  "additionalProperties": false
}

Nullable tiplere dikkat et. Strict kiplerde genelde her alan zorunludur, yani "isteğe bağlı" ifadesi "zorunlu ama null olabilir" olarak yazılmalıdır. Ayrıca sürpriz alanları engelleyen additionalProperties: false'a da dikkat et. Strict kipler genelde JSON Schema'nın yalnızca bir alt kümesini destekler; karmaşık bir şey kurmadan önce hangi anahtar kelimelere izin verildiğine bak.

Python ya da TypeScript kullanıyorsan şemayı bir Pydantic modeli ya da Zod şeması olarak tanımla ve JSON Schema'yı ondan üret. Böylece aynı tanım yanıtı da doğrular ve ikisi birbirinden ayrışamaz.

Adım 3: Zorlama olsa bile her şeyi doğrula

Şema zorlaması yapıyı garanti eder. Şunları garanti etmez:

  • due_date'in gerçek bir tarih olduğunu (30 Şubat geçerli bir string'dir),
  • total'in kalem toplamıyla eşleştiğini,
  • vendor'ın kaynak e-postada bir yerde geçtiğini,
  • modelin beş kalemden üçüncüsünü atlamadığını.

Alanın için önemli kontrolleri yaz. Tarihleri ayrıştır. Toplamların negatif olmadığını kontrol et. Çıkarım görevlerinde çıkarılan string'lerin girdide gerçekten geçtiğini kontrol et; bu tek test şaşırtıcı miktarda halüsinasyonu yakalar.

Adım 4: Körü körüne değil, hatayla retry yap

Doğrulama başarısız olunca aynı isteği tekrar gönderip umma. Hatayı geri gönder:

Önceki yanıtın doğrulamayı geçemedi:
- "due_date": "3 Mart" YYYY-MM-DD biçimine uymuyor
- "currency": "dolar" USD, EUR, GBP değerlerinden biri değil

Yalnızca düzeltilmiş JSON nesnesini döndür.

Modeller belirli, adı konmuş hataları iyi düzeltir. Retry sayısını bir ya da ikiyle sınırla, her başarısızlığı logla ve logları haftalık incele. Aynı alanda tekrar eden hatalar genelde modelin güvenilmez olduğunu değil, prompt'un ya da şemanın belirsiz olduğunu gösterir. Instructor (Python) gibi kütüphaneler bu doğrula-ve-tekrarla döngüsünü senin yerine sarar, ama kalıp kendin yazılacak kadar basit.

Zorlama olmayan sağlayıcılarda yalnızca sözdizimi bozulduğunda, JSON.parse'tan önce çitleri ve sondaki metni temizleyen toleranslı bir ayrıştırıcı en yaygın durumları halleder. Bunu bir strateji değil, yedek olarak gör.

Bir JSON yanıtında akıl yürütme nereye konmalı?

Görev muhakeme gerektiriyorsa (gerekçeli bir sınıflandırma, bir risk puanı), bir akıl yürütme alanını karar alanından önce koy:

{
  "evidence": "Müşteri, Mart faturasında mükerrer bir tahsilattan söz ediyor.",
  "category": "billing",
  "confidence": "high"
}

Modeller alanları sırayla üretir. Önce yazılan karar, akıl yürütmeden beslenmek yerine sonradan gerekçelendirilir. Bunu chain-of-thought prompting açıklaması yazısında daha derinlemesine anlatıyoruz.

Madalyonun öbür yüzü: akıl yürütme alanları her çağrıda token harcar. Basit çıkarım işlerinde bırak.

Çıktı şemalarında sık tasarım hataları

Sebepsiz derin iç içelik. Düz bir liste yeterken üç seviye nesne. Her seviye, modelin bir değeri yanlış yere koyabileceği bir yer daha.

Enum olması gereken serbest metin alanları. Alt akıştaki kod status'a göre dallanıyorsa onu enum yap. Yoksa aynı şey için "Pending", "pending", "In progress" ve "awaiting review" alırsın.

Belirsiz alan adları. Bir faturadaki date, düzenleme tarihi, vade tarihi ya da ödeme tarihi olabilir. Adı due_date yap ve tanımla.

Tek çağrıda çok şey istemek. Yirmi sayfalık bir sözleşmeden çıkarılan kırk alanlı bir şema eksiklikleri davet eder. Böl: bölüm başına bir çağrı ya da ilgili pasajları bulmak için bir çağrı, onlardan çıkarım için bir başkası.

Boş durumu unutmak. E-posta hiç fatura değilse çıktı ne olmalı? Bir is_invoice boolean'ı ekle ya da boş sonuca izin ver; yoksa model bir öğle yemeği davetinden fatura çıkarır.

Yalnızca prompt yazmak hiç yeterli mi?

Prototipler, elle çalıştırdığın betikler ya da yapılandırılmış çıktı desteği olmayan modeller için evet. Kesin bir format tanımı, tam çıktı örneği ve savunmacı bir ayrıştırıcı seni yüksek güvenilirliğe getirir. Kullanıcıya dönük her şey için varsa zorlamayı, her zaman doğrulamayı kullan.

Temel beceri her durumda aynı: çıktıyı o kadar kesin tanımla ki doldurmanın tek makul yolu kalsın. Yapılandırılmış çıktı konusu bu kararları pratik ettirir; ürettiğin JSON nihai cevap değil de bir tool çağrısıysa tool calling ve AI ajanları buradan devam eder. Kaynak belgelere dayalı çıkarım için RAG nedir yazısına bak.

Sık sorulan sorular

Bir LLM'i geçerli JSON döndürmeye nasıl zorlarım?

Varsa sağlayıcının JSON Schema destekli yapılandırılmış çıktı özelliğini kullan; üretimi şemaya göre kısıtlar. Sonra yine de sonucu kodda doğrula, doğrulama başarısız olursa retry yap ya da onar.

JSON mode ile structured outputs arasındaki fark nedir?

JSON mode, modelin sözdizimi geçerli JSON üretmesini sağlar ama anahtarlarını ya da tiplerini garanti etmez. Katı (strict) şemalı structured outputs ise çıktıyı verdiğin şemaya uymaya zorlar.

LLM'im neden JSON'u markdown kod bloğuna sarıyor?

Sohbet için ayarlanmış modeller, kodu insanlar için düzgün biçimlendirmek üzere eğitilir. Modele yalnızca ham JSON nesnesini döndürmesini söyle ya da yapılandırılmış çıktı kipini kullan; ayrıştırıcında da çitleri (fence) savunmacı biçimde temizle.

Şema olsa bile LLM'den gelen JSON'u doğrulamalı mıyım?

Evet. Şema yapıyı garanti eder, doğruluğu değil. JSON kusursuz geçerli olup yine de yanlış bir tarih, uydurma bir değer ya da verinin olduğu yerde boş bir alan içerebilir.

  • #yapılandırılmış çıktı
  • #JSON
  • #JSON schema
  • #doğrulama

Şimdi pratiğini yap

TokIQ, prompt mühendisliğini kısa quizlere dönüştürür; her cevap için bir açıklamayla.

Yakında burada:App StoreŞuradan al:Google Play

Günde birkaç soruyla daha iyi prompt yaz.

Gerçek prompt kararları üzerine kısa quizler ve her cevap için açıklama. iPhone ve Android'de ücretsiz başla.

Yakında burada:App StoreŞuradan al:Google Play