JSON Toolkit

Průvodce opravou JSON: jak zachránit pokazený výstup LLM a zachovat důvěru

Shrnutí: Výstup LLM zabalený do markdownového plotu, s koncovými čárkami a literály Python, striktní parser odmítne celý — stejně tak konfigurace ručně upravené bez uvozovek. Tento průvodce vytyčuje skutečnou hranici mezi devíti třídami chyb, které opravný nástroj zvládne, a čtyřmi, které neopraví nikdy, vysvětluje, proč stavový automat poráží regex, a dodává produkční řetězec parsování s jsonrepair a json-repair.

Středně pokročilý~6 min čteníPublikováno 2026-11-08Aktualizováno 2026-11-08
Diagram opravné pipeline JSON: odstranění plotu, normalizace uvozovek, vyvážení závorek, finální validace

Striktní parser nedává pokazenému vstupu žádnou polovičnost: jednu chybovou zprávu, jedno číslo řádku — a ani jeden bajt vašich dat. Opravný nástroj existuje proto, aby změnil „totální selhání“ na „dost dobré na spuštění“ — ale to, co doplní, je vždy jen nejlepší odhad záměru, nikdy záruka správnosti.

Jedna: odkud pokazený JSON pochází

Oprava není magie — začněte prozkoumáním vstupu. V reálných projektech nestandardní JSON pochází ze tří soustředěných zdrojů:

  1. Výstup LLM. Jazykové modely generují text token po tokenu; nespouštějí žádný JSON serializátor. I když požádáte „jen JSON“, model odpověď zabalí do plotu ```json, předsadí „Tady jsou vaše data“, nechá koncovou čárku, nebo narazí na strop tokenů a zastaví se uprostřed objektu.
  2. Kopírování z jiných jazyků. Objekt JavaScript vytištěný přes console.log nese jednoduché uvozovky a klíče bez uvozovek; slovník Python se tiskne jako True/False/None. Tyto „JSON-podobné“ řetězce vybuchnou při prvním kontaktu s JSON.parse.
  3. Konfigurace JSON5/JSONC. Soubory jako tsconfig legálně povolují komentáře a koncové čárky. Vložte takový soubor do striktního parseru — odmítne celý soubor.

Tři zdroje vyžadují různé zacházení, ale opravné nástroje pokryjí všechny — za předpokladu, že chyba je na jejich deklarovaném seznamu opravitelných případů.

Dva: devět tříd chyb, které opravný nástroj skutečně opravuje

Kombinací dokumentace knihovny jsonrepair a seznamů schopností publikovaných dodavateli nástrojů se automaticky opravitelné chyby dělí na devět tříd:

Třída Pokazený vstup Opravený výsledek
Koncová čárka [1, 2, 3,] [1, 2, 3]
Jednoduché / typografické uvozovky {'a': 'b'}、{"a": "b"} {"a": "b"}
Klíče bez uvozovek {name: 'Ada'} {"name": "Ada"}
Komentáře {"a": 1 /* poznámka */} {"a": 1}
Literály Python {"ok": True, "v": None} {"ok": true, "v": null}
Markdownové ploty ```json {...} ``` {...}
Chybějící čárky [1 2] [1, 2]
Neuzavřené závorky / uvozovky {"a": [1, 2 {"a": [1, 2]}
JSONP / spojování řetězců cb({...})、"x" + "y" {...}、"xy"

Co mají těchto devět společné: data jsou všechna na místě; pokazená je jen syntaxe. Opravný nástroj upraví interpunkci a obaly, aniž by se dotkl jediné hodnoty. Pár detailů si zaslouží zvláštní pozornost:

  • Čísla s nulou na začátku se stanou řetězci. 007 se opraví na "007", ne na 7, aby se neztratily číslice. Pokud je pole skutečně textovým kódem, je to správné; jde-li o skutečné číslo, rozhodnutí je na vás.
  • Holá slova se stanou řetězci. NaN nelze opravit na číslo — některé implementace vydají "NaN", jiné null. Chování se liší mezi knihovnami; otestujte svou, než ji zapojíte do pipeline.
  • Platný vstup projde nedotčený. Každý seriózní opravný nástroj nejprve spustí rychlou cestu striktního parsování. Platný JSON se nikdy nedostane do opravné logiky, takže „opravit dobrý dokument na špatný“ je nemožné.

Tři: čtyři věci, které opravný nástroj neopraví

Hranice na druhé straně je stejně výslovná. Nečekejte opravu pro:

  1. Chybové stránky HTML nebo čistou prózu. Ve vstupu není žádná JSON struktura a žádný nástroj nevytvoří data z ničeho.
  2. Syntakticky platná, ale chybná data. Klíč s překlepem, hodnota na špatném místě, číslo uložené jako řetězec — to jsou sémantické problémy, které každý parser, opravné nástroje nevyjímaje, bez mrknutí pustí.
  3. Data ztracená přerušením. Doplnění promění {"items": [{"id": 1}, {"na v platný JSON, ale hodnota pole name se už nikdy nevrátí. Dostanete „platný, ale neúplný“ objekt. V produkci zkontrolujte stopReason === "max_tokens", než se rozhodnete mezi doplněním a opakováním požadavku.
  4. Duplicitní klíče a jednoznačnosti zbavené struktury. Který ze dvou stejných klíčů vyhraje, závisí na implementaci parseru. Zodpovědné opravné nástroje nabízejí strict režim, který místo potichu vybrat jeden vyhodí chybu.

Jednou větou shrnuto: oprava je nejlepší odhad, ne záruka správnosti. Pustit neověřený výsledek opravy dál do pipeline znamená vyměnit hlučnou syntaktickou chybu za tichou chybu dat.

Čtyři: dvě implementační školy — jedna URL ukončí spor

Opravné nástroje na trhu přicházejí ve dvou podobách a rozdíl se projeví na zcela konkrétním typu vstupu.

Škola regex náhrady aplikuje globální hledání-a-nahrazení na pokazené vzory. Zvažte tento vstup:

{"url": "http://example.com", 'note': 'fine'}

Regex, který převádí jednoduché uvozovky na dvojité, rozžvejí i obsah URL; regex pro čištění komentářů, který maže každé //, přetne http:// napůl. Uvnitř řetězce a vně struktury vypadají znaky stejně — regex je nedokáže rozlišit.

Škola znak po znaku, stavový automat sleduje stav parsování: uvnitř řetězce v dvojitých uvozovkách, v jednoduchých, uvnitř řádkového komentáře, blokového komentáře, nebo čeká na hodnotu. Když uvidí ', nejprve se zeptá „jsem uvnitř řetězce?“ a teprve potom rozhodne, zda uvozovku převést, nebo přeskočit. http://example.com sedí uvnitř řetězce v dvojitých uvozovkách, takže stavový automat ví, že tamní // jsou data, ne komentář, a zachová je. jsonrepair a json-healer patří do této školy a mantru komunity „opravný nástroj není hledání-a-nahrazení“ se týká právě tohoto.

Úplné pořadí opravné pipeline (jak ho odhalila implementace devkits) také stojí za pohled: odstranit ploty → normalizovat typografické uvozovky → extrahovat první vyvážený blok → odstranit komentáře → obalit holé klíče uvozovkami → odstranit koncové čárky → převést literály → na konci znovu serializovat přes JSON.stringify. Toto finální znovuserializování je klíčový krok: ať dělaly předchozí fáze cokoli, výstup se generuje znovu z rozparsovaného výsledku, takže ho každý striktní parser po proudu přijme.

Pět: napojení v kódu — sekvenční řetězec parsování

Když opravu napojujete do kódu, pořadí hraje větší roli než volba knihovny. Podle vzorů publikovaných json2toon a aijsonmedic má být sekvence taková: kontrola přerušení → extrakce úseku JSON → striktní parse → oprava jako fallback → validace podle schématu.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Opravený přerušený výstup zůstává neúplný — opakujte požadavek
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Extrahujte úsek JSON: LLM může žvanit před i po
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // rychlá cesta pro platný vstup
  } catch {
    return JSON.parse(jsonrepair(candidate));  // oprava jako fallback
  }
}

Na straně Python nabízí balíček json-repair (přes 4 700 hvězd) loads(), který vrací objekt přímo:

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

Dva inženýrské detaily:

  • Zarovnejte stacky. Pokud opravují frontend i backend, vyberte implementace se sdílenou sémantikou — Python json-repair a jeho TypeScript port @yarmu/json-repair, nebo jsonmend, jehož verze Python a JS procházejí stejným korusem shody o 485 případech. Jinak se tentýž výstup opraví na A na klientovi a na B na serveru a ladění se změní v noční můru.
  • Zapněte log oprav. @yarmu/json-repair s logging: true vrací pole každé opravné operace. Prudký nárůst počtu oprav obvykle znamená, že se změnil prompt nebo verze modelu — signál dřívější než jakákoli zpráva o chybě.

Ještě jeden krok po opravě je neprojednatelný: validace podle schématu. Syntakticky platné neznamená použitelné. Chybějící pole, špatné typy a neočekávané klíče chytí schéma. Přístup kontraktového testování se použije přímo zde; viz náš průvodce kontraktovým testováním JSON Schema.

Šest: kontrolní seznam prevence — nejlevnější oprava je ta, kterou nepotřebujete

Oprava je záchranná síť. Skutečné vítězství je méně pokazeného JSON u zdroje, v pořadí priorit:

  1. Structured Outputs (režim json_schema). Dekódování je omezeno schématem, takže koncová čárka prostě nemůže vzniknout. Strict režim OpenAI selže zhruba v 0,1 % případů — ceny tvrdých požadavků jako additionalProperties: false.
  2. Režim JSON (json_object). Garantuje jen syntaktickou platnost — ne tvar — a přerušení kvůli limitu tokenů se stále stává.
  3. Výslovné instrukce. Na koncových bodech bez režimu JSON snižuje formulace „žádné ploty, žádné komentáře, žádné koncové čárky, vypisuj jen objekt“ míru chyb o 70–80 %.
  4. Snížit temperature, zvýšit limit tokenů. První snižuje drift do prózy; druhé snižuje přerušení.
  5. Opakování s přiloženou chybou. Když validace selže, přiložte ke konverzaci pokazený výstup plus „JSON path + chybová zpráva“ a požádejte znovu. S přesnou chybou se modely obvykle opraví samy.

V praxi vrstvení „structured outputs + oprava jako fallback + validace podle schématu“ pokrývá prakticky každý scénář.

Sedm: dělení práce — konverze dialektu není oprava

V sadě nástrojů tohoto webu jsou dvě místa určení, která pokrývají odlišné segmenty této pipeline:

  • Problémy dialektu (komentáře, jednoduché uvozovky, koncové čárky) jdou rovnou do konvertoru JSON5. Konverze JSON5 ↔ standardní JSON pokrývá přesně tyto tři třídy, s výslovnou sémantikou, bez hádání. Je-li celý vstup soubor JSONC/JSON5, je konverze předvídatelnější než oprava. O kompromisech samotných dialektů viz průvodce JSON5 a JSONC.
  • Po opravě pusťte výsledek přes nástroj pro parsování JSON, aby se validoval a naformátoval — chyby lokalizované na řádek a sloupec potvrdí, že striktní parser výstup skutečně přijme.
  • Problémy knihovní třídy (literály Python, doplnění přerušení, obaly JSONP, markdownové ploty) zatím vyžadují jsonrepair / json-repair na straně kódu — ekvivalentní oprava na jedno kliknutí v prohlížeči neexistuje, protože tyto opravy zahrnují odhad záměru a lokální knihovna je pro ně bezpečnější domov než univerzální konvertor.

Pokud v ruce držíte chybovou zprávu, ne pokazená data, začněte průvodcem opravou chyb parsování JSON, přeložte zprávu na souřadnice a teprve potom se rozhodněte: upravit ručně, nebo opravit.

FAQ

Poškodí oprava JSON moje data?

Pro devět opravitelných tříd se mění jen interpunkce a obaly — hodnoty zůstávají netknuté a //, čárky a složené závorky uvnitř řetězců stavový automat rozpozná a zachová. Doplnění přerušení ale dává neúplné objekty, čísla s nulou na začátku se stanou řetězci a zacházení s NaN se liší mezi knihovnami. Kontrola klíčových polí po opravě je povinná.

Jaký je vztah mezi opravou a validací?

Validace řekne, kde je vstup nelegální; oprava vám podá legální dokument. Spolehlivý proces dělá obojí: nejprve opravit, poté validovat — schéma chytá typy a povinná pole, syntaktická kontrola potvrzuje, že striktní parser výsledek přijme. Opravovat bez validování znamená vyměnit hlučnou syntaktickou chybu za tichou chybu dat.

LLM vždy zabalí výstup do plotu ```json — co dělat?

Krátkodobě extrahujte: vezměte text od prvního { nebo [ po poslední } nebo ] a parsujte ho; opravný nástroj se zbavováním plotů spolkne i celou zprávu. Dlouhodobě použijte structured outputs nebo výslovnou instrukci „bez markdownových plotů“, aby plot vůbec nevznikl.

jsonrepair, nebo json-repair — který vybrat?

Pro JavaScript balíček npm jsonrepair (podporuje streamový transform); pro Python json-repair z PyPI. Pokud opravují oba konce, vyberte pár se zarovnanou sémantikou — řekněme json-repair plus jeho TS port — aby tentýž vstup se opravil shodně na obou stranách.

Zvládnou opravné nástroje češtinu a typografické uvozovky?

Ano. Typografické uvozovky z českých klávesnic („“), pevné mezery a BOM na začátku souboru jsou všechny ve standardním seznamu oprav; typografické uvozovky se normalizují na rovné. Výsledek jednou pusťte validátorem a hotovo.