Yapilandirilmis Cikti

Claude’dan 200 destek biletini siniflandirmasini istiyorsunuz. Ilk 50’si temiz JSON dondurur. 51. bilet bunun yerine konusma tarzinda bir paragraf dondurur. --json-schema olmadan, Claude’un cikti formati bir garanti degil, bir oneridir.

--json-schema bayragi Claude’u bir JSON semasina uyan verileri dondurmeye zorlar. Token duzeyinde kisitli kod cozme kullanir ve pratikte semaniza guvenilir sekilde uyan cikti uretir. Cogu insan bunu bilmez, ancak guvenilir veri cikartma, siniflandirma ve API entegrasyonu icin en temiz yoldur.

Claude’un ciktisini programatik olarak ayristirmasi gereken her sey icin, --output-format json ile --json-schema’yi birlestirin. Sema kisitlamasi her cagride tahmin edilebilir, tipli yapi verir — ciktinin ayristirilabilir olmasini ummak yok artik.

Bunu Ne Zaman Kullanmali (ve Ne Zaman Kullanmamali)

--json-schema’yi su durumlarda kullanin:

• Claude’un ciktisini yapilandirilmis sistemlere (veritabanlari, API’ler, alt akis araclari) ayristiriyorsaniz
• Bircoq cagri arasinda tutarli, tipli veriye ihtiyaciniz varsa (toplu isleme, siniflandirma boru hatlari)
• Sema uyumlulugu dogal aciklamalardan daha onemliyse

--json-schema’yi su durumlarda kullanmayin:

• Serbest bicimli metin veya Claude’un dogal aciklamalarina ihtiyaciniz varsa
• Cikti insanlar tarafindan okunacaksa, makineler degil
• Semaniz uyumlulugu zorlamanin yanit kalitesini dusurecegi kadar karmasiksa

JSON Schema, JSON yapisini dogrulamak icin bir sozvarliqidir. Spesifikasyon, araclarin veri sekillerini uygulamak icin kullandigi tipleri, kisitlamalari ve ek aciklamalari tanimlar. Tam spesifikasyon icin json-schema.org adresine bakin.

Temel Sema

--output-format json ile birlikte --json-schema’ya bir JSON Schema dizesi gecirin. Claude, semaya uyan verileri iceren bir structured_output alanina sahip bir yanit zarfi dondurur.

Sema gir, yapilandirilmis veri cik. Ayristirma regex’i yok, “lutfen JSON olarak yanit verin” promptu yok. structured_output alani, dogru tiplerle cikarilmis verileri icerir — age, "32" dizisi degil, 32 tamsayisidir.

Karmasik Semalar

Semalar ic ice nesneler, diziler, enum’lar ve aciklama ipuclari icerebilir. Kisitli kod cozme, karmasik semalarda yuksek guvenilirlik saglar, ancak API duzeyinde kesin bir garanti degildir.

Nesne Dizileri

Siniflandirma Icin Enum Kisitlamalari

Bir alani sabit bir deger kumesuyle sinirlamak icin enum kullanin. Kisitli kod cozme ile birlestirildiginde, bu Claude’u deterministik bir siniflandiriciya donusturur:

{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" }
  },
  "required": ["sentiment", "confidence"]
}

Claude, sentiment icin yalnizca uc enum degerinden birini uretebilir. Halusinasyon uretilmis dorduncu bir secenek imkani yoktur.

Aciklama Ipuclari

Sema yapisini degistirmeden cikarmayi yonlendirmek icin description alanlari ekleyin. Bu, ozellikle alan adlari tek basina belirsiz oldugunda kullanislidir:

{
  "type": "object",
  "properties": {
    "action_items": {
      "type": "array",
      "description": "Toplanti notlarinda belirtilen somut sonraki adimlar listesi",
      "items": {
        "type": "object",
        "properties": {
          "task": { "type": "string", "description": "Yapilacak belirli eylem" },
          "owner": { "type": "string", "description": "Sorumlu kisi" },
          "deadline": { "type": "string", "description": "Belirtildiyse ISO 8601 tarihi, aksi halde bos dize" }
        },
        "required": ["task", "owner", "deadline"]
      }
    }
  },
  "required": ["action_items"]
}

Sema Tasarim Ipuclari

• required’i bolca kullanin. required listesinde olmayan herhangi bir alan atlanabilir. Gercekten istege bagli alanlar istemiyorsaniz her seyi required’a koyun.
• Siniflandirma icin enum kullanin. Duygu, onem derecesi, kategori — sonlu bir deger kumesine sahip her sey enum icin uygundur.
• Cikarmayi yonlendirmek icin description kullanin. Model, uretim sirasinda bu ipuclarini okur. Iyi yazilmis bir aciklama genellikle daha uzun bir prompttan daha etkilidir.
• Semalari mumkun oldugunca duz tutun. Derin ic ice gecme, derlemek ve uretmek icin daha fazla token gerektirir. Semanizda ucten fazla ic ice gecme seviyesi varsa, yeniden yapilandirmayi dusunun.

result ve structured_output Karsilastirmasi

--json-schema kullanildiginda, JSON zarfi yeni bir ust duzey alan kazanir. Hangi alanin okunacagini anlamak kritiktir.

Bu iki alan birbirinden bagimsizdir. Claude result’ta bir metin aciklamasi VE structured_output’ta yapilandirilmis veri saglayabilir, veya result bos olabilir. Davranis cagrilar arasinda tutarsizdir — bazen her ikisi de doldurulmus, bazen yalnizca structured_output. Ayristiricıniz her zaman veri icin structured_output’u okumali ve result’u istege bagli bir bonus olarak ele almalidir.

Yukaridaki temel varlik cikarimi orneginde, result bos bir dizeydi. Ancak dizi orneginde, Claude hem result’ta insan tarafindan okunabilir bir ozet hem de structured_output’ta yapilandirilmis diziyi sagladi:

Kisitli Kod Cozme

Prompt tabanli yaklasimlardan (“JSON formatinda yanit verin”) farkli olarak, --json-schema gramer tabanli kisitli kod cozme kullanir. Her token uretim adiminda, model yalnizca ciktiyi semaya karsi gecerli tutan token’lari uretebilir. Bu, son isleme veya dogrulama degildir — uretim sirasinda gerceklesir.

Pratik sonuclari:

• Neredeyse %100 uyumluluk — cikti pratikte guvenilir sekilde semaya uyar, ancak OpenAI’nin strict: true modundan farkli olarak, Claude’un kisitli kod cozmesi API duzeyinde kesin bir garanti degildir
• Halusinasyon uretilmis alan yok — yalnizca bildirilen ozellikler ciktida gorunur
• Dogru tipler — tamsayilar tamsayidir, dizeler dizedir, diziler dizidir
• Zorunlu alanlar mevcut — required listesindeki her alan bulunacaktir
• Enum uygulamasi — degerler tam olarak belirttiginiz seceneklerle sinirlanir

Bu, --json-schema’yi Claude’dan “lutfen JSON dondurmesinI” istemekten ayiran seydir. Prompt muhendisligi ile ~%95 uyumluluk elde edersiniz ve ayristirma basarisizliklarini yonetmeniz gerekir. Kisitli kod cozme ile pratikte neredeyse %100 uyumluluk elde edersiniz.

Odul, karmasik semalarin daha fazla token tuketmesidir. Semanin kendisi bir gramere derlenir ve 20 ic ice gecmis nesne iceren bir sema, duz 3 alanli bir semadan derlenmesi ve cikti uretmesi daha uzun surer. Cogu kullanim alani icin fark ihmal edilebilir, ancak derin ic ice gecmis bir semayla binlerce belge isliyorsaniz bilmeye deger.

Kullanim Alanlari

Yapilandirilmis cikti, duz metin yanitlarla imkansiz olan bir is akisi kategorisinin kilidini acar:

1. Veri cikarimi — yapilandirilmamis metinden (e-postalar, PDF’ler, loglar) yapilandirilmis alanlar cekme
2. Siniflandirma — enum kisitlamalariyla duygu, kategori, oncelik seviyesi
3. Kod inceleme — onem derecesi, dosya, satir numarasi ve oneri iceren yapilandirilmis inceleme ciktisi
4. Form doldurma — dogal dil girdisinden form alanlari cikarma
5. API yanit uretimi — Claude destekli API’nizin gecerli, tipli yanitlar dondurdugunu garanti etme
6. Toplu isleme — tutarli ciktiyla yuzlerce belgeden ayni alanlari cikarma

Hata yonetimi ve sema olusturma dahil Node.js’deki tam bir ayristirma ornegi icin kaynak kılavuza bakin.