Analýza JSONu, který ještě nedorazil celý: průběžný náhled a inkrementální oprava
Shrnutí: LLM posílají JSON token po tokenu a API vrací velké odpovědi po částech, ale JSON.parse odmítá pracovat, dokud nedorazí celý dokument. Tento článek rozděluje tři přístupy k implementaci — kompletní oprava, skutečný inkrement a částečná analýza — ukazuje, jak maska Allow udrží náhled stabilní, a doplňuje měření pipeline a kód připravený do produkce.

JSON.parseslibuje „nastartuji, až dorazí celý dokument“, streamování slibuje „posílám data kousek po kousku“. Konflikt není v rychlosti, ale v sémantice úplnosti: nedokončený dokument zatím nemá žádný „správný výsledek analýzy“.
Příznak: tři scénáře, které si nemohou dovolit čekat na celý text
První scénář jsou aplikace s LLM. Model vydává JSON token po tokenu; strukturovaný výstup o velikosti 8 KB může dorazit za desítky sekund, zatímco uživatel zírá na prázdný panel — přestože první pole byla k dispozici už v první sekundě. Druhý scénář jsou brány a proxy: upstream tlačí odpověď o desítkách megabajtů po HTTP chunkách a proxy, která chce před přeposláním filtrovat pole, si plným bufferováním přes res.json() znásobí paměťovou špičku. Třetí scénář jsou fronty zpráv a logovací pipeline: záznamy NDJSON přicházejí jeden za druhým a konzument nechce skládat dávky.
Společný jmenovatel je zřetelný: data přicházejí postupně, zatímco standardní analyzátor přijímá jen kompletní dokument. JSON.parse hodí Unexpected end of JSON input u prvního kousku, hodí týž error u šedesátého pátého a výsledek vrátí až u posledního. Čekání není jediná možnost — ale nejdřív si musíte určit, co znamená „analyzovat“ nedokončený dokument.
Sémantika analýzy po prefixech: je každý kousek platný?
Vezměte pole objednávek o 7847 bajtech, rozřežte ho na kousky po 120 znacích, abyste simulovali streamované doručení (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), a pusťte přes každý prefix tři analyzátory:
| Přístup | Úspěchy na 66 prefixech | Kumulativní čas | Sémantika |
|---|---|---|---|
JSON.parse |
1 (jen poslední kousek) | 2,1 ms | všechno nebo nic |
partial-json (Allow.ALL) |
66 (od prvního kousku) | 14,3 ms | vždy vrátí „zatím známé“ |
jsonrepair spouštěný znovu na každém prefixu |
66 | 23,8 ms | po doplnění závorek analyzovatelné, ale pokaždé spočítáno znovu od začátku |
Dvě klíčové závěry. První: selhání JSON.parse nese nulovou informaci — nahlášená pozice je vždy konec, takže nevíte, ani kolik ještě chybí, ani zda přijatá část je sama o sobě koherentní. Druhý: opakovaná kompletní oprava na každém prefixu funguje, ale nevyplatí se: průměrná délka textu na volání roste lineárně a kumulativní náklady rostou kvadraticky, O(n²). 23,8 ms vypadá neškodně; u textů v řádu megabajtů se stejný faktor mění ve ztracené sekundy CPU.
A pozor: „analyzovatelný po prefixech“ neznamená „data úplná“. Poslední číslo doplněného prefixu může další kousek ještě doplnit a poslední řetězec může být uříznut uprostřed escape sekvence — právě tady pramení veškerá nestabilita průběžného náhledu.
Tři přístupy k implementaci a kam každý patří
Knihovny pro streamování se dělí do tří postojů a špatně zvolený postoj škodí víc než špatně zvolená knihovna:
| Knihovna | Postoj | Hodí se | Nehodí se |
|---|---|---|---|
jsonrepair (3.15.0) |
kompletní oprava + Transform stream | dostanete „dokument, který bude jednou kompletní“, a chcete bezztrátový výsledek | jen náhled (výstupem je celý opravený text, ne datový objekt) |
partial-json (0.1.7) |
částečná analýza, dovolí zahodit nedokončený konec | UI náhled: každý prefix má hned použitelný objekt | ukládání do databáze (náhled může chybět pole, čísla jsou nestabilní) |
jsonmend (0.1.3) |
skutečný inkrement, veřejný konzistenční korpus | pipeline typu „přijde dávka, vyjde verze“ bez znovuprocítání minulosti | už dokončený dokument (kompletní analýza je rychlejší) |
Nejsou to soupeři. jsonrepair skrze podcestu ./stream exportuje jsonrepairTransform, standardní Transform stream: kousky posíláte zleva, zprava vycházejí opravené bloky JSON textu a je zaručeno, že jejich spojení se rovná analýze celého textu najednou — rovnici decode(encode(x)) === x udrží. partial-json drží jinou linku: každý prefix okamžitě vydá objekt, za cenu vzdání se slibu „výsledek už se nezmění“. jsonmend omezuje třetí linku veřejným konzistenčním korpusem: skutečný inkrement, sémanticky zarovnatelný, obě implementace mají tentýž regresní základ.
Maska Allow: která pole se v náhledu smí ukázat
Jádro partial-json není „dokáže rozparovat jakkoliv rozbitý vstup“, ale to, že volající sám deklaruje, jakou neúplnost je ochoten snést. Maska se skládá bitově podle JSON typů (STR, NUM, ARR, OBJ…); odeberete-li typ, nedokončené hodnoty tohoto typu do náhledu nepatří:
import { parse, Allow } from 'partial-json';
parse('{"price": 12', Allow.ALL);
// → { price: 12 } číslo 12 je „dosud přečtené“
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 } totéž pole se změnilo: náhled není stabilní
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {} bez bitu NUM se nedokončené číslo nezobrazí
To je z měření nejužitečnější zjištění: čísla jako cena nebo počet, která může další kousek doplnit, se na UI mění s každým snímkem; Allow.ALL & ~Allow.NUM je nechá tiše počkat, až budou hotová. Totéž platí pro řetězce — řetězec uříznutý uprostřed Unicode escape sekvence partial-json 0.1.7 bezpečně zahodí, místo aby hádal. Stabilita náhledu není dar od analyzátoru; kupuje se ji maskou.
Cena implementace streamované opravy: look-back buffer a kvadratické kopírování
Streamovaná pipeline není „kompletní API zabalené do for cyklu“. Na stejném vzorku 66 kousků trvala pipeline s jsonrepairTransform celkem 6,7 ms, zatímco opakovaná kompletní oprava na každém prefixu 23,8 ms — rozdíl 3,5× pochází z implementace: streamovaná implementace se dívá zpět jen v nutném okně, výstup přidává inkrementálním bufferem a předchozí text nekopíruje znovu a znovu.
Portování streamovaného jádra jsonrepair na HarmonyOS ArkTS (openHarmony adaptace třetích knihoven) odhalilo tři konkrétní náklady: upstreamová streaming cesta potřebuje „look-back buffer“, takže u malých dokumentů čeká výsledek na flush — autor proto napsal zvláštní IncrementalRepairer pro krátké texty; upstreamová regulérní cesta kopíruje výstup celý znovu, což je kvadratické, a při portování to OutputBuilder zrušil; a je tu ještě past s hraničním znakem — podmínka text[i] === undefined jako test „dočetl jsem se až na konec“ převedená na charAt klame, protože ''.includes('') je trvale true, takže překročení mezí je nutné předem chránit prázdným řetězcem. Tahle detaily vysvětlují, proč si „streamovaná oprava“ zaslouží vlastní kategorii: její inženýrská složitost je jiné řádu než jednorázová oprava.
Za zmínku stojí i známá hranice: issue #214 v jsonrepair hlásí, že streamovaná oprava odmítá platný prefix s chybějící čárkou před hodnotou se lomítkem — ve streamovaném režimu je lexikálně těžké rozeznat „další znak ještě nedorazil“ od „vstup je neplatný“; look-back okno je cena za tuhle nejednoznačnost.
Jak to poskládat: náhled a perzistence jdou zvlášť
Spojte předchozí sémantiku do jedné pipeline; princip se vejde do jedné věty: náhled dělá částečná analýza, ukládání dělá striktní analýza.
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// Linka 1: bezztrátová pipeline. Vchod: kousky, výstup: opravený JSON text, nakonec striktní validace
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink pak udělá JSON.parse + business validaci
chunkStream.pipe(tr);
// Linka 2: náhledová pipeline. Každý prefix dá snímek UI; nedokončená čísla a řetězce maska zadrží
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // vykreslí jen stabilní pole; rychlá pole nechají počkat
}
Smlouvy obou linek se liší a nenahrazují se: náhledový snímek smí chybět pole, ukládaný nesmí; ukládaný musí počkat na konec streamu a projít kompletní JSON.parse s business validací, náhledový se nikam neukládá. Pokud je upstream výstup LLM, před ukládáním je potřeba podle stop_reason posoudit, zda nedošlo k useknutí — tenhle postup „nejdřív stop_reason, pak teprve oprava“ rozebírá článek o opravě useknutého JSONu z LLM, tady ho neopakujeme.
Kdy streamování vynechat
Tři podmínky zamítnutí; stačí splnit jednu a čestně použijte kompletní analýzu: malý soubor — obyčejný JSON.parse do ~22 MB přečte jedním tahem obvykle pod sekundu, streamování jen přidává kód; jen jednorázová statistika — agregace zvládne jq --stream nebo řádkový NDJSON pohodlněji, viz praktická příručka JSONL; příjemce nepřijímá částečná data — například součet částek, kde jeden špatně vynásobený mezivýsledek z náhledu znamená ztrátu peněz; tu má průběžný náhled hodnotu jen jako ukazatel postupu.
Streamovaná analýza řeší pořád „nedá se čekat“, ne „bude to rychlejší“. Při stejném objemu textu je celkové CPU kompletní analýzy vždy menší než jakákoli streamovaná varianta; vyměňujete čas do prvního použitelného bajtu a konstantní hladinu paměti. Kdo si tohle ujasní, nemá důvod kolísat při volbě technologie.
Časté otázky
Můžu náhledový objekt rovnou uložit do databáze?
Nemůžete. Náhled je snímek „zatím známého“: číslo může dorazit další kousek, řetězec může být useknutý, pole mohou chybět. Před ukládáním musíte počkat na konec streamu, pustit kompletní striktní JSON.parse a pak business validaci. Náhled patří jen do UI vrstvy.
partial-json, nebo jsonrepair?
Závisí na tom, jestli chcete text, nebo objekt. Bezztrátový opravený text (předáte dál k analýze) poskytne jsonrepair — jeho streamovaný výstup garantuje shodu s analýzou celku; objekt pro každý prefix hned k UI náhledu dodá partial-json, a to s maskou Allow nastavenou podle toho, kolik nestability unesete.
Snižuje streamovaná analýza celkový čas?
Ne. Celkové CPU je u kompletní analýzy vždy nejmenší a streamovaná varianta připlácí za správu stavu. Vyměňujete tři věci: čas do prvního kousku, paměť, která neroste s délkou celku, a schopnost zpracovávat za běhu (přeposílat, filtrovat, zobrazovat).
Co když prvky pole přicházejí po jednom a chci je zpracovávat po jednom?
To je jiná cesta: stream-json se streamArray hází {key, value} v okamžiku uzavření prvku a s for await přirozeně tvoří backpressure — hodí se pro hromadný import typu „naparsovat a zapsat“, zatímco tento článek řeší náhled na úrovni celého dokumentu.