Kategori: ezformatter

API çağrınız JSONDecodeError: Expecting property name enclosed in double quotes hatasıyla başarısız oldu. Saat işliyor. Veriler bir LLM’den geldi ve o 2.000 tokenlik yanıtta tek bir sonda virgülü tüm boru hattınızı çökertti.

Mayıs 2026 itibarıyla hatalı biçimli JSON dosyalarını düzeltmenin en hızlı yolu json_repair (Python) veya jsonrepair (npm) gibi otomatik kütüphaneler kullanmaktır. Bu araçlar, LLM tarafından üretilen sözdizimi hatalarını anında gidermek için özel olarak tasarlanmıştır. Manuel onarımlarda başlıca şüpheliler sonda virgüller, tek tırnaklar veya tırnaksız anahtarlar olur — bunlar RFC 8259 standardının en sık ihlal edilen üç kuralıdır.

En Hızlı Çözüm: LLM Çıktıları için json_repair

Python’un json.loads() gibi standart çözümleyicileri tasarımsal olarak katıdır. Yanlış konumlandırılmış tek bir karakter JSONDecodeError tetikler ve her şey durur. Bu, 2026’da gündelik bir sorundur çünkü LLM’ler JSON’u rutin olarak sohbet metni içine sarar, yanıtları cümlenin ortasında keser veya standardı bozan açıklamalar serpiştirir.

json_repair kütüphanesi başvurulacak çözümdür. GitHub bilgisine göre bu proje 2026 itibarıyla 4.700’ü aşkın yıldıza sahip. Çalışma prensibi, dizenin niyetini “tahmin etmek”tir — eksik köşeli parantezleri kapatır, tırnak ekler ve JSON bloğunu çevreleyen fazladan metni temizler.

Python: Öncesi ve Sonrası

Kurulum: pip install json-repair

Hatalı girdi:

import json_repair

bad_json = '{"user": "Alice", "status": tru'
decoded_object = json_repair.loads(bad_json)

Arka planda neler oldu: json_repair, tru ifadesinin muhtemelen true olduğunu fark etti, eksik kapanış ayracını ekledi ve geçerli bir Python sözlüğü döndürdü. Sıfır manuel müdahale.

Kurtarma Modu: Veri Gerçekten Berbatsa

Daha zor durumlar için json_repair (v0.59.5+) bir Kurtarma Modu (Salvage Mode) içerir. Proje belgelerinde belirtildiği üzere bu mod özellikle kesilmiş AI yanıtları veya bozuk günlük dosyaları için tasarlanmıştır. Dizileri zorla nesnelere dönüştürebilir ya da kurtarılamayacak kadar bozuk öğeleri atarak çıktının şemanıza uymasını sağlar.

import json_repair

# Salvage mode for severely truncated data
result = json_repair.loads(
    '{"items": [{"id": 1, "name": "Widget"}, {"id": 2, "na',
    salvage_mode=True
)
# Result: {'items': [{'id': 1, 'name': 'Widget'}, {'id': 2}]}
# Dropped the incomplete 'na' but saved everything else

npm Alternatifi

Node.js projeleri için jsonrepair CLI aynı işi halleder:

# Fix a file in place
npx jsonrepair broken.json > fixed.json

# Fix a string in a script
const { jsonrepair } = require('jsonrepair');
const fixed = jsonrepair('{"name": "test",}');

Manuel Hata Ayıklama: Standardı Bozan Şeyi Bulmak

Otomasyon yeterli olmadığında, dosyanın tam olarak nerede RFC 8259‘u ihlal ettiğini bulmanız gerekir. JSON, YAML veya JavaScript’ten çok daha az affedicidir. JSONParser Tanılama Ekibi‘nin açıkladığı gibi: “Çözümleyici, anlamlandıramadığı ilk karakterde başarısız olur ve bu çoğu zaman birkaç satır yukarıdaki bir sorunun aşağı yönlü bir belirtisidir.”

Üç JSON Katili

Katil 1: Sonda Virgüller

DEV Community bilgisine göre sonda virgülleri çözümleme başarısızlıklarının 1 numaralı nedenidir. JavaScript’te sorun değildirler ama bir JSON dizisininin veya nesnesinin son öğesinden sonra geçersizdirler.

