---
title: "JSON modu ve JSON şeması ile yapılandırılmış çıktı | BroadRouter"
description: "JSON modu geçerli JSON verir, json_schema ise sizin yapınızı. OpenAI uyumlu modellerde ikisi nasıl istenir, Pydantic ile doğrulanır ve hatalı çıktı döngüde onarılır?"
url: https://broadrouter.com/tr/blog/structured-output-json-schema/
lang: tr
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

İngilizceden yapay zekâ desteğiyle çevrilmiştir. [İngilizce aslını okuyun](https://broadrouter.com/blog/structured-output-json-schema/) (güncelleme: 2026-11-14).

# JSON modu ve json\_schema: sağlam yapılandırılmış çıktı

BroadNet Inference ekibi · 4 dk okuma · Yayımlandı 2026-11-14

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.

## Öne çıkanlar

-   OpenAI'ın rehberi: iki mod da geçerli JSON üretir, ama "only Structured Outputs ensure schema adherence" (BroadRouter çevirisi: "şemaya uyumu yalnızca Structured Outputs garanti eder").
-   Destek, OpenAI uyumlu sağlayıcılar arasında farklılık gösterir. Önce json\_schema'yı test edin, olmazsa json\_object'e, o da olmazsa yalnızca isteme dayalı yönteme geçin.
-   Her yanıtı doğrulayın. max\_tokens nedeniyle kesilen bir yanıt, şema ne derse desin bozuk JSON'dur.
-   Onarım döngüleri, doğrulama hatasını aynen geri gönderdiğinizde işe yarar. Bunları iki veya üç denemeyle sınırlayın.
-   BroadNet Inference'ta GLM 5.3 ve Qwen3.8 27B, yapılandırılmış çıktıyı destekleyen modeller arasında listelenir.

**Bu sayfada**

1.  JSON modu ile json\_schema arasındaki fark nedir?
2.  json\_schema nasıl istenir?
3.  Sağlayıcınız hangi modu destekliyor?
4.  Hatalı çıktı nasıl doğrulanır ve onarılır?
5.  Hangi şema özellikleri sorun çıkarır?
6.  Üretimde yapılandırılmış çıktı nasıl izlenir?
7.  Bunun yerine ne zaman bir araç kullanmalısınız?
8.  BroadNet Inference nerede devreye giriyor

Kodunuz veriye ihtiyaç duyar, modeller ise metin yazar. [Yapılandırılmış çıktı](https://broadrouter.com/tr/glossary/structured-output/) 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?

```python
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](https://broadrouter.com/tools/json-schema-generator/), ö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](https://broadrouter.com/tr/models/glm-5.3/) ve [Qwen3.8 27B](https://broadrouter.com/tr/models/qwen3.8-27b/) ([yan yana karşılaştırma](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)) 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?

```python
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`](https://broadrouter.com/tr/glossary/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](https://broadrouter.com/tr/guides/reasoning-tokens-empty-response/); 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ı](https://broadrouter.com/tr/glossary/input-and-output-tokens/) 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ı](https://broadrouter.com/tr/blog/tool-calling-open-models/) 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](https://broadrouter.com/tr/guides/read-arabic-invoices-with-vision/) 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](https://broadrouter.com/tr/guides/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](https://broadrouter.com/tr/pricing/) karşılaştırın.

Bu konu için ücretsiz araçlar (İngilizce)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Ücretsiz araçlar (İngilizce)](https://broadrouter.com/tools/)

## Bu yazıdaki terimler

[Yapılandırılmış çıktı (structured output)](https://broadrouter.com/tr/glossary/structured-output/)

Yapılandırılmış çıktı, modelin yanıtını geliştiricinin belirlediği bir biçimle, genellikle bir JSON Schema ile sınırlayan bir LLM API özelliğidir; böylece kod yanıtı güvenilir şekilde ayrıştırabilir. Geçerli JSON'u garanti eden ama belirli bir yapıyı garanti etmeyen JSON modundan daha katıdır.

[JSON Schema (JSON şeması)](https://broadrouter.com/tr/glossary/json-schema/)

JSON Schema, JSON verisinin yapısını tanımlamak ve doğrulamak için JSON ile yazılan bir sözlüktür: türler, zorunlu alanlar, izin verilen değerler ve iç içe yapı. Güncel sürüm 2020-12'dir. LLM API'leri onu araç parametrelerini ve yapılandırılmış çıktının izlemesi gereken kesin yapıyı tanımlamak için kullanır.

[JSON modu (JSON mode)](https://broadrouter.com/tr/glossary/json-mode/)

JSON modu, OpenAI tarzı API'lerde response\_format {"type": "json\_object"} ile açılan ve modelin yanıtını geçerli, ayrıştırılabilir JSON yapan bir LLM API ayarıdır. JSON Schema kullanan yapılandırılmış çıktıların aksine, nesnenin hangi anahtarları, türleri veya değerleri içereceğini garanti etmez.

[Token](https://broadrouter.com/tr/glossary/token/)

Token, bir dil modelinin okuduğu ve yazdığı metin birimidir: modelin tokenizer'ının ürettiği bir kelime, kelime parçası, noktalama işareti veya bayt dizisi. LLM API'leri kullanımı token cinsinden sayar, sınırlar ve genellikle faturalandırır.

[Açık ağırlıklı model (open-weight model)](https://broadrouter.com/tr/glossary/open-weight-model/)

Açık ağırlıklı model (open-weight model), eğitilmiş ağırlıkları herkesin indirip çalıştırabileceği şekilde, genellikle koşullar içeren bir lisansla yayımlanan bir makine öğrenimi modelidir. Eğitim kodunu ve eğitim verileri hakkında ayrıntılı bilgiyi de yayımlayan, böylece başkalarının modeli incelemesine ve yeniden üretmesine imkân veren tam açık kaynak yapay zekadan farklıdır.

[Araç çağırma (tool calling)](https://broadrouter.com/tr/glossary/tool-calling/)

Araç çağırma (tool calling), fonksiyon çağırma (function calling) olarak da bilinir; modelin, geliştiricinin tanımladığı bir fonksiyonu çalıştırmak için JSON argümanlı yapılandırılmış bir istek döndürdüğü bir LLM API özelliğidir. Fonksiyonu uygulama çalıştırır ve sonucu geri gönderir; model hiçbir zaman kodu kendisi çalıştırmaz.

[Chat Completions API](https://broadrouter.com/tr/glossary/chat-completions-api/)

Chat Completions API, OpenAI'nin bir model adı ile rollerle etiketlenmiş mesaj listesini alıp modelin sonraki mesajını döndüren HTTP uç noktasıdır: POST /v1/chat/completions. İstek ve yanıt yapısı, OpenAI uyumlu sağlayıcıların ve SDK'ların yeniden kullandığı ortak format hâline geldi.

## 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.

## Okumaya devam edin

-   [LLM ile Arapça metin sınıflandırma: duygu, niyet, önceliklendirme](https://broadrouter.com/tr/blog/arabic-text-classification-llm/)
-   [Açık modellerle araç çağırma: şema, paralel çağrı, yeniden deneme](https://broadrouter.com/tr/blog/tool-calling-open-models/)
-   [OpenAI uyumlu API'ye geçiş: adım adım kontrol listesi](https://broadrouter.com/tr/blog/openai-compatible-api-migration-checklist/)
-   [Ucuz LLM ile n8n AI Agent: kurulum, model seçimi ve maliyet](https://broadrouter.com/tr/blog/n8n-ai-agent-cheap-llm/)
-   [LLM'den gelen geçersiz JSON: nedenler, onarım ve yeniden deneme](https://broadrouter.com/tr/blog/fix-invalid-json-from-llm/)
-   [LLM ile Arapça varlık çıkarımı: JSON, tarihler ve denetimler](https://broadrouter.com/tr/blog/arabic-named-entity-extraction-llm/)
-   [BroadNet'in GPU donanımı ve sunum yaklaşımı, BroadNet'in anlatımıyla](https://broadrouter.com/tr/blog/broadnet-gpu-fleet-and-serving/)
-   [LLM API yanıtlarını önbelleğe alıp maliyeti düşürün: Python örneği](https://broadrouter.com/tr/blog/cache-llm-responses-cut-cost/)
-   [Rehber: OpenAI Python SDK'yı BroadNet Inference ile kullanın](https://broadrouter.com/tr/guides/openai-python-sdk/)
-   [Rehber: Arapça faturaları ve fişleri bir görü modeliyle okuyun](https://broadrouter.com/tr/guides/read-arabic-invoices-with-vision/)
-   [Rehber: Akıl yürüten model neden boş yanıt döndürür?](https://broadrouter.com/tr/guides/reasoning-tokens-empty-response/)

Gerçek iş yükünüzle deneyin. Yeni hesaplar şunlar için US$5 kredi ile başlar: Gemma ve transkripsiyon. Bakiye yüklemesi gerekenler: DeepSeek, GLM ve Qwen3.8.

[Başlayın](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=tr-blog-structured-output-json-schema&utm_content=page-cta) ·

**Kaynaklar**

-   [OpenAI, Structured Outputs rehberi (2026-11-14 tarihinde kontrol edildi)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [OpenAI API referansı, chat completion oluşturma (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Pydantic belgeleri, JSON Schema ve doğrulama](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [BroadNet Inference API referansı, modeller (İngilizce)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=tr-blog-structured-output-json-schema&utm_content=sources#models)
