Yapılandırılmış çıktı: Yapay zekâdan şemaya uyan cevap

Murat Bey, orta ölçekli bir firmanın satın alma biriminde çalışıyor. Her sabah tedarikçilerden gelen teklif e-postalarını bir sohbet aracına yapıştırıp “bunları tabloya dök” diyor. Çoğu gün işe yarıyor, ama bazen sütunların adı değişiyor, bir gün teslim tarihi yerine “gelecek hafta” yazıyor, başka bir gün tutar sütunu hiç gelmiyor. Firma bu işi muhasebe programına otomatik bağlamak isteyince yazılım ekibi tek bir şey soruyor: “Şeman hazır mı?”

Bu derste yapay zekâdan önceden tanımlanmış alanlara uyan cevap almanın ne demek olduğunu öğreneceksiniz. Sohbet ekranında tablo istemekle, yazılımların bağlandığı arayüzde (API) şema vererek cevabı bir kalıba zorlamak arasındaki farkı göreceksiniz. Kod yazmayacağız; kendi işiniz için kâğıt üzerinde bir şema taslağı çıkaracaksınız.

Aklınıza bir soru mu takıldı?

Sorunuzu ya da aradığınız konuyu yazın Ders bul

Bu derste neler öğreneceksiniz?

• Şema, alan, alan türü ve izinli değer kavramlarını kendi cümlelerinizle açıklamak
• Sohbette biçim istemek ile API’de şema zorlamak arasındaki iki temel farkı saymak
• Yapılandırılmış çıktının neyi garanti edip neyi etmediğini bir örnek üzerinde göstermek
• Tekrarlayan bir işiniz için en çok altı alanlı bir şema taslağı hazırlamak

Şema nedir, yapılandırılmış çıktı ne yapar?

Şema, bir cevabın hangi parçalardan oluşacağını önceden yazan bir kalıptır. Bir teklif kaydı için alanlar firma adı, toplam tutar, teslim tarihi ve durum olabilir. Şema her alan için türü de söyler: tutar sayı, firma adı metin, durum ise yalnızca belirli değerlerden biri olur. Bu son türe izinli değerler listesi (enum) denir.

Yapay zekâ araçlarında bu kalıplar çoğunlukla JSON (JavaScript Object Notation) biçiminde yazılır. JSON, verileri ad ve değer çiftleri hâlinde tutan, hem insanın hem programın okuyabildiği bir metin biçimidir. JSON verisinin nasıl olması gerektiğini anlatan ortak dile de JSON şeması (JSON Schema) adı verilir. Resmî sitesine göre amacı, verinin tutarlı, geçerli ve farklı sistemler arasında birlikte kullanılabilir olmasını sağlamaktır. Şemada hangi alanların zorunlu olduğu ve her alanın ne anlama geldiğini anlatan açıklamalar da yer alabilir.

Yapılandırılmış çıktı (structured outputs), bu şemanın modele bir ayar olarak verilmesidir. OpenAI, Google Gemini ve Anthropic’in geliştirici belgeleri aynı fikri anlatır: Şemayı verirsiniz, model cevabını o kalıba uyacak biçimde üretir. Anthropic’in belgesi bunun kısıtlı kod çözme (constrained decoding) ile yapıldığını belirtir. Kabaca söylersek, model cevabı yazarken şemaya uymayan bir devam yolu seçemez.

Sohbette tablo istemek ile API’de şema zorlamak

Sohbet ekranında “şu sütunlarla tablo yap” dediğinizde bir ricada bulunursunuz. Model çoğu zaman uyar, ama sonucu bir insan okuyacağı için küçük kaymalar fark edilmeden geçebilir. Sütun adının bir gün “Tutar”, ertesi gün “Toplam” olması sizin için sorun değildir; o tabloyu otomatik okuyan bir program içinse kayıt kaybı demektir.

API’de şema verdiğinizde biçim, ricanın değil ayarın parçası olur. OpenAI’ın belgesi burada önemli bir ayrım yapar: Yalnızca geçerli JSON üretmeyi sağlayan JSON modu (JSON mode) ile şemaya bağlılığı da sağlayan yapılandırılmış çıktı aynı şey değildir. Belgeye göre şemaya uyumu yalnızca ikincisi sağlar. Aynı belge, biçimi tutturmak için sert ve uzun komutlar yazma ihtiyacının azaldığını da söyler.

• Sohbette: Biçim bir istektir; sonucu insan okur ve düzeltir.
• API’de şemayla: Biçim bir kuraldır; sonucu program okur ve kaydı doğrudan işler.
• Her ikisinde de: İçeriğin doğru olup olmadığını ayrıca kontrol etmeniz gerekir.

Şema neyi garanti eder, neyi etmez?

Şema biçimi garanti eder, doğruluğu etmez. Google’ın Gemini belgesi, sözdizimi doğru bir cevapta bile değerlerin uygulama tarafında kontrol edilmesini ister. Belge, şemaya uyan ama anlamca yanlış cevaplar için hata yönetimi kurulmasını önerir. Yani model tutarı doğru alana yazar, ama yanlış e-postadaki tutarı da yazabilir.

Belgelerde geçen başka sınırlar da var. Anthropic’in belgesine göre model güvenlik gerekçesiyle cevap vermeyi reddederse ya da cevap uzunluk sınırına takılırsa çıktı şemaya uymayabilir. Aynı belge, izinli değerlerde büyük ve küçük harfin değişebileceğini de not eder. Gemini belgesi, en az ya da en çok karakter sayısı gibi bazı şema kurallarının dikkate alınmadığını, bunların ayrıca kontrol edilmesi gerektiğini yazar. Anthropic ve Gemini belgelerine göre fazla büyük ya da karmaşık şemalar hata verilerek reddedilebilir. OpenAI ise şemanın anlatamadığı iş kurallarının uygulama tarafından denetlenmesi gerektiğini söyler.

Bu konu güvenlikle de ilgilidir. OWASP’ın yapay zekâ güvenlik listesi, komut enjeksiyonuna (prompt injection) karşı önerdiği önlemler arasında beklenen çıktı biçimini tanımlamayı ve bunu sabit kurallı kodla doğrulamayı sayar. Cevabın dar bir kalıba sığması, beklenmedik bir talimatın sonuca sızmasını zorlaştırır.

Adım adım uygulama

1. Her hafta en az birkaç kez tekrarladığınız, metinden bilgi çıkarma gerektiren bir iş seçin: teklif, dilekçe, randevu talebi ya da müşteri şikâyeti gibi.
2. Bu iş için kâğıda en çok altı alan yazın. Her alanın yanına türünü ekleyin: metin, sayı, tarih ya da izinli değerler listesi.
3. İzinli değerli alanlar için seçenekleri tek tek yazın ve bilgi bulunmadığında kullanılacak bir değer ekleyin, örneğin “belirtilmemiş”.
4. Her alanın zorunlu mu isteğe bağlı mı olduğunu işaretleyin ve alanın ne anlama geldiğini tek cümleyle açıklayın.
5. Bu taslağı yukarıdaki güçlü komut gibi bir komuta dönüştürün ve kişisel veri içermeyen üç farklı örnek metinle sohbet aracında deneyin.
6. Kabul ölçütü: Üç denemede de alan adları ve sırası aynıysa, izinli değerlerin dışına çıkılmamışsa ve eksik bilgi uydurulmak yerine “belirtilmemiş” olarak yazılmışsa görev tamamdır. Biri tutmuyorsa alan açıklamasını netleştirip yeniden deneyin.

Sık yapılan hatalar

• Şemaya uyan cevabı doğru cevap sanmak. Şema yalnızca kalıbı korur; tutarı, tarihi ve adı kaynağıyla karşılaştırmak yine sizin işinizdir.
• Eksik bilgi için bir yol bırakmamak. Her alan dolmak zorundaysa ve “belirtilmemiş” gibi bir seçenek yoksa, boşluğun nerede olduğunu görmek zorlaşır.
• Şemayı gereğinden büyük kurmak. Onlarca alan ve iç içe katmanlar hem hataya açıktır hem de bazı araçlarda reddedilebilir; önce az ve net alanla başlayın.

Kendinizi deneyin

Kaynaklar

• Structured model outputs (OpenAI API belgeleri) (İngilizce)
• Structured outputs (Gemini API belgeleri) (İngilizce)
• Structured outputs (Claude Platform belgeleri) (İngilizce)
• JSON Schema resmî sitesi (İngilizce)
• Creating your first schema (JSON Schema) (İngilizce)
• LLM01:2025 Prompt Injection (OWASP Gen AI Security Project) (İngilizce)

Son kontrol: 13 Kasım 2026. Bu bilgi 13.11.2026 tarihli kaynaklara dayanır; durum değişebilir.

Kaynak: yzdersleri.com/ders/yapilandirilmis-cikti-semaya-uyan-cevap/ · Yapay Zeka Dersleri