“JSON ile yanıt ver” diyen bir istem, yapıyı şansa bırakır. JSON Schema ise yapıyı, bir makinenin kontrol edebileceği şekilde yazıya döker.
Nasıl çalışır
Spesifikasyonun iki ana bölümü vardır: “defines the basic foundation of JSON Schema” (çeviri: JSON Schema’nın temel altyapısını tanımlar) olan Core ve “defines the validation keywords” (çeviri: doğrulama anahtar kelimelerini tanımlar) olan Validation. Güncel sürüm 2020-12’dir; bir önceki 2019-09’du.
{
"type": "object",
"properties": {
"name": {"type": "string"},
"amount": {"type": "number", "minimum": 0},
"currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
"note": {"type": ["string", "null"]}
},
"required": ["name", "amount", "currency", "note"],
"additionalProperties": false
}
LLM API’leri şemaları iki yerde kullanır. Araç tanımları, argümanları tanımlamak için parameters alanına bir şema koyar. Yapılandırılmış çıktı ise response_format içinde {"type": "json_schema", "json_schema": {...}} biçiminde bir şema gönderir; OpenAI bunun “ensures the model will match your supplied JSON schema” (çeviri: modelin sağladığınız JSON şemasına uymasını sağlar) olduğunu söyler.
OpenAI’nin strict modu yalnızca bir alt kümeyi kabul eder. Desteklenen şemalar bölümünden:
- Türler: string, number, boolean, integer, object, array, enum ve anyOf.
- Kök bir nesne olmalı ve
anyOfkullanamaz. additionalProperties: falseolmalı ve her alanrequirediçinde listelenmeli; bir alanı isteğe bağlı yapmak için yukarıdakinotegibinulldeğerine izin verin.- En fazla 5000 nesne özelliği ve 10 iç içe seviye, toplamda en fazla 1000 enum değeri.
- Desteklenmeyenler:
allOf,not,dependentRequired,dependentSchemas,if,then,else.
Neden önemli
- Doğrulama. Modele yol gösteren aynı şema, kodunuzda modelin yanıtını kontrol eder. Başarısız bir kontrol, modele geri gönderebileceğiniz kesin bir hata mesajı verir.
- Taşınabilirlik. Strict alt kümeye göre yazılmış bir şema, her anahtar kelimeyi kullanan bir şemadan daha fazla sağlayıcıda çalışır.
- Token’lar. Araç tanımlarındaki şemalar her istekte girdi olarak gönderilir. Uzun açıklamalar her turda token harcar.
BroadNet Inference’ta
BroadNet’in API referansı, GLM 5.3 ve Qwen3.8 27B için araç çağırmayı ve yapılandırılmış çıktıyı belgeler, ancak hangi şema anahtar kelimelerinin uygulandığını belgelemez. Şemaları yukarıdaki basit alt kümeyle sınırlı tutun ve her yanıtı doğrulayın. Şemayı JSON Schema oluşturucuyla hazırlayın, yanıtları LLM JSON çıktı doğrulayıcısıyla kontrol edin ve tam bir örnek için yapılandırılmış çıktı yazısına bakın. Diğer modellerde istemde JSON isteyin ve yanıtı doğrulayın; JSON modu BroadNet tarafından belgelenmemiştir, bu yüzden güvenmeden önce test edin.
Sık yapılan hatalar
allOfveya koşullu anahtar kelimeler kullanıp sunucunun bunları uyguladığını varsaymak.- Strict modda alanları
nulldeğerine izin vermek yerinerequireddışında bırakarak isteğe bağlı yapmaya çalışmak.