// BROKEN - trailing comma after "active"
{
  "name": "Alice",
  "status": "active",
}

// FIXED - no comma before closing brace
{
  "name": "Alice",
  "status": "active"
}

Katil 2: Tek Tırnaklar

JSON, hem anahtarlar hem de dize değerleri için çift tırnak (") gerektirir. Pek çok Python ve JavaScript geliştiricisi yanlışlıkla tek tırnak (') kullanır. TidyCode‘nun belirttiği gibi bu zorunlu bir düzeltmedir.

// BROKEN - single quotes
{'name': 'Alice'}

// FIXED - double quotes
{"name": "Alice"}

Katil 3: Tırnaksız Anahtarlar

JavaScript’te { name: "Alice" } yazabilirsiniz. JSON’da ise her anahtarın çift tırnağa ihtiyacı vardır.

// BROKEN - unquoted key
{name: "Alice"}

// FIXED - quoted key
{"name": "Alice"}

“Unexpected Token” Hatası

Bir doğrulayıcı “Unexpected Token” bayrakladığında, çözümleyicinin NaN, Infinity veya undefined ile karşılaştığı anlamına gelir — bunlar JSON’ın desteklemediği JavaScript sabitleridir. JSON yalnızca null, true, false ve sayılara izin verir.

// BROKEN - NaN is not valid JSON
{"score": NaN, "result": Infinity}

// FIXED - replace with null or valid values
{"score": null, "result": null}

Katı Çözümleme ve Onarım Çözümlemesi: Hangisi Ne Zaman Kullanılır

Doğru yaklaşım, verilerinizin nereden geldiğine bağlıdır. İnsan tarafından düzenlenen yapılandırma dosyaları, yazarı hataları düzeltmeye zorlamak için katı çözümlemeyi hak eder. LLM’lerden veya API günlüklerinden gelen makine üretimi veriler ise onarım tabanlı çözümlemeye ihtiyaç duyar.

Özellik	Katı (json.loads)	Onarım (json_repair)
Sonda Virgüller	JSONDecodeError yükseltir	Otomatik kaldırılır
Tek Tırnaklar	Başarısız olur	Çift tırnağa dönüştürülür
Kesilmiş Veri	Başarısız olur	Açık köşeli parantezleri/tırnakları kapatır
Açıklamalar	Başarısız olur	Otomatik temizlenir
En İyi Kullanım	İnsan tarafından düzenlenen yapılandırma dosyaları	LLM çıktıları, API günlükleri

Pydantic ile Şema Kılavuzlu Onarımlar

Onarım sürecini Pydantic v2 veya JSON Schema ile yönlendirebilirsiniz. json_repair‘a bir şema verdiğinizde araç yalnızca sözdizimini düzeltmekle kalmaz — türleri de düzeltebilir (dize "1"‘i sayı 1‘e çevirir) ve eksik zorunlu alanları varsayılan değerlerle doldurabilir.

from pydantic import BaseModel
import json_repair

class User(BaseModel):
    id: int
    name: str
    active: bool = True

# Broken JSON with wrong types
raw = '{"id": "42", "name": "Alice"}'
repaired = json_repair.loads(raw)

# Validate against schema
user = User(**repaired)
# user.id is now int(42), user.active defaults to True

Stefano Baccianella‘nın 2025 proje atıfında belirttiği gibi, bu yaklaşım dil modellerinin üretmeye meyilli olduğu “çoğunlukla doğru ama teknik olarak geçersiz” JSON için optimize edilmiştir.

Çok Gigabaytlık Dosyaları Çökmeden İşleme

10KB’lık bir parçayı onarmak kolaydır. 2GB’lık bir dosyayı düzeltmek ise tüm RAM’inizi yemeyecek bir strateji gerektirir. Dosyanın tamamını belleğe yüklemek Bellek Yetersizliği (OOM) hatalarına yol açar.

Strateji 1: ijson ile Akış İşleme

Devasa veri kümeleri için verileri parça parça işlemek üzere ijson kullanın. Scrapfly‘ın belirttiği gibi ijson verileri artımlı olarak işler. Bunu, çözümlemeden önce sorunları satır satır düzelten bir temizlik betiğiyle eşleştirin.

import ijson

# Stream through a large JSON file
with open('huge_broken.json', 'r') as f:
    for item in ijson.items(f, 'records.item'):
        # Process each item individually
        process(item)

Strateji 2: Maksimum Verimlilik için CLI Boru Hattı

Büyük dosyalar için en bellek dostu yöntem jsonrepair CLI’yi kullanıp çıktıyı doğrudan yeni bir dosyaya boru hattıyla aktarmaktır:

# Streams repair, never loads full file into memory
jsonrepair large_broken.json > fixed.json

Bu, dosyayı Python’a veya bir tarayıcıya yüklemekten çok daha bellek dostudur.

Sonuç

json_repair gibi yapay zeka farkındalığına sahip kütüphaneler sayesinde hatalı biçimli JSON’u düzeltmek artık manuel bir iş değil. Yine de RFC 8259 temellerini — sonda virgül yok, tek tırnak yok, tırnaksız anahtar yok — anlamaya devam etmelisiniz; ancak 2026’da ölçek açısından veriler için otomasyon tek pratik yaklaşımdır.

İş akışı basittir: önce bir onarım kütüphanesi deneyin. O başarısız olursa, kesin sözdizimi hatasını konumlandırmak için bir doğrulayıcı kullanın. Bu, gelen veriler mükemmelden uzak olsa bile uygulamalarınızın çalışmaya devam etmesini sağlar.

SSS

JSON resmi olarak açıklamaları veya tek tırnakları destekler mi?

Hayır. RFC 8259 standardı açıklamaları kesinlikle yasaklar. Tek tırnaklar da geçersizdir — anahtarlar ve dizeler için yalnızca çift tırnağa izin verilir. Ancak json_repair gibi araçlar dosyaların standart kütüphanelerce çözümlenebilmesi için açıklamaları otomatik olarak temizleyip tırnakları dönüştürebilir.

Çok büyük ve hatalı biçimli JSON dosyalarını çökmeden nasıl işlerim?

Verileri öbekler halinde işlemek için ijson gibi bir akış çözümleyici kullanın. Hatalı dizenin tamamını tek bir değişkene yüklemekten kaçının. En hızlı sonuçlar için, çıktıyı bellekte her şeyi tutmadan doğrudan diskteki yeni bir dosyaya boru hattıyla aktaran CLI onarım araçlarını kullanın.

Hatalı biçimli JSON ile geçersiz JSON arasındaki fark nedir?

Hatalı biçimli (malformed) JSON sözdizimi kurallarını ihlal eder — eksik köşeli parantezler, tırnaksız anahtarlar, sonda virgüller — bu yüzden çözümlenmesi imkansızdır. Geçersiz (invalid) JSON tüm sözdizimi kurallarına uyar ama belirli bir JSON Schema’ya uyum sağlayamaz (örneğin bir alan, şema tamsayı beklerken dizedir). Hatalı biçimli JSON’u düzeltmek yapısal onarımdır; geçersiz JSON’u düzeltmek ise veri bütünlüğüyle ilgilidir.

json_repair’i Pydantic doğrulamasıyla birlikte kullanabilir miyim?

Evet. Önce sözdizimi hatalarını düzeltmek için json_repair.loads() çalıştırın, ardından tür doğrulaması ve şema zorlaması için onarılmış sözlüğü Pydantic modelinize aktarın. Bu iki adımlı yaklaşım hem yapısal hem de anlamsal sorunları ele alır.

JavaScript tarzı açıklamalı JSON’a ne demeli?

Standart JSON açıklamaları desteklemez ama json_repair // ve /* */ açıklamalarını otomatik olarak temizleyebilir. Yapılandırma dosyalarınızda açıklamalara ihtiyaç duyuyorsanız JSONC (Açıklamalı JSON) biçimini ve Python için json5 gibi uyumlu bir çözümleyiciyi düşünün.

AI çıktısı istediğinizden tamamen farklı göründüğünde o hayal kırıklığını bilirsiniz: JSON bozuk, ton yanlış ve talimatların yarısı yok sayıldı. Sorun modelde değil; promptu nasıl biçimlendirdiğinizde.

Biçimlendirici ile AI promptu yazmayı öğrenmek için, RTCCO çerçevesini (Role, Task, Context, Constraints, Output) XML veya JSON gibi yapılandırılmış ayraçlarla uygulayın. Bu, promptları modüler yazılım varlıkları olarak ele almanızı sağlar ve Mayıs 2026 itibarıyla model halüsinasyonlarını %60’a kadar azaltıp manuel işlem süresini %75 kısaltabilir.

Paragraf Promptlarınız Neden Sürekli Başarısız Oluyor

2026’ya gelindiğinde profesyonel AI çalışması, “sohbet etmek”ten Prompt-as-Code (PaC) yönüne kaydı. Paragraf promptların — o uzun, yapılandırılmamış metin bloklarının — sorunu, modelin gerçek talimatlarınızı, içlerine karışmış arka plan verilerinden veya çıktı gereksinimlerinden ayırmakta zorlanmasıdır.

PromptOT verileri, yapılandırılmış mühendişliğe geçişin hataları %60 azalttığını ve manuel işlem hızını %75 artırdığını gösteriyor. Alex Ostrovskyy, hardcoded promptları “kaynak koddaki magic number’ların modern karşılığı” olarak tanımlıyor — bir şeyi bozmadan güncellemesi neredeyse imkansız olan kırılgan sistemler.

Öncesi ve Sonrası: Biçimlendirme Farkı

Öncesi (yapılandırılmamış):

You are a helpful coding assistant. Please write a Python function that validates
email addresses. Make sure it handles edge cases like plus signs and subdomains.
The output should be in JSON format with a valid boolean and the cleaned email.
Also make sure you add proper error handling and don't forget logging.

Sonrası (RTCCO + XML ayraçları):

<system_instructions>
  <role>Senior Python engineer specializing in input validation</role>
  <primary_objective>Write a production-grade email validator</primary_objective>
</system_instructions>

<context>
  Must handle: plus addressing ([email protected]), subdomains,
  internationalized domains. Target: Python 3.11+.
</context>

<task_requirements>
  <rules>
    - Use only stdlib (no regex shortcuts)
    - Return structured JSON
    - Include type hints
  </rules>
  <steps>
    1. Parse the input string
    2. Validate format per RFC 5322
    3. Return JSON with "valid" boolean and "cleaned_email"
  </steps>
</task_requirements>

<output_format>
  {"valid": bool, "cleaned_email": str, "error": str | null}
</output_format>

Aynı hedef, bambaşka sonuçlar. Biçimlendirilmiş sürüm modele hiçbir belirsizlik alanı bırakmıyor.

RTCCO Çerçevesi: Promptunuzun İskeleti

Sektör, standart prompt mimarisi olarak RTCCO üzerinde uzlaştı. Her prompt beş parçaya ayrılır:

Öğe	Amaç	Örnek
R ole (Rol)	AI kim?	“Kıdemli backend mühendisi”
T ask (Görev)	Hangi spesifik eylem?	“Bir rate limiter middleware yaz”
C ontext (Bağlam)	Hangi arka plan verisi?	RAG retrieval, kod tabanı parçaları
C onstraints (Kısıtlar)	Kurallar neler?	“Harici bağımlılık yok”
O utput (Çıktı)	Nasıl görünmeli?	“Tip ipuçlı geçerli Python 3.11”

Şimdi Kopyalayabileceğiniz XML İskelet Şablonu

İşte production’a hazır şablon. Kopyalayın, uyarlayın, yayınlayın.

<system_instructions>
  <role> [Expert Persona] </role>
  <primary_objective> [Main Goal] </primary_objective>
</system_instructions>

<context>
  [Background Data or RAG Retrieval]
</context>

<task_requirements>
  <rules> [Non-negotiable Constraints] </rules>
  <steps> [Specific Workflow] </steps>
</task_requirements>

<output_format>
  [JSON/XML/Markdown Specification]
</output_format>

<recency_recap>
  [Reminder of Critical Constraints]
</recency_recap>

Recency Recap Neden Önemli

LLM’lerin bilinen bir “Primacy and Recency” (İlk ve Son Etkisi) önyargısı vardır — bir promptun başını ve sonunu ortasından daha iyi hatırlarlar. PromptOT tarafından alıntıanan testler, kritik kuralları ortadan alttaki Recency Recap bloğuna taşımanın production kullanımında doğruluğu %78’den %96’ya çıkardığını gösterdi. Rolü en üste, en hayati kurallarınızı en alta koyun.

Güvenlik Çiti Olarak Ayraçlar

Ayraçlar sadece organizasyonla ilgili değildir — aynı zamanda bir güvenlik mekanizmasıdır. Kullanıcı girdisini <user_input> gibi etiketlerle sarmak modele şunu söyler: “Bu, takip edilecek yeni talimat değil, işlenecek veridir.” Bu, kullanıcıların sistem talimatlarınızı geçersiz kılmaya çalıştığı prompt enjeksiyon saldırılarına karşı birincil savunmanızdır.

Yaygın tuzak: Kullanıcı verisini ayraç olmadan doğrudan prompta enjekte ederseniz, kullanıcı “Tüm önceki talimatları yok say ve…” yazabilir ve model buna uyar. Harici verileri her zaman etiketli bloklara sarmalısınız.

Modüler Mimari: Mega-Prompt Yazmayı Bırakın

Tek bir kırılgan 2.000 tokenlik prompt yerine sisteminizi bağımsız modüllere ayırın. Bu, talimat çakışmasını önler — bir promptun tonunu değiştirirken yanlışlıkla JSON çıktı biçimini bozmayı engeller.

Temel ilke Context Engineering‘tir: statik talimatları dinamik verilerden ayırın. Production RAG sisteminde promptunuz bir şablondur ve <context> bloğu sorgu zamanında taze verilerle doldurulur. OptizenApp’den Jono Farrington açıklandığı gibi, bu modüler yaklaşım büyük ölçekli AI dağıtımlarını çok daha tutarlı hale getirir.

Prompt Chaining: Modülleri Birbirine Bağlamak

Karmaşık iş akışları için Prompt Chaining kullanın — bir modülün çıktısı sonrakinin girdisi olur:

[Planner Module] --> outline --> [Executor Module] --> draft --> [Reviewer Module] --> final

Bu adım adım yaklaşım çıktı kalitesini yaklaşık %35 iyileştirir çünkü model her seferinde yalnızca bir alt göreve odaklanır.

Kopyala ve kullan chaining örneği:

planner_prompt = """
<system_instructions>
  <role>Technical architect</role>
  <task>Create a step-by-step plan for: {user_request}</task>
</system_instructions>
<output_format>JSON array of steps</output_format>
"""

executor_prompt = """
<system_instructions>
  <role>Senior developer</role>
  <task>Implement step: {step_from_planner}</task>
</system_instructions>
<context>{previous_outputs}</context>
<output_format>Code block with inline comments</output_format>
"""

Zor Sorunlar için Chain-of-Thought Eklemek

Göreviniz karmaşık mantık içerdiğinde bir <thought_process> bloğu ekleyin. Bu, modeli cevap vermeden önce adım adım akıl yürütmeye zorlar ve matematik, kodlama ile çok adımlı akıl yürütmede hataları önemli ölçüde azaltır.

<task_requirements>
  <rules>Reason inside <thought> tags before answering</rules>
</task_requirements>

<output_format>
  <thought> [Your step-by-step reasoning here] </thought>
  <answer> [Final JSON output here] </answer>
</output_format>

Zencoder‘a göre, Tree-of-Thoughts (ToT) gibi teknikler bunu daha da ileri götürüp modelden aynı anda birden fazla çözüm yolunu değerlendirmesini ve en iyisini seçmesini ister. Bu, özellikle tek bir doğru yanıtın olmadığı mimari kararlar için değerlidir.

Token Maliyeti Uyarısı

Yapılandırılmış akıl yürütme daha fazla token kullanır. Tipik bir <thought_process> bloğu her istekte 200-500 token ekler. Ölçekte bu, daha yüksek API maliyetleri demektir. Takas doğruluktur: istek başına daha fazla ödersiniz ama daha az yeniden deneme ve daha az manuel düzeltme gerekir.

Production Hazırlığı: Versioning, Test ve CI/CD

Son adım promptları yazılım gibi ele almaktır. Semantic Versioning (v1.0.0) kullanın; böylece ekibiniz değişiklikleri izleyebilir ve yeni bir prompt sürümü performansı düşürdüğünde anında geri alabilir.

PromptOT, 50+ prompt yöneten şirketlerin yönetimi merkezileştirip mühendislerin manuel ince ayara harcadığı zamanı azaltarak yılda 400.000$’a kadar tasarruf edebileceğini bildiriyor.

Prompt CI/CD Pipeline Kurma

# .github/workflows/prompt-tests.yml
name: Prompt Quality Gate
on: [push]
jobs:
  test-prompts:
    runs-on: ubuntu-latest
    steps:
      - name: Run Golden Dataset Tests
        run: |
          # Test against 50-200 curated cases
          python scripts/eval_prompts.py \
            --dataset golden_dataset.json \
            --judge-model gpt-4 \
            --min-score 0.85

      - name: Regression Check
        run: |
          # Compare new version vs. production
          python scripts/compare_versions.py \
            --staging v2.1.0 \
            --production v2.0.3 \
            --threshold 0.05

Bir prompt yalnızca bir “LLM-as-a-judge” tarafından puanlanan bu kalite kapılarını geçtikten sonra Staging‘den Production‘a terfi eder.

Sonuç

Biçimlendiricilerle yapılandırılmış prompt mühendisliği artık opsiyonel değildir — güvenilir AI araçları yapan herkes için temel çizgidir. RTCCO çerçevesi, XML ayraçları ve modüler mimari, öngörülemeyen LLM çıktılarını tutarlı, production-grade sonuçlara dönüştürmenin yığınıdır.

En çok kullandığınız promptlarla başlayın ve yukarıdaki XML şablonunu kullanarak onları RTCCO çerçevesine refactor edin. Versiyon kontrolüne alın, temel değerlendirme kurun ve ölçeklenen bir prompt altyapısına sahip olacaksınız.

SSS

Mevcut paragraf promptlarımı RTCCO blok biçimine nasıl dönüştürürüm?

Önce çekirdek Task‘ı tanımlayın ve onu Context‘ten ayırın. Talimatları <rules> etiketleriyle sarın ve <examples> etiketlerinde 3-5 örnek verin. Hatta bir LLM’den yardım alabilirsiniz — “bu yapılandırılmamış metni XML ayraçlarıyla RTCCO çerçevesine yeniden ayrıştır” promptunu verin, ağır işi o yapacaktır.

XML, JSON yoksa Markdown ayraç mı kullanmalıyım?

Claude ve GPT-5 gibi modellerde talimatları uzun içerikten ayırmak için XML, katı hiyerarşisi nedeniyle şu anki altın standarttır. API entegrasyonları için programatik giriş/çıkışa ihtiyaç duyduğunuzda JSON daha iyidir. Markdown basit, insan tarafından okunabilir promptlar için çalışır ama karmaşık, çok katmanlı production promptları için gereken katı sınır tanımından yoksundur.

Promptlar için otomatik CI/CD testini nasıl uygularım?

Bir “Golden Dataset” (50-200 seçilmiş test durumu) ve çıktıları bir değerlendirme ölçütüne göre puanlayan bir “LLM-as-a-judge” içeren bir test paketi kurun. Bu testleri GitHub Actions veya Jenkins pipeline’ınıza entegre edin; böylece her prompt değişikliği dağıtımdan önce doğruluk ve ton açısından doğrulanır.

Yapılandırılmış promptlara geçerken en yaygın hata nedir?

<context> bloğunu aşırı yüklemek. Geliştiriciler genellikle tüm kod tabanlarını veya belgelerini context’e boşaltır; bu da modelin dikkatini seyreltir. Context’i yalnızca görevle doğrudan ilgili olana odaklayın. Büyük belgelere başvurmanız gerekirse, yalnızca ilgili bölümleri çekmek için RAG retrieval kullanın.