Function Calling: JSON Şema İpuçları

LLM’lerde “function calling / tool calling”, modelin serbest metin yerine yapılandırılmış bir JSON argüman seti üretmesini ve bunu bir fonksiyona iletmenizi sağlar. Başarının anahtarı, şemanın kalitesi ve doğru kısıtlarla modeli yönlendirmektir. Aşağıdaki ipuçları, OpenAI/Anthropic gibi sağlayıcılarda kullanılan JSON-Schema benzeri tanımlara uygundur (desteklenen alt küme ve sürüm detayları sağlayıcıya göre değişebilir; her zaman resmi dokümantasyona bakın).

1) Mutlaka “kapatan” bir kök nesne tanımlayın

Fonksiyon argümanlarını tek bir object altında toplayın ve boş/ekstra alanların sızmasını engellemek için additionalProperties: false kullanın.

{
  "type": "object",
  "properties": {
    "city": { "type": "string", "description": "Şehir adı, örn. 'Gaziantep'" },
    "date": { "type": "string", "format": "date", "description": "YYYY-MM-DD" }
  },
  "required": ["city"],
  "additionalProperties": false
}

Neden? Modelin “tahmini alan” icat etmesini zorlaştırır, doğrulamayı basitleştirir.

2) Serbest metin yerine sınırlayıcılar kullanın

• enum: Sınırlı seçenekler için en güçlü kısıt.
• pattern: Format uygulatmak için düzenli ifade.
• minLength/maxLength: Aşırı uzun prompt argümanlarını sınırlar.
• minimum/maximum: Sayısal aralığı belirler.

{
  "type": "object",
  "properties": {
    "unit": { "type": "string", "enum": ["metric", "imperial"] },
    "zipcode": { "type": "string", "pattern": "^[0-9]{5}$" }
  }
}

3) Boolean tuzaklarından kaçının

Opsiyonel boolean alanlar (örn. use_cache) “varsayılan” belirsizliği doğurur. İki yaklaşım:

• Varsayılanı açıkça arka planda atayın ve alanı opsiyonel bırakın.
• Ya da üç durumlu yapın: mode: enum["auto","force","bypass"].

4) Dizi ve iç içe yapıları sade tutun

LLM’ler derin iç içe şemalarda hata yapmaya daha yatkındır. 2–3 seviye genellikle yeterlidir.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 }
        },
        "required": ["sku","qty"],
        "additionalProperties": false
      },
      "minItems": 1
    }
  },
  "required": ["items"]
}

5) “oneOf/anyOf” ile aşırı dallanmadan kaçının

Koşullu argümanlar gerekliyse oneOf kullanın; fakat çok sayıda varyant modeli zorlayabilir. Alternatif: üst düzeyde bir type veya mode alanı (enum) ile dallanmayı kontrol etmek.

{
  "type": "object",
  "properties": {
    "mode": { "type": "string", "enum": ["by_id","by_query"] },
    "id": { "type": "string" },
    "query": { "type": "string", "minLength": 3 }
  },
  "allOf": [
    { "if": { "properties": { "mode": { "const": "by_id" } } },
      "then": { "required": ["id"] } },
    { "if": { "properties": { "mode": { "const": "by_query" } } },
      "then": { "required": ["query"] } }
  ],
  "additionalProperties": false
}

6) Açıklamaları (description) görev odaklı yazın

Her alana kısa, net örnek ve iş kuralı belirtin. Açıklama kalitesi, modelin doğru argümanları seçmesini doğrudan etkiler. Gereksiz teori yerine “kullanım niyeti” yazın.

7) Format ipuçlarını kullanın (ama doğrulamayı sunucuda yapın)

format: "date", "date-time", "uri", "email" gibi ipuçları yönlendiricidir, fakat tek başına güvenlik/validasyon değildir. Sunucu tarafında doğrulamayı zorunlu tutun.

8) Yerelleştirme ve çok dillilik

Serbest metin girdi alacaksanız, şemada dil seçeneklerini belirtin (örn. language: enum["tr","en"]). Aynı alanın hem Türkçe hem İngilizce gelmesi riskini azaltır.

9) Hata güvenliği ve idempotensi

Fonksiyonlar yan etkili ise (ödeme, sipariş oluşturma):

• Şemaya idempotency_key (string, pattern/length kısıtıyla) ekleyin.
• dry_run: boolean ile etkisiz prova çağrılarına izin verin.
• Yanıt şemasında status, error_code, message gibi alanları standartlaştırın.

10) Varsayılanlar ve sürümleme

• Sunucu tarafında güvenilir defaults atayın; modele bırakmayın.
• Büyük değişikliklerde schema_version veya api_version alanı tanımlayın. Geriye dönük uyumluluk için eski alanları geçici olarak “deprecated” açıklamasıyla tutun.

11) Güvenlik ve gizlilik

• PII/duyarlı veriler için alanları ayırın ve zorunlu kılmayın. Maskeleme/redenksiyon şemasını tanımlayın (örn. mask: enum["none","partial","full"]).
• Komut enjeksiyonu benzeri saldırılara karşı, fonksiyon tamamlama sonrası validasyon + iş kuralı kontrolü uygulayın. Şema güvenlik duvarı değildir, sadece ilk savunmadır.

12) Test ve değerlendirme

• Altın veri setiyle oto-test: argüman doğrulamadan kaç örnek geçiyor?
• Adversarial testler: geçersiz enum, çok uzun string, yanlış format.
• Canlıda telemetri: şema ihlali oranı, başarısız doğrulama yüzdesi, geriye dönüş düzeltmeleri.

Özet: İyi bir function-calling şeması; kapalı, anlaşılır, sınırlayıcı ve sürümlenebilir olmalı. additionalProperties:false, enum/pattern/length kısıtları, net description’lar ve sunucu tarafı validasyonuyla; modelin doğru argüman üretme oranını yükseltir, hataları ve güvenlik risklerini azaltır.