Bir Yapay Zekâ Modelinden Neden Bazen Geçersiz JSON Çıkar ve Yapılandırılmış Çıktı Nasıl Güvence Altına Alınır

Structured output, JSON Schema, constrained decoding, function calling, validation, retry ve fallback

Bir hukuk birimi, sisteme yeni bir tedarik sözleşmesi yüklüyor. Yapay zekâdan tarafları, başlangıç tarihini, yıllık bedeli, para birimini, otomatik yenileme koşulunu ve fesih bildirim süresini çıkarması isteniyor. İnsan için görev basit görünüyor: Belgeyi oku ve alanları doldur.

İlk denemede model bütün bilgileri doğru yazıyor; ancak cevabın başına kısa bir açıklama ekliyor. İkinci denemede JSON içindeki tutarı 3.250.000 yerine ‘3,25 milyon’ metni olarak döndürüyor. Üçüncü denemede zorunlu fesih süresi alanını atlıyor. Dördüncü denemede ise teknik olarak kusursuz görünen JSON içindeki başlangıç tarihi belgedeki tarihle uyuşmuyor.

Bu cevapların bazıları bir insan için anlaşılırdır. Fakat yazılım; açıklama cümlesini, eksik alanı, yanlış veri türünü veya serbest yazılmış para değerini güvenli biçimde işleyemez. Daha önemlisi, JSON’un kusursuz olması içindeki bilginin doğru olduğunu kanıtlamaz.

Makinenin okuyabilmesi için biçim; kurumun güvenebilmesi için doğrulama gerekir.

Bir önceki DERİNLEŞME bölümünde modelin neden tekrar ettiğini ve cevabın hangi koşullarda bittiğini incelemiştik. Bu bölümde model çıktısını başka bir yazılımın güvenle kullanabileceği yapıya dönüştüreceğiz. Aynı sözleşme örneği üzerinden structured output (yapılandırılmış çıktı), JSON Schema, constrained decoding (kısıtlı çözümleme), function calling (işlev çağırma), validation (doğrulama), retry (yeniden deneme) ve fallback (yedek davranış) kavramlarını ele alacağız.

Yapılandırılmış çıktı nedir

Şekil 1. Güvenli entegrasyon, doğal dil girdisini doğrudan işleme dönüştürmez; yapılandırma, doğrulama ve yetki kontrolünü ayrı aşamalar olarak uygular.

Structured output, modelin serbest bir paragraf yerine önceden tanımlanmış alanlara sahip makinece okunabilir bir nesne üretmesidir. Amaç yalnızca metnin güzel görünmesi değil, çıktının uygulama kodu tarafından belirsizliğe yer bırakmadan ayrıştırılmasıdır.

Sözleşme örneğinde sistemin beklediği çıktı aşağıdaki gibi olabilir:

{

  “taraf”: “Ege Lojistik A.Ş.”,

  “baslangic_tarihi”: “2026-11-01”,

  “yillik_bedel”: 3250000,

  “para_birimi”: “TRY”,

  “otomatik_yenileme”: true,

  “fesih_bildirim_gunu”: 60,

  “risk_duzeyi”: “yuksek”

}

Burada alan adları sabittir; tutar sayı, yenileme bilgisi boolean, para birimi ve risk düzeyi ise izin verilen değerlerden biridir. Böyle bir çıktı arayüzde gösterilebilir, veri tabanına aktarılabilir veya başka bir sürecin girdisi olabilir.

Her JSON yapılandırılmış çıktı değildir

JSON, verinin yazım biçimidir. JSON Schema ise bu verinin hangi yapıya uyması gerektiğini tanımlayan kurallar bütünüdür. Yalnızca ‘JSON üret’ demek, alanların adını, türünü, zorunluluğunu ve izin verilen değerleri garanti etmez.

OpenAI dokümantasyonu JSON mode ile Structured Outputs arasındaki ayrımı açıkça yapar: JSON mode geçerli JSON üretmeyi hedeflerken Structured Outputs belirlenen şemaya uyumu güvence altına alır. Benzer biçimde Anthropic araç tanımlarında işlev girdileri bir input_schema ile tarif edilir. Ayrıntılar sağlayıcıya göre değişse de ortak fikir aynıdır: Serbest metin yerine yazılım sözleşmesi kullanmak (OpenAI, 2026a; Anthropic, 2026).

