Teknik not

Yapay Zekâda Structured Outputs: JSON Schema ile Güvenilir Yanıt

Yapay zekâdan çıkan yapılandırılmış verilerin JSON Schema kartına ve yeşil onay işaretlerine dönüştüğünü gösteren soyut görsel

Bir dil modelinden “yanıtı JSON ver” istemek kolaydır. Ancak düzgün görünen JSON’un beklediğiniz alanları içerdiği, doğru türleri kullandığı veya uygulamanızın kurallarına uyduğu garanti değildir. Eksik alanlar ve beklenmeyen değerler, destek talebini yanlış kuyruğa gönderebilir ya da uygulamanın hata vermesine yol açabilir.

Structured Outputs (yapılandırılmış çıktılar), model yanıtının tanımladığınız JSON Schema biçimine uymasını sağlar. Bu, entegrasyonu daha öngörülebilir kılar; modelin verdiği bilginin doğru olduğunu tek başına kanıtlamaz.

Yapay zekâdan çıkan yapılandırılmış verilerin JSON Schema kartına ve yeşil onay işaretlerine dönüştüğünü gösteren soyut görsel
JSON Schema ile düzenli yapay zekâ çıktıları

JSON modu ile Structured Outputs arasındaki fark

JSON modu, modelin yanıtının geçerli JSON olarak biçimlenmesine yardımcı olur. Fakat beklenen şemaya—örneğin zorunlu alanlara ve izin verilen kategori değerlerine—uyacağını garanti etmez. Structured Outputs ise desteklenen JSON Schema kurallarıyla yanıt yapısını sınırlar.

Bu ayrım pratikte önemlidir: {"kategori":"teknik"} geçerli bir JSON olsa da uygulamanız oncelik ve ozet alanlarını da bekliyor olabilir. Şema biçimi güvenceye alır; içeriğin doğruluğunu ve iş kurallarına uygunluğunu yine uygulama kontrol etmelidir.

Örnek: Destek talebini sabit alanlara ayırmak

Bir müşteri mesajını sınıflandırırken modele serbest biçimli yanıt yerine şu sözleşmeyi verebilirsiniz:

{
  "type": "object",
  "properties": {
    "kategori": { "type": "string", "enum": ["odeme", "hesap", "teknik", "diger"] },
    "oncelik": { "type": "string", "enum": ["dusuk", "normal", "yuksek"] },
    "ozet": { "type": "string" },
    "musteri_yaniti": { "type": ["string", "null"] }
  },
  "required": ["kategori", "oncelik", "ozet", "musteri_yaniti"],
  "additionalProperties": false
}

Bu şemada her alan zorunludur. Bir yanıt henüz önerilemiyorsa musteri_yaniti alanı kaldırılmaz; değeri null olur. Strict kullanımında nesneye yeni alan eklenmesini de additionalProperties: false ile engellersiniz.

Responses API’de şema, isteğin text.format bölümünde type: "json_schema", bir ad, strict: true ve şema tanımıyla gönderilir. Dönen metni JSON olarak ayrıştırıp uygulamanızdaki tiplere aktarabilirsiniz. İsteğinizi kullandığınız SDK sürümünün güncel örneğine göre uyarlayın; desteklenmeyen şema anahtar sözcükleri strict isteğin reddedilmesine neden olabilir.

Uygulamada güvenilir kullanmak için 5 adım

  1. Çıktı sözleşmesini belirleyin. Her alanın adını, türünü ve izin verilen değerlerini yazın. Kategorileri serbest metin yerine enum ile sınırlayın.
  2. Gerekli alanları açıkça işaretleyin. Strict şemada tüm özellikleri required listesine koyun. Bir değer gerçekten isteğe bağlıysa, alanı atlatmak yerine uygun türle birlikte null kabul edecek biçimde tanımlayın.
  3. Model yanıtının durumunu kontrol edin. Ret (refusal), kesilmiş/eksik yanıt, API hatası ve başarılı yapılandırılmış çıktıyı ayrı durumlar olarak ele alın. Her cevabı koşulsuzca JSON sanıp parse etmeyin.
  4. İş kurallarını ayrıca doğrulayın. “Ödeme” kategorisindeki her talebin acil olduğu ya da modelin önerdiği müşteri yanıtının doğru olduğu varsayılmamalıdır. Kimlik, yetki, tutar ve kayıt durumu gibi kontroller kendi sisteminizde yapılmalıdır.
  5. Gerçekçi örneklerle sınayın. Eksik bilgi, çelişkili mesaj, boş metin ve desteklenmeyen talepleri deneyin. Şemayı ve kodunuzu birlikte sürümleyin.

Şema garantisi neyi çözmez?

Şemaya uyan bir çıktı hâlâ yanlış sınıflandırma, uydurma özet veya kötü bir öneri içerebilir. Yapılandırılmış çıktı, modelin cevabını makinece okunabilir ve biçim bakımından öngörülebilir yapar; doğruluk, güvenlik ve iş kararı garantisi vermez. Özellikle para iadesi, hesap kapatma veya kullanıcı erişimini değiştirme gibi sonuçlarda model önerisini doğrudan çalıştırmayın. Önce yetki denetimi, kurala dayalı kontroller ve gerekiyorsa insan incelemesi uygulayın.

Kısa kontrol listesi

  • Şema yalnızca uygulamanın gerçekten kullandığı alanları içeriyor mu?
  • İzin verilen değerler sınırlı mı, her anahtar zorunlu mu?
  • Ret ve eksik yanıt durumları güvenli biçimde ele alınıyor mu?
  • Model çıktısı, uygulama veritabanına yazılmadan önce doğrulanıyor mu?

Özet: Yapay zekâdan tutarlı veri almak için yalnızca “JSON döndür” demek yerine çıktı sözleşmesini JSON Schema ile tanımlayın. Ardından bu sözleşmeyi uygulama kuralları ve testlerle destekleyin.

Kaynaklar

Yazar hakkında

Ali Eren Çınar; mobil uygulamalar, yapay zekâ ve ürün geliştirme üzerine çalışan bağımsız yazılımcı. Cueora, Harcamio, Deep Focus ve Weather Note projelerini geliştiriyor; öğrendiklerini uygulamalı rehberlerle paylaşıyor.

Hakkımda ve diğer uygulamalar

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir