Ajanın hata yapmasını azaltan çıktı formatı ve şema kullanımı

Yapay zeka ajanlarıyla çalışırken en sinir bozucu anlardan biri, modelin “doğru” bilgiyi üretip yanlış formatta sunmasıdır. Bir API’den JSON bekliyorsunuz, ajan size düz metin döndürüyor. Ya da tarih formatı her seferinde farklı geliyor. İşte ajanın hata yapmasını azaltan çıktı formatı ve şema kullanımı tam da bu noktada devreye giriyor: Modelin ne söyleyeceğini değil, nasıl söyleyeceğini kontrol altına alıyorsunuz.

Kısa Tanım: Çıktı şeması (output schema), bir yapay zeka ajanının ürettiği yanıtın yapısını önceden tanımlayan bir kalıptır. JSON Schema, Pydantic modelleri veya TypeScript arayüzleri gibi araçlarla tanımlanır ve ajanın “serbest metin” yerine belirli bir formatta yanıt vermesini zorunlu kılar.

Ajanlar Neden Tutarsız Çıktı Üretir?

Büyük dil modelleri (LLM) doğaları gereği olasılıksal çalışır. Aynı prompt’a farklı zamanlarda farklı yanıtlar verebilirler. Bu durum sohbet uygulamalarında sorun yaratmaz; ancak bir ajan pipeline’ında zincirleme işlemler yürütüyorsanız, tek bir format hatası tüm sistemi çökertebilir.

Pratikte en sık karşılaşılan sorunlar şunlar:

• Tip uyumsuzluğu: Sayı beklenen alanda string dönmesi
• Eksik alanlar: Zorunlu bir key’in yanıtta bulunmaması
• Format kayması: Tarih, para birimi veya boolean değerlerin tutarsız temsili
• Ekstra açıklama: JSON’dan önce veya sonra gereksiz metin eklenmesi

Kilit Çıkarım: Şema kullanımı, bu hataların büyük çoğunluğunu daha model yanıt üretmeden önce engeller.

Yapılandırılmış Çıktı Nasıl Çalışır?

Modern LLM API’leri (OpenAI, Anthropic, Google) artık “structured output” veya “function calling” özellikleri sunuyor. Bu özellikler etkinleştirildiğinde model, verilen şemaya uymayan bir yanıt üretemez. Sistem, token üretim aşamasında şemayı bir kısıtlama (constraint) olarak uygular.

JSON Schema ile Tanımlama

En yaygın yöntem JSON Schema kullanmaktır. Aşağıda bir ürün analizi ajanı için örnek şema:

{
  "type": "object",
  "properties": {
    "urun_adi": { "type": "string" },
    "puan": { "type": "number", "minimum": 1, "maximum": 10 },
    "artilari": { "type": "array", "items": { "type": "string" } },
    "eksileri": { "type": "array", "items": { "type": "string" } },
    "tavsiye_edilir": { "type": "boolean" }
  },
  "required": ["urun_adi", "puan", "tavsiye_edilir"]
}

Bu şema sayesinde ajan her zaman aynı yapıda yanıt döner. “puan” alanı kesinlikle 1-10 arası bir sayı olur, “tavsiye_edilir” ise true/false dışında bir değer alamaz.

Pydantic ile Tip Güvenliği

Python ekosisteminde Pydantic modelleri daha okunabilir bir alternatif sunar:

from pydantic import BaseModel, Field
from typing import List

class UrunAnalizi(BaseModel):
    urun_adi: str
    puan: int = Field(ge=1, le=10)
    artilari: List[str]
    eksileri: List[str]
    tavsiye_edilir: bool

LangChain, LlamaIndex gibi framework’ler bu modelleri doğrudan şemaya çevirir. Kod tarafında da otomatik validasyon kazanırsınız.

Şema Kullanımının Somut Faydaları

Pro İpucu: Şema kullanımı token sayısını da dolaylı olarak azaltır. Model, “işte JSON formatında yanıtım:” gibi gereksiz açıklamalar eklemez; doğrudan veriyi döner.

Uygulama Senaryoları

Senaryo 1: Veri Çıkarma (Extraction)

Bir e-posta ajanı düşünün. Gelen mesajlardan gönderici, konu, aciliyet seviyesi ve eylem öğelerini çıkarması gerekiyor. Şemasız çalıştığında bazen “Acil” bazen “acil” bazen “1” döner. Şema ile enum tanımlarsanız:

"aciliyet": { "type": "string", "enum": ["dusuk", "orta", "yuksek", "kritik"] }

Artık downstream sistemleriniz bu dört değerden birini garanti olarak alır.

Senaryo 2: Çoklu Ajan Koordinasyonu

Bir ajan diğerine görev aktarıyorsa, aralarındaki “sözleşme” şema ile tanımlanır. Planlayıcı ajan şu yapıda çıktı üretir:

{
  "gorev_id": "task_001",
  "hedef_ajan": "arastirma_ajani",
  "parametreler": { "konu": "...", "derinlik": "detayli" },
  "oncelik": 2
}

Alıcı ajan bu yapıyı parse etmekte zorlanmaz; çünkü format sabittir.

Doğru Bilinen Yanlışlar

• “Şema kullanmak modeli kısıtlar, yaratıcılığı azaltır.” Yanlış. Şema yalnızca çıktının yapısını belirler, içeriğini değil. Model hâlâ “artilari” listesine istediği kadar yaratıcı madde ekleyebilir.
• “Prompt’ta format belirtmek yeterli.” Kısmen doğru ama güvenilir değil. Prompt talimatları %100 uyum garantisi vermez; özellikle uzun bağlamlarda model “unutabilir”.
• “Her API structured output destekler.” Hayır. Bazı sağlayıcılar bu özelliği sunmaz veya beta aşamasındadır. Kullandığınız API’nin dokümantasyonunu kontrol edin.

Şema Tasarımında Dikkat Edilecekler

Etkili bir şema tasarlamak için şu ilkeleri göz önünde bulundurun:

1. Minimalist başla: Sadece gerçekten ihtiyacın olan alanları tanımla. Fazla alan, modelin gereksiz veri “uydurmaya” çalışmasına yol açabilir.
2. Açıklayıcı alan adları kullan: “x1” yerine “musteri_puani” gibi anlamlı isimler, modelin doğru veriyi eşleştirmesini kolaylaştırır.
3. Opsiyonel alanları işaretle: Her alan zorunlu olmak zorunda değil. “required” listesine yalnızca kritik alanları ekle.
4. Enum’ları akıllıca kullan: Sınırlı seçenekli alanlar için enum tanımla; serbest metin gereken yerlerde string bırak.
5. Nested yapıları sınırla: Çok derin iç içe geçmiş objeler modelin hata yapma olasılığını artırır. Mümkünse düz yapılar tercih et.

Risk Seviyesi: Şema olmadan production’a çıkmak, özellikle finansal veya sağlık verisi işleyen ajanlarda ciddi risk taşır. Bir format hatası yanlış hesaplama veya kayıp veriye neden olabilir.

Sıkça Sorulan Sorular

Şema kullanmak API maliyetini artırır mı?

Hayır, aksine azaltabilir. Retry ihtiyacı düştüğü için toplam token tüketimi genellikle azalır. Şema tanımının kendisi birkaç yüz token yer kaplar; ancak bu, başarısız denemelerin maliyetinin yanında ihmal edilebilir.

Hangi framework’ler structured output destekliyor?

LangChain, LlamaIndex, Instructor, Marvin ve OpenAI’nin kendi SDK’sı native destek sunuyor. Anthropic Claude için de “tool use” üzerinden benzer işlevsellik mevcut.

Şema validasyonu başarısız olursa ne olur?

API seviyesinde zorlanan şemalarda bu durum nadiren yaşanır. Ancak client-side validasyon yapıyorsanız, hata yakalayıp retry mekanizması kurmanız gerekir. Üç başarısız denemeden sonra fallback stratejisi (varsayılan değerler veya insan müdahalesi) devreye girmelidir.

Streaming çıktıyla şema kullanılabilir mi?

Evet, ancak dikkatli olunmalı. Tam JSON oluşana kadar parse edilemez. Bazı kütüphaneler partial parsing desteği sunar; bu sayede veri parça parça işlenebilir.

Sonuç

Yapay zeka ajanlarının güvenilirliği, büyük ölçüde çıktılarının öngörülebilirliğine bağlıdır. Şema kullanımı bu öngörülebilirliği sağlamanın en etkili yoludur. Özellikle production ortamlarında, zincirleme ajan sistemlerinde ve veri bütünlüğünün kritik olduğu senaryolarda şemasız çalışmak kabul edilebilir bir risk değildir.

Yapmanız gereken basit: Ajanınızın üretmesini beklediğiniz çıktıyı bir şema olarak tanımlayın, API’nizin structured output özelliğini etkinleştirin ve format hatalarını geride bırakın. Bu küçük adım, ajan sistemlerinizin stabilitesinde büyük fark yaratacaktır.