Yapay Zekâdan Güvenilir JSON Alma: Structured Outputs ve JSON Schema Rehberi

Yapay zekâdan gelen yanıtı doğrudan uygulama koduna bağlamak, ilk prototipte hızlı görünür; ancak üretimde beklenmedik sonuçlara yol açabilir. Model aynı soruya bazen farklı alan adları, eksik değerler veya açıklama metni eklenmiş bir JSON döndürebilir. Bu noktada Structured Outputs ve JSON Schema, serbest metni uygulamanın okuyabileceği kontrollü bir veri sözleşmesine dönüştürür.

Bu rehberde JSON Schema nedir, Structured Outputs ne işe yarar, güvenilir JSON çıktısı nasıl tasarlanır ve doğrulama başarısız olduğunda ne yapılır sorularını uygulamalı olarak ele alacağız. En önemli sınır şudur: Şema, çıktının biçimini kontrol eder; modelin verdiği bilginin doğru olduğunu tek başına kanıtlamaz.

Structured Outputs nedir?

Structured Outputs, dil modelinden belirlediğiniz bir şemaya uyan yapılandırılmış çıktı isteme yaklaşımıdır. Klasik JSON modunda modelin geçerli JSON üretmesi beklenir; fakat alanların eksiksiz olması, doğru türde gelmesi veya yalnızca izin verilen değerleri kullanması ayrıca garanti edilmeyebilir. Structured Outputs ise destekleyen model ve API’lerde yanıtın tanımladığınız JSON Schema sözleşmesine uymasını hedefler.

Bu yaklaşım; ürün bilgisi çıkarma, destek taleplerini sınıflandırma, form doldurma, arama filtresi üretme, içerik etiketleme ve fonksiyon çağrısı hazırlama gibi işlerde kullanışlıdır. Modelin yanıtını ekranda göstermek yerine kodla işleyecekseniz, serbest metin yerine açık bir çıktı sözleşmesi tanımlamak daha güvenli bir başlangıçtır.

JSON ile JSON Schema arasındaki fark

JSON, verinin kendisini temsil eden bir formattır. JSON Schema ise bu verinin nasıl görünmesi gerektiğini tarif eder. Örneğin aşağıdaki JSON bir ürün kaydıdır:

{
  "name": "Kablosuz Kulaklık",
  "price": 1299.90,
  "inStock": true
}

Bu nesnenin geçerli sayılması için name alanının metin, price alanının sayı ve inStock alanının doğru/yanlış olması gerektiğini JSON Schema ile tanımlayabilirsiniz. Schema ayrıca zorunlu alanları, izin verilen değerleri, dizi elemanlarının türünü ve ek alanların kabul edilip edilmeyeceğini belirler. JSON Schema’nın resmi dokümantasyonu da şemayı veri yapısını, kısıtları ve türleri tanımlayan deklaratif bir dil olarak açıklar.

Güvenilir JSON çıktısı için 5 adımlı akış

1. Önce uygulamanın ihtiyacını sözleşmeye çevir

Şema yazmaya başlamadan önce model çıktısını kullanacak kodu düşünün. Uygulama gerçekten hangi alanlara ihtiyaç duyuyor? Bir alan eksikse işlem durmalı mı, varsayılan değer kullanılabilir mi? Bir sınıflandırma sonucunda yalnızca üç kategori mi geçerli?

Örneğin destek mesajını sınıflandıran bir sistem için şu sözleşme yeterli olabilir:

• category: billing, technical veya account değerlerinden biri
• priority: low, normal veya urgent değerlerinden biri
• summary: kısa bir metin
• needsHuman: insan incelemesi gerekip gerekmediğini belirten boolean

İhtiyaç olmayan alanları şemaya eklemeyin. Daha büyük şema, modele daha fazla karar alanı verir ve doğrulama sonrasında işlenmesi gereken durumları artırır.

2. Alan türlerini ve sınırlarını açık yaz

Şemada yalnızca alan adlarını değil, her alanın türünü ve kabul edilebilir sınırlarını da belirtin. Bir etiket alanı için serbest metin yerine enum kullanmak, yazım farklılıklarını azaltır. Sayısal bir alan için minimum ve maksimum değerleri belirlemek, hatalı model çıktılarının uygulamaya ulaşmasını engeller.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "needsHuman": {
      "type": "boolean"
    }
  },
  "required": ["category", "priority", "summary", "needsHuman"]
}

additionalProperties: false, sözleşmede olmayan alanların kabul edilmemesini sağlar. Bazı sağlayıcıların katı şema modlarında tüm alanların required listesinde bulunması gerekebilir. Gerçek API’nin desteklediği JSON Schema alt kümesini ayrıca kontrol edin.

3. İsteği ve çıktıyı birbirinden ayır

Kullanıcı metni, sistem talimatı ve çıktı şeması farklı sorumluluklara sahiptir. Prompt içinde modele “yalnızca JSON döndür” demek faydalı olsa da güvenilirliği yalnızca bu cümleye bırakmayın. Şemayı API’nin yapılandırılmış çıktı özelliğiyle gönderin; model yanıtını aldıktan sonra da sunucu tarafında doğrulayın.

Örneğin ürün yorumlarını etiketleyen akışta modelden şu davranış istenebilir:

1. Yorumu yalnızca verilen metne dayanarak değerlendir.
2. Belirsizse needsHuman: true üret.
3. Category alanında yalnızca tanımlı enum değerlerini kullan.
4. Özet alanına yeni bir iddia ekleme.

Bu kurallar model davranışını yönlendirir. Schema ise çıktının biçimsel sözleşmesidir. İkisini aynı şey gibi görmemek, hata ayıklamayı kolaylaştırır.

4. Yanıtı uygulamaya almadan önce doğrula

Structured Outputs kullansanız bile doğrulama katmanını tamamen kaldırmayın. API’den dönen yanıtı parse edin, şemaya göre doğrulayın ve iş kuralı kontrollerini ayrıca çalıştırın. Örneğin priority alanı doğru türde olsa bile, acil olarak işaretlenen bir talebin insan onayı gerektirip gerektirmediği ayrı bir iş kuralıdır.

Doğrulama hattını şu sırada kurabilirsiniz:

• Yanıt gerçekten beklenen formatta mı?
• JSON parse edilebiliyor mu?
• Zorunlu alanlar mevcut mu?
• Alan türleri, uzunlukları ve enum değerleri geçerli mi?
• İş kuralları ve yetki kontrolleri sağlanıyor mu?

Son kontrolden geçmeyen veriyi veritabanına yazmayın, kullanıcıya kesin sonuç gibi göstermeyin ve dış servise komut olarak göndermeyin.

5. Hata durumunu baştan tasarla

Her model çağrısının başarılı JSON döndüreceğini varsaymak yerine hata akışını tasarlayın. Şema doğrulaması başarısız olursa aynı isteği sınırsız kez tekrar etmek maliyeti ve gecikmeyi artırabilir. Daha güvenli yaklaşım; sınırlı sayıda yeniden deneme, basitleştirilmiş bir fallback şeması ve gerektiğinde insan incelemesidir.

Örnek fallback stratejisi şöyle olabilir:

1. İlk isteği tam şemayla gönder.
2. Doğrulama başarısızsa hatalı alanları logla; hassas verileri maskele.
3. En fazla bir kez, daha kısa talimatla yeniden dene.
4. Tekrar başarısızsa kaydı “inceleme bekliyor” durumuna al.
5. Kullanıcıya doğrulanmamış sonucu kesin bilgi gibi gösterme.

Optional alan mı, nullable alan mı?

Şema tasarımında sık karıştırılan iki kavram vardır. Optional alan hiç gönderilmeyebilir. Nullable alan ise gönderilir fakat değeri null olabilir. Uygulamanız iki durumu farklı yorumluyorsa şemada bu ayrımı açıkça belirtin.

Örneğin bir kargo takip sisteminde deliveredAt alanı teslim edilmemiş siparişlerde null olabilir; ancak orderId alanının hiç gelmemesi veri hatasıdır. Bu ayrımı uygulama kodunda sonradan tahmin etmeye çalışmak yerine veri sözleşmesinde tanımlayın.

Structured Outputs hangi sorunları çözmez?

• Gerçeklik garantisi vermez: Model, yanlış bir bilgiyi doğru JSON biçiminde üretebilir.
• İş kuralının yerini tutmaz: Geçerli türdeki bir değer yine de yetkisiz veya mantıksız olabilir.
• Prompt injection’ı tek başına çözmez: Harici içerikten gelen talimatları ayrıca güvenilmeyen veri olarak ele alın.
• Her JSON Schema özelliğini desteklemeyebilir: Sağlayıcı ve model dokümantasyonundaki sınırlara uyun.
• Akışkan yanıt tasarımını otomatik çözmez: Streaming, kısmi çıktı ve bağlantı kopması için ayrı hata yönetimi gerekir.

Üretime almadan önce test listesi

Şemayı yalnızca örnek bir başarı yanıtıyla test etmeyin. Aşağıdaki senaryoları küçük bir test setine ekleyin:

Test	Beklenen davranış
Zorunlu alan eksik	Yanıt reddedilir ve fallback çalışır
Enum dışında bir değer	Uygulamaya yazılmadan önce doğrulama hatası oluşur
Sayı metin olarak gelir	Otomatik dönüştürme yerine açık politika uygulanır
Çok uzun özet	Uzunluk kontrolü başarısız olur
Yanlış ama biçimsel olarak geçerli bilgi	Kaynak veya insan kontrolü istenir
Harici metin talimat vermeye çalışır	İçerik veri olarak işlenir, komut çalıştırılmaz

Sonuç: Güvenilir yapay zekâ çıktısı bir sözleşme işidir

Yapay zekâdan güvenilir JSON almak, prompt’a tek bir cümle eklemekten ibaret değildir. İyi sonuç için önce uygulamanın veri ihtiyacını tanımlayın, bunu açık bir JSON Schema sözleşmesine dönüştürün, Structured Outputs ile model çıktısını sınırlandırın ve sonrasında sunucu tarafında hem şema hem iş kuralı doğrulaması yapın.

Bu yaklaşım, modeli hatasız hale getirmez; fakat belirsizliği görünür, ölçülebilir ve yönetilebilir duruma getirir. Özellikle kullanıcı verisi, ödeme, otomasyon veya dış API çağrısı içeren sistemlerde “geçerli JSON” ile “güvenilir karar” arasındaki farkı her zaman koruyun.

Daha fazla bilgi için JSON Schema başlangıç rehberine ve Structured Outputs teknik dokümantasyonuna göz atabilirsiniz.