Yapay Zeka Araçlarından Düzenli Veri Alma: JSON ve Tablo Çıktısı İçin İstem Tasarımı Rehberi

Yapay zeka araçlarından yapılandırılmış çıktı alma, modelden yalnızca doğru bilgiyi değil, bu bilgiyi yazılımın veya çalışma tablonun doğrudan kullanabileceği biçimde istemeyi gerektirir. Serbest metin yerine geçerli JSON ya da düzenli bir tablo istiyorsanız; alanları, veri türlerini, eksik bilgi davranışını ve kontrol adımlarını baştan tanımlamalısınız.

En güvenilir yaklaşım üç parçadan oluşur: önce çıktı şemasını belirtmek, sonra kaynak veriyi ve kuralları ayırmak, son olarak da dönen sonucu teknik ve anlamsal açıdan doğrulamak. Modern API’lerde şema tabanlı yapılandırılmış çıktı özellikleri bu işi kolaylaştırır; ancak biçim kurallarına uyan bir JSON’un içindeki değerlerin mutlaka doğru olduğu anlamına gelmez. Google’ın yapılandırılmış çıktı belgeleri de şema uyumunun anlamsal doğruluğu garanti etmediğini ve uygulama tarafında doğrulama yapılması gerektiğini belirtir. İlgili ayrıntılar için Yapay Zeka Araçları kategorisindeki ilgili yazılar içeriği de değerlendirilebilir.

Yapılandırılmış çıktı istemi hangi parçalardan oluşur?

İyi bir istem, modele yalnızca “JSON döndür” demez. Modelin neyi çıkaracağını, hangi alanları dolduracağını ve belirsizlikle nasıl davranacağını tanımlar. Aşağıdaki dört katman çoğu veri çıkarma görevi için yeterlidir:

• Görev: Metinden ürün, kişi, tarih veya tutar bilgilerini çıkar.
• Şema: Alan adlarını, veri türlerini ve zorunlu alanları belirt.
• Kısıtlar: Tarih biçimi, para birimi, izin verilen değerler ve eksik bilgi davranışını yaz.
• Çıktı kuralı: Yalnızca JSON veya yalnızca tablo üretmesini iste.

Bu ayrım, açıklama metninin JSON’a karışmasını ve aynı alanın farklı adlarla dönmesini önler. Şema içinde email, phone ve date gibi alanlar için açık isimler kullanmak; “iletişim bilgisi” gibi geniş etiketlerden daha güvenlidir.

JSON çıktısı için istem şablonu nasıl yazılır?

JSON isteyen bir istemde alan adları, türler ve eksik veri politikası birlikte verilmelidir. Örneğin müşteri kayıtlarını ayıklamak için şu şablon kullanılabilir:

Görev: Aşağıdaki metinden müşteri bilgilerini çıkar.

Çıktı şeması:
{
  "ad_soyad": "string veya null",
  "eposta": "string veya null",
  "telefon": "string veya null",
  "urun": "string veya null",
  "talep_tarihi": "YYYY-AA-GG veya null"
}

Kurallar:
- Metinde bulunmayan bilgileri tahmin etme.
- Bilgi yoksa null kullan.
- E-posta ve telefon alanlarını metindeki biçimi koruyarak yaz.
- Yalnızca geçerli JSON döndür; açıklama ekleme.

Metin:
{{KAYNAK_METINI}}

Bu şablon, modelin eksik alanları uydurmasını sınırlar. Alanların boş bırakılması gerekiyorsa boş dize yerine null kullanmak, daha sonra yapılacak filtreleme ve veri tabanı işlemlerini kolaylaştırır.

JSON istemi yazarken şema neden önemlidir?

Basit görevlerde örnek bir JSON nesnesi yeterli olabilir. Çok sayıda alan, iç içe nesne veya liste bulunduğunda JSON Schema ya da kütüphane tabanlı bir model kullanmak daha sağlamdır. OpenAI’nin güncel API belgelerinde json_schema biçimiyle şemaya sıkı uyum istenebildiği, eski genel JSON moduna göre şema tabanlı yaklaşımın tercih edildiği açıklanır. platform.openai.com

Şema hazırlarken şu kararları baştan verin:

• Zorunlu alanlar hangileri?
• Bir alan metin mi, sayı mı, doğru/yanlış değeri mi?
• Alan yalnızca belirli seçenekleri mi kabul ediyor?
• Liste boş kalabilir mi?
• Eksik bilgi null olarak mı dönmeli?
• Model bilinmeyen bir değeri reddetmeli mi?

Şema ne kadar açık olursa çıktı biçimindeki değişkenlik o kadar azalır. Yine de şema, kaynak metinde bulunmayan bir bilgiyi doğrulayamaz; bunun için ayrıca kaynak kontrolü veya iş kuralı doğrulaması gerekir.

