Kodunuz bir model yanıtında json.loads() çağırıyor ve JSONDecodeError: Expecting value: line 1 column 1 alıyor. Ya da ayrıştırma başarılı oluyor ama sayı beklediğiniz bir alan dize olarak geliyor. Bu yazı nedenleri her biri için güvenle ne yapabileceğinize göre sıralıyor, yalnızca tek anlamlı durumları onaran test edilmiş bir Python fonksiyonu veriyor ve yeniden denemenin ne zaman işe yaramayacağını bilen bir yeniden deneme döngüsü gösteriyor.
JSON modu ile json_schema arasındaki seçim JSON modu ve json_schema yazısında ele alınıyor. Bu yazı ise gerçekte aldığınız yanıtla ne yapacağınızla ilgili.
LLM’ler neden geçersiz JSON döndürür?
Bir model metni token token yazar. Sunucu çözümlemeyi (decoding) kısıtlamadıkça, modelin dostça bir cümle eklemesini ya da yerinin bitmesini hiçbir şey engellemez. Yaygın hatalar:
| Gördüğünüz | Neden | Kodda onarmak güvenli mi? |
|---|---|---|
Nesnenin çevresinde ```json … ``` |
Sohbet biçimlendirme alışkanlığı | Evet: çiti kaldırın |
| Önde “Here is the JSON:”, arkada “Let me know…” | Aynı alışkanlık | Evet: yalnızca ilk değeri okuyun |
Nesneden önce <think>...</think> |
Bazı sunucularda içerik alanına düşen akıl yürütme metni | Evet: bloğu kaldırın |
| Dizenin ortasında bitiyor, parantezler açık kalmış | max_tokens sınırına ulaşıldı |
Hayır: daha fazla yer vererek yeniden gönderin |
| Boş içerik | Akıl yürütme bütçenin tamamını kullandı | Hayır: daha fazla yer vererek yeniden gönderin |
{"a": 1,} |
Sondaki virgül; JavaScript izin verir, RFC 8259 vermez | Evet: tek anlamı var |
{'a': True, 'b': None} |
Python sözdizimi | Evet: ast.literal_eval bunu güvenle okur |
NaN, Infinity |
JSON değil; Python varsayılan olarak kabul eder | Hayır: reddedin |
| Geçerli JSON, yanlış türler veya eksik alanlar | Şema zorlanmıyor | Hayır: hatayla birlikte yeniden isteyin |
Ayrım çizgisi belirsizliktir. Modelin kastetmiş olabileceği tam olarak tek bir şey varsa, bunu kodda düzeltin ve düzelttiğinizi loglayın. Tahmin etmeniz gerekecekse yanıtı reddedin.
Kesilmiş JSON neden onarılmamalı?
Çünkü onarılmış hali doğru görünür ama doğru değildir. Popüler, MIT lisanslı bir kütüphane olan json_repair 0.64.9’u kelimenin ortasında kesilmiş bir yanıt üzerinde çalıştırdık:
'{"name": "Omar", "city": "Jed' -> {'name': 'Omar', 'city': 'Jed'}
Şehri “Jed” olan geçerli bir JSON döndürdü. README’si bu konuda açık: kütüphane “automatically completes missing values in JSON fields with reasonable defaults” (BroadRouter çevirisi: JSON alanlarındaki eksik değerleri makul varsayılanlarla otomatik olarak tamamlar). Bu, log okumak için faydalıdır. Sakladığınız veya üzerine işlem yaptığınız verilerde ise görünür bir hatayı sessiz bir hataya çevirir.
Ayrıştırmadan önce finish_reason değerini kontrol edin. "length", yanıtın max_tokens sınırına ulaştığı anlamına gelir. Aynı isteği aynı sınırla yeniden göndermek aynı şekilde başarısız olur; bu yüzden sınırı iki katına çıkarın veya çağrı başına daha az isteyin. Akıl yürüten modeller bunu daha sık hale getirir: BroadNet’in API referansı, DeepSeek V4.1 Flash, GLM 5.3 ve Qwen3.8 27B’nin yanıt vermeden önce akıl yürüttüğünü ve akıl yürütmenin max_tokens’tan düşüldüğünü söylüyor. Küçük bir sınırla yanıt boş gelebilir. 1.000 veya daha fazla token bırakın ya da reasoning_effort değerini low yapın; sayılar akıl yürütme bütçesi yazısında.
Yalnızca güvenli durumları düzelten bir onarım fonksiyonu
Bu fonksiyon yalnızca standart kütüphaneyi kullanır. Ayrıştırılmış değeri ve yaptığı onarımların listesini döndürür; böylece onarımları sayabilirsiniz.
import ast, json, re
class Truncated(Exception): pass
class NotJSON(Exception): pass
FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)
def _reject_constant(name): # NaN, Infinity: Python accepts them, JSON does not
raise NotJSON(f"non-standard constant {name}")
_decoder = json.JSONDecoder(parse_constant=_reject_constant)
def _first_value(s):
"""Decode the first JSON object or array in s, ignoring prose before and after it."""
for i, ch in enumerate(s):
if ch in "{[":
try:
return _decoder.raw_decode(s, i)[0]
except json.JSONDecodeError:
continue # a stray brace in prose; try the next one
raise NotJSON("no JSON object or array found")
def _scan(s):
"""Drop commas before } or ] outside strings; report brackets left open."""
out, stack, in_str, esc = [], [], False, False
for i, ch in enumerate(s):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch in "{[":
stack.append(ch)
elif ch in "}]" and stack:
stack.pop()
elif ch == ",":
rest = s[i + 1:].lstrip()
if rest[:1] in ("}", "]"):
continue # trailing comma: skip it
out.append(ch)
return "".join(out), len(stack) + (1 if in_str else 0)
def _python_literal(s):
"""Output in Python syntax: single quotes, True/False/None, trailing commas."""
start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
end = max(s.rfind("}"), s.rfind("]"))
if start < 0 or end <= start:
raise NotJSON("no braces")
value = ast.literal_eval(s[start:end + 1]) # literals only; never runs code
if not isinstance(value, (dict, list)):
raise NotJSON("not an object or array")
json.dumps(value, allow_nan=False) # must round-trip as strict JSON
return value
def parse_llm_json(content, finish_reason=None):
"""Return (value, repairs). Raises Truncated or NotJSON."""
if finish_reason == "length":
raise Truncated("hit max_tokens; raise the limit or shorten the output")
if not content or not content.strip():
raise NotJSON("empty content (reasoning may have used the whole budget)")
repairs = []
s = content.strip().lstrip("\ufeff")
if THINK.search(s):
s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
m = FENCE.search(s)
if m:
s = m.group(1).strip(); repairs.append("removed code fence")
try:
value = _decoder.decode(s)
return value, repairs
except json.JSONDecodeError:
pass
try:
value = _first_value(s); repairs.append("ignored text around JSON")
return value, repairs
except NotJSON:
pass
fixed, open_count = _scan(s)
if open_count:
raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
if fixed != s:
try:
value = _first_value(fixed); repairs.append("removed trailing commas")
return value, repairs
except NotJSON:
pass
try:
value = _python_literal(s); repairs.append("parsed Python-style literal")
return value, repairs
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
raise NotJSON(f"unrepairable: {e}") from None
Her adımın işleyişi:
- Kesilmiş ve boş yanıtlar herhangi bir ayrıştırmadan önce hata fırlatır; böylece asla veriye dönüşmezler.
- Çitler ve akıl yürütme blokları iki düzenli ifadeyle (regex) temizlenir.
raw_decodeburadaki asıl araçtır. Python belgeleri, bu fonksiyonun bir belgeyi “from a string that may have extraneous data at the end” (BroadRouter çevirisi: sonunda fazladan veri olabilecek bir dizeden) çözümlediğini ve nerede durduğunu döndürdüğünü söylüyor. İlk{veya[karakterinden başlayarak nesneden önceki metni atlar, sonrasındakini yok sayar. Metin içindeki bir parantez çözümlenemezse bir sonrakini dener.- Parantez taraması dizeleri ve kaçış karakterlerini izleyerek metni baştan sona dolaşır. Açık kalan parantezler,
finish_reasonsöylemese bile yanıtın kesildiği anlamına gelir; bu durumda hata fırlatılır. Dizelerin dışında doğrudan}veya]önüne gelen virgüller atılır. ast.literal_evaltek tırnaklı,TrueveNoneiçeren Python tarzı çıktıyı okur. Yalnızca sabit değerleri (literal) değerlendirir, asla kod çalıştırmaz. Sonuç daha sonra katı JSON olarak serileştirilebilmelidir.NaNveInfinity,parse_constantüzerinden hata fırlatır. Python’unjsonmodülü bunları varsayılan olarak kabul eder; RFC 8259 bunların “are not permitted” (BroadRouter çevirisi: izin verilmediğini) söyler ve JavaScript’inJSON.parsefonksiyonu da onları reddeder.
Fonksiyonu 17 test dizesiyle çalıştırdık: temiz JSON, çitli JSON, çit içinde Arapça anahtarlar ve değerler, önünde ve arkasında metin, nesneden önceki metinde bir {name} yer tutucusu, bir <think> bloğu, nesnelerde ve dizilerde sondaki virgüller, dizelerin içinde virgüller ve parantezler, kaçışlı tırnaklar, ters eğik çizgiyle biten bir Windows yolu, Python sabitleri, NaN, boş bir yanıt, finish_reason: "length" ile ve onsuz kesilmiş bir yanıt ve art arda iki nesne. Hepsi yukarıdaki tablonun söylediği gibi davrandı. Bir test gerçek bir hata yakaladı: erken bir sürüm kapanış tırnağını kontrol etmeden önce kaçış bayrağını tersine çeviriyordu; bu yüzden "he said \"hi,]\"" virgülünü kaybediyordu. Kendi onarım kodunuzu kaçışlı tırnaklarla test edin.
Bilmeniz gereken iki sınır var. Art arda iki nesne verildiğinde ilkini döndürür; birden fazla öğe istiyorsanız tek bir JSON dizisi isteyin. Ayrıca bir dize içinde çift tırnak barındıran tek tırnaklı Python çıktısı, parantez taraması tarafından yanlış okunup reddedilebilir. Reddetmek güvenli başarısızlıktır.
Onarım başarısız olunca nasıl yeniden denenmeli?
Onarım biçimle ilgilenir. Doğrulama içerikle ilgilenir: doğru alanlar, doğru türler, makul değerler. Bu döngü jsonschema paketiyle doğrulama yapar ve yeniden denemeyi nedene göre seçer:
import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON
client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
"required": ["name", "city", "amount"],
"properties": {"name": {"type": "string", "minLength": 1},
"city": {"type": ["string", "null"]},
"amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)
def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
"Schema: " + json.dumps(SCHEMA)},
{"role": "user", "content": text}]
for attempt in range(1, attempts + 1):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
reasoning_effort="low", temperature=0)
c = r.choices[0]
try:
value, repairs = parse_llm_json(c.message.content, c.finish_reason)
errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
if not errors:
log({"attempt": attempt, "repairs": repairs, "ok": True})
return value
problem = "The JSON does not match the schema: " + "; ".join(errors)
except Truncated:
log({"attempt": attempt, "ok": False, "why": "truncated"})
max_tokens *= 2 # same prompt, more room; a re-ask would be cut off too
continue
except NotJSON as e:
problem = f"That reply was not valid JSON ({e})."
log({"attempt": attempt, "ok": False, "why": problem})
messages += [{"role": "assistant", "content": c.message.content or ""},
{"role": "user", "content": problem + " Return the corrected JSON object only."}]
raise RuntimeError(f"no valid JSON after {attempts} attempts")
Döngüdeki kurallar:
- Kesilmişse: aynı mesajları iki katı sınırla yeniden gönderin. Bir “lütfen düzelt” mesajı eklemek istemi uzatır, çıktıyı ise kısaltmaz.
- JSON değilse veya yapısı yanlışsa: hatayı birebir geri gönderin. “amount: ‘1200’ is not of type ‘number’” modele düzeltmesi için somut bir şey verir. Yalın bir yeniden deneme çoğu zaman aynı hatayı tekrarlar.
- Deneme sayısını üçle sınırlayın. Her yeniden deneme tüm konuşmayı girdi token’ı olarak yeniden gönderir. Üç denemeden sonra girdiyi loglayın ve başka bir yere yönlendirin.
- Onarım listesini loglayın. Bir istem değişikliğinden sonra artan “removed code fence” sayısı, hiçbir şey başarısız olmasa bile istemin kötüleştiğini gösterir.
Bu döngüyü, senaryolu yanıtları oynatan yerel bir sahte (mock) sunucuya karşı çalıştırdık. Sondaki virgülü olan ve "amount": "1200" değerini dize olarak içeren çitli bir yanıt onarıldı, doğrulamadan geçemedi ve hata geri gönderilince ikinci çağrıda düzeltildi. finish_reason: "length" ile kesilmiş bir yanıt, max_tokens 1.500’den 3.000’e yükseltilerek yeniden gönderildi ve başarılı oldu. Sahte sunucu her seferinde isteği kaydetti ve döngünün gönderdiği mesaj sayısını ve sınırı doğruladı. Gerçek bir model farklı şekillerde başarısız olabilir; bu yüzden sayılara güvenmeden önce döngüyü kendi girdilerinizden 100 tanesiyle çalıştırın.
Yapılandırılmış çıktı bunu gereksiz kılar mı?
Çoğunu ortadan kaldırır. Çözümlemeyi şemanıza göre kısıtlayan bir sunucu çit, sondaki virgül veya eksik alan üretemez. Yaygın bir açık model sunucusu olan vLLM bunu xgrammar veya guidance arka uçlarıyla yapar. Yine de iki hata kalır: max_tokens’ta kesilme ve retler. OpenAI, JSON modu çıktısının “except for in some edge cases” (BroadRouter çevirisi: bazı uç durumlar hariç) geçerli olduğunu ve uygulamanızın tam bir nesne olmayan çıktıyı “must detect and handle” (BroadRouter çevirisi: tespit edip ele alması gerektiğini) belirtiyor. Bu yüzden json_schema kullansanız bile finish_reason kontrolünü ve doğrulayıcıyı koruyun.
Her yaklaşımın neyi önlediği:
| Yaklaşım | Çitler ve metin | Sözdizimi hataları | Yanlış yapı | Kesilme |
|---|---|---|---|---|
| Yalnızca istem (“JSON ile yanıt ver”) | Azaltır | Azaltır | Azaltır | Hayır |
JSON modu (json_object) |
Evet | Evet | Hayır | Hayır |
Yapılandırılmış çıktı (json_schema, zorlanmış) |
Evet | Evet | Evet | Hayır |
OpenAI, JSON modunda bir mesajda modele “must always instruct the model to produce JSON” (BroadRouter çevirisi: her zaman JSON üretmesini söylemeniz gerektiğini) de belirtiyor; aksi halde model token sınırına ulaşana kadar boşluk üretebilir. Diğer OpenAI uyumlu sunucular farklılık gösterir; bu yüzden modu yayına alacağınız model üzerinde test edin. Test, yapılandırılmış çıktı yazısında yer alıyor.
Bir yanıtı elle kontrol etmek için LLM JSON çıktı doğrulayıcısına yapıştırın ya da örnek bir nesneden JSON şema oluşturucu ile katı bir şema üretin.
BroadNet Inference’ın yeri
BroadRouter, BroadNet’in sitesidir. BroadNet’in API referansı yapılandırılmış çıktıyı yalnızca GLM 5.3 ve Qwen3.8 27B için listeliyor ve istek parametresinin adını vermiyor; bu yüzden ona güvenmeden önce json_schema’yı model üzerinde test edin. DeepSeek V4.1 Flash ve Gemma 4 VL 26B modellerinde, yalnızca istemle istenen JSON’u yukarıdaki onarım fonksiyonu ve doğrulayıcıyla birlikte kullanın. Dört modelden üçü yanıt vermeden önce akıl yürütür; max_tokens bütçesini buna göre ayarlayın. Toplu çıkarım için toplu çalıştırıcı yazısı, finish_reason değerinin öğe başına nasıl loglanacağını gösteriyor. İstemler ve yanıtlar her istekten sonra saklanmaz.
