BroadRouter

LLM'den gelen geçersiz JSON: nedenler, onarım ve yeniden deneme

BroadNet Inference ekibi · 7 dk okuma · Yayımlandı · Güncellendi

Önce finish_reason değerine bakın: max_tokens'ta kesilmiş bir yanıt güvenle onarılamaz, sınırı yükseltip yeniden gönderin. Aksi halde kod çitlerini ve çevresindeki metni temizleyin, ilk JSON değerini çözümleyin, sonra yalnızca sondaki virgül gibi tek anlamlı hataları düzeltin. Bir şemaya göre doğrulayın; başarısız olursa hatayı birebir bir ya da iki kez geri gönderin. Desteklenen yerlerde yapılandırılmış çıktı bunun çoğunu önler.

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:

  1. Kesilmiş ve boş yanıtlar herhangi bir ayrıştırmadan önce hata fırlatır; böylece asla veriye dönüşmezler.
  2. Çitler ve akıl yürütme blokları iki düzenli ifadeyle (regex) temizlenir.
  3. raw_decode buradaki 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.
  4. Parantez taraması dizeleri ve kaçış karakterlerini izleyerek metni baştan sona dolaşır. Açık kalan parantezler, finish_reason sö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.
  5. ast.literal_eval tek tırnaklı, True ve None iç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.
  6. NaN ve Infinity, parse_constant üzerinden hata fırlatır. Python’un json modülü bunları varsayılan olarak kabul eder; RFC 8259 bunların “are not permitted” (BroadRouter çevirisi: izin verilmediğini) söyler ve JavaScript’in JSON.parse fonksiyonu 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.

Sık sorulan sorular

LLM'im neden JSON'u markdown kod bloğu içinde döndürüyor?

Sohbet modelleri kodu genellikle insanlar için biçimlendirir ve kod çiti, sohbet arayüzlerinin kodu gösterme şeklidir. "Yalnızca JSON, kod çiti yok" diye isteyin, ama çitleri yine de kodda temizleyin: talimat oranı düşürür, ortadan kaldırmaz.

LLM çıktısında JSONDecodeError hatasını nasıl düzeltirim?

Önce finish_reason değerine bakın. "length" ise yanıt kesilmiştir: max_tokens'ı yükseltip yeniden gönderin. Değilse kod çitlerini temizleyin ve ilk JSON değerini, sonrasındaki metni yok sayan raw_decode ile çözümleyin. Sondaki virgülleri düzeltin, sonra doğrulayın. Hâlâ başarısız olursa hatayla birlikte yeniden isteyin.

Bir JSON onarım kütüphanesi kullanmalı mıyım?

Loglar ve hata ayıklama için evet. Üzerine işlem yapacağınız veriler için dikkatli olun. json_repair gibi kütüphaneler eksik değerleri varsayılanlarla tamamlar; bu yüzden kesilmiş "Jed" şehri geçerli bir "Jed" olarak geri gelir. Bunun yerine kesilmiş çıktıyı reddedip yeniden gönderin.

LLM'imin JSON çıktısı neden yarıda kesiliyor?

Yanıt max_tokens sınırına ulaştı. DeepSeek V4.1 Flash, GLM 5.3 ve Qwen3.8 27B gibi akıl yürüten modellerde akıl yürütme bu sınırdan düşülür; uzun bir düşünme yanıta çok az yer bırakabilir. Sınırı yükseltin, reasoning_effort'u low yapın veya çağrı başına daha az çıktı isteyin.

JSON modu geçerli JSON'u garanti eder mi?

Neredeyse. OpenAI, JSON modu çıktısının geçerli JSON olduğunu söylüyor, "except for in some edge cases" (BroadRouter çevirisi: bazı uç durumlar hariç), örneğin token sınırına ulaşıldığında; şemanızı da zorlamaz. json_schema ile yapılandırılmış çıktı, sağlayıcının zorladığı yerlerde şemaya bağlılık ekler. Her iki durumda da doğrulayın.

Hangi BroadNet modelleri yapılandırılmış çıktıyı destekliyor?

BroadNet'in API referansı, 15 Kasım 2026'daki kontrolde yapılandırılmış çıktıyı GLM 5.3 ve Qwen3.8 27B için listeliyor. DeepSeek V4.1 Flash veya Gemma 4 VL 26B için listelemiyor; bu modellerde yalnızca istemle istenen JSON'u onarım ve doğrulamayla birlikte kullanın.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor