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

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.

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
- Çıktı sözleşmesini belirleyin. Her alanın adını, türünü ve izin verilen değerlerini yazın. Kategorileri serbest metin yerine
enumile sınırlayın. - Gerekli alanları açıkça işaretleyin. Strict şemada tüm özellikleri
requiredlistesine koyun. Bir değer gerçekten isteğe bağlıysa, alanı atlatmak yerine uygun türle birliktenullkabul edecek biçimde tanımlayın. - 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.
- İş 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.
- 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.