LLM'den Yapılandırılmış (JSON) Çıktı Nasıl Alınır: Şema, Doğrulama ve Hata Yönetimi

Neden yapılandırılmış çıktı?

Bir büyük dil modeli varsayılan olarak serbest metin üretir. Bir sohbet ekranında bu yeterlidir; ancak yanıtı başka bir yazılımın okuması gerektiğinde sorun başlar. Bir destek talebini kategoriye ayıran, bir faturadan alanları çıkaran ya da bir veritabanı kaydı oluşturan uygulama, modelin yanıtını ayrıştırabilmek zorundadır. Serbest metni düzenli ifadelerle ayrıştırmak kırılgandır: model bir gün açıklama cümlesi ekler, başka gün alan adını değiştirir ve uygulama çöker.

Yapılandırılmış çıktı, modelden önceden tanımlı bir biçimde, çoğunlukla JSON olarak yanıt almak ve bu yanıtı bir şemaya göre doğrulamaktır. Böylece model çıktısı yazılımın güvenle tüketebileceği bir veriye dönüşür.

JSON modu ile şema tabanlı çıktı arasındaki fark

Birbirine yakın görünen seviyeler vardır ve aynı garantiyi vermezler.

• Yalnızca geçerli JSON isteme. Model, sözdizimi açısından geçerli bir JSON üretmeye zorlanır; ancak hangi alanların bulunacağı, tiplerinin ne olacağı garanti edilmez. Alan eksik olabilir, beklenmeyen bir alan gelebilir.
• Şemaya uygun çıktı. Bir JSON Schema verilir ve yanıtın bu şemaya uyması sağlanır. Alan adları, tipler, zorunlu alanlar ve izin verilen değerler çıktıda korunur.

OpenAI dokümantasyonu bu ayrımı şöyle yapar: JSON modu geçerli JSON'u garanti eder ama şemayı zorlamaz; Yapılandırılmış Çıktılar (Structured Outputs) ise json_schema türü ve strict ayarıyla yanıtın verilen şemaya uymasını sağlar ve mümkün olduğunda JSON moduna tercih edilmesini önerir. Başka sağlayıcıların da benzer özellikleri olabilir; hangi modelin ve hangi seçeneğin desteklendiğini ilgili sağlayıcının güncel dokümantasyonundan kontrol edin.

Şema zorlaması desteklenmeyen bir modelde çalışıyorsanız, istemde biçimi tarif etmek ve çıktıyı uygulama tarafında doğrulamak gerekir.

Şema nasıl tasarlanır?

İyi bir şema, modelin neyi doldurması gerektiğini ve hangi değerleri alabileceğini sınırlar. Örnek olarak bir müşteri talebini sınıflandıran şema:

{ "type": "object", "properties": { "kategori": { "type": "string", "enum": ["fatura", "teknik", "iade"] }, "aciliyet": { "type": "string", "enum": ["dusuk", "orta", "yuksek"] }, "ozet": { "type": "string", "description": "Talebin tek cümlelik özeti" } }, "required": ["kategori", "aciliyet", "ozet"], "additionalProperties": false }

Şema tasarımının ilkeleri: • Serbest metin yerine enum kullanın. Sınıflandırma alanlarında olası değerleri kapalı bir listeyle verin. • Tüm alanları zorunlu yapın ve bilinmeyen alanı reddedin. Dokümantasyondaki örneklerde de bu desen kullanılır: bütün özellikler required içinde ve additionalProperties false olarak ayarlanır. • Alanlara açıklama ekleyin. Description alanı, modelin her alanın ne anlama geldiğini anlamasına yardım eder. • Tipleri dar tutun. Tarih için biçimini açıkça belirten bir string, kesin sayı için number ya da integer kullanın. • Belirsizlik için yer açın. Bilgi metinde yoksa modeli uydurmaya zorlamamak için "bilinmiyor" değeri ya da boş izin verilen bir alan tanımlayın. • Derin ve karmaşık iç içe yapılardan kaçının. Basit şemalar daha güvenilir sonuç verir.

İstem (prompt) ve çıktı birlikte tasarlanır

Şema yapıyı zorlar ama içeriğin doğruluğunu garanti etmez. Model şemaya uyan ama yanlış bir değer üretebilir. Bu yüzden istemde görevin kuralları da açık yazılmalıdır: hangi kategori ne zaman seçilir, aciliyet neye göre belirlenir, bilgi yoksa ne yapılır?

