DEV Community

Cover image for OpenAI Yapılandırılmış Çıktıları Nasıl Kullanılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

OpenAI Yapılandırılmış Çıktıları Nasıl Kullanılır

Bu kılavuzda OpenAI yapılandırılmış çıktılarını kendi kodunuzdan nasıl çağıracağınızı adım adım uygulayacaksınız: modele JSON Şeması verecek, strict: true ayarını kullanacak, beklediğiniz şekle uyan yanıtı ayrıştıracak, ret ve kırpılma gibi uç durumları yönetecek ve Apidog’da yanıtın gerçekten şemaya uyduğunu doğrulayan API test koleksiyonları oluşturacaksınız.

Apidog'u bugün deneyin

Başlamadan Önce İhtiyaç Duyduklarınız

Yapılandırılmış çıktılar, model yanıtını verdiğiniz JSON Şemasına göre kısıtlar. Şemayı strict: true ile gönderdiğinizde model, şemaya aykırı alan üretemez: gerekli anahtarlar bulunur, türler eşleşir ve enum değerleri tanımladığınız listeden gelir.

Bu yaklaşım, “yalnızca JSON döndür” gibi serbest metin istemlerinden daha güvenilirdir. JSON modu geçerli JSON üretebilir; ancak alan adlarını, zorunlu alanları veya enum değerlerini garanti etmez. Yapılandırılmış çıktılar ise sözleşmeyi model çıktısı üretilirken uygular.

Devam etmek için şunlara ihtiyacınız var:

  • OPENAI_API_KEY olarak ayarlanmış bir OpenAI API anahtarı.
  • Katı şema uygulamasını destekleyen bir model.
  • Döndürmek istediğiniz yanıt şeklini tanımlayan bir JSON Şeması.

Doğru Modeli Seçin

Yapılandırılmış çıktılar, GPT-4o ailesiyle başlayıp GPT-5 serisiyle devam eden yeni OpenAI modellerinde kullanılabilir. OpenAI belgeleri, yeni projeler için güncel amiral gemisi modellerin kullanılmasını önerir. Bu yazının yazıldığı sırada örneklerde gpt-5.5 kullanılmıştır.

Daha eski modeller ve gpt-3.5 dönemi modelleri JSON modunu destekleyebilir; ancak katı şema uygulamasını desteklemez. strict: true davranışına güveniyorsanız, üretime çıkmadan önce kullandığınız tam model kimliğinin yapılandırılmış çıktıları desteklediğini doğrulayın.

OpenAI tarafında karıştırılması kolay iki özellik vardır:

Özellik JSON modu Yapılandırılmış çıktılar
Parametre response_format: {"type":"json_object"} response_format içinde type: "json_schema" ve strict: true
Geçerli JSON üretir Evet Evet
Şemanızla eşleşir Hayır Evet
Gerekli alanları uygular Hayır Evet
Tür ve enum kontrolü yapar Hayır Evet
Akış aşağı doğrulama gerekir mi? Her zaman Önerilir

Kısaca:

  • JSON modu, yalnızca çıktının sözdizimsel olarak geçerli JSON olmasını sağlar.
  • Yapılandırılmış çıktılar, çıktının hem geçerli JSON olmasını hem de verdiğiniz şemayla eşleşmesini sağlar.

Yeni geliştirmelerde sabit bir yanıt sözleşmesine ihtiyacınız varsa json_schema + strict: true kullanın.

Not: Sohbet Tamamlamaları API’sı response_format kullanır. Daha yeni Responses API’sında aynı yapı text.format altında ifade edilir. Şema kuralları aynıdır; yalnızca alan yolu farklıdır.

İlk İsteğinizi Gönderin

Aşağıdaki örnekte bir destek mesajını yapılandırılmış bir destek bileti kaydına dönüştürüyoruz.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "Extract the ticket into the schema."
      },
      {
        "role": "user",
        "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary": {
              "type": "string"
            },
            "category": {
              "type": "string",
              "enum": ["billing", "bug", "account", "other"]
            },
            "severity": {
              "type": "integer"
            },
            "account_id": {
              "anyOf": [
                { "type": "string" },
                { "type": "null" }
              ]
            }
          },
          "required": [
            "summary",
            "category",
            "severity",
            "account_id"
          ],
          "additionalProperties": false
        }
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Bu istekte kritik noktalar şunlar:

  • response_format.type değeri json_schema.
  • json_schema.strict değeri true.
  • Kök şema bir object.
  • Tüm alanlar required içinde.
  • Nesnede additionalProperties: false kullanılıyor.
  • “Opsiyonel” alan için anahtar kaldırılmıyor; değer null olabilir şekilde modelleniyor.

Yanıtı Ayrıştırın

Modelin döndürdüğü mesajın content alanı, şemanızla eşleşen bir JSON dizesidir.

Örnek yanıt:

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}
Enter fullscreen mode Exit fullscreen mode

Python tarafında temel ayrıştırma şu şekilde olabilir:

import json

msg = response.choices[0].message
ticket = json.loads(msg.content)

print(ticket["summary"])
print(ticket["category"])
print(ticket["severity"])
print(ticket["account_id"])
Enter fullscreen mode Exit fullscreen mode

account_id alanı için anyOf kullanıldığına dikkat edin:

"account_id": {
  "anyOf": [
    { "type": "string" },
    { "type": "null" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Yapılandırılmış çıktılarda klasik anlamda “alan yoksa opsiyonel” yaklaşımı yerine, alanı her zaman döndürüp değeri null yapabilirsiniz.

Şemanızı Desteklenen Alt Kümede Tutun

Yapılandırılmış çıktılar, JSON Şemasının tamamını değil, bir alt kümesini destekler. Bunun nedeni OpenAI’ın şemayı güvenilir şekilde uygulayabilmesi ve derlenmiş şemayı önbelleğe alabilmesidir.

Uygulamada şu kurallara dikkat edin:

1. Kök her zaman nesne olmalı

Geçersiz:

{
  "type": "array",
  "items": {
    "type": "string"
  }
}
Enter fullscreen mode Exit fullscreen mode

Geçerli yaklaşım:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

2. Her özellik required içinde olmalı

Yapılandırılmış çıktılarda klasik opsiyonel alan mantığı yoktur. Bir alan boş kalabiliyorsa null ile modelleyin.

{
  "type": "object",
  "properties": {
    "email": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  },
  "required": ["email"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

3. Her nesnede additionalProperties: false kullanın

Bu, modelin beklenmeyen alanlar üretmesini engeller.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["open", "closed"]
    }
  },
  "required": ["status"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

4. Şemayı fazla derinleştirmeyin

Yaklaşık sınırlar:

  • En fazla 100 nesne özelliği.
  • En fazla 5 seviye iç içe yapı.

Çok derin veya çok geniş şemalar reddedilebilir. Mümkün olduğunda düzleştirilmiş alanlar kullanın.

5. Bazı doğrulama anahtar kelimeleri garanti edilmez

Aşağıdaki gibi yalnızca doğrulama amaçlı anahtar kelimeler model tarafından garanti edilmeyebilir:

  • pattern
  • format
  • minLength
  • minimum
  • maximum

Örneğin email alanına format: "email" koymak, modelin her zaman geçerli e-posta döndüreceği anlamına gelmez. Bu tür değer düzeyi kontrolleri için yanıt geldikten sonra kendi doğrulamanızı çalıştırın.

Eğer daha önce oneOf/anyOf/allOf ile isteğe bağlı veya birleşik alanları modellediyseniz, yaklaşım benzerdir: şema yapıyı sınırlar; iş kurallarını ayrıca doğrularsınız.

Retleri ve Kırpılmaları Yönetin

Yapılandırılmış çıktılar, güvenli olmayan isteklerde her zaman şemaya uygun içerik döndürmez. Model isteği reddederse mesajda şema içeriği yerine refusal alanı bulunabilir.

Bu yüzden ayrıştırmadan önce ret durumunu kontrol edin:

import json

msg = response.choices[0].message

if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)
    process_ticket(ticket)
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, yanıt metninde “üzgünüm” gibi ifadeleri aramaktan daha güvenilirdir.

Şemaya uygun yanıt alamayabileceğiniz diğer durumlar:

  1. max_tokens sınırına ulaşılması

    Yanıt nesnenin ortasında kesilebilir ve JSON kırpılabilir.

  2. Paralel tool call kullanımı

    Yapılandırılmış çıktılarla birlikte paralel araç çağrıları kullanıyorsanız parallel_tool_calls değerini false yapın.

Örnek:

{
  "parallel_tool_calls": false
}
Enter fullscreen mode Exit fullscreen mode

Apidog’da Nasıl Test Edilir

Katı mod, model üretimi sırasında şemayı uygular. Ancak bu, test ihtiyacını ortadan kaldırmaz.

Şu durumlarda yanıt sözleşmeniz bozulabilir:

  • Model kimliği değişir.
  • Prompt değişir.
  • Şemadaki required alanları düzenlenir.
  • Ret veya hata akışı farklılaşır.
  • Akış aşağı servisler farklı bir şekil beklemeye başlar.

Bu yüzden yanıtın şemaya uyduğunu CI’da doğrulayan bir test koleksiyonu çalıştırmak iyi bir güvenlik ağıdır. Burada Apidog kullanabilirsiniz.

Apidog ekran görüntüsü

Önemli ayrım:

  • OpenAI strict: true, model çıktısının şemaya uygun üretilmesini sağlar.
  • Apidog, dönen yanıtı beklediğiniz şemaya göre doğrular.
  • Böylece sapmaları üretimde değil, test veya CI aşamasında yakalarsınız.

1. OpenAI isteğini Apidog’da oluşturun

Apidog’da yeni bir istek oluşturun:

  • Method: POST
  • URL: https://api.openai.com/v1/chat/completions
  • Header:
    • Authorization: Bearer {{OPENAI_API_KEY}}
    • Content-Type: application/json

Body kısmına response_format içeren isteğinizi ekleyin.

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "Extract the ticket into the schema."
    },
    {
      "role": "user",
      "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "category": {
            "type": "string",
            "enum": ["billing", "bug", "account", "other"]
          },
          "severity": { "type": "integer" },
          "account_id": {
            "anyOf": [
              { "type": "string" },
              { "type": "null" }
            ]
          }
        },
        "required": ["summary", "category", "severity", "account_id"],
        "additionalProperties": false
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

İsteği bir koleksiyona kaydedin. Böylece aynı çağrıyı tekrar çalıştırabilir ve CI’a taşıyabilirsiniz.

2. Yanıt şemasını doğrulayın

Apidog’da yanıt doğrulamaları ekleyin:

  • category, billing | bug | account | other değerlerinden biri mi?
  • severity integer mı?
  • account_id string veya null mı?
  • Beklenmeyen ek alan var mı?
  • Tüm required alanları dönüyor mu?

Apidog, yanıtı JSON Şemasına göre doğrulayabilir. Aynı şemayı test doğrulamasına ekleyerek yanıt saptığında çalıştırmayı başarısız hale getirebilirsiniz.

3. Koleksiyonu CI’da çalıştırın

Koleksiyonu pipeline’a ekleyin. Böylece her prompt, model veya şema değişikliğinde sözleşme tekrar kontrol edilir.

Hedef davranış:

  • Şema uyuyorsa build geçer.
  • Yanıt eksik, hatalı tipte veya beklenmeyen alana sahipse build kırılır.

Bu, sessiz şema bozulmalarını erken yakalamanızı sağlar.

4. Şema-geçerli mock API oluşturun

Gerçek OpenAI çağrısını beklemeden veya token harcamadan akış aşağı servisleri geliştirmek için mock API oluşturabilirsiniz.

Örneğin frontend ekibi şu örnek yanıtla çalışabilir:

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım özellikle entegrasyon sırasında faydalıdır:

  • Frontend sabit bir sözleşmeye göre geliştirilir.
  • Backend gerçek OpenAI çağrısını daha sonra bağlayabilir.
  • Testler gerçek model çağrısından bağımsız çalışır.
  • Aynı şema hem gerçek çağrıda hem mock yanıtta referans alınır.

Apidog’u indirin ve isteği, doğrulamaları ve mock API’yi tek bir yerde yönetin.

Sıkça Sorulan Sorular

Yapılandırılmış çıktılar varken JSON modu artık kullanılmıyor mu?

Hayır. JSON modu hâlâ çalışır ve geçerli JSON üretmeyi garanti eder. Ancak şema uygulamaz.

Yeni kodlarda sabit bir yanıt şekline ihtiyacınız varsa strict: true ile yapılandırılmış çıktılar daha güçlü bir seçenektir. JSON modunu, katı şema desteklemeyen modellerde veya sabit bir şekle ihtiyacınız olmayan durumlarda kullanın.

Şemamın kökü bir dizi olabilir mi?

Hayır. En üst düzey yapı nesne olmalıdır.

Bunun yerine listeyi bir nesne alanına sarın:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

Bir alanı nasıl isteğe bağlı yapabilirim?

Yapılandırılmış çıktılar her özelliğin required içinde olmasını bekler. Bu yüzden klasik “alan hiç gelmeyebilir” yaklaşımı yerine null kullanın.

{
  "type": "object",
  "properties": {
    "phone": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  },
  "required": ["phone"],
  "additionalProperties": false
}
Enter fullscreen mode Exit fullscreen mode

Anahtar her zaman gelir; ancak değeri null olabilir.

Katı mod kullanıyorsam doğrulamayı tamamen atlayabilir miyim?

Yapı düzeyi büyük ölçüde garanti altındadır; ancak iş kuralları için doğrulama hâlâ gereklidir.

Örneğin:

  • format: "email" her zaman geçerli e-posta anlamına gelmeyebilir.
  • pattern gibi kurallar garanti edilmeyebilir.
  • Sayısal aralıklar ayrıca kontrol edilmelidir.
  • Ret ve kırpılma durumları şema dışı akış üretebilir.

JSON Şeması konusunda yeniyseniz, JSON Şeması başlangıç rehberi temel yapı taşlarını anlamanıza yardımcı olur.

Hangi modelleri kullanmalıyım?

Yapılandırılmış çıktılar GPT-4o ve sonrası modellerde, GPT-5 serisi dahil olmak üzere kullanılabilir. OpenAI belgeleri yeni projeler için güncel amiral gemisi modelleri önerir.

Ancak destek model sürümlerine bağlıdır. Üretime geçmeden önce kullandığınız tam model kimliğinin strict: true ile yapılandırılmış çıktıları desteklediğini doğrulayın.

Özet

Uygulama akışı şu şekilde:

  1. Katı şema uygulamasını destekleyen bir model seçin.
  2. response_format içinde type: "json_schema" kullanın.
  3. strict: true ayarını etkinleştirin.
  4. Kök şemayı nesne olarak tasarlayın.
  5. Tüm alanları required içine alın.
  6. Opsiyonel değerleri null ile modelleyin.
  7. Her nesnede additionalProperties: false kullanın.
  8. refusal ve kırpılma durumlarını ayrıştırmadan önce yönetin.
  9. Değer düzeyi iş kurallarını ayrıca doğrulayın.
  10. Yanıt sözleşmesini Apidog ile test ve CI sürecine ekleyin.

Model, yanıtın şeklini vaat eder. Testleriniz ise bu sözleşmenin zaman içinde bozulmadığını kanıtlar.

Top comments (0)