JSON mode ya da structured output hep çalışır mı?

Output Format Kontrolü: JSON, Markdown, Tablo

Claude'un çıktısını parse edilebilir, tutarlı ve hatasız almak için format kontrolünün üç tekniğini ustalaş: schema, prefill, validator-loop.

Şükrü Yusuf KAYA

13 dakikalık okuma

13.05.2026

Orta

JSON, Markdown ve tablo çıktılarını üreten format kontrol pipeline'ı

Üç teknik, sıfır toleranslı format

Format hatası genelde geliştiriciyi en çok yakan şeydir. Bu derste schema-driven prompting, assistant prefill ve validator-loop tekniklerini öğreneceksin.

Format Kontrolü Neden Bu Kadar Önemli?

Çıktıyı bir başka sistem (parser, UI, başka API) tüketecekse, her küçük format sapması bug demektir. Bizim için ideal: çıktı her seferinde aynı kalıpta.

Format pipeline: schema → prefill → model → validate → retry — Format kontrol pipeline'ı: schema, prefill, model, validate, retry.

Teknik 1 — Schema-Driven Prompting#

Çıktıyı bir JSON schema ile sınırla. Schema'yı doğrudan prompt'a yapıştır.

text

<output_schema>
{
  "type": "object",
  "required": ["category", "confidence", "next_action"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["auth", "billing", "tech", "other"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "next_action": {
      "type": "string",
      "maxLength": 120
    }
  },
  "additionalProperties": false
}
</output_schema>
 
<rules>
Sadece geçerli JSON döndür. Açıklama / yorum ekleme.
Bilinmeyen alan ekleme. Schema'ya tam uymayan değer üretme.
</rules>

JSON schema'yı doğrudan prompt'ta vermek — hata oranını dramatik düşürür.

Teknik 2 — Assistant Prefill#

API çağrılarında

assistant

mesajını yarım bırakarak başlatabilirsin. Claude o noktadan devam eder. Bu, formatı fizik olarak zorlar.

python

# Anthropic SDK ile prefill örneği
import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="Sen bir destek bileti sınıflandırıcısısın. Sadece geçerli JSON döndür.",
    messages=[
        {"role": "user", "content": "Şifremi sıfırlayamıyorum"},
        {"role": "assistant", "content": "{"},  # ← prefill
    ],
)
 
# Çıktı garantili '{' ile başlar, JSON parse'a hazır
text = "{" + response.content[0].text
print(text)

Prefill — JSON formatını fiziksel olarak zorlamanın en sağlam yolu.

Teknik 3 — Validator-Loop#

Schema doğrulamasını kodla yap; başarısızsa aynı hata mesajını Claude'a yolla ve düzeltmesini iste.

python

# Sentetik validator loop demo
import json
 
def validate(payload: str) -> tuple[bool, str]:
    try:
        obj = json.loads(payload)
    except json.JSONDecodeError as e:
        return False, f"JSON parse hatası: {e}"
    if "category" not in obj:
        return False, "category alanı eksik"
    if obj["category"] not in {"auth","billing","tech","other"}:
        return False, "category enum dışı: " + str(obj["category"])
    if not (0.0 <= obj.get("confidence", -1) <= 1.0):
        return False, "confidence 0..1 aralığında olmalı"
    return True, "ok"
 
# Bozuk cevap
bozuk = '{"category":"login","confidence":1.4}'
ok, msg = validate(bozuk)
print("Geçerli mi?", ok, "—", msg)
 
# Düzeltilmiş cevap (Claude bir tur sonra dönecek diye varsay)
duzelt = '{"category":"auth","confidence":0.91,"next_action":"şifre sıfırlama linki gönder"}'
ok, msg = validate(duzelt)
print("Geçerli mi?", ok, "—", msg)

Validator-loop — başarısız çıktıyı geri besle, model düzeltsin.

json · diff modu

Senin kodun

Hedefe karşı diff

+ // Üretim seviyesi: schema + prefill
- // Naif istek — olası başarısızlık
  {
    "model": "claude-sonnet-4-6",
+   "system": "Sınıflandırıcı. Sadece geçerli JSON. Schema: {...}",
    "messages": [
+     {"role": "user", "content": "Şu bileti sınıflandır: ..."},
+     {"role": "assistant", "content": "{"}
+   ],
+   "max_tokens": 256,
+   "temperature": 0.0
-     {"role": "user", "content": "Şu bileti sınıflandır: ..."}
-   ]
  }

İki istek arası fark — gece uykunu çalan format buglarını ortadan kaldırır.

Boşluk doldur · text

Çıktı formatını kontrol etmenin üç tekniği: schema, _____ ve _____ -loop. JSON formatını fiziksel olarak zorlayan teknik _____ olarak adlandırılır.

Sık Sorulan Sorular

Modelin Tool Use ya da structured output desteğiyle birleşince çoğu durumda çok yüksek isabetle çalışır. Ama yine de validator-loop ile sigorta atmayı bırakma — kritik production yollarında doğrulama olmadan asla.

Yorumlar & Soru-Cevap

(0)

Yorum yazmak için giriş yap.

Yorumlar yükleniyor...