JSON Schema neyi tarif eder

Şekil 2. JSON bir veri örneğidir; JSON Schema ise alanları, türleri, zorunlulukları ve izin verilen değerleri tanımlar.

JSON Schema, JSON belgelerini açıklamak ve doğrulamak için kullanılan bir sözlüktür. type alanın veri türünü, properties nesnenin alanlarını, required zorunlu alanları, enum izin verilen değerleri, additionalProperties ise tanımlanmamış yeni alanlara izin verilip verilmeyeceğini belirler (JSON Schema, 2020-12).

Sözleşme kaydı için sadeleştirilmiş şema şöyle düşünülebilir:

{

  “type”: “object”,

  “properties”: {

    “taraf”: { “type”: “string” },

    “baslangic_tarihi”: { “type”: “string”, “format”: “date” },

    “yillik_bedel”: { “type”: “number”, “minimum”: 0 },

    “para_birimi”: { “enum”: [“TRY”, “EUR”, “USD”] },

    “risk_duzeyi”: { “enum”: [“dusuk”, “orta”, “yuksek”] }

  },

  “required”: [“taraf”, “baslangic_tarihi”, “yillik_bedel”, “para_birimi”, “risk_duzeyi”],

  “additionalProperties”: false

}

Şema tasarlarken sağlayıcının desteklediği JSON Schema alt kümesi kontrol edilmelidir. Örneğin OpenAI strict structured output özelliği JSON Schema dilinin bir alt kümesini destekler; bazı koşullu veya türe özgü anahtar sözcükler modele göre kullanılamayabilir. Bu nedenle standartta geçerli olan her şemanın her model hizmetinde doğrudan çalışacağı varsayılmamalıdır (OpenAI, 2026a).

Kısıtlı çözümleme çıktıyı nasıl biçimde tutar

Şekil 3. Kısıtlı çözümleme, her üretim adımında şemaya aykırı belirteçleri seçim dışı bırakır; ancak seçilen değerin kaynaktaki gerçeği yansıtmasını tek başına garanti etmez.

Dil modeli her adımda olası sonraki belirteçler için skor üretir. Kısıtlı çözümleme, mevcut JSON konumu ve şema kurallarına göre hangi belirteçlerin yasal devam olduğunu hesaplar. Geçersiz devamların olasılığı sıfıra indirilir veya seçim havuzundan çıkarılır. Böylece model yanlış yerde kapatma parantezi, tanımsız alan veya enum dışında değer üretemez.

OpenAI bu süreci JSON Schema’nın bir gramer temsiline dönüştürülmesi ve her belirteçten sonra geçerli devamların dinamik olarak maskelenmesi şeklinde açıklar. Yeni bir şemanın ilk kullanımında ön işleme nedeniyle ek gecikme oluşabilir; daha sonraki çağrılarda şema önbellekten kullanılabilir (OpenAI, 2024).

Geng ve arkadaşlarının JSONSchemaBench çalışması, farklı kısıtlı çözümleme sistemlerinin şema kapsaması, verimlilik ve çıktı kalitesi bakımından aynı davranmadığını gösterir. Dolayısıyla ‘kısıtlı çözümleme var’ ifadesi tek başına yeterli değildir; kullanılan şema özellikleri ve gerçek görevler üzerinde test gerekir (Geng ve diğerleri, 2025).

Kısıtlı çözümleme, yanlış biçimi engelleyebilir; yanlış gerçeği değil.

Şemaya uygun JSON neden yine de yanlış olabilir

Model, belgedeki yıllık bedeli 3.250.000 TL yerine 325.000 TL olarak çıkarabilir. Çıktı number türündedir, bütün zorunlu alanlar vardır ve enum değerleri geçerlidir. Yani şema doğrulaması başarılıdır; fakat veri yanlıştır.

Bu nedenle validation yalnızca JSON parser çalıştırmak değildir. Kurumsal uygulamada en az beş ayrı kontrol katmanı gerekir:

Kaynak doğrulaması için modelden yalnızca değeri değil, değerin bulunduğu madde numarasını, sayfa numarasını veya kısa kaynak kesitini de üretmesi istenebilir. Ancak bu referansların da belge üzerinde yeniden kontrol edilmesi gerekir; model var olmayan bir madde numarası üretebilir.

İş kuralı doğrulaması deterministik kodla yapılmalıdır. Örneğin fesih bildirim günü negatif olamaz, başlangıç tarihi bitiş tarihinden sonra olamaz, para birimi kurumun izin verdiği listede bulunmalıdır ve belirli bir bedelin üzerindeki sözleşme ek yönetici onayı gerektirmelidir.

Function calling işlev çağırma nedir

Function calling veya tool calling, modelin yalnızca veri döndürmesi yerine uygulamada tanımlı bir işlevi hangi argümanlarla çağırmak istediğini bildirmesidir. Örneğin model aşağıdaki çağrıyı önerebilir:

sozlesme_kaydi_olustur({

  “taraf”: “Ege Lojistik A.Ş.”,

  “baslangic_tarihi”: “2026-11-01”,

  “yillik_bedel”: 3250000,

  “risk_duzeyi”: “yuksek”

})

Buradaki kritik ayrım şudur: Model çoğu mimaride işlevi kendisi çalıştırmaz; işlev adını ve argümanları üretir. Uygulama bu çağrıyı alır, şemayı doğrular, kullanıcının yetkisini kontrol eder ve uygun bulursa gerçek kodu çalıştırır. OpenAI function calling kılavuzu function parametrelerinin JSON Schema ile tanımlandığını ve strict modun çağrı argümanlarını şemaya bağladığını belirtir (OpenAI, 2026b).

İşlev tanımının şemaya uyması, işlemin yapılmasına izin verildiği anlamına gelmez. Bir çalışan sözleşme kaydı oluşturabilir ama imza sürecini başlatamayabilir. Model ‘imzaya gönder’ işlevini doğru argümanlarla seçse bile yetki ve onay kapısı uygulama katmanında kalmalıdır.

OWASP, araç erişimi olan yapay zekâ sistemlerinde çağrıların kullanıcı yetkileri ve oturum bağlamına göre doğrulanmasını, araç özelinde parametre kontrolü yapılmasını ve en az ayrıcalık ilkesinin uygulanmasını önerir. Belge içindeki kötü niyetli bir talimatın modele araç çağrısı yaptırabilmesi nedeniyle dış içerik güvenilir komut kabul edilmemelidir (OWASP, 2025).

Retry yeniden deneme ne zaman yapılmalıdır

Şekil 4. Yeniden deneme yalnızca düzelebilir ve yan etkisiz hatalarda sınırlı uygulanmalı; kalıcı doğrulama veya yetki hataları insan incelemesine ya da yedek davranışa yönelmelidir.

Retry, başarısız olan adımın yeniden çalıştırılmasıdır. Ancak her hata yeniden denenebilir değildir. Eksik bir tırnak, geçici ağ kesintisi ve yetkisiz işlem aynı yöntemle ele alınmamalıdır.

• Biçim veya şema hatası: Hata mesajı ve beklenen alanlar modele verilerek bir veya iki sınırlı yeniden deneme yapılabilir.
• Kaynakta bulunmayan bilgi: Modeli tekrar çağırmak gerçeği üretmez. Alan null bırakılmalı ve insan incelemesine yönlendirilmelidir.
• Geçici servis hatası: Zaman aşımı veya hız sınırı gibi geçici sorunlarda artan bekleme süresiyle yeniden deneme uygulanabilir.
• Yetki veya iş kuralı hatası: Aynı isteği tekrarlamak sonucu değiştirmez; işlem durdurulmalıdır.
• Yan etkili işlem: Kayıt açma, e-posta gönderme veya ödeme başlatma gibi işlevler ancak idempotency anahtarıyla güvenli biçimde yeniden denenmelidir.

Microsoft Retry Pattern, geçici hatalar ile kalıcı hataların ayrılmasını ve önceden belirlenmiş deneme sayısından sonra hatanın normal istisna olarak ele alınmasını önerir. AWS ise yan etkili API çağrılarının idempotent değilse güvenle yeniden denenemeyeceğini vurgular (Microsoft, 2026; AWS, 2019).

Fallback yedek davranış başarısızlığı gizlemek değildir

Fallback, ana yol güvenilir sonuç üretemediğinde sistemin önceden tanımlanmış güvenli davranışa geçmesidir. Amaç hatayı görünmez kılmak değil, işlemi kontrollü biçimde sınırlandırmaktır.