Tablo çıktısı ne zaman JSON’dan daha kullanışlıdır?

İnsanların hızlı karşılaştırma yapacağı listelerde tablo, makine işleyecek verilerde JSON daha uygundur. Örneğin toplantı notlarından görev listesi çıkarırken tablo okunabilirliği artırır; bu listeyi proje yönetim sistemine aktaracaksanız JSON daha doğru seçim olur.

Tablo isteminde “uygun gördüğün sütunları seç” demek yerine sütunları önceden yazın. Aksi halde model, her kayıtta farklı sütunlar kullanabilir. Sayısal alanlar için birim eklenip eklenmeyeceği de açıkça belirtilmelidir.

Yapay zeka araçlarından yapılandırılmış çıktı alma sürecinde doğrulama

Yapay zeka araçlarından yapılandırılmış çıktı alma sürecinin en sık atlanan adımı doğrulamadır. Çıktıyı kullanmadan önce en az üç kontrol uygulayın:

1. Sözdizimi kontrolü: JSON ayrıştırılabiliyor mu, tüm parantezler ve virgüller doğru mu?
2. Şema kontrolü: Zorunlu alanlar var mı, veri türleri beklenen biçimde mi?
3. İçerik kontrolü: Tarih geçerli mi, toplamlar tutarlı mı, değer gerçekten kaynak metinde bulunuyor mu?

Bir ürün fiyatı çıkarıyorsanız, fiyatın sayısal olup olmadığını kontrol etmek yeterli değildir. Para biriminin doğru okunması, indirimli fiyatın normal fiyatla karıştırılmaması ve kaynakta olmayan bir değerin eklenmemesi de denetlenmelidir.

Uygulama tarafında doğrulama başarısız olursa sonucu otomatik olarak yayımlamak yerine kaydı incelemeye almak daha güvenlidir. Özellikle finans, müşteri verisi, sağlık veya hukuki belgelerde model çıktısı doğrudan nihai karar olarak kullanılmamalıdır.

Yaygın hatalar ve düzeltme yöntemleri

JSON yerine açıklama dönmesi

İstemin sonuna “yalnızca geçerli JSON döndür” kuralını ekleyin. API destekliyorsa JSON Schema veya yapılandırılmış çıktı özelliğini kullanın. Kod bloğu işaretleri de istenmiyorsa bunu ayrıca belirtin.

Aynı alanın farklı adlarla gelmesi

Örnek olarak bir yerde customer_name, başka bir yerde musteri_adi kullanmayın. Tek bir adlandırma standardı seçin ve şemayı zorunlu tutun.

Eksik bilgilerin tahmin edilmesi

“Metinde yoksa null yaz” kuralını açıkça ekleyin. “Eksik alanları tamamla” gibi ifadeler, modelin çıkarım yapmasına yol açabilir.

Tablo sütunlarının değişmesi

Sütun başlıklarını ve sıralarını doğrudan yazın. Bir hücrede birden fazla bilgi bulunuyorsa ayırıcı karakteri de belirleyin.

Geçerli ama yanlış JSON

Bu hata biçimden değil, içerikten kaynaklanır. Kaynak metinle karşılaştırma, izin verilen değer listesi, tarih aralığı ve sayısal sınırlar ek doğrulama katmanlarıdır. Google’ın yapılandırılmış çıktı rehberinde de şema uyumlu sonucun anlamsal olarak doğru olmayabileceği ve uygulama kodunda kontrol edilmesi gerektiği vurgulanır.

Tekrarlanabilir bir istem için pratik kontrol listesi

Bir istemi yayına veya otomasyona almadan önce şu kısa listeyi uygulayın:

• Görev tek cümlede açıkça tanımlanıyor mu?
• Her alanın adı ve veri türü belli mi?
• Eksik veya çelişkili bilgi için davranış tanımlı mı?
• Modelin tahmin yapmaması gerektiği yazıyor mu?
• Çıktı biçimi ve izin verilen değerler sınırlandırılmış mı?
• JSON ayrıştırma ve şema doğrulama uygulanıyor mu?
• Hatalı sonuç insan incelemesine yönlendiriliyor mu?

İyi bir istem, modelden “daha dikkatli olmasını” istemek yerine başarının ölçülebilir koşullarını tanımlar. Bu yaklaşım çıktıyı yalnızca okunabilir değil, sonraki iş akışında kullanılabilir hale getirir.

Özet karar şu: İnsan okuyacaksa sabit sütunlu tablo, yazılım işleyecekse şemalı JSON seçin; her iki durumda da eksik veri politikasını ve doğrulama adımını istemin ayrılmaz parçası yapın.