Structured Output ile LLM: JSON Schema, Pydantic ve Outlines Pratiği

LLM structured output, büyük dil modellerinin serbest metin yerine önceden tanımlanmış bir şemaya (JSON Schema, Pydantic modeli, dataclass veya regex) bire bir uyan deterministik veri üretmesini sağlayan tekniktir. 2026 itibarıyla üretim ortamında çalışan her ciddi LLM uygulaması (chatbot, agent, RAG, ETL pipeline) çıktıyı parse etmek zorunda kalır ve burada serbest metin %3-15 oranında parse hatası verirken structured output OpenAI’nin Ağustos 2024’te duyurduğu Structured Outputs özelliğinde %100 schema conformance garantisi sunar. Bu yazıda function calling, JSON mode, constrained decoding (Outlines), Instructor ve provider seviyesinde native structured output yaklaşımlarını karşılaştırıyor, Pydantic ile şema tanımının neden endüstri standardı olduğunu, latency etkisini, parse error oranlarını ve hangi senaryoda hangi yaklaşımın seçileceğini somut sayılarla ortaya koyuyoruz. Hedef kitle: LLM API’larıyla üretim kodu yazan backend mühendisleri, ML mühendisleri ve agentic sistem mimarları.

LLM Structured Output Nedir ve Neden Kritiktir?

Klasik LLM çağrısı serbest metin döner. “Bu metinden kişi adı, şirket ve tarihi JSON olarak ver” dediğinizde model çoğu zaman doğru yapar, ancak ```json bloğu eklemesi, virgül unutması, trailing comma bırakması veya açıklayıcı bir paragraf yapıştırması gibi sapmalar üretim ortamında %3-15 arasında parse error’a yol açar. 1000 çağrıda 30-150 hata, retry mekanizması, exponential backoff ve insan gözetim maliyeti demektir. Structured output bu belirsizliği ortadan kaldırır: çıktı önceden ilan edilmiş şemaya bire bir uyar, downstream sistem garanti edilmiş tiplerle çalışır.

Üç ana yaklaşım vardır. Birincisi prompt-only: “Şu JSON şemasına uy” diye yazarsınız, model çoğu zaman uyar ama garanti yoktur. İkincisi provider-native structured output: OpenAI Structured Outputs, Anthropic tool_use, Google Gemini function calling – provider sampling sırasında token’ları kısıtlar. Üçüncüsü client-side constrained decoding: Outlines, LMFE, vLLM Guided Decoding gibi kütüphaneler logit’leri filtreleyerek geçersiz token’ları olasılık 0’a çeker. Üretim sistemlerinde Pydantic + Instructor veya provider-native + JSON Schema kombinasyonu baskındır; agentic mimarilerde Function Calling Tool Use bu paradigmanın doğrudan uzantısıdır.

Yaklaşımların Karşılaştırılması: 5 Yöntem Tek Tabloda

Aşağıdaki tablo en yaygın 5 yaklaşımı mühendislik kriterleriyle özetliyor. “Conformance” çıktının şemaya uyma garantisi, “latency overhead” baseline’a kıyasla ek gecikme, “provider lock-in” yöntemin tek sağlayıcıya bağımlılığıdır.

Yöntem	Conformance	Latency overhead	Provider lock-in	Tipik kullanım
Prompt-only JSON	%85-97	Yok	Yok	Prototip, low-stakes
OpenAI JSON Mode	%99 (geçerli JSON, şema garantisi yok)	+%2-5	OpenAI	Genel amaçlı
OpenAI Structured Outputs	%100	+%5-10 (ilk çağrı warm-up)	OpenAI	Üretim, deterministik
Anthropic tool_use	%99+	+%3-7	Anthropic	Claude agent, tool routing
Outlines / LMFE constrained	%100	+%5-15 (logit masking)	Yok (local model)	Self-hosted, regex/CFG

Function Calling tarihsel olarak ilk büyük çözümdü (OpenAI Haziran 2023), JSON Mode Kasım 2023, Structured Outputs Ağustos 2024’te geldi ve şu an provider-native tarafta altın standarttır. Self-hosted modellerde Outlines (dottxt-ai) ve LMFE (Microsoft) token-by-token logit masking ile aynı garantiyi sunar.

Provider Desteği: OpenAI, Anthropic, Google, Mistral

Provider seçimi yalnızca model kalitesiyle değil, structured output API’sinin olgunluğuyla da ilgilidir. 2026 itibarıyla durum:

Provider	Native özellik	JSON Schema desteği	Strict mode	Pydantic entegrasyon
OpenAI	Structured Outputs, JSON Mode, Function Calling	Tam (draft 2020-12 subset)	Var (strict: true)	Resmi SDK response_format
Anthropic	tool_use input_schema	Tam (JSON Schema)	Implicit (tool çağırınca)	Instructor üzerinden
Google Gemini	Function Calling, response_schema	OpenAPI 3.0 subset	responseSchema	Pydantic destekli
Mistral	Function Calling, JSON Mode	JSON Schema	response_format json_object	Instructor uyumlu
vLLM (self-hosted)	Guided Decoding (JSON, regex, choice)	Tam	guided_json parametresi	Outlines backend

OpenAI Structured Outputs dokümantasyonu şu kısıtları belirtir: schema’da kök obje olmalı, tüm property’ler required, additionalProperties: false zorunlu, oneOf yerine anyOf, recursive ref desteği var ama derinlik sınırlı. Anthropic tool_use rehberi 200k context içinde tool tanımı kabul eder, tool_choice ile zorla çağırma mümkündür. Detaylı Claude entegrasyonu için Claude API Tool Use yazısına bakın.

Schema Tanım Dilleri: JSON Schema vs Pydantic vs Zod vs Dataclasses

Şema yalnız sunucu tarafında değil, kod tabanında da yaşar. Geliştirici Python class’ı yazar, kütüphane bunu JSON Schema’ya çevirir, provider’a gönderilir, dönen JSON tekrar class instance’ına parse edilir. Bu döngünün ergonomisi tercih sebebidir.

Dil/Kütüphane	Ekosistem	Validation	JSON Schema export	LLM popülerliği
JSON Schema (raw)	Polyglot	ajv, jsonschema	Yerli format	Orta (verbose)
Pydantic v2	Python	Tip + custom validator	.model_json_schema()	Yüksek (Instructor 8M+ DL/ay)
Zod	TypeScript	Schema-first runtime	zod-to-json-schema	Yüksek (Node ekosistem)
Python dataclasses	Python stdlib	Yok (manuel)	Manuel/ek lib	Düşük
TypedDict + Annotated	Python	Yok	Pydantic adapter	Orta

Pydantic v2 Rust core’u sayesinde validation 5-50x hızlandı, pydantic.dev resmi sitesi v2 benchmark’larını yayınlıyor. Instructor kütüphanesi Pydantic modelini alıp OpenAI, Anthropic, Gemini, Mistral, Cohere, Groq, Bedrock provider’larına aynı API ile gönderir; 2026 itibarıyla aylık 8 milyon download bandında ve LangChain’in with_structured_output metodu altyapısının önemli bir parçasıdır. JavaScript tarafında Zod aynı rolü üstlenir, OpenAI resmi Node SDK’sı zodResponseFormat helper’ı sunar.

Constrained Decoding Nasıl Çalışır?

Provider-native API’ları kullanamadığınızda (self-hosted Llama, Mistral, Qwen) veya regex/CFG seviyesinde kontrol istediğinizde constrained decoding devreye girer. Outlines library’sinin mantığı şudur: her decoding adımında modelin ürettiği logit vektörünü alır, JSON Schema’dan derlenen finite state machine’e (FSM) bakar, mevcut durumda geçerli olmayan token’ların logit’ini -inf yapar, softmax sonrası bu token’lar olasılık 0 alır, sampling yalnız geçerli token’lardan yapılır. Sonuç: çıktı şemaya 100% uyar, model halüsine etse bile geçersiz JSON üretmesi matematiksel olarak imkansızdır.

• Outlines (github.com/dottxt-ai/outlines): JSON Schema, Pydantic, regex, context-free grammar, choice (enum) desteği. Hugging Face Transformers, llama.cpp, vLLM, MLX backend’leri.
• LMFE (lm-format-enforcer): Microsoft tarafından geliştirildi, tokenizer-aware FSM, vLLM ve TGI ile entegre.
• vLLM Guided Decoding: docs.vllm.ai içinde guided_json, guided_regex, guided_choice parametreleri; backend olarak Outlines, LMFE veya XGrammar seçilebilir.
• XGrammar: 2024 sonu çıktı, CFG için pretokenized mask cache ile Outlines’tan 3-10x hızlı, vLLM 0.6+ default backend.

Latency etkisi backend ve şema karmaşıklığına bağlıdır. Basit flat JSON (5-10 alan) için +%5, nested + array of objects için +%10-15 tipiktir. vLLM benchmark’larında XGrammar ile overhead %2-5’e iner. Bu maliyet 0-1 parse error oranı karşılığında neredeyse her zaman kabul edilir; özellikle LLM Hallucination Azaltma stratejilerinin yapısal yarısını oluşturur.

Pydantic + Instructor Pratiği

Üretim kodunda en sık karşılaşılan pattern Pydantic modeli tanımla, Instructor ile sar, provider değiştir-değiştirme aynı çağrı imzasını kullan. Aşağıdaki kavramsal akış senaryodur:

from pydantic import BaseModel, Field
from typing import Literal
import instructor
from openai import OpenAI

class TicketClassification(BaseModel):
    category: Literal["billing", "technical", "account", "other"]
    priority: Literal["low", "medium", "high", "critical"]
    summary: str = Field(..., max_length=200)
    requires_human: bool

client = instructor.from_openai(OpenAI())

result = client.chat.completions.create(
    model="gpt-4o",
    response_model=TicketClassification,
    messages=[{"role": "user", "content": "..."}],
    max_retries=2,
)
# result tipi: TicketClassification, IDE autocomplete + tip güvenliği

Instructor’ın değer önermesi üç katmanlı: birincisi Pydantic modelini OpenAI response_format veya tool_use formatına otomatik çevirir, ikincisi validation hatasında otomatik retry (model self-corrects), üçüncüsü streaming destekli partial validation. max_retries=2 ile model şemaya uymazsa hata mesajıyla yeniden çağrılır, çoğu zaman 2. denemede düzelir. Bu yaklaşım Prompt Engineering disiplinini yapısal taraftan tamamlar.

Parse Error Oranları ve Üretim Metrikleri

Pratikte farklı yaklaşımların parse error oranlarını saha verisi olarak görmek karar süreçini hızlandırır. Aşağıdaki tablo halka açık benchmark’lardan ve büyük ölçekli deployment raporlarından derlenmiştir; rakamlar şemanın karmaşıklığına göre değişir (10-20 alan, 2-3 nested seviye varsayımı).

Yöntem	Parse error oranı	Retry sonrası	Şema ihlali (geçerli JSON ama yanlış alan)
Prompt-only (GPT-4o)	%3-8	%1-2	%5-12
Prompt-only (Llama 3.1 70B)	%8-15	%3-5	%10-20
OpenAI JSON Mode	%0.5-1	%0.1	%3-8
OpenAI Structured Outputs	%0	—	%0 (schema guaranteed)
Anthropic tool_use	%0.1-0.5	%0	%0.5-2
Outlines (local model)	%0	—	%0

Buradaki kritik ayrım geçerli JSON ile doğru şema arasındadır. JSON Mode geçerli JSON garantisi verir ama alan adlarını veya enum değerlerini doğrulamaz; Structured Outputs ve constrained decoding ikisini birden garanti eder. Üretim sistemi tasarlarken bu fark SLA’yi belirler: tek başına JSON Mode kullanan agent’lar hala downstream validation gerektirir, Structured Outputs/Outlines kullananlar şema seviyesinde temizdir.

Agent ve Tool Routing Senaryosu

Structured output’un en yoğun kullanıldığı yer agent mimarileridir. AI Agent Tasarım Pattern içinde modelin bir tool seçmesi ve doğru argümanlarla çağırması gerekir; serbest metinle bunu yapamazsınız. Tool tanımı = JSON Schema, tool çağrısı = structured output. Agentic AI iş akışlarında her node bir Pydantic modeliyle giriş/çıkış tanımlar, tüm sistem tipli bir graph haline gelir.

Pratik bir routing örneği: chatbot’a gelen mesaj 5 kategoriye yönlendirilecek (sipariş_sorgu, iade, teknik_destek, fatura, genel_bilgi). Model Literal[...] ile tanımlı bir enum dönerse, kod tarafında match-case ile router yazmak güvenlidir. Kurumsal Chatbot mimarisinde bu yaklaşım, regex-based intent detection’a göre %30-50 daha düşük yanlış routing verir.

RAG ve Bilgi Çıkarımı (Information Extraction)

RAG sistemleri çoğunlukla “ham metin → vector db → cevap” akışı sanılır ama olgun pipeline’larda yapılandırılmış meta-veri (entity, tarih, kategori, kaynak) çıkarımı kritik bir adımdır. PDF’lerden, e-postalardan, ticket’lardan yapılandırılmış alan çıkarımı için Pydantic modeli + LLM + Instructor üçlüsü endüstri standardıdır. RAG Altyapı yazısında detaylanan chunking + embedding adımının üstüne, structured extraction katmanı eklenir ve sonuç vector db meta-data filtresine girer.

• Entity extraction: kişi, kurum, ürün, lokasyon, tarih (NER yerine LLM + Pydantic).
• Sentiment + reason: yalnız polarite değil, gerekçeyi de structured field olarak çıkar.
• Form parsing: PDF/Word/scan → Pydantic model. Tax form, fatura, kontrat.
• Code analysis: kod parçasını al, fonksiyon imzalarını/imports/security issues structured döndür.
• Multimodal extraction: görüntüden tablo verisi → DataFrame şemasına uygun JSON.

Open source modellerle çalışıyorsanız Open Source LLM seçeneklerinde Llama 3.1, Mistral Large, Qwen 2.5 hepsi vLLM Guided Decoding ile structured output yapabilir; fine-tuning gerekmez, runtime’da şema dayatılır.

Schema Evolution ve Versiyonlama

Üretim sisteminde şemalar zamanla değişir: alan eklenir, enum genişler, alan adı değişir. Structured output kullanıyorsanız şema kod’la birlikte versiyonlanmalı, log’lara hangi şema sürümüyle çağrı yapıldığı yazılmalıdır. Pydantic v2 model_config = ConfigDict(extra='forbid') ile katı modda, extra='ignore' ile geriye dönük uyumlu modda kullanılır.

• Semver şemaları: TicketV1, TicketV2 sınıfları, model çağrısında hangi sürüm kullanıldığını trace.
• Backward compatibility: yeni alan eklerken Optional[X] = None default ile başlat.
• Migration test: eski şemayla üretilmiş JSON’lar yeni şemayla validate edilmeli (regression suite).
• Schema registry: organizasyon büyüdükçe central registry (örn. JSON Schema Store benzeri), json-schema.org referans implementasyonları.

Multi-provider agent sistemlerde MCP Model Context Protocol tool şemalarını standardize eder; provider’dan bağımsız structured output mümkün olur. MCP tool tanımları zaten JSON Schema, yani structured output ile native uyumludur.

Latency, Maliyet ve Streaming

Structured output ek overhead getirir mi? Cevap: az ama ölçülebilir miktarda. Provider-native API’larda overhead %2-10 arasında, ilk çağrıda şema derleme (FSM build) sebebiyle bir kerelik ek 50-200ms görülebilir; sonraki çağrılarda cache devreye girer. Self-hosted vLLM’de XGrammar backend ile overhead %2-5’e iner, Outlines klasik backend ile %5-15 olabilir. Anthropic Claude tool_use 200k+ context window’da bile structured output ek %3-7 latency ile sunar.

Senaryo	Baseline (serbest metin)	Structured output	Overhead
GPT-4o + JSON Schema (5 alan)	1.2s	1.27s	+5.8%
Claude 3.7 Sonnet + tool_use	1.5s	1.59s	+6.0%
Llama 3.1 70B + Outlines (vLLM)	0.9s	1.03s	+14.4%
Llama 3.1 70B + XGrammar (vLLM)	0.9s	0.94s	+4.4%
Gemini 2.0 Flash + responseSchema	0.6s	0.64s	+6.7%

Streaming senaryosunda Instructor Partial[Model] tipi ile akan token’ları kademeli Pydantic instance’a parse eder; UI tarafında her chunk geldikçe doğrulanmış field’ları gösterebilirsiniz. Bu özellikle uzun raporlar veya çok alanlı formlarda kullanıcı deneyimini iyileştirir.

Hata Yönetimi ve Retry Stratejileri

%100 schema conformance veren yöntemlerde bile semantik hatalar olabilir (model yanlış değer üretir ama şemaya uyar). Validation katmanı her zaman gereklidir:

1. Pydantic validator: alan içi iş kuralları (@field_validator). Örn. “iade tutarı 0 olamaz”.
2. Cross-field validator: @model_validator(mode='after') ile alanlar arası tutarlılık.
3. Instructor retry: validation hatası mesajını LLM’e geri besle, max_retries=2-3.
4. Circuit breaker: 3 başarısız retry sonrası human-in-the-loop’a yönlendir.
5. Logging: her validation hatası → structured log + metric (Prometheus counter).
6. Fallback model: küçük model başarısız olursa daha büyük modele eskalasyon.

Fine-tuning veya RAG ile structured output’un karşılaştırması için LLM Özelleştirme yazısı yöntemlerin trade-off’larını detaylandırır; structured output bunlardan biriyle değil hepsiyle bir arada kullanılır.

Üretim Önerileri ve Anti-Pattern’lar

Bu alanda 2023-2026 arasında birikmiş pratiğin damıtılmış halini özetlemek gerekirse, kurumsal projelerde dikkat edilmesi gereken birkaç temel ilke vardır. Ömer Önal olarak farklı sektörlerden gelen LLM entegrasyon taleplerini değerlendirdiğimde, sık tekrarlanan anti-pattern’ların listesi şudur:

• Şemayı prompt içine yapıştırmak: structured output API’sı varken şemayı sözel anlatmak gereksiz token + düşük garanti.
• Çok büyük şema: 50+ alanlı tek model yerine 3-5 küçük model + composition; debugging kolaylaşır.
• Free-form string için Literal kullanmamak: enum varsa Literal tipini kullan, model %30-50 daha az hata yapar.
• Description’sız alanlar: Field(..., description="...") JSON Schema’ya yansır, model performansı %10-20 iyileşir.
• Streaming’i atlamak: uzun çıktılarda kullanıcı 5 saniye boş ekran görür, partial parse ile akıt.
• Validation testi olmamak: golden dataset + property-based testing (Hypothesis) ile şema regresyon koru.
• Provider lock-in’i ihmal: Instructor veya LangChain abstraction kullanmazsan bir provider’a çakılırsın.

Ek kaynak olarak huggingface.co/blog structured generation yazıları, arxiv.org üzerinde “constrained decoding”, “grammar-guided generation” ve “JSON-mode LLM” araştırmaları (Willard & Louf 2023 Outlines paper’ı, Microsoft LMFE 2024 raporu, XGrammar 2024 paper’ı) okumaya değer.

Sıkça Sorulan Sorular (FAQ)

Sonuç

LLM structured output 2026 itibarıyla “isteğe bağlı iyileştirme” değil, üretim seviyesi LLM uygulamasının temel bileşenidir. OpenAI Structured Outputs ve Anthropic tool_use ile provider-native, vLLM Guided Decoding (XGrammar/Outlines) ile self-hosted tarafta %100 schema conformance erişilebilir bir hedeftir. Pydantic v2 + Instructor kombinasyonu Python ekosisteminde, Zod + OpenAI SDK TypeScript tarafında endüstri standardıdır. Latency overhead %5-15 aralığında kabul edilebilir, parse error oranı %0’a iner, retry mantığı sadeleşir, downstream sistem tipli kontratla çalışır. Yapısal çıktı zorunluluğu RAG, agent, chatbot, veri çıkarımı ve otomasyon iş akışlarında doğrudan SLA’ya, maliyete ve geliştirici deneyimine yansır.

Kurumsal LLM altyapısı, agent mimarisi, RAG pipeline veya structured extraction sistemi tasarımı için danışmanlık ve uygulama destek talepleriniz için omeronal.com/iletisim/ sayfasından iletişime geçebilirsiniz.