Herhangi Bir LLM'den Güvenilir JSON: 2026 için Pydantic + Zod Kalıpları

LLM yapılandırılmış çıktı, bir dil modelinin yanıtının önceden tanımlanmış bir şemaya uymasını garanti eden mekanizmadır -- yalnızca geçerli JSON değil, belirttiğiniz tam alanlar, türler ve kısıtlamalarla şema geçerli JSON. Tüm büyük sağlayıcılar artık bunu yerel olarak destekliyor ve bu, üretim LLM uygulamalarının nasıl inşa edildiğini değiştirdi.

Hızlı Özet: Yapılandırılmış Çıktılara Genel Bakış

Zamanınız kısıtlıysa, 2026'daki tablo şöyle:

Şimdi her parçayı inceleyelim.

LLM Yapılandırılmış Çıktılar Nedir?

Yapılandırılmış çıktı, bir LLM'nin geçerli JSON döndüreceğini ummak ile garanti etmek arasındaki farktır. Yapılandırılmış çıktıyı etkinleştirdiğinizde, model fiziksel olarak şemanızı ihlal eden token'lar üretemez. Bir JSON Şeması (veya Pydantic modeli ya da Zod şeması) tanımlarsınız, bunu API'ye iletirsiniz ve her seferinde buna uyan bir yanıt alırsınız.

Bu neden önemli? Yapılandırılmış çıktıdan önce, geliştiriciler kırılgan regex ayrıştırıcılar yazıyor, her LLM çağrısını try/catch JSON.parse bloklarıyla sarıyor ve yine de "neredeyse doğru" yanıtlarla uğraşıyordu -- bir alanı eksik olan ya da yanlış türde olan geçerli JSON. Tüm bu hata sınıfı ortadan kalktı.

Yapı zorlamanın üç seviyesi var ve bunlar açık bir evrimi temsil ediyor:

1. İstem mühendisliği -- "Lütfen bu alanlarla JSON döndür." Güvenilmez. Model zamanın %80-90'ında uyabilir.
2. JSON Modu -- Sözdizimsel olarak geçerli JSON garanti eder, ancak şemanızı zorlamaz. {"name": string, "age": number} beklerken {"foo": "bar"} alabilirsiniz.
3. Katı Mod / Kısıtlı kod çözme -- %100 şema uyumluluğu garanti eder. Model kelimenin tam anlamıyla geçersiz token'lar üretemez. 2026'da "yapılandırılmış çıktı" budur.

2026 başından itibaren OpenAI, Anthropic ve Google Gemini hepsi native yapılandırılmış çıktıyı destekliyor. Ekosistem birleşti.

Sonuç: Üretimde LLM yanıtlarını regex veya JSON.parse ile ayrıştırıyorsanız, işi zor yoldan yapıyorsunuzdur. Native yapılandırılmış çıktı, o hata sınıfının tamamını ortadan kaldırır.

JSON Modu vs. Katı Mod: Gerçekte Ne Değişti?

Bu ayrım pek çok geliştiricinin kafasını karıştırıyor çünkü isimler benzer geliyor. Değiller.

Zaman çizelgesi: OpenAI, JSON Modunu 2023 sonunda tanıttı. Bu bir adım ileriydi, ancak geliştiriciler hızla "geçerli JSON"un yeterli olmadığını fark etti -- şema geçerli JSON'a ihtiyaçları vardı. Ağustos 2024'te OpenAI, şema uyumluluğunu garanti etmek için kısıtlı kod çözmeyi kullanan Katı Modla birlikte Yapılandırılmış Çıktıları başlattı. 2025-2026'ya kadar her büyük sağlayıcı aynı yaklaşımı benimsedi.

JSON Modunun hâlâ dar bir kullanım durumu var: yanıtın şeklini önceden gerçekten bilmediğinizde ve yapılandırılmamış keşif için yalnızca herhangi bir geçerli JSON istediğinizde. Ama bu üretimde nadirdir.

Sonuç: Üretimde her şey için Katı Modu kullanın. JSON Modu, şemaya bağlı kullanım durumları için etkin biçimde kullanımdan kalkmıştır. Bir şemanız varsa (ve olmalıdır), strict: true ile type: "json_schema" kullanın.

Kısıtlı Kod Çözme Gerçekte Nasıl Çalışır?

İşte %100 şema uyumluluğunu mümkün kılan mekanizma -- %99,9 değil, kelimenin tam anlamıyla %100.

Katı Mod etkinleştirilmiş bir sağlayıcıya JSON Şeması gönderdiğinizde, şema bir sonlu durum makinesi (FSM) olarak derlenir. Bu FSM, şemanızdaki her geçerli yolu temsil eder. Her token oluşturma adımında, çıkarım motoru hangi token'ların çıktıyı geçerli bir yolda tutacağını ve hangilerinin tutmayacağını kontrol eder. Geçersiz token'ların logitleri örneklemeden önce negatif sonsuza ayarlanır; bu da seçilme olasılıklarının sıfır olduğu anlamına gelir.

Bunu steroidli otomatik tamamlama gibi düşünün. Model az önce {"rating": ürettiyse ve şemanız rating'in bir tamsayı olduğunu söylüyorsa, izin verilen tek sonraki token'lar rakam token'larıdır. Tırnak işaretleri, harfler, parantezler -- hepsi maskelendi. Model "istese" bile "beş" üretemez.

Bu, XGrammar (vLLM, SGLang ve çoğu yerel çıkarım sunucusunun arkasındaki motor) ve Outlines (kısıtlı üretim için açık kaynak Python kütüphanesi) tarafından kullanılan temel mekanizmanın aynısıdır. API sağlayıcıları bunu çıkarım altyapılarına entegre etmiştir.

Bilinmesi gereken bir ödün var: yeni bir şemayla yapılan ilk istek, FSM oluşturulurken bir derleme gecikmesine (genellikle 50-200ms) yol açar. Aynı şemayla yapılan sonraki istekler önbelleğe alınmış bir FSM kullanır ve neredeyse sıfır ek yük ekler. Ayrıca ince bir kalite değerlendirmesi var -- token kelime dağarcığını kısıtlamak, yaratıcı veya serbest biçimli alanlar için çıktı kalitesini zaman zaman azaltabilir, bu nedenle şemalarınızı gerçekten yapılandırılmış veriye odaklı tutun.

Sonuç: Kısıtlı kod çözme, "genellikle çalışır"ı "her zaman çalışır"dan ayıran şeydir. Yapılandırılmış çıktıyı üretime hazır hale getiren mühendislik budur.

Çok Sağlayıcılı Uygulama: OpenAI, Anthropic ve Gemini

İşte diğer kılavuzların hiçbirinin size göstermediği bir şey: aynı çıkarma görevi, üç büyük sağlayıcının tamamında uygulanmış. Yapılandırılmamış metinden yapılandırılmış bir ürün incelemesi çıkaracağız.

Pydantic şeması (tüm sağlayıcılar arasında paylaşılan):

from pydantic import BaseModel, Field
from typing import Literal

class ProductReview(BaseModel):
    reasoning: str = Field(description="Think through the review before scoring")
    rating: int = Field(description="Rating from 1-5", ge=1, le=5)
    sentiment: Literal["positive", "negative", "neutral"]
    pros: list[str] = Field(description="Key positive points")
    cons: list[str] = Field(description="Key negative points")
    summary: str = Field(description="One-sentence summary")

OpenAI Uygulaması

from openai import OpenAI

client = OpenAI()

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract a structured review from the text."},
        {"role": "user", "content": review_text}
    ],
    response_format=ProductReview,  # Pydantic modeli doğrudan
)

review = response.choices[0].message.parsed  # Tiplenmiş ProductReview nesnesi

OpenAI'nin uygulaması en olgunudur. parse() metodu bir Pydantic modelini doğrudan kabul eder ve tiplenmiş bir nesne döndürür. Bir kısıtlama: OpenAI'nin Katı Modu, JSON Şemasının bir alt kümesini destekler -- $ref yok, sınırlı anyOf ve tüm alanlar additionalProperties: false ile zorunlu olmalıdır.

Anthropic Uygulaması

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": f"Extract a structured review:\n\n{review_text}"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "json_schema": ProductReview.model_json_schema()
        }
    }
)

import json
review_data = json.loads(response.content[0].text)
review = ProductReview(**review_data)

Anthropic'in native yapılandırılmış çıktısı, JSON Şemasıyla output_config.format kullanır. 2026 başında GA'ya ulaştı. Anthropic ayrıca "sahte" bir araç tanımlama ve tool_use üzerinden çıkarma eski kalıbını da destekliyor -- bu hâlâ çalışıyor, ancak native yapılandırılmış çıktı saf çıkarım için daha temizdir.

Gemini Uygulaması

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=f"Extract a structured review:\n\n{review_text}",
    config={
        "response_mime_type": "application/json",
        "response_schema": ProductReview,  # Pydantic modeli doğrudan
    }
)

import json
review = ProductReview(**json.loads(response.text))

Gemini, Python SDK'sında response_schema üzerinden Pydantic modellerini doğrudan destekler. Benzersiz bir özellik: Gemini, şemada propertyOrdering'e saygı gösterir, böylece alan çıktı sırasını kontrol edebilirsiniz (akıl yürütme önce kalıbı için kullanışlı).

Sağlayıcı Karşılaştırması

Sonuç: OpenAI, parse() metoduyla en olgun geliştirici deneyimine sahip. Anthropic, en yetenekli temel modelleri sunuyor. Gemini'nin özellik sıralaması benzersiz biçimde kullanışlı. Üçü de işi yapıyor -- mevcut sağlayıcı ilişkinize göre seçin.

Python Geliştiricileri için Pydantic Kalıpları

Pydantic, Python'da yapılandırılmış çıktı şemalarını tanımlamak için fiili standarttır. İşte önemli kalıplar.

Açıklamalı Temel Şema

from pydantic import BaseModel, Field
from typing import Literal, Optional

class ExtractedEntity(BaseModel):
    reasoning: str = Field(description="Think step by step about the entity")
    name: str = Field(description="Full name of the entity")
    entity_type: Literal["person", "company", "location"]
    confidence: float = Field(description="Confidence score 0.0-1.0", ge=0.0, le=1.0)
    context: Optional[str] = Field(description="Surrounding context, if relevant")

Bu description dizileri yalnızca belgeleme için değil -- modele gönderilen JSON Şemasının bir parçası haline gelir ve modelin ürettiklerini doğrudan etkiler. Bunları şema içindeki istem mühendisliği olarak düşünün.

İç İçe Modeller

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: Optional[str] = None

class Company(BaseModel):
    reasoning: str = Field(description="Analysis of the company details")
    name: str
    industry: Literal["tech", "finance", "healthcare", "retail", "other"]
    headquarters: Address  # İç içe model
    key_products: list[str] = Field(description="Top 3 products or services")

İç içe geçmeyi en fazla 2-3 seviyede tutun. Derin iç içe şemalar hata oranlarını artırır ve şema derlemesini yavaşlatır.

Akıl Yürütme-Önce Kalıbı

Bu, en etkili şema tasarım kalıbıdır. Yanıt alanlarından önce bir reasoning alanı koyun:

# Kötü -- model düşünmeden önce bir cevaba bağlanıyor
class ClassificationBad(BaseModel):
    category: Literal["spam", "ham"]
    confidence: float

# İyi -- model önce problemi düşünüyor
class ClassificationGood(BaseModel):
    reasoning: str = Field(description="Analyze the text before classifying")
    category: Literal["spam", "ham"]
    confidence: float = Field(ge=0.0, le=1.0)

LLM'ler token'ları soldan sağa üretir. category önce gelirse, model bir kategori seçer ve sonra rasyonalize eder. reasoning önce gelirse, model problemi çalışır ve ardından bir kategoriye bağlanır. Bu, şemaya yerleştirilmiş düşünce zinciridir.

JSON Şeması Dışa Aktarma

# Herhangi bir Pydantic modeli için JSON Şeması oluştur
schema = ProductReview.model_json_schema()
# Bunu ham JSON Şemasını kabul eden herhangi bir sağlayıcıya iletin

Sonuç: Pydantic + açıklayıcı alanlar + akıl yürütme önce sırası, Python yapılandırılmış çıktı üçlüsüdür. Bu üç kalıbı öğrenin ve kullanım durumlarının %90'ını halledeceksiniz.

TypeScript Geliştiricileri için Zod Kalıpları

Zod, Pydantic'in TypeScript karşılığıdır -- ve yapılandırılmış çıktı iş akışlarına o kadar merkezi.

Açıklamalı Temel Şema

import { z } from "zod";

const ProductReview = z.object({
  reasoning: z.string().describe("Think through the review before scoring"),
  rating: z.number().int().min(1).max(5),
  sentiment: z.enum(["positive", "negative", "neutral"]),
  pros: z.array(z.string()).describe("Key positive points"),
  cons: z.array(z.string()).describe("Key negative points"),
  summary: z.string().describe("One-sentence summary"),
});

// TypeScript türünü otomatik çıkar
type ProductReview = z.infer<typeof ProductReview>;

Pydantic'in Field(description=...) gibi, Zod'un .describe() de JSON Şemasının bir parçası haline gelir ve modelin çıktısını yönlendirir.

OpenAI Node SDK ile Entegrasyon

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";

const client = new OpenAI();

const response = await client.beta.chat.completions.parse({
  model: "gpt-4o-2024-08-06",
  messages: [
    { role: "system", content: "Extract a structured review." },
    { role: "user", content: reviewText },
  ],
  response_format: zodResponseFormat(ProductReview, "product_review"),
});

const review = response.choices[0].message.parsed; // Tiplenmiş!

Vercel AI SDK ile Entegrasyon

import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";

const { object: review } = await generateObject({
  model: openai("gpt-4o"),
  schema: ProductReview,
  prompt: `Extract a structured review:\n\n${reviewText}`,
});
// review, ProductReview olarak tam tiplenmiş

Vercel AI SDK, generateObject() ile Zod'u native olarak kullanır; bu da onu en temiz TypeScript entegrasyonu yapar. Birleşik bir API üzerinden OpenAI, Anthropic, Gemini ve diğer sağlayıcılarla çalışır.

JSON Şeması Dönüşümü

import { zodToJsonSchema } from "zod-to-json-schema";

const jsonSchema = zodToJsonSchema(ProductReview);
// Ham JSON Şemasını kabul eden herhangi bir sağlayıcıyla kullan

Sonuç: Zod + .describe() + Vercel AI SDK, TypeScript yapılandırılmış çıktı yığınıdır. Node/Next.js ekosistemindeyseniz, bu en az dirençli yoldur.

Yapılandırılmış Çıktı vs. Fonksiyon Çağırma: Hangisini Ne Zaman Kullanırsınız?

Bu, en yaygın karışıklık kaynaklarından biridir. Her ikisi de şema içerir, her ikisi de yapılandırılmış veri döndürür -- ancak farklı sorunları çözerler.

Yapılandırılmış çıktı şunu söyler: "Bana tam bu şekilde veri ver." Çıkarım, sınıflandırma ve biçimlendirme içindir. Yapılandırılmamış metinden yapılandırılmış bilgi çıkarırsınız.

Fonksiyon çağırma (araç kullanımı) şunu söyler: "İşte gerçekleştirebileceğiniz eylemler -- hangisini çalıştıracağınıza karar verin ve argümanları sağlayın." Modelin birden fazla araç arasından seçim yaptığı ve eylemleri tetiklediği ajan iş akışları içindir.

Karışıklık tarihsel olarak mantıklı. Anthropic'in orijinal "yapılandırılmış çıktısı" kelimenin tam anlamıyla fonksiyon çağırmaktı -- extract_review adında sahte bir araç tanımlıyor ve argümanları alıyordunuz. Bu hâlâ çalışıyor, ancak native yapılandırılmış çıktı saf çıkarım için daha basit.

Yapılandırılmış çıktı, yapay zeka ajan sistemlerindeki araç çağırma boru hatlarını güçlendirir. Bunların üretim iş akışlarına nasıl uyduğunu görmek için işletmeler için yapay zeka ajanları kılavuzumuza bakın.

Sonuç: Verilerin hangi şekilde olması gerektiğini bildiğinizde yapılandırılmış çıktıyı kullanın. Modelin bir eylem seçmesi gerektiğinde fonksiyon çağırmayı kullanın. Pratikte çoğu uygulama her ikisini de kullanır -- veri çıkarımı için yapılandırılmış çıktı ve ajan orkestrasyonu için fonksiyon çağırma.

Üretim Kalıpları: Hatalar, Yeniden Denemeler ve Streaming

Yapılandırılmış çıktıyı bir demoda çalıştırmak kolaydır. Üretimde güvenilir tutmak üç şeyin ele alınmasını gerektirir: reddedişler, doğrulama hataları ve streaming.

Reddetme İşleme

Bazen bir model istenen çıktıyı üretmeyi reddeder -- tipik olarak güvenlik filtreleri girişi işaretlediği için. Bu gerçekleştiğinde, yapılandırılmış çıktı API'leri şemanızı döndürmez. Bir reddetme döndürürler.

response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=messages,
    response_format=ProductReview,
)

# Ayrıştırılmış içeriğe erişmeden önce HER ZAMAN reddetmeyi kontrol edin
if response.choices[0].message.refusal:
    print(f"Model refused: {response.choices[0].message.refusal}")
else:
    review = response.choices[0].message.parsed

Reddetme kontrolünü atlayıp bir reddetmede .parsed'a erişmeye çalışırsanız, None ve kafa karıştırıcı bir aşağı yönlü hata alırsınız. Her zaman önce kontrol edin.

Doğrulama Geri Bildirimiyle Yeniden Deneme Kalıpları

Şema uyumluluğu kısıtlı kod çözme tarafından garanti edilir, ancak anlamsal doğruluk garanti edilmez. Model {"rating": 1, "sentiment": "positive"} döndürebilir -- geçerli şema, çelişkili içerik. İşte bu noktada doğrulama + yeniden denemeler devreye girer.

import instructor

client = instructor.from_openai(OpenAI())

# Instructor yeniden denemeleri otomatik olarak işler
review = client.chat.completions.create(
    model="gpt-4o",
    response_model=ProductReview,
    max_retries=3,  # Doğrulama hatası geri bildirimiyle yeniden denemeler
    messages=[
        {"role": "user", "content": review_text}
    ],
)

Instructor, yeniden denemede doğrulama hatasını modele geri besler, böylece kendini düzeltebilir. Instructor olmadan manuel yeniden deneme kalıpları için:

from pydantic import ValidationError

for attempt in range(3):
    try:
        response = client.beta.chat.completions.parse(
            model="gpt-4o-2024-08-06",
            messages=messages,
            response_format=ProductReview,
        )
        review = response.choices[0].message.parsed
        # Burada ek anlamsal doğrulama çalıştırın
        break
    except ValidationError as e:
        messages.append({"role": "assistant", "content": str(response)})
        messages.append({"role": "user", "content": f"Validation error: {e}. Fix it."})

Yapılandırılmış Çıktı Streaming'i

Büyük yapılandırılmış yanıtlar için -- uzun diziler, birçok alan, karmaşık iç içe nesneler -- streaming, kısmi sonuçları aşamalı olarak render etmenizi sağlar.

import instructor

client = instructor.from_openai(OpenAI())

# Alanlar doldukça kısmi sonuçları akışa alın
review_stream = client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=ProductReview,
    messages=[{"role": "user", "content": review_text}],
)

for partial_review in review_stream:
    # Token'lar akışa girerken alanlar tek tek dolduruluyor
    if partial_review.summary:
        print(f"Summary so far: {partial_review.summary}")

Bir tuzak: Bireysel streaming parçaları kendi başlarına şema geçerli değildir. reasoning alanı doldurulmuş olabilirken rating hâlâ None olabilir. Kullanıcı arayüzünüzü buna göre planlayın -- doldurulamayan alanlar için yükleme durumu gösterin.

Sonuç: Reddetme kontrolleri tartışmasızdır. Doğrulama geri bildirimiyle yeniden denemeler anlamsal hataları yakalar. Streaming, birkaç saniyeden fazla süren her yanıt için buna değer.

Yapılandırılmış Çıktı Kütüphaneleri Karşılaştırması

Yapılandırılmış çıktıyı native API'ler üzerinden kullanabilirsiniz, ancak kütüphaneler doğrulama, yeniden denemeler, streaming ve çok sağlayıcı desteği ekler. İşte mevcut tablo.

Instructor, 11K+ GitHub yıldızı ve 3M+ aylık indirme ile en popüler seçenektir. Birleşik Pydantic tabanlı arayüzle OpenAI, Anthropic, Gemini, Cohere, Ollama ve daha fazlasını kapsar. Temel özellikler: doğrulama geri bildirimiyle otomatik yeniden denemeler, create_partial() üzerinden streaming ve basit kurulum (instructor.from_openai(client)). Python ekibiyseniz buradan başlayın.

BAML, farklı bir yaklaşım benimser: özel bir DSL üzerinden şema önce. .baml dosyalarında şemalar tanımlar ve Python, TypeScript, Ruby ve daha fazlası için istemciler otomatik oluşturursunuz. SAP (şema hizalı ayrıştırma) algoritması dağınık model çıktılarını zarif biçimde ele alır. Diller arası ekipler veya LLM katmanınız ile uygulama katmanınız arasında sözleşme istediğinizde en iyisi. Dezavantajı: ek derleme adımı ve öğrenilecek yeni sözdizimi.

LangChain, sağlayıcıdan bağımsız yapılandırılmış çıktı için .with_structured_output(schema) sunar. Zaten LangChain ekosistemindeyseniz kullanışlıdır. Dezavantajı: ağır bir bağımlılık ve soyutlama, ihtiyaç duyabileceğiniz sağlayıcıya özgü özellikleri gizleyebilir.

Native API'ler -- response_format / output_config ile doğrudan çağrılar -- sağlayıcı SDK'sının ötesinde hiçbir bağımlılık gerektirmez. Tam kontrol ve tam görünürlük elde edersiniz. Basit kullanım durumları veya minimum soyutlamayı tercih eden ekipler için en iyisi.

Doğru yapılandırılmış çıktı kütüphanesini seçmek, daha geniş bir yapay zeka yığını kararının parçasıdır. SaaS için En İyi Yapay Zeka Yığını kılavuzumuzda tam yığını ele alıyoruz.

Instructor, BAML, Mirascope ve daha fazlasının derinlemesine karşılaştırması için LLM Yapılandırılmış Çıktılar için En İyi Kütüphaneler [yakında] bölümümüze bakın.

Sonuç: Python için Instructor ile başlayın, TypeScript için native API'lerle. Diller arası şema sözleşmelerine ihtiyacınız varsa BAML'a geçin. Yalnızca yapılandırılmış çıktı için LangChain'den kaçının -- bu aşırıya kaçmak.

Şema Tasarımı için En İyi Uygulamalar (ve Yaygın Hatalar)

Şema tasarımınız çıktı kalitesini doğrudan etkiler. İşte önemli kalıplar ve doğruluk kaybettiren hatalar.

Akıl Yürütmeyi Yanıtlardan Önce Koymak

Bunu Pydantic bölümünde ele aldık, ancak en yüksek etkili tasarım kararı olduğu için tekrarlanmayı hak ediyor:

# Önce: model cevabı tahmin eder, sonra rasyonalize eder
class Bad(BaseModel):
    answer: str
    reasoning: str

# Sonra: model önce düşünür, sonra bağlanır
class Good(BaseModel):
    reasoning: str = Field(description="Think step by step")
    answer: str

LLM'ler soldan sağa üretir. Alan sırası istem sırasıdır. Akıl yürütme önce demek, modelin bir yanıta bağlanmadan önce problemi çalışmak zorunda olduğu anlamına gelir.

Anti-Kalıp Tablosu

Null'ları Açıkça İşleme

Bir alanda kaynak metinde veri bulunmayabiliyorsa, onu isteğe bağlı yapın. Veri mevcut olmadığında gerekli bir alanı zorlamak hallüsinasyona yol açar:

class PersonInfo(BaseModel):
    name: str  # Her zaman mevcut
    email: Optional[str] = Field(None, description="Email if mentioned, null otherwise")
    phone: Optional[str] = Field(None, description="Phone if mentioned, null otherwise")

Şemaları Odaklı Tutmak

Görev başına bir şema. Her şeyi tek bir devasa şemada çıkarmaya çalışmayın. 50'den fazla alana ihtiyacınız varsa, birden fazla çıkarım çağrısına bölün. OpenAI'nin Katı Modunun şema karmaşıklığı üzerinde pratik sınırları var ve çalışsa bile çok büyük şemalar çıktı kalitesini düşürür.

Sonuç: Akıl yürütme önce, açıklayıcı alanlar, açık null'lar ve odaklı şemalar. Bu dördünü doğru yapın ve yapılandırılmış çıktı doğruluğunuz ölçülebilir biçimde artar.

Yerel LLM'lerle Yapılandırılmış Çıktı

Yapılandırılmış çıktı için bir API sağlayıcısına ihtiyacınız yok. Yerel çıkarım motorları, dilbilgisi tabanlı kısıtlı kod çözme aracılığıyla bunu destekler -- aynı temel mekanizma, kendi donanımınızda çalışıyor.

Ollama

Yerel yapılandırılmış çıktı için en kolay yol. Ollama, format parametresi aracılığıyla bir JSON Şemasını kabul eder:

import ollama
from pydantic import BaseModel

class Country(BaseModel):
    name: str
    capital: str
    languages: list[str]

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Tell me about Japan."}],
    format=Country.model_json_schema(),
)

import json
country = Country(**json.loads(response.message.content))

Ollama, kısıtlı kod çözme için arka planda XGrammar kullanır. API sağlayıcılarıyla aynı garanti: %100 şema uyumluluğu.

vLLM ve SGLang

Üretim kalitesinde yerel çıkarım için, vLLM ve SGLang her ikisi de guided_json ve guided_regex parametreleri aracılığıyla yapılandırılmış çıktıyı destekler. XGrammar, JSON üretiminde neredeyse sıfır ek yük sağlayan varsayılan arka uçtur -- alternatif dilbilgisi motorlarından 3,5 kata kadar daha hızlı.

Outlines

Outlines, dilbilgisi tabanlı kısıtlı üretimi öncülük eden açık kaynak Python kütüphanesidir. Herhangi bir Hugging Face modeliyle çalışır ve JSON Şeması, regex ve tam bağlamdan bağımsız dilbilgisi (CFG/EBNF) kısıtlamalarını destekler. Ayrıca bir dilbilgisi arka uç seçeneği olarak vLLM ve SGLang'a entegre edilmiştir.

API sağlayıcılarından temel fark: yerel yapılandırılmış çıktının şema alt kümesi sınırlaması yoktur. Dilbilgisini tamamen kontrol edersiniz. Ancak model kalitesi daha fazla değişir -- 7B parametreli yerel bir model, karmaşık çıkarım görevlerinde GPT-4o veya Claude'a erişemez. Şema her zaman geçerli olacaktır; içerik kalitesi modele bağlıdır.

Sonuç: Geliştirme için Ollama, üretim için XGrammar ile vLLM/SGLang. Yerel yapılandırılmış çıktı, küçük modellerin şema içinde daha düşük kaliteli içerik ürettiği uyarısıyla çoğu kullanım durumu için yeterince olgunlaşmıştır.

Sık Sorulan Sorular

LLM'lerde yapılandırılmış çıktı nedir?

Yapılandırılmış çıktı, bir LLM'nin yanıtının önceden tanımlanmış bir JSON Şemasına uymasını garanti eden bir mekanizmadır. Düz metin veya JSON Modunun aksine, yapılandırılmış çıktı, şemanızdaki her alanın, türün ve kısıtlamanın karşılandığından emin olmak için kısıtlı kod çözme kullanır -- zamanın %100'ünde, "genellikle" değil.

JSON Modu ile Yapılandırılmış Çıktılar arasındaki fark nedir?

JSON Modu sözdizimsel olarak geçerli JSON garanti eder ancak şemanızı zorlamaz -- herhangi bir geçerli JSON nesnesi alabilirsiniz. Yapılandırılmış Çıktılar (Katı Mod), kısıtlı kod çözme aracılığıyla tam şema uyumluluğunu garanti eder. Üretim için Katı Mod kullanın; JSON Modu yalnızca önceden şemanız olmadığında geçerlidir.

Hangi LLM sağlayıcıları yapılandırılmış çıktıyı native olarak destekliyor?

OpenAI (Ağustos 2024'ten beri), Google Gemini (2024, 2026'da genişletildi), Anthropic (beta Kasım 2025, GA 2026 başı), Cohere ve xAI (Grok) hepsi native yapılandırılmış çıktıyı destekliyor. Yerel tarafta, Ollama, vLLM ve SGLang dilbilgisi tabanlı kısıtlı kod çözme aracılığıyla bunu destekliyor.

Kısıtlı kod çözme şema uyumluluğunu nasıl garanti eder?

JSON Şeması bir sonlu durum makinesine (FSM) derlenir. Her token oluşturma adımında, yalnızca çıktıyı FSM üzerindeki geçerli bir yolda tutan token'lara izin verilir -- geçersiz token'lar logitleri negatif sonsuza ayarlanmış olarak gelir. Bu, geçersiz token'ların oluşturulma olasılığının sıfır olduğu anlamına gelir ve size istatistiksel değil matematiksel bir garanti sunar.

Yapılandırılmış çıktı mı yoksa fonksiyon çağırma mı kullanmalıyım?

Çıkarım ve sınıflandırma için yapılandırılmış çıktı kullanın -- belirli bir şekilde veri istediğinizde. Ajan iş akışları için fonksiyon çağırma kullanın -- modelin hangi eylemi alacağına karar vermesi gerektiğinde. Pek çok üretim uygulaması her ikisini de kullanır: veri çıkarımı için yapılandırılmış çıktı ve orkestrasyon için fonksiyon çağırma.

Yapılandırılmış çıktıyı akışa alabilir miyim?

Evet. OpenAI, parse() metoduyla streaming'i destekler ve Instructor, alan alan doldurulan Pydantic modellerini akışa almak için create_partial() sağlar. Bireysel streaming parçalarının tek tek şema geçerli olmadığını unutmayın -- alanlar artımlı olarak doldurulur.

Instructor kütüphanesi nedir?

Instructor, en popüler yapılandırılmış çıktı kütüphanesidir (11K+ GitHub yıldızı, 3M+ aylık indirme). Pydantic tabanlı doğrulama, doğrulama geri bildirimiyle otomatik yeniden denemeler ve streaming desteğiyle sağlayıcı SDK'larını kapsar. OpenAI, Anthropic, Gemini, Cohere, Ollama ve 10'dan fazla sağlayıcıyla çalışır.

Yapılandırılmış çıktı yerel LLM'lerle çalışıyor mu?

Evet. Ollama, JSON Şemasıyla format parametresi aracılığıyla yapılandırılmış çıktıyı destekler. vLLM ve SGLang bunu guided_json parametreleri aracılığıyla destekler. Üçü de kısıtlı kod çözme için XGrammar veya Outlines kullanır. Şema uyumluluğu garantisi API sağlayıcılarıyla aynıdır; içerik kalitesi modele bağlıdır.

Yaygın şema tasarım hataları nelerdir?

En önemli hatalar: akıl yürütme alanını yanıt alanından sonra koymak (model düşünmeden karar veriyor), derin iç içe şemalar (4+ seviye hataları artırır), eksik alan açıklamaları (model amacı tahmin ediyor), isteğe bağlı veriler için null işleme yok (hallüsinasyona zorluyor) ve aşırı büyük şemalar (50+ alan kaliteyi düşürür).

Yapılandırılmış çıktı gecikme ekliyor mu?

İlk istekte bir şema derleme ek yükü var -- FSM oluşturulurken genellikle 50-200ms. Aynı şemayla yapılan sonraki istekler önbelleğe alınmış bir FSM kullanır ve neredeyse sıfır gecikme ekler. Çoğu uygulama için bu, toplam model çıkarım süresine kıyasla ihmal edilebilir düzeydedir.

Görüntüler veya çok modlu girişlerle yapılandırılmış çıktı kullanabilir miyim?

Evet. Yapılandırılmış çıktı, girişe değil yanıt biçimine uygulanır. GPT-4o veya Gemini'ye yapılandırılmış çıktı şemasıyla bir görüntü gönderebilir ve görüntünün şema uyumlu bir analizini geri alabilirsiniz. Bu, görsel çıkarım iş akışları için güçlüdür -- makbuzlardan, formlardan veya ürün görüntülerinden yapılandırılmış veri çıkarma.

Kaynaklar

• OpenAI Structured Outputs Guide
• Anthropic Tool Use Documentation
• Google Gemini Structured Output
• Instructor Library Documentation
• BAML Documentation
• Pydantic Documentation
• Zod Documentation
• Outlines Library
• XGrammar GitHub
• Ollama Structured Outputs
• Vercel AI SDK