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

Bu kılavuzun sonunda, kendi kodunuzdan OpenAI yapılandırılmış çıktılarını çağırabileceksiniz: modele bir JSON Şeması verecek, strict: true ayarını yapacak ve istediğiniz şekle uygun olduğu garantili bir yanıt alacaksınız. İlk isteği gönderecek, yanıtı okuyacak, uç durumları ele alacak ve Apidog'da yükün gerçekten uygun olduğunu doğrulayan API test koleksiyonları oluşturacaksınız.

button

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

Yapılandırılmış çıktılar, modelin üretimini kısıtlayarak çıktının sağladığınız bir JSON Şemasına uymasını sağlar. Bir şemayı strict: true ile geçirdiğinizde, model onu ihlal eden bir alan oluşturamaz. Her gerekli anahtar mevcuttur, her tür eşleşir ve her enum değeri listelediklerinizden biridir. Artık savunmacı ayrıştırma kodu yazmayı bırakır ve yüke güvenmeye başlarsınız.

Bu, alternatife göre gerçek bir yükseltmedir. "Yalnızca JSON ile yanıt ver" gibi serbest metin istemleri, çalışmayı bırakana kadar çalışır. Tek bir mantık sapması, nesnenizin etrafına sarılmış bir metin veya bir tamsayı beklediğiniz yerde bir tarih almanıza neden olur. Yapılandırılmış çıktılar, sözleşmeyi umutlu bir talimattan, çözme anında uygulanan bir kısıtlamaya dönüştürür.

Devam etmek için ihtiyacınız olanlar:

OPENAI_API_KEY olarak ayarlanmış bir OpenAI API anahtarı.
Katı şema uygulamasını destekleyen bir model (hangi modellerin desteklediği aşağıda daha fazla açıklanmıştır).
Geri almak istediğiniz şekli açıklayan 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 OpenAI'ın yeni modellerinde mevcuttur. OpenAI'ın belgeleri şu anda yeni projeleri en son amiral gemileri (bu yazının yazıldığı sırada gpt-5.5) üzerinde başlatmayı önermektedir. Daha eski modeller ve gpt-3.5 dönemi modelleri JSON modunu destekler ancak katı şema uygulamasını desteklemez. Eğer strict: true özelliğine bağımlıysanız, destek model sürümlerine bağlı olduğundan ve OpenAI bunları ileriye taşıdığından, ürününüzü piyasaya sürmeden önce belirli model kimliğinin bunu desteklediğini onaylayın.

Hangi özelliğe ulaşmaya çalıştığınızı bilmek önemlidir, çünkü OpenAI karıştırılması kolay iki ilgili özellik sunar.

JSON modu (response_format: { "type": "json_object" }) çıktının sözdizimsel olarak geçerli JSON olmasını garanti eder. Hepsi bu. Alanlarınızı, türlerinizi veya gerekli anahtarlarınızı bilmez. Şekli hala kendiniz doğrulamanız gerekir.

Yapılandırılmış çıktılar (type: "json_schema" ve strict: true ile response_format) çıktının geçerli JSON olmasını ve şemanızla eşleşmesini garanti eder. OpenAI, yapılandırılmış çıktıları JSON modunun evrimi olarak tanımlar: her ikisi de geçerli JSON üretir, ancak yalnızca yapılandırılmış çıktılar şema uyumunu zorlar. Yeni çalışmalar için, istediğiniz şey yapılandırılmış çıktılardır.

	JSON modu	Yapılandırılmış çıktılar (katı)
Parametre	`response_format: {"type":"json_object"}`	`type: "json_schema"`, `strict: true` ile `response_format`
Geçerli JSON	Evet	Evet
Şemanızla eşleşir	Hayır	Evet
Gerekli alanlar uygulanır	Hayır	Evet
Türler ve enum'lar uygulanır	Hayır	Evet
Akış aşağı doğrulamaya devam edersiniz	Her zaman	Önerilir (aşağıya bakınız)

API'lar hakkında bir not: Sohbet Tamamlamaları uç noktası yukarıda gösterildiği gibi response_format kullanır. Daha yeni Yanıtlar API'sı, type: "json_schema" ile text.format altında aynı şeyi ifade eder. Şema kuralları aynıdır; yalnızca sarmalayıcı farklıdır. Çağırdığınız uç noktadaki tam alan yolu için güncel belgelere bakın.

İlk İsteğinizi Yapın

Bir destek biletini tipik bir kayda dönüştürdüğünüzü varsayalım. İşte katı bir şemaya sahip bir Sohbet Tamamlamaları isteği.

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
        }
      }
    }
  }'

Yanıtı Okuyun

Model, content alanı belirtilen şemayla eşleşen bir JSON dizesi olan bir mesaj döndürür, örneğin:

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

account_id alanının null ile anyOf kullandığına dikkat edin. İsteğe bağlı bir alanı bu şekilde modelliyorsunuz, bu da kendi şemalarınızı yazarken uymanız gereken kurallara doğrudan götürüyor.

Şema Alt Kümesi İçinde Kalın

Yapılandırılmış çıktılar, JSON Şemasının bir alt kümesini kabul eder. Bu alt küme, OpenAI'ın kısıtlamaları güvenilir bir şekilde uygulayabilmesi ve derlenmiş şemayı önbelleğe alabilmesi için mevcuttur. Akılda tutulması gereken kurallar:

Kök bir nesne olmalıdır. Üst düzeyi bir dizi veya çıplak bir dize yapamazsınız. Bir listeyi bir nesne özelliği içine sarın.
Her özellik required içinde listelenmelidir. Klasik anlamda "isteğe bağlı" diye bir şey yoktur. Bir alanı null yapılabilir hale getirmek için, yukarıdaki örnekte olduğu gibi null türüyle birlikte anyOf verin.
additionalProperties her nesnede false olmalıdır. Bu, modelin fazladan anahtarlar icat etmesini engeller.
Boyut sınırları geçerlidir. Bir şema, yaklaşık 100 nesne özelliğini ve en fazla 5 düzeyde iç içe geçmişliği barındırabilir. Derinlemesine iç içe geçmiş veya yayılmış şemalar reddedilir, bu nedenle mümkün olduğunca düzleştirin.
Bazı anahtar kelimeler uygulanmaz. pattern, format, minLength ve minimum gibi yalnızca doğrulama amaçlı anahtar kelimeler model tarafından garanti edilmez. Bir düzenli ifade veya sayısal bir aralığın uygulanmasını istiyorsanız, yanıt geldikten sonra bunu yine kendiniz kontrol etmeniz gerekir.
İlk çağrı gecikmesi. Yeni bir şemayla yapılan ilk istek, derlenmesi için zaman harcar (genellikle saniyeler, bazen karmaşık şemalar için bir dakikaya kadar). Bundan sonra önbelleğe alınır ve hızlıdır.

Doğrulama anahtar kelimeleri uygulanmadığı için, "garantili JSON", "garantili iş açısından geçerli" anlamına gelmez. Yapı kilitlenmiştir. İçindeki değerler hala bir testi hak eder. Eğer oneOf/anyOf/allOf ile isteğe bağlı veya birleşik alanları hiç modellemişseniz, zihinsel model tanıdıktır: bir şema şekli kısıtlar, ancak gerçek değerleri ayrı ayrı doğrulamanız gerekir.

Reddedilmeleri ve Kırpılmaları Yönetin

Çıktının şemanızla bilerek eşleşmeyeceği bir durum vardır. Model güvenli olmayan bir isteği reddederse, şema şekilli içerik yerine mesajda bir refusal alanı döndürür. Kodunuzun ayrıştırmadan önce bu durumu ele alması gerekir:

msg = response.choices[0].message
if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)

Reddedilmeler artık programatik olarak tespit edilebilir, bu da metni bir özür için taramaktan daha temizdir. Bir yanıtın şemadan yetersiz kalmasının diğer iki yolu: nesnenin ortasında max_tokens sınırına ulaşmak (JSON kırpılır) veya yapılandırılmış çıktıların desteklemediği paralel araç çağrıları kullanmak. İkisini birleştirdiğinizde parallel_tool_calls değerini false olarak ayarlayın.

Apidog'da Nasıl Test Edilir

Katı mod, şemayı üretim zamanında uygular. Bu sizi test etmekten kurtarmaz. Modeller değiştirilir, şemalar değişir, bir ekip arkadaşı required dizisini düzenler veya bir ret yolu değişir. Yanıt sözleşmeyle eşleşmeyi bıraktığında yüksek sesle başarısız olan bir test istersiniz. İşte Apidog burada devreye girer.

İş bölümünü kesinleştirmek gerekirse: OpenAI'ın katı modu, şema-geçerli JSON üreten şeydir. Apidog, şemayı modelde uygulamaz. Apidog'un yaptığı şey, geri aldığınız yanıtı beklediğiniz şemaya göre doğrulamaktır, böylece üretimde değil, CI'da sapmaları yakalarsınız.

İşte iş akışı:

İsteği gönderin. Apidog'da response_format bloğunuzla Sohbet Tamamlamaları çağrısını oluşturun. Tekrarlanabilir olması için bir koleksiyona kaydedin.
Şekli doğrulayın. Apidog'da yanıt doğrulamaları ekleyin. category'nin enum değerlerinizden biri olduğunu, severity'nin bir tamsayı olduğunu, account_id'nin bir dize veya null olduğunu kontrol edin. Apidog, yanıtı JSON Şemasına göre doğrulayabilir, böylece tam şemayı eklersiniz ve yük saptığında çalıştırmayı başarısız kılarsınız.
CI'da çalıştırın. Her model veya istem değişikliğinin uygunluğu yeniden kontrol etmesi için koleksiyonu ardışık düzeninize yerleştirin. Sessiz bir şema bozulması, kırmızı bir yapı haline gelir.
Sözleşmeyi taklit edin. Gerçek çağrı mevcut olmadan veya jeton harcamadan aşağı akış tüketicilerini test etmek için, şema-geçerli örnek yanıtlar döndüren bir taklit API kurun. Entegrasyon sağlamlaşırken ön uçunuz ve testleriniz sabit bir şekle göre çalışır.

Bu son nokta, değeri bilinmeyendir. Yapılandırılmış çıktıyı tüketen her şeyi, aynı şemayı onurlandıran bir taklide karşı geliştirebilir ve test edebilir, ardından hazır olduğunuzda canlı OpenAI çağrısını değiştirebilirsiniz. Apidog'u indirin ve isteği, doğrulamaları ve taklidi tek bir yerde oluşturabilirsiniz.

Sıkça Sorulan Sorular

Yapılandırılmış çıktılar varken JSON modu artık kullanılmıyor mu? JSON modu hala çalışır ve hala geçerli JSON'u garanti eder. Sadece bir şemayı uygulamaz. Yeni kodlar için, strict: true ile yapılandırılmış çıktılar daha güçlü bir seçimdir. Yalnızca katı şemaları desteklemeyen modellerde veya gerçekten sabit bir şekliniz olmadığında düz JSON moduna başvurun.
Şemamın kökü bir dizi olabilir mi? Hayır. En üst düzey bir nesne olmalıdır. Listenizi { "items": [...] } gibi bir özellik içine sarın ve items'ı required içine koyun. Bu, birçok kişiyi ilk günden şaşırtır.
Bir alanı nasıl isteğe bağlı yapabilirim? Yapılandırılmış çıktılar, her özelliğin required içinde olmasını gerektirir, bu nedenle klasik bir isteğe bağlı alan yoktur. "Eksik" olanı null yapılabilir olarak modelleyin: string (veya herhangi bir tür) ve null ile birlikte anyOf kullanın. Anahtar her zaman mevcuttur; değeri null olabilir.
Katı mod, doğrulamayı tamamen atlayabileceğim anlamına mı geliyor? Yapı garantilidir, bu nedenle şekil kontrollerini atlayabilirsiniz. Ancak pattern, format gibi anahtar kelimeler ve sayısal aralıklar model tarafından uygulanmaz ve reddedilmeler veya kırpılmalar yine de belirtilmeyen yanıtlar üretebilir. Uygunluk testi hala değerlidir. Bu formata yeni başlıyorsanız, bu JSON Şeması başlangıç rehberi yapı taşlarını kapsar ve kontrolü her dağıtımda çalıştırabilirsiniz.
Hangi modelleri kullanmalıyım? Yapılandırılmış çıktılar, GPT-5 serisi de dahil olmak üzere GPT-4o ve sonrasındaki modellerde çalışır. OpenAI'ın belgeleri yeni projeleri mevcut amiral gemilerine yönlendirir. Destek model sürümlerini takip ettiğinden, ona güvenmeden önce tam model kimliğinin katı modu desteklediğini onaylayın.

Özet

Artık tam döngüye sahipsiniz: katı modu destekleyen bir model seçin, json_schema ve strict: true ile bir Sohbet Tamamlamaları isteği gönderin, şemanızı desteklenen alt küme içinde tutun, refusal üzerinde dallanın ve değer düzeyindeki kuralların hala kontrol edilmesi gerektiğini unutmayın. Ardından bunu bir testle kanıtlayın: isteği Apidog'da oluşturun, yanıtı şemanıza göre doğrulayın ve entegrasyon yerleşirken yığınınızın geri kalanının ilerleyebilmesi için onu taklit edin. Model şekli vaat ediyor. Testleriniz ise öyle kaldığını kanıtlıyor.

button