• Model üç denemede şemaya uyamazsa belge insan inceleme kuyruğuna alınabilir.
• Kritik alan belgeden çıkarılamıyorsa tahmin üretmek yerine null değeri ve ‘inceleme gerekli’ durumu döndürülebilir.
• Model servisi erişilemiyorsa yalnızca açık iş kurallarına dayanan sınırlı bir çıkarım moduna geçilebilir.
• Yeni kayıt açılamıyorsa veri taslak olarak saklanıp kullanıcıya işlem yapılmadığı açıkça gösterilebilir.

Sessiz fallback en riskli davranışlardan biridir. Kullanıcı sistemin gerçek yapay zekâ analizi yaptığını düşünürken uygulama eski şablonu kullanıyorsa kararın dayanağı belirsizleşir. Arayüz ve denetim kaydı, hangi yolun çalıştığını açıkça göstermelidir.

Günlük işlerde yapılandırılmış çıktı nerede kullanılır

Bu örneklerin ortak noktası, model çıktısının başka bir iş akışını başlatmasıdır. Çıktı yalnızca ekranda okunacaksa serbest metin yeterli olabilir. Çıktı veri tabanına yazılacak, rapor üretilecek veya görev açılacaksa şema, doğrulama ve hata davranışı tasarımın zorunlu parçası hâline gelir.

Sözleşme örneğini uçtan uca kuralım

1. Girdi hazırlanır: PDF metni, sayfa numaraları ve belge kimliği modele verilir; belge içeriği komut değil veri olarak sınırlandırılır.
2. Şema seçilir: Alan adları, veri türleri, zorunlu alanlar, enum değerleri ve null kullanım kuralları tanımlanır.
3. Model yapılandırılmış çıktı üretir: Sağlayıcı destekliyorsa strict structured output veya kısıtlı çözümleme kullanılır.
4. Şema doğrulanır: Çıktı sunucu tarafındaki bağımsız validator ile yeniden kontrol edilir.
5. İçerik ve iş kuralları doğrulanır: Tutarın kaynak kesitiyle eşleşmesi, tarihler arasındaki ilişki ve kurum limitleri kontrol edilir.
6. İşlev çağrısı yetkilendirilir: Kullanıcının rolü, onay gereksinimi ve idempotency anahtarı belirlenir.
7. Sonuç ve hata yolu kaydedilir: Kullanılan model, şema sürümü, doğrulama sonuçları, retry sayısı, fallback türü ve insan onayı denetim kaydında tutulur.

Üretim sisteminde başarı, yalnızca JSON’un parse edilmesi değil; doğru verinin doğru yetkiyle doğru işleme dönüşmesidir.

Kurumsal uygulama için on kontrol sorusu

• Çıktı şeması sürümleniyor mu ve hangi modelin hangi şema sürümüyle çalıştığı kaydediliyor mu?
• Zorunlu alanlar ile gerçekten bilinmeyebilecek alanlar birbirinden ayrıldı mı?
• additionalProperties veya benzeri kurallarla beklenmeyen alanlar engelleniyor mu?
• Şema doğrulamasından sonra iş kuralları ve kaynak doğrulaması ayrıca yapılıyor mu?
• Modelin ürettiği kaynak referansları belge üzerinde yeniden kontrol ediliyor mu?
• Function calling sonucu otomatik çalışmadan önce yetki ve onay kapısından geçiyor mu?
• Retry yalnızca geçici veya düzeltilebilir hata türlerine mi uygulanıyor?
• Yan etkili işlemler idempotency anahtarıyla mükerrer çalışmaya karşı korunuyor mu?
• Fallback devreye girdiğinde kullanıcı ve denetim kaydı bunu görebiliyor mu?
• Şema geçerlilik oranı ile içerik doğruluğu ayrı ölçülüyor mu?

Kısa kavram sözlüğü

Structured output — yapılandırılmış çıktı: Önceden tanımlı alan ve türlere göre üretilen makinece okunabilir model çıktısı.

JSON Schema: JSON verisinin alanlarını, türlerini, zorunluluklarını ve kısıtlarını tanımlayan şema dili.

Constrained decoding — kısıtlı çözümleme: Üretim sırasında yalnızca kurala uygun sonraki belirteçlerin seçilmesine izin veren yöntem.

Function calling — işlev çağırma: Modelin uygulamadaki bir işlevi hangi argümanlarla çağırmak istediğini yapılandırılmış biçimde bildirmesi.

Validation — doğrulama: Çıktının sözdizimi, şema, iş kuralı, kaynak ve yetki kurallarına uygunluğunu kontrol etme süreci.

Retry — yeniden deneme: Düzelebilir bir hata sonrasında aynı adımı sınırlı ve kontrollü biçimde tekrar çalıştırma.

Fallback — yedek davranış: Ana yol başarısız olduğunda devreye giren önceden tanımlanmış güvenli alternatif.

Idempotency — yinelenebilir işlem güvenliği: Aynı isteğin birden fazla kez gönderilmesinin sistemde yalnızca tek etki oluşturmasını sağlayan özellik.

Sonuç geçerli biçim güvenilir kararın yalnızca ilk adımıdır

Yapılandırılmış çıktı, dil modeli ile kurumsal yazılım arasındaki belirsizliği azaltır. JSON Schema alanları ve türleri tanımlar; kısıtlı çözümleme modelin şemaya aykırı belirteç üretmesini engeller; function calling ise doğal dildeki niyeti uygulamadaki işlevlerle ilişkilendirir.

Fakat bu mekanizmaların hiçbiri tek başına modelin belgeyi doğru anladığını veya önerdiği işlemin yapılmaya yetkili olduğunu kanıtlamaz. Şema geçerliliği, içerik doğruluğu ve işlem yetkisi farklı sorulardır; farklı kontroller gerektirir.

Güvenilir kurumsal mimari; modeli yapı üreten bir bileşen olarak kullanır, doğrulamayı deterministik kodla yapar, yeniden denemeyi sınırlar, hatayı görünür kılar ve risk yükseldiğinde insanı sürece geri çağırır.

Yapay zekâdan düzgün JSON almak entegrasyonu başlatır; güvenilir sistemi ise doğrulama, yetki ve hata yönetimi kurar.

Bir sonraki DERİNLEŞME bölümünde

“Bir yapay zekâ işlev çağrısını gerçek işleme nasıl dönüştürür ve aynı işlemin iki kez yapılması nasıl önlenir?”

DERİNLEŞME 15’te idempotency (yinelenebilir işlem güvenliği), transaction (işlem bütünlüğü), timeout (zaman aşımı), circuit breaker (devre kesici), confirmation gate (onay kapısı), compensation (telafi işlemi) ve audit trail (denetim izi) kavramlarını tek bir görev oluşturma senaryosu üzerinden inceleyeceğiz.

Yazar

Dr. Mert Dönerçark

Yapay Zekâ Araştırmacısı ve Yazılım Stratejisti

Yayın Destekçisi ve Şeffaflık Notu

Bu yayın, MicroDestek katkılarıyla hazırlanmaktadır. Yazılarımda zaman zaman örneklerine yer verdiğim KolayOfis, ContractFlow ve MicroDestek Yapay Zekâ Asistanı, görev yaptığım MicroDestek tarafından geliştirilmektedir. Paylaştığım değerlendirmeler ise akademik ve uygulamalı çalışmalarım doğrultusunda oluşturulmuş kişisel görüşlerimi yansıtmaktadır.

Kaynakça

• Amazon Web Services. (2019). Timeouts, retries, and backoff with jitter. AWS Builders’ Library. Bağlantı
• Anthropic. (2026). Define tools. Claude Platform documentation. Bağlantı
• Geng, S., Cooper, H., Moskal, M., Jenkins, S., Berman, J., Ranchin, N., West, R., Horvitz, E. ve Nori, H. (2025). Generating structured outputs from language models: Benchmark and studies. Bağlantı
• JSON Schema. (2020). A vocabulary for structural validation of JSON. Draft 2020-12. Bağlantı
• JSON Schema. (2026). Understanding JSON Schema reference. Bağlantı
• Microsoft. (2026). Retry pattern. Azure Architecture Center. Bağlantı
• OpenAI. (2024). Introducing Structured Outputs in the API. Bağlantı
• OpenAI. (2026a). Structured model outputs. OpenAI API documentation. Bağlantı
• OpenAI. (2026b). Function calling. OpenAI API documentation. Bağlantı

OWASP. (2025). LLM Prompt Injection Prevention Cheat Sheet. Bağlantı