BroadRouter
Başlayın

Yapılandırılmış çıktı (structured output)

Güncellendi

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.

Diğer adları: yapılandırılmış çıktı, yapılandırılmış çıkış, JSON şeması çıktısı, JSON modu, structured output, structured outputs, JSON schema output, response_format

Kod öngörülebilir girdiye ihtiyaç duyar. Yapılandırılmış çıktı, bir modelin serbest metnini programınızın güvenebileceği veriye dönüştürür.

Nasıl çalışır

Üç kontrol düzeyi vardır:

Yöntem Ne elde edersiniz
İstemde rica etmek Genellikle JSON; bazen fazladan metin veya eksik alanlarla
JSON modu Geçerli JSON, herhangi bir yapıda
Şemalı yapılandırılmış çıktı Şemanıza uyan JSON

OpenAI biçiminde JSON modu response_format: {"type": "json_object"} şeklindedir. Yapılandırılmış çıktı ise bir şema verir:

"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "invoice",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total": { "type": "number" }
      },
      "required": ["vendor", "total"],
      "additionalProperties": false
    }
  }
}

OpenAI’nin referansı, json_schema türünün “ensures the model will match your supplied JSON schema” (çeviri: modelin verdiğiniz JSON şemasına uymasını sağladığını) söyler. Birçok sağlayıcı bunu kısıtlı kod çözme (constrained decoding) ile yapar: modelin her adımda üretebileceği token’ları sınırlar, böylece şemayı bozan çıktı üretilemez.

Neden önemli

  • Daha az ayrıştırma hatası. Bilgi çıkarma hatları, sınıflandırıcılar ve ajanlar alanları doğrudan okuyabilir.
  • Daha basit istemler. Şema, uzun biçim talimatlarının yerini alır.
  • Tam bir garanti değil. OpenAI’nin rehberi uygulamanızın retleri, eksik yanıtları ve hataları yine de ele alması gerektiğini söyler. max_tokens nedeniyle kesilmiş bir yanıt, şema ne derse desin bozuk JSON’dur.

Destek OpenAI uyumlu API’ler arasında farklılık gösterir. Bazıları yalnızca json_schema, bazıları yalnızca json_object kabul eder, bazıları ise alanı yok sayar. Ona güvenmeden önce kontrol edin.

BroadNet Inference’ta

BroadNet’in belgeleri GLM 5.3 ve Qwen3.8 27B için yapılandırılmış çıktıyı listeler. Belgeler istek parametresinin adını vermez; bu yüzden response_format alanını modelinizde test edin ve her durumda hata yönetimi olan bir JSON ayrıştırıcısı kullanın. LLM JSON çıktı doğrulayıcısı yanıtın nerede bozulduğunu gösterir ve onu şemanıza göre kontrol eder. İki model de önce akıl yürütür; bu yüzden max_tokens değerinde düşünme artı JSON için pay bırakın.

Yapılandırılmış çıktı görsel modelleriyle iyi bir ikili oluşturur. Arapça fatura rehberi bir görsel gönderir ve alanları JSON olarak ister. Yanıt yerine eylem istiyorsanız araç çağırmayı kullanın.

Sık yapılan hatalar

  • Strict modu kullanırken additionalProperties: false eklemeyi ya da her alanı required içinde listelemeyi unutmak.
  • Ayrıştırmadan önce finish_reason değerini kontrol etmemek.

Sık sorulan sorular

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

JSON modu yalnızca yanıtın JSON olarak ayrıştırılabileceğini taahhüt eder. Şemalı yapılandırılmış çıktı ise tanımladığınız alanları, türleri ve zorunlu anahtarları da taahhüt eder. OpenAI'nin rehberine göre şemaya uyumu yalnızca Structured Outputs sağlar.

Çıktıyı yine de doğrulamam gerekir mi?

Evet. Yanıt yine bir ret olabilir veya max_tokens nedeniyle kesilebilir; ayrıca bir şema, kalem tutarlarının toplamına eşit olması gereken bir toplam gibi her iş kuralını ifade edemez.

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

Nihai yanıtı sabit bir yapıda istiyorsanız yapılandırılmış çıktı kullanın. Modelin kodunuzdan bir şey yapmasını isteyip ardından devam etmesi gerekiyorsa araç çağırma (tool calling) kullanın.

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