BroadRouter
Başlayın

JSON modu ve json_schema: sağlam yapılandırılmış çıktı

BroadNet Inference ekibi · 4 dk okuma · Yayımlandı

JSON modu (response_format json_object) yalnızca geçerli JSON sözü verir. Yapılandırılmış çıktı (response_format json_schema) ise sağlayıcının uyguladığı yerlerde alanlarınızı ve tiplerinizi de garanti eder. Her iki durumda da finish_reason değerini kontrol edin, yanıtı ayrıştırın ve Pydantic modeli gibi bir şemayla doğrulayın. Doğrulama başarısız olursa hatayı geri gönderip yeniden isteyin; deneme sayısına kesin bir sınır koyun.

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:

  1. Fazladan bir alan eklemeye davet eden bir istemle (“kısa bir yorum da ekle”) json_schema gönderin.
  2. İstek hata verirse sağlayıcı json_schema kabul etmiyordur. json_object deneyin.
  3. Yanıtta fazladan alan varsa şema uygulanmıyordur. Bunu JSON modu gibi değerlendirin.
  4. json_object da 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_reason değerini kontrol edin. max_tokens sı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:

  1. Düz yapı iç içe yapıdan iyidir. Çoğu veri çıkarma işi için iki seviye fazlasıyla yeterli.
  2. Kategoriler için serbest metin yerine enum kullanın.
  3. Ucu açık nesneler kullanmayın. Serbest biçimli dict alanları işin amacını boşa çıkarır.
  4. Açıklamalı kısa alan adları. Şemadaki açıklamalar modele yol gösterir.
  5. İsteğe bağlı alanları nullable yapın. Strict modda her alanı zorunlu olarak listeleyin ve null değ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.

Sık sorulan sorular

JSON modu ile yapılandırılmış çıktı arasındaki fark nedir?

JSON modu (response_format type json_object) yalnızca yanıtın JSON olarak ayrıştırılabileceğini garanti eder. Yapılandırılmış çıktı (type json_schema) ise sağlayıcının uyguladığı yerlerde tanımladığınız alanları ve tipleri de garanti eder. OpenAI, mümkün olduğunda JSON modu yerine yapılandırılmış çıktıyı öneriyor.

Açık modeller json_schema response_format destekliyor mu?

Sağlayıcıya bağlı. Bazıları json_schema kabul eder, bazıları yalnızca json_object, bazıları da alanı tamamen yok sayar. Bir şema ve modeli fazladan bir alan eklemeye teşvik eden bir istemle test isteği gönderin, ardından yanıtı kontrol edin.

Yapılandırılmış çıktıyı yine de doğrulamam gerekiyor mu?

Evet. Yanıtlar max_tokens nedeniyle kesilebilir, birer ret olabilir ve bir şemanın ifade edemediği iş kurallarını, örneğin tutması gereken toplamları, bozabilir.

Geçersiz JSON'u kaç kez yeniden denemeliyim?

Doğrulama hatasını da ekleyerek iki veya üç deneme genellikle yeterlidir. Sonrasında girdiyi kaydedin ve bir yedek yola, daha güçlü bir modele veya bir insana yönlendirin. Sınırsız döngüler token israf eder.

Yapılandırılmış çıktı mı kullanmalıyım, araç çağırma mı?

Son yanıtı sabit bir yapıda istiyorsanız yapılandırılmış çıktıyı kullanın. Modelin kodunuzun bir şey yapmasına ihtiyaç duyup sonra devam etmesi gerekiyorsa araç çağırmayı kullanın.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor