Yapılandırılmış LLM Çıktılarını OpenAI, Anthropic ve Gemini Genelinde Taşınabilir Hale Getirme

Ekipler sağlayıcı desteğini birbirinin yerine kullanılabilir olarak değerlendirdiğinde, yapılandırılmış LLM çıktıları kırılgan hale gelir. OpenAI, Anthropic ve Gemini'nin tümü yapılandırılmış veri üretebilir ancak aynı sözleşmeyi sunmazlar. Şema sözdizimi, araç çağrısı zarfları, kesinlik garantileri, reddetme davranışı, akış davranışı ve doğrulama hatası modları, bir modelle çalışan bir ayrıştırıcının diğer modelde sessizce başarısız olmasına yetecek kadar farklılık gösterir.

Pratik çözüm, sağlayıcıya özel yapılandırılmış çıktı özelliklerini iş sözleşmesi olarak ele almayı bırakmaktır. Her iş akışı için bir kanonik çıktı sözleşmesi tanımlayın, bunu her sağlayıcının desteklenen istek biçiminde derleyin, her yanıtı kanonik şemaya göre doğrulayın ve her modeli, üretim trafiğine hizmet etmesine izin verilmeden önce test edin.

Taşınabilir Yapılandırılmış Çıktı Nedir?

Taşınabilir yapılandırılmış çıktı, temel model sağlayıcı değişse bile uygulamanın aynı iş düzeyindeki yanıt şekline güvenebileceği anlamına gelir. Bu, her sağlayıcının tamamen aynı JSON Şemasını alacağı anlamına gelmez. Bu aynı zamanda sağlayıcı tarafı doğrulamanın yeterli olduğu anlamına da gelmez.

Taşınabilir bir sözleşmenin beş katmanı vardır:

• Kanonik şema: iş akışının sağlayıcıdan bağımsız veri şekli.
• Taşınabilirlik astarı: şemanın, sağlayıcılar arasında desteklenmeyen, zayıf şekilde uygulanan veya riskli yapılardan kaçınıp kaçınmadığını kontrol eder.
• Sağlayıcı derlemesi: standart sözleşmeden OpenAI, Anthropic, Gemini'ye veya başka bir sağlayıcının yerel yapılandırılmış çıktı yüzeyine çeviri.
• Çalışma zamanı doğrulaması: döndürülen nesnenin standart şemaya göre uygulama tarafı doğrulaması.
• Sözleşme testleri: her modelin üretim yönlendirmesi değişikliklerinden önce gerekli alanları, numaralandırmaları, retleri, kesmeyi, hatalı biçimlendirilmiş istekleri ve anlamsal uç durumları ele aldığını kanıtlayan tekrarlanabilir testler.

Bu model, birden fazla ekibin, kiracının veya iş ortağı iş akışının öngörülebilir çıktı sözleşmelerine bağlı olduğu kurumsal LLM API için özellikle önemlidir.

Gerçekler: Sağlayıcının Yapılandırılmış Çıktısı Tek Bir Standart Değil

Taşınabilirlik katmanını tasarlamadan önce, belgelenmiş sağlayıcı davranışını varsayımlardan ayırın.

OpenAI

OpenAI, JSON modundan farklı olarak Yapılandırılmış Çıktıları belgeler. JSON modunun geçerli JSON olmasını sağlaması amaçlanırken, Yapılandırılmış Çıkışların sağlanan JSON Şeması ile eşleşmesi amaçlanır. OpenAI, yanıt biçimlendirmesi ve katı şema uyumuyla işlev çağrısı aracılığıyla yapılandırılmış çıktıyı destekler, ancak belgelenen davranış, model ve sürüm kısıtlamalarını ve desteklenen bir şema alt kümesini içerir. Katı modda desteklenmeyen şemalar API hata üretebilir ve uygulamaların yine de uç durumları ele alması gerekir.

Anthropic

Anthropic, geliştirici tarafından sağlanan araçları temel alan yapılandırılmış araç çağrıları olarak Claude aracının kullanımını input_schema ile belgeliyor. Model tool_use bloğunu döndürür ve uygulama istenen aracı çalıştırır. Bu, işlev çağrısına benzer, ancak OpenAI yanıt biçimi JSON şema yanıtıyla aynı sözleşme değildir. Anthropic'nin mühendislik kılavuzu ayrıca JSON Şemasının yapıyı, gerekli alanları ve numaralandırmaları tanımlayabildiğini ancak isteğe bağlı parametrelerin ne zaman dahil edilmesi gerektiği veya hangi alan birleşimlerinin iş açısından anlamlı olduğu gibi kullanım kalıplarını ifade edemediğini belirtir.

Gemini

Google'in Gemini API belgeleri, yapılandırılmış çıkışın JSON yanıtları için yapılandırılabileceğini ve Gemini yapılandırılmış çıkış modunun JSON Şema spesifikasyonunun bir alt kümesini desteklediğini söylüyor. Bu önemlidir çünkü geçerli JSON Şeması olan bir şema, taşınabilir sağlayıcı istek şeması olarak hâlâ uygun olmayabilir.

Gözlemlenebilirlik

OpenTelemetry GenAI anlam kuralları; sağlayıcı, istenen model, yanıt modeli, çıktı türü, bitiş nedenleri, belirteç kullanımı, araç tanımları, araç çağrısı bağımsız değişkenleri ve ilgili GenAI istek ve yanıt alanlarına ilişkin öznitelikleri içerir. Bu alanlar, yapılandırılmış çıktı hatalarının bilgi istemi, şema, model veya sağlayıcı sorunlarından ayırt edilmesi zor olduğunda sağlayıcılar arası hata ayıklamayı destekleyebilir.

1. Adım: Kanonik İş Şemasını Tanımlayın

Sağlayıcıyla değil iş akışıyla başlayın API. Destek önceliklendirme iş akışı, fatura çıkarma iş akışı, onay önerisi veya iş ortağına yönelik otomasyon uç noktalarının her biri, uygulamanın aşağı yönde neye ihtiyaç duyduğunu temsil eden standart bir şemaya sahip olmalıdır.

Örneğin, bir destek önceliklendirme iş akışı şu standart şekli kullanabilir:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "requires_human_review"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "security", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "requires_human_review": {
      "type": "boolean"
    },
    "customer_risk_signals": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  }
}

Bu şema, uygulamanın geri kalanının güvendiği sözleşmedir. Sağlayıcıya özel istek formatları bundan oluşturulur; onlar gerçeğin kaynağı değiller.

Açıkça zorunlu alanları, sınırlı dizileri, sınırlı dizeleri, kapalı numaralandırmaları ve doğrulayıcınızın desteklediği additionalProperties: false kullanın. Aşağı akış sistemi rastgele anahtarları işleyecek şekilde tasarlanmadığı sürece, rastgele iç içe yerleştirilmiş nesneleri kabul etmekten kaçının.

2. Adım: Şema Taşınabilirliği Tüysüzleştirme Adımı Ekle

Taşınabilirlik linter'ı, teknik olarak geçerli JSON Şema olan ancak çoklu model kullanımı açısından riskli olan şemaları reddetmelidir. Amaç tam JSON Şema ifadesi değildir. Amaç, uygulama garantisini zayıflatmadan çeşitli sağlayıcı yüzeylerinde derlenebilecek istikrarlı bir çıktı sözleşmesidir.

Yararlı tüy bırakma kontrolleri şunları içerir:

• Derleyiciniz onlar için açık sağlayıcı eşlemelerine sahip olmadığı sürece, desteklenmeyen kompozisyon anahtar kelimelerini reddedin.
• Rastgele özelliklere izin veren kısıtlanmamış object alanları reddedin.
• Yönlendirmeyi, faturalandırmayı, onayları veya iş ortağı tarafından görülebilir durumu yönlendiren sınıflandırma alanları için numaralandırma yapılmasını zorunlu kılın.
• Otomasyon veya kullanıcı arayüzü görüntülemede kullanılan diziler için maxItems kodunu zorunlu tutun.
• Veritabanlarına, kuyruklara veya iş ortağı API'lerine giren metin alanları için maxLength kodunu zorunlu kılın.
• Yokluğu iş anlamını değiştiren isteğe bağlı alanları işaretleyin.
• İç içe yerleştirilmesi veya boyutu, yetenek matrisinizde bilinen sağlayıcı sınırlarını aşan şemaları reddedin.

Linter CI'da ve şema dağıtımından önce çalışmalıdır. Bir şema anahtar kelimesi desteklenmediği için üretim isteğinin sağlayıcı hatasıyla karşılaşmasını beklemeyin.

3. Adım: Sağlayıcıya Özel İstek Formatlarında Derleyin

Sağlayıcı derlemesi, kanonik şemayı her modelin gerçekte desteklediği API yüzeyine çevirir. Derleyici deterministik ve versiyonlu olmalıdır. Ayrıca hangi standart şema sürümünün, hangi sağlayıcının istek yükünü ürettiğini gösteren bir denetim izi de bırakmalıdır.

OpenAI derleme

OpenAI için derleyici, çıkarma ve sınıflandırma görevleri için yanıt biçimlendirmesi veya eylem odaklı iş akışları için katı işlev çağrısı yoluyla Yapılandırılmış Çıkışları hedefleyebilir. Derlenen veri, şemanın desteklenen alt kümesini ve mümkün olduğunda sağlayıcıya özgü katılık ayarlarını içermelidir.

Anthropic derleme

Anthropic için derleyici genellikle istenen çıktıyı input_schema işaretiyle bir araç olarak temsil eder. Uygulama daha sonra bir araç kullanım bloğu bekler ve araç girişini kanonik şemaya göre doğrular. Bu, bağdaştırıcının yalnızca JSON.

Gemini derleme

Gemini için derleyici, yalnızca desteklenen şema alt kümesini kullanarak yapılandırılmış JSON yanıt yapılandırmasını hedeflemelidir. Kurallı bir şema Gemini'nin yerel olarak uygulamaya koymadığı kısıtlamalar kullanıyorsa, derleyicinin bu kısıtlamaları uygulama tarafı doğrulaması gerektirdiğini kaydetmesi gerekir.

Bağdaştırıcı çıktısı tek bir dahili sonuç türüne göre normalleştirilmelidir:

type StructuredResult = {
  provider: "openai" | "anthropic" | "gemini";
  model: string;
  schema_version: string;
  status: "ok" | "refusal" | "truncated" | "provider_error" | "invalid";
  raw_response: unknown;
  parsed_output?: unknown;
  finish_reason?: string;
};

Bu normalleştirme, aşağı akış iş akışı kodunun sağlayıcı zarflarına bağlı olmasını engeller.

4. Adım: Her Yanıtı Kanonik Şemaya Göre Doğrulayın

Sağlayıcı tarafı yapısı, son doğruluk kontrolü değil, ilk savunma hattıdır. Model yanıt verdikten sonra ayrıştırılan çıktıyı her zaman standart şemaya göre doğrulayın.

Çalışma zamanı doğrulaması aşağıdaki gibi yapısal hatalar üretmelidir:

• missing_required_field
• invalid_enum
• unexpected_property
• type_mismatch
• array_too_long
• string_too_long
• semantic_rule_failed

Yapısal doğrulamayı anlamsal doğrulamadan ayrı tutun. JSON Şema şekli, gerekli özellikleri, numaralandırmaları ve temel tür kısıtlamalarını kontrol edebilir. Geçerli durum geçişleri, onay eşikleri, müşteriye özel politika veya karşılıklı bağımlı alan kombinasyonları gibi iş kurallarını tam olarak ifade edemez.

Örneğin, bu bir semantik doğrulayıcıdır, şema kuralı değil:

if (output.priority === "urgent" && output.requires_human_review !== true) {
  throw new SemanticValidationError(
    "urgent tickets must require human review"
  );
}

Bu kontrolleri müşteri yapılandırmasını, iş akışı durumunu, yetkilendirme bağlamını ve politika sürümü oluşturmayı kullanabilecekleri uygulama koduna yerleştirin.

5. Adım: Sınırlı Onarımı Kullanın, Ardından Başarısız Bir Şekilde Kapatın

Onarım yolu küçük çıktı hatalarını düzeltebilir, ancak aynı zamanda sistematik şemayı ve istem sorunlarını da gizleyebilir. Doğrulama hatası dahil olmak üzere hedefli bir onarım denemesi kullanın. Onarılan yanıt hâlâ doğrulamada başarısız oluyorsa başarısız olun veya incelemeye yönlendirin.

Pratik bir onarım politikası şuna benzer:

• Yalnızca eksik zorunlu alanlar, geçersiz numaralandırmalar veya hatalı biçimlendirilmiş JSON.
gibi uygun hata türleri için onarım yapmayı deneyin.
• Sağlayıcı retlerini, güvenlik engellemelerini, yetkilendirme hatalarını veya politikaya duyarlı çıktıları onarmayın.
• Onarım istemine standart şema sürümünü ve doğrulama hatasını ekleyin.
• Müşterinin görebileceği veya eylemi tetikleyen iş akışları için en fazla bir onarım girişimine izin verin.
• Onarım sayısını, onarım başarısını, jeton kullanımını ve son durumu günlüğe kaydedin.

Düşük riskli dahili çıkarma işleri için, gecikme önemli değilse ikinci bir onarım girişimi kabul edilebilir. Ödemeleri, erişim değişikliklerini, iş ortağı API yanıtlarını veya uyumluluk eylemlerini tetikleyen iş akışları için, arıza durumunda kapatılan bir politika genellikle daha güvenlidir.

6. Adım: Her Üretim Modeli için Sözleşme Testleri Oluşturun

Sözleşme testleri, bir modelin iş akışı için uygun olup olmadığına karar verir. İlk lansmandan, model yükseltmelerinden ve yönlendirme politikası değişikliklerinden önce çalıştırılmalıdır.

En azından her modeli ve sağlayıcı adaptörünü aşağıdakiler açısından test edin:

• Geçerli mutlu yol çıktısı.
• Zorunlu alanlar eksik.
• Geçersiz numaralandırma değerleri.
• Şema kapatıldığında ekstra özellikler.
• Çok fazla dizi öğesi.
• Aşırı uzun dizeler.
• Reddetme veya uymama.
• Kısaltılmış çıktı.
• Araç çağrısı uyumsuzluğu veya eksik araç çağrısı.
• Yapısal olarak geçerli ancak anlamsal olarak yanlış çıktı.

Modele sözleşmeyi ihlal etmesi için baskı yapan düşmanca yönlendirmeler kullanın. Örneğin, ekstra bir açıklayıcı alan eklemesini, numaralandırma dışında bir öncelik döndürmesini veya gerekli bir boole değerini atlamasını isteyin. Test yalnızca sağlayıcı, bağdaştırıcı ve doğrulayıcının beklenen uygulama durumunu sağlaması durumunda başarılı olur.

Her iş akışı için basit bir uyumluluk kaydı tutun:

{
  "workflow": "support_triage",
  "schema_version": "2026-09-24",
  "model": "provider-model-name",
  "supports_strict_schema": true,
  "supports_tool_calling": true,
  "supports_streaming_structured_output": false,
  "refusal_signal_normalized": true,
  "contract_tests_passed": true,
  "known_limitations": ["max schema depth 4"]
}

Bu yetenek matrisi, dağınık uygulama sabitlerine değil, kontrol düzlemine aittir.

7. Adım: Cihaz Yapılandırılmış Çıktı Güvenilirliği

Telemetri olmadan ekipler, hataların sağlayıcı uyumsuzluğundan mı, model sapmasından mı, şema kusurlarından mı, istem kusurlarından mı, kesintiden mi, yoksa aşağı akış doğrulayıcılardan mı kaynaklandığını anlayamaz.

Her yapılandırılmış çıkış isteği için bu alanları günlüğe kaydedin:

• İş akışı adı ve şema sürümü.
• Sağlayıcı, istenen model ve yanıt modeli.
• Yanıt şeması, araç çağrısı veya JSON modu gibi çıkış modu.
• Doğrulama durumu ve hata türü.
• Onarım sayısı ve onarım sonucu.
• Bitirme nedeni ve ret durumu.
• İstem jetonları, tamamlama jetonları, toplam maliyet ve gecikme.
• Bağdaştırıcı sürümü ve derleyici sürümü.

Yönlendirmeyi değiştirmeden önce modelleri karşılaştırmak için bu verileri kullanın. Daha ucuz bir model, onarım girişimlerini, manuel incelemeyi, iş ortağı API hatalarını veya sonraki olay yönetimini artırıyorsa daha ucuz değildir.

Açıkça Karar Vermek İçin Takaslar

En düşük ortak paydalı şemalar taşınabilirliği artırır ancak kısıtlamaları zayıflatır. Sağlayıcı istek şemasının basitleştirilmesi gerekiyorsa, kanonik doğrulama ve anlamsal doğrulayıcılarda daha sıkı kontrolleri koruyun.

Sağlayıcıya özel derleme, yerel güçlü yönleri korur ancak bakım sağlar. Bu genellikle üretim iş akışları için buna değerdir, ancak yalnızca derleyiciler sürümlendirilmişse ve sözleşme testleri kapsamındaysa.

Katı şemalar ayrıştırıcı hatalarını azaltır ancak daha iyi görev tasarımı gerektirir. Görev yeterince belirtilmemişse, katılık belirsizliği daha çabuk ortaya çıkarır. Bu faydalıdır ancak ilk gelişmeyi yavaşlatabilir.

Onarım tamamlanma oranlarını artırır ancak maliyet ve gecikmeyi artırır. Sınırlı onarım bir kurtarma mekanizmasıdır, şema tasarımının yerine geçmez.

Araç çağırma ve yanıt formatı JSON farklı iş akışlarına hizmet eder. Araç çağırma genellikle eylem odaklı iş akışlarına daha uygundur. Yanıt formatı JSON, çıkarma, sınıflandırma ve özetleme açısından daha basittir. Çok modelli bir platform her ikisini de destekleyebilir ancak iş akışı politikasının açık olması gerekir.

Tahminler: Yapılandırılmış Çıktı Taşınabilirliği Nereye Gidiyor

Yapılandırılmış çıktı için sağlayıcı desteği muhtemelen gelişmeye devam edecektir, ancak modeller arasında tam JSON Şema taşınabilirliği varsayılmamalıdır. Sağlayıcıların farklı model mimarileri, API geçmişleri, araç kullanım modelleri ve güvenlik davranışları vardır. Şema desteği güçlense bile, iş doğruluğu JSON şeklinden daha fazlasına bağlı olduğundan uygulamaların kanonik doğrulamaya ihtiyacı olmaya devam edecektir.

Ekipler, yapılandırılmış çıktı yönlendirme kararlarının daha fazla veriye dayalı hale gelmesini beklemelidir. Güvenilirlik, onarım oranı, ret yönetimi, gecikme ve maliyet, model kalitesinin yanı sıra önemli olacaktır. Operasyonel soru "bu model JSON'i destekliyor mu?" şeklinde değişecektir. "Bu model, bu iş akışının sözleşmesini kabul edilebilir bir maliyet ve başarısızlık oranıyla karşılıyor mu?"

Uygulama Kontrol Listesi

• İş akışı başına bir standart şema tanımlayın.
• Sürüm şemaları ve sağlayıcı istek yüklerinin tekrarlanabilir olmasını sağlayın.
• Desteklenmeyen veya riskli şema özellikleri için CI astarı ekleyin.
• Kanonik şemaları sağlayıcıya özel biçimlerde derleyin.
• Sağlayıcı zarflarını tek bir dahili sonuç türü halinde normalleştirin.
• Ayrıştırılmış her yanıtı standart şemaya göre doğrulayın.
• İş kuralları için anlamsal doğrulayıcılar ekleyin.
• Yalnızca sınırlı onarım girişimlerine izin ver.
• Yüksek riskli iş akışları için başarısızlıkla kapatılır veya incelemeye yönlendirilir.
• Üretim modellerini eklemeden veya yükseltmeden önce sözleşme testlerini çalıştırın.
• Kontrol düzleminde bir model yetenek matrisi koruyun.
• Her istek için doğrulama, onarım, maliyet, gecikme, sağlayıcı ve model alanlarını günlüğe kaydedin.

Uygulanabilir Sonuç

Yapılandırılmış çıktı taşınabilirliği bir API sözleşme sorunudur, hızlı biçimlendirme sorunu değildir. Güvenilir model, kanonik bir iş şeması tanımlamak, taşınabilirlik için onu lintlemek, her sağlayıcının yerel yüzeyinde derlemek, sağlayıcı geri gönderdikten sonra her yanıtı doğrulamak ve hangi modellerin üretime uygun olduğuna karar vermek için sözleşme testlerini kullanmaktır.

Bu tasarım bazı ön mühendislik çalışmaları ekler, ancak daha pahalı olan arıza modunu önler: Model yönlendirme, sağlayıcı davranışı veya şema uygulaması bunların altında sessizce değişirken aşağı akış sistemleri istikrarlı bir sözleşme varsayar.

İlgili okuma

• yapılandırılmış çıktı sözleşmelerini koruyan yedek yönlendirme