Skip to content

Structured Output Pitfalls: JSON Mode Token Greed and the Real Cost of Tool-Use Forcing

Using JSON mode doesn't mean 'fewer tokens' — in most cases it uses **more tokens**. Schema complexity, field name length, escape characters — all hidden token costs. This lesson covers cost-aware structured output design.

Şükrü Yusuf KAYA
16 min read
Intermediate
Structured Output Tuzakları: JSON Mode Token Açgözlülüğü ve Tool-Use Forçalamanın Gerçek Maliyeti
🏗 Strüktürlü output bedavaya gelmiyor
JSON output, parse etmeyi kolaylaştırıyor. Ama token açısından dikkat etmediğin sürece structured output free-text'ten daha pahalıya gelir. Bu derste 6 prensip görüyoruz.

Free Text vs JSON — Token Karşılaştırma#

Aynı veriyi temsil etmenin iki yolu:

Free text (45 token)#

Müşterinin adı Ahmet Yılmaz. Sorunu kargonun gelmemesi. Aciliyet: yüksek.

JSON (72 token)#

{
  "customer_name": "Ahmet Yılmaz",
  "issue_type": "delivery_delay",
  "urgency": "high"
}
JSON %60 daha çok token! Bracket'ler, tırnaklar, virgüller, field name'ler — hepsi token.

Verdict#

Eğer downstream gerçekten JSON parse etmiyorsan, JSON kullanma. Free text + regex/heuristic yeterliyse, JSON token israfı.

Prensip 1 — Kısa Field Name'ler#

JSON çıktısında field name'ler her seferinde yer kaplıyor.

Before (52 token)#

{
  "customer_full_name": "Ahmet",
  "customer_email_address": "ahmet@example.com",
  "request_priority_level": "high",
  "issue_description": "..."
}

After (38 token)#

{
  "name": "Ahmet",
  "email": "ahmet@example.com",
  "priority": "high",
  "issue": "..."
}
%27 tasarruf, sadece field name'leri kısaltarak.

Prensip 2 — Enum Kullan (Open String Yerine)#

Enum tip'ler model'e kısıtlı seçenek verir, daha az token üretir.

Before#

"category": "Bu mesaj iade ile ilgili görünüyor, kullanıcı iade talep ediyor"

After (schema'da enum)#

"category": "return"  ← max 1-2 token
Schema:
{
  "category": {
    "type": "string",
    "enum": ["return", "shipping", "payment", "product", "account"]
  }
}
Model schema'yı görür, sadece enum değerlerinden birini üretir.

Prensip 3 — Flat Structure, Avoid Deep Nesting#

// Deep (152 token)
{
  "customer": {
    "profile": {
      "personal": {
        "name": "Ahmet",
        "contact": {
          "email": "ahmet@..."
        }
      }
    }
  }
}

// Flat (62 token)
{
  "name": "Ahmet",
  "email": "ahmet@..."
}
Her nesting level bracket'leri ekler. %60 token tasarrufu.

Prensip 4 — Sadece İstediğin Alanları Schema'ya Koy#

Modeller schema'daki tüm field'ları doldurmaya çalışır. Optional field'lar sana lazım değilse onları çıkar — model token üretmeye gerek duymaz.

Schema'da gereksiz alan#

// Schema:
{
  "name": "string",
  "email": "string",
  "category": "string",
  "subcategory": "string",  // bunu zaten kullanmıyorsun
  "tags": "array"           // bunu da
}

// Output:
{
  "name": "Ahmet",
  "email": "ahmet@...",
  "category": "return",
  "subcategory": "broken_item",  // israf
  "tags": ["urgent", "vip"]      // israf
}
Schema'yı yalnızca gerçekten kullandıkların ile sınırla.

Prensip 5 — Tool Use mu, JSON Mode mu, Free Text + Regex mi?#

Üç yöntem var:

A — JSON Mode (
response_format: json_schema
)#

  • ✅ Schema enforcement guaranteed
  • ✅ Parse error yok
  • ⚠️ +%5-10 token (schema prefill)

B — Tool Use forçalama#

  • ✅ Schema enforcement
  • ✅ Multi-tool routing imkanı
  • ⚠️ Tool definition token'ı (200-500 ek input)
  • ⚠️ +%10-15 token total

C — Free text + parsing#

  • ✅ Minimum token
  • ❌ Parse error riski (5-10% durumda format kırılır)
  • ❌ Manuel retry logic gerekli

Tavsiye#

SenaryoYöntem
Mission-critical structured (financial, medical)JSON Mode
Multi-route agentTool Use
High-volume classification + edge case tolerantFree text + regex
Yes/no questionFree text
Simple key-value extractionFree text + regex

Prensip 6 — Output Prefilling (Anthropic-spesifik)#

Anthropic'te modele "cevabın
{
ile başlasın" diyebilirsin. Cevap garanti JSON başlar.
response = client.messages.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "Müşteri mesajını analiz et: ..."},
        {"role": "assistant", "content": "{"},  # ← prefill
    ],
)

result = "{" + response.content[0].text  # "{...} JSON"
Bu pattern:
  • ✅ Schema overhead yok
  • ✅ Format guarantee
  • ✅ %5-8 daha az output token (preamble cümleler yok)
  • ❌ Sadece Anthropic'te çalışır

Side-by-Side Maliyet Karşılaştırma#

Aynı görev, 4 farklı yaklaşım:
YaklaşımInputOutputToplam $/100 istek
Free text20080$0.18
JSON Mode (verbose schema)250120$0.255
JSON Mode (optimal schema)22090$0.21
Anthropic prefill20075$0.18
Tool Use forçalama400100$0.330

Sonuç#

  • Anthropic prefill en ekonomik structured (kalite + cost dengeli)
  • JSON Mode optimal schema ikinci tercih (provider-agnostik)
  • Tool Use sadece routing gerekli ise
▶️ Sıradaki ders
5.6 — Output Kısaltma Teknikleri. max_tokens, stop sequences, format kısıtlamaları, "be terse" prompt. Output token'ı pahalı tarafta — burada %50 tasarruf doğrudan faturana yansır.

Frequently Asked Questions

Yes — each field's description is added to input tokens (so the model understands the schema). If field name is self-explanatory, remove description. Necessary for complex business rules, but half the wording is unnecessary.

Yorumlar & Soru-Cevap

(0)
Yorum yazmak için giriş yap.
Yorumlar yükleniyor...

Related Content

Module 0: Why Cost, Why Now?

The AI Cost Explosion: Why Token Prices Fell 96% from 2022 to 2026 — Yet Bills Grew 40×

Start Learning
Module 0: Why Cost, Why Now?

Unit Economics Vocabulary: COGS, Gross Margin, $/User, Contribution Margin — 9 Financial Concepts Every AI Engineer Must Know

Start Learning
Module 0: Why Cost, Why Now?

Workshop Toolkit: A Quick Tour of the 11 Tools We'll Use Throughout the Course

Start Learning

Connected pillar topics

Pillar topics this article maps to

Pillar Topic

Agentic AI and Autonomous Systems

Agentic AI is the architecture in which a large language model — instead of producing a single answer — autonomously completes multi-step tasks by combining planning, tool use, memory and feedback loops.