Örnek girdi ve beklenen çıktı çiftlerini istemde göstermek, özellikle kenar durumlarda tutarlılığı artırır. Kullanıcıdan gelen metni istemin içine yerleştirirken, talimat ile veri arasında net bir ayrım yapın; kullanıcı metninin içinde "önceki talimatları yok say" gibi ifadeler olabilir ve yapılandırılmış çıktı bu riski ortadan kaldırmaz.

Doğrulama, onarım ve hata durumları

Şemaya uyan çıktı bile bazı durumlarda kullanılamaz. Üretim kodunda şu durumlar karşılanmalıdır.

• Reddetme. Güvenlik nedeniyle model yanıtı reddedebilir. OpenAI dokümantasyonuna göre ret, normal çıktı yerine ayrı bir refusal alanında ya da refusal türünde bir içerik öğesi olarak gelir ve şemaya uymayabilir; ayrıştırmadan önce reddin olup olmadığı kontrol edilmelidir.
• Kesilme. Yanıt çıktı token sınırına takılırsa durum incomplete olur ve çıktı eksik kalabilir. Bu durumu yakalayıp sınırı artırın ya da çıktıyı küçültün.
• İş kuralı doğrulaması. Şema tipi doğrular ama "bitiş tarihi başlangıçtan önce olamaz" gibi kuralları doğrulamaz. Uygulama tarafında ek doğrulayıcı gerekir.
• Onarım. Doğrulama başarısız olursa hatayı modele geri bildirip yeniden denemek yaygın bir kalıptır. Deneme sayısını sınırlayın, sonunda başarısızlığı kullanıcıya ya da kuyruğa bildirin.
• Şema sürümleme. Şemayı değiştirdiğinizde bu veriyi tüketen kodu da güncelleyin; şema sürümünü kayıt altında tutun.

Uygulamada şema, tip tanımlarından otomatik üretilirse (örneğin kullandığınız dilin doğrulama kütüphanesiyle) şema ile kod arasında sapma azalır.

Kullanım örnekleri

Yapılandırılmış çıktı, sınıflandırma ve çıkarım gibi veri üreten görevlerde yaygındır.

Bir belge işleme hattında bir sözleşmeden taraf adları, başlangıç tarihi ve fesih koşulu çıkarılır; sonuç bir veritabanına yazılır. Destek biletleri kategori, aciliyet ve önerilen yönlendirme alanlarıyla etiketlenir. Bir araştırma asistanı, yanıtını başlık, özet ve kaynak listesi alanlarıyla döner; arayüz bunları ayrı bileşenlerde gösterir. Araç çağırma senaryolarında modelin hangi işlevi hangi parametrelerle çağıracağı da şemayla tanımlanır.

Her senaryoda ortak fayda, çıktının insan okumasından önce yazılım tarafından güvenle işlenebilmesidir.

Sık yapılan hatalar

Yapılandırılmış çıktı kurulumunda sorunlar genellikle şemanın kendisinden değil, çevresindeki varsayımlardan çıkar.

• Şema vermeden "JSON döndür" demek ve çıktının her seferinde aynı yapıda gelmesini beklemek.
• Reddetme ve kesilme durumlarını ele almamak; yalnızca başarılı yolu test etmek.
• Şemadaki alanları çok serbest bırakmak. Enum yerine string kullanmak sonradan eşleme sorunu doğurur.
• Doğruluğu şemaya bırakmak. Şemaya uygun yanlış değerler hâlâ mümkündür; örnek girdilerle ve gerçek verilerle değerlendirme seti kurmak gerekir.
• Büyük belgeyi tek istekte işlemeye çalışmak; bağlam penceresi dolduğunda kalite düşer.
• Kullanıcı girdisini doğrulamadan istemin içine koymak.

Mindset programlarında nerede çalışılır?

Yapılandırılmış Çıktı ve Şema Tabanlı LLM Yanıtları eğitimi Çıktı Sözleşmesi ve Şema Tasarımı, Kısıtlı Üretim Yöntemleri ile Doğrulama, Onarım ve Üretim Kullanımı modüllerinden oluşur. Yazılım geliştiriciler ve yapay zeka uygulaması yapan mühendisler için uygundur.

OpenAI API ile Kurumsal Uygulama Geliştirme eğitiminin Fonksiyon Çağırma ve Araç Kullanımı modülü ise modelin dış sistemlerle yapılandırılmış biçimde konuşması konusunu genişletir. Kurumsal ekiplerde belge işleme ya da talep sınıflandırma otomasyonları geliştirenler için birlikte değerlendirilebilir.