Kodunuz veriye ihtiyaç duyar, modeller ise metin yazar. Yapılandırılmış çıktı bu açığı kapatır; ama “model JSON döndürür” ifadesi, nasıl istediğinize göre üç farklı anlama gelir. Bu yazı OpenAI uyumlu açık modellerdeki seçenekleri karşılaştırıyor, her birinin nasıl isteneceğini gösteriyor ve üretime doğrudan ekleyebileceğiniz bir doğrulama ve onarım döngüsü sunuyor.
JSON modu ile json_schema arasındaki fark nedir?
| Yöntem | İstek | Size verilen söz |
|---|---|---|
| Yalnızca istem | “Şu alanlarla JSON olarak yanıt ver…” | Hiçbir şey; genellikle JSON, bazen ek metinle |
| JSON modu | response_format: {"type": "json_object"} |
Herhangi bir yapıda geçerli JSON |
| Yapılandırılmış çıktı | response_format: {"type": "json_schema", ...} |
Uygulandığı yerde şemanıza uyan JSON |
OpenAI’ın Structured Outputs rehberi bunu açıkça söylüyor: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (BroadRouter çevirisi: “İkisi de geçerli JSON üretilmesini sağlasa da şemaya uyumu yalnızca Structured Outputs garanti eder.”) Rehber, mümkün olan her durumda JSON modu yerine yapılandırılmış çıktıyı öneriyor.
Açık model sağlayıcılarında garanti, sunucunun bunu nasıl uyguladığına bağlıdır. Birçoğu, şemayı bozacak tokenları engelleyen kısıtlı çözümleme (constrained decoding) kullanır. Bazıları alanı kabul eder ama uygulamaz. Aşağıdaki kodun her durumda doğrulama yapmasının nedeni budur.
json_schema nasıl istenir?
import os
from openai import OpenAI
from pydantic import BaseModel, Field
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
class Invoice(BaseModel):
vendor: str
currency: str = Field(pattern="^[A-Z]{3}$")
total: float
line_items: list[float]
schema = Invoice.model_json_schema()
schema["additionalProperties"] = False
response_format = {"type": "json_schema",
"json_schema": {"name": "invoice", "strict": True, "schema": schema}}
Pydantic, JSON Schema’yı sınıfınızdan üretir; böylece şema ile doğrulayıcı hiçbir zaman birbirinden kopmaz. Pydantic kullanmıyorsanız JSON şeması oluşturucu, örnek bir nesneden strict moda uygun bir şema oluşturur. OpenAI, strict mod için additionalProperties: false ve her özelliğin zorunlu (required) olarak listelenmesini şart koşar.
Sağlayıcınız hangi modu destekliyor?
Bir model üzerine bir şey inşa etmeden önce bu testi model başına bir kez çalıştırın:
- Fazladan bir alan eklemeye davet eden bir istemle (“kısa bir yorum da ekle”)
json_schemagönderin. - İstek hata verirse sağlayıcı
json_schemakabul etmiyordur.json_objectdeneyin. - Yanıtta fazladan alan varsa şema uygulanmıyordur. Bunu JSON modu gibi değerlendirin.
json_objectda hata verirse yalnızca istem ve doğrulama kullanın.
BroadNet Inference’ta belgeler GLM 5.3 ve Qwen3.8 27B (yan yana karşılaştırma) için yapılandırılmış çıktıyı listeliyor, ama istek parametresinin adını vermiyor. Yukarıdaki testi yayına aldığınız model üzerinde çalıştırın.
Hatalı çıktı nasıl doğrulanır ve onarılır?
import json
from pydantic import ValidationError
def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
messages = [
{"role": "system", "content": "Extract the invoice. Reply with JSON only."},
{"role": "user", "content": text},
]
for attempt in range(attempts):
r = client.chat.completions.create(model=model, messages=messages,
response_format=response_format,
max_tokens=4000)
choice = r.choices[0]
if choice.finish_reason == "length":
raise RuntimeError("Cut off: raise max_tokens") # retrying won't help
if getattr(choice.message, "refusal", None):
raise RuntimeError(f"Refused: {choice.message.refusal}")
raw = choice.message.content or ""
try:
inv = Invoice.model_validate_json(raw)
if abs(sum(inv.line_items) - inv.total) > 0.01:
raise ValueError("total must equal the sum of line_items")
return inv
except (ValidationError, ValueError) as e:
messages += [
{"role": "assistant", "content": raw},
{"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
]
raise RuntimeError(f"No valid JSON after {attempts} attempts")
Bu döngüyü işe yarar kılanlar:
- Önce
finish_reasondeğerini kontrol edin.max_tokenssınırına takılan bir yanıt, kesilmiş JSON’dur. Aynı sınırla yeniden denemek aynı şekilde başarısız olur. Yukarıdaki iki model de yanıt vermeden önce akıl yürütür ve akıl yürütme sınıra dahildir; bu yüzden pay bırakın. - Retleri ayrı ele alın. OpenAI’ın rehberi bir retin “does not necessarily follow the schema you have supplied” (BroadRouter çevirisi: “verdiğiniz şemaya uymayabileceğini”) belirtiyor.
- Hatayı aynen geri gönderin. Kör bir yeniden deneme çoğu zaman aynı hatayı döndürür. “line_items: field required” gibi bir mesaj ise modele düzeltecek somut bir şey verir.
- İş kurallarını kodda kontrol edin. Bir şema, toplamın kalemlerin toplamına eşit olması gerektiğini söyleyemez. Yukarıdaki kontrol söyleyebilir.
- Deneme sayısını sınırlayın. Her deneme, istemin tamamını girdi tokenı olarak yeniden gönderir.
Hangi şema özellikleri sorun çıkarır?
Şemaları sade tutun:
- Düz yapı iç içe yapıdan iyidir. Çoğu veri çıkarma işi için iki seviye fazlasıyla yeterli.
- Kategoriler için serbest metin yerine enum kullanın.
- Ucu açık nesneler kullanmayın. Serbest biçimli
dictalanları işin amacını boşa çıkarır. - Açıklamalı kısa alan adları. Şemadaki açıklamalar modele yol gösterir.
- İsteğe bağlı alanları nullable yapın. Strict modda her alanı zorunlu olarak listeleyin ve
nulldeğerine izin verin.
OpenAI’ın rehberi, bazı JSON Schema özelliklerinin strict modda desteklenmediğini belirtiyor. Açık model sunucularının da kendi sınırları var. Bir şema reddedilirse modu değiştirmeden önce şemayı sadeleştirin.
Üretimde yapılandırılmış çıktı nasıl izlenir?
Sessizce onarım yapan bir döngü, size her gün token kaybettiren bir sorunu gizleyebilir. Her çağrı noktası için üç sayı kaydedin:
| Metrik | Size ne söyler |
|---|---|
| İlk denemede başarı oranı | Model ile şemanın ne kadar uyumlu olduğu; düşüş çoğu zaman bir istem veya model değişikliğinin ardından gelir |
| Başarı başına ortalama deneme | Onarımların token maliyeti |
| Nihai başarısızlıklar | İşlem hattınızın baş edemediği girdiler; bunları elle inceleyin |
İlk denemedeki başarı alıştığınız seviyenin altına düşerse daha fazla yeniden deneme eklemeden önce şemayı sadeleştirin veya başka bir model deneyin. Başarısız ham yanıtlardan bir örneklem saklayın; böylece düzeltmeleri gerçek vakalar üzerinde test edebilirsiniz.
Bunun yerine ne zaman bir araç kullanmalısınız?
Yapılandırılmış çıktıyı son yanıt için kullanın: bir veri çıkarma, bir sınıflandırma, bir plan. Modelin kodunuzun bir şey yapmasına ihtiyaç duyup devam etmesi gerekiyorsa araç çağırmayı kullanın. Birçok ajan ikisini birlikte kullanır: döngü sırasında araçlar, son adım için bir şema. Görselden JSON’a bir örnek için bir görüntü modeliyle Arapça faturaları okuma rehberine bakın.
BroadNet Inference nerede devreye giriyor
BroadNet Inference, GLM 5.3 ve Qwen3.8 27B için standart chat completions biçiminin arkasında yapılandırılmış çıktıyı listeler; bu yüzden yukarıdaki kod OpenAI Python SDK ile değiştirilmeden çalışır. Qwen3.8 27B görsel de kabul eder; bu da belgelerden veri çıkarmaya uygundur. BroadNet’in belgeleri DeepSeek V4.1 Flash veya Gemma 4 VL 26B için yapılandırılmış çıktıdan söz etmiyor; bu modellerde doğrulamalı, yalnızca isteme dayalı yolu kullanın. Token başına fiyatları fiyat sayfasında karşılaştırın.
