Przewodnik naprawy JSON: jak uratować uszkodzone wyjście LLM bez utraty zaufania
Podsumowanie: Wyjście LLM owinięte w ogrodzenie markdown, z przecinkami końcowymi i literałami Python, surowy parser odrzuci w całości — podobnie jak konfiguracje ręcznie edytowane bez cudzysłowów. Ten przewodnik wyznacza realną granicę między dziewięcioma klasami błędów, które naprawiacz faktycznie poprawia, a czterema, których nie poprawi nigdy, wyjaśnia, dlaczego automat stanów bije regex, i dostarcza łańcuch parsowania gotowy na produkcję z jsonrepair i json-repair.

Surowy parser nie daje uszkodzonemu wejściu żadnej litości: jedną wiadomość o błędzie, jeden numer linii — i ani jednego bajta twoich danych. Naprawiacz istnieje po to, by zamienić „całkowite fiasko“ na „wystarczająco dobre, by ruszyć“ — ale to, co uzupełnia, zawsze jest tylko najlepszym domysłem intencji, nigdy gwarancją poprawności.
Jeden: skąd bierze się uszkodzony JSON
Naprawa nie jest magią — zacznij od zbadania wejścia. W realnych projektach niestandardowy JSON pochodzi z trzech skoncentrowanych źródeł:
- Wyjście LLM. Modele językowe generują tekst token po tokenie; nie uruchamiają żadnego serializatora JSON. Nawet przy prośbie „tylko JSON“ model owinie odpowiedź w ogrodzenie
```json, dopisze z przodu „Proszę, oto dane“, zostawi przecinek końcowy albo uderzy w limit tokenów i zatrzyma się w połowie obiektu. - Kopiowanie z innych języków. Obiekt JavaScript wydrukowany przez
console.logniesie pojedyncze cudzysłowy i klucze bez cudzysłowów; słownik Python drukuje się jakoTrue/False/None. Te „przypominające JSON“ ciągi eksplodują przy pierwszym kontakcie zJSON.parse. - Konfiguracje JSON5/JSONC. Pliki takie jak tsconfig legalnie dopuszczają komentarze i przecinki końcowe. Wklej taki plik do surowego parsera — odrzuci cały plik.
Trzy źródła wymagają różnego traktowania, ale naprawiacze pokrywają wszystkie — pod warunkiem, że błąd jest na ich deklarowanej liście przypadków naprawialnych.
Dwa: dziewięć klas błędów, które naprawiacz faktycznie poprawia
Łącząc dokumentację biblioteki jsonrepair z listami możliwości publikowanymi przez dostawców narzędzi, automatycznie naprawialne błędy dzielą się na dziewięć klas:
| Klasa | Uszkodzone wejście | Wynik naprawy |
|---|---|---|
| Przecinek końcowy | [1, 2, 3,] |
[1, 2, 3] |
| Apostrofy / cudzysłowy typograficzne | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| Klucze bez cudzysłowów | {name: 'Ada'} |
{"name": "Ada"} |
| Komentarze | {"a": 1 /* notatka */} |
{"a": 1} |
| Literały Python | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| Ogrodzenia markdown | ```json {...} ``` |
{...} |
| Brakujące przecinki | [1 2] |
[1, 2] |
| Niedomknięte nawiasy / cudzysłowy | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP / konkatenacja ciągów | cb({...})、"x" + "y" |
{...}、"xy" |
Wspólne dla tych dziewięciu: dane są wszystkie na miejscu; uszkodzona jest tylko składnia. Naprawiacz poprawia interpunkcję i opakowania, nie dotykając ani jednej wartości. Kilka szczegółów zasługuje na osobną uwagę:
- Liczby z zerem wiodącym stają się ciągami.
007naprawia się na"007", a nie na7, żeby nie stracić cyfr. Jeśli pole to naprawdę kod tekstowy, jest to poprawne; jeśli to prawdziwa liczba, decyzja należy do ciebie. - Nagie słowa stają się ciągami.
NaNnie da się naprawić na liczbę — niektóre implementacje wypuszczą"NaN", innenull. Zachowanie różni się między bibliotekami; przetestuj swoją, zanim podłączysz ją do pipeline. - Poprawne wejście przechodzi nietknięte. Każdy porządny naprawiacz najpierw uruchamia ścieżkę szybką surowego parsowania. Poprawny JSON nigdy nie wchodzi do logiki naprawy, więc „naprawienie dobrego dokumentu w zły“ jest niemożliwe.
Trzy: cztery rzeczy, których naprawiacz nie poprawi
Granica po drugiej stronie jest równie jednoznaczna. Nie oczekuj naprawy dla:
- Stron błędów HTML albo czystej prozy. W wejściu nie ma żadnej struktury JSON i żadne narzędzie nie wytworzy danych z niczego.
- Danych składniowo poprawnych, ale błędnych. Klucz z literówką, wartość w złym miejscu, liczba zapisana jako ciąg — to problemy semantyczne, które każdy parser, naprawiacze nie wyłączając, przepuści bez mrugnięcia.
- Danych utraconych przez urwanie. Dokańczanie zmieni
{"items": [{"id": 1}, {"naw poprawny JSON, ale wartość polanamenigdy nie wróci. Dostaniesz obiekt „poprawny, ale niekompletny“. W produkcji sprawdzajstopReason === "max_tokens", zanim zdecydujesz: dokańczać czy ponawiać. - Zduplikowanych kluczy i niejednoznacznych struktur. Który z dwóch identycznych kluczy wygra, zależy od implementacji parsera. Odpowiedzialne naprawiacze oferują tryb strict, który rzuca błąd zamiast po cichu wybrać jeden.
Jedno zdanie podsumowuje granicę zaufania: naprawa to najlepszy domysł, nie gwarancja poprawności. Przepuszczenie niezweryfikowanego wyniku naprawy dalej do potoku oznacza wymianę głośnego błędu składni na cichy błąd danych.
Cztery: dwie szkoły implementacji — jedna URL kończy spór
Naprawiacze na rynku występują w dwóch odmianach, a rozjazd ujawnia się na bardzo konkretnym typie wejścia.
Szkoła zamiany regexem stosuje globalne znajdź-i-zamień na uszkodzonych wzorcach. Rozważ takie wejście:
{"url": "http://example.com", 'note': 'fine'}
Regex zamieniający apostrofy na cudzysłowy przeżre także zawartość URL; regex czyszczący komentarze, kasujący każde //, przeciągnie http:// na pół. Wewnątrz ciągu i na zewnątrz struktury znaki wyglądają identycznie — regex nie umie ich odróżnić.
Szkoła automatu stanów znak po znaku śledzi stan parsowania: wewnątrz ciągu w cudzysłowach podwójnych, w pojedynczych, wewnątrz komentarza liniowego, blokowego, albo w oczekiwaniu na wartość. Gdy zobaczy ', najpierw zapyta „czy jestem wewnątrz ciągu?“ i dopiero potem zdecyduje, czy cudzysłów zamienić, czy pominąć. http://example.com siedzi wewnątrz ciągu w cudzysłowach podwójnych, więc automat wie, że tamtejsze // to dane, nie komentarz, i je zachowa. jsonrepair i json-healer należą do tej szkoły, a mantrze społeczności „naprawiacz to nie znajdź-i-zamień“ chodzi właśnie o to.
Pełna kolejność potoku naprawy (jak ujawnia implementacja devkits) też zasługuje na rzut oka: zdjąć ogrodzenia → znormalizować cudzysłowy typograficzne → wyciągnąć pierwszy zrównoważony blok → usunąć komentarze → opatrzyć nagie klucze cudzysłowami → usunąć przecinki końcowe → skonwertować literały → na końcu przeserializować przez JSON.stringify. To końcowe przeserializowanie to kluczowy krok: cokolwiek robiły wcześniejsze etapy, wyjście generuje się od nowa z wyniku sparsowania, więc każdy surowy parser po prądzie je przyjmie.
Pięć: podłączenie w kodzie — sekwencyjny łańcuch parsowania
Gdy podłączasz naprawę do kodu, kolejność znaczy więcej niż wybór biblioteki. Zgodnie ze wzorcami opublikowanymi przez json2toon i aijsonmedic sekwencja powinna być taka: kontrola urwania → wyciągnięcie odcinka JSON → surowe parse → naprawa jako fallback → walidacja schematem.
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// Naprawione urwane wyjście i tak ma ubytki — ponów zapytanie
throw new Error("Truncated output: retry with a higher max_tokens");
}
// Wyciągnij odcinek JSON: LLM lubi gadać przed 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); // ścieżka szybka dla poprawnego wejścia
} catch {
return JSON.parse(jsonrepair(candidate)); // naprawa jako fallback
}
}
Po stronie Python pakiet json-repair (ponad 4 700 gwiazdek) oferuje loads(), które zwraca obiekt wprost:
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}
Dwa inżynierskie szczegóły:
- Wyrównaj stacki. Jeśli naprawiają frontend i backend, wybierz implementacje o wspólnej semantyce — Python json-repair i jego port TypeScript
@yarmu/json-repair, albo jsonmend, którego wersje Python i JS przechodzą ten sam korpus zgodności z 485 przypadkami. Inaczej to samo wyjście naprawi się w A po stronie klienta i w B po stronie serwera, a debugowanie zamieni się w koszmar. - Włącz log napraw.
@yarmu/json-repairzlogging: truezwraca tablicę każdej operacji naprawy. Gwałtowny wzrost liczby napraw zwykle oznacza, że zmienił się prompt albo wersja modelu — to sygnał wcześniejszy niż jakikolwiek raport o błędzie.
Jeszcze jeden krok po naprawie nie podlega negocjacji: walidacja schematem. Składniowo poprawne nie znaczy użyteczne. Brakujące pola, złe typy i nieoczekiwane klucze łapie schemat. Podejście testów kontraktowych stosuje się tu bezpośrednio; zobacz nasz przewodnik o testach kontraktowych JSON Schema.
Sześć: checklista zapobiegania — najtańsza naprawa to ta, której nie potrzebujesz
Naprawa to zapas. Prawdziwe zwycięstwo to mniej uszkodzonego JSON u źródła, w kolejności priorytetów:
- Structured Outputs (tryb json_schema). Dekodowanie jest ograniczone schematem, więc przecinek końcowy po prostu nie da się wygenerować. Tryb strict OpenAI zawodzi w około 0,1% przypadków — ceną twarde wymagania jak
additionalProperties: false. - Tryb JSON (json_object). Gwarantuje tylko poprawność składniową — nie kształt — a urwanie z powodu limitu tokenów i tak się zdarza.
- Instrukcje jawne. Na endpointach bez trybu JSON sformułowanie „bez ogrodzeń, bez komentarzy, bez przecinków końcowych, wypisuj tylko obiekt“ obniża wskaźnik błędów o 70–80%.
- Obniżyć temperature, podnieść limit tokenów. Pierwsze ogranicza dryf w prozę; drugie ogranicza urwania.
- Ponowić z dolączonym błędem. Gdy walidacja zawodzi, dodaj do rozmowy uszkodzone wyjście plus „ścieżkę JSON + komunikat błędu“ i poproś jeszcze raz. Z precyzyjnym błędem modele zwykle poprawiają się same.
W praktyce uwarstwienie „structured outputs + naprawa jako fallback + walidacja schematem“ pokrywa praktycznie każdy scenariusz.
Siedem: podział pracy — konwersja dialektu to nie naprawa
W skrzynce narzędziowej tej strony są dwa miejsca docelowe, które pokrywają odmienne segmenty tego potoku:
- Problemy dialektu (komentarze, apostrofy, przecinki końcowe) idą prosto do konwertera JSON5. Konwersja JSON5 ↔ JSON standardowy pokrywa dokładnie te trzy klasy, o jawnej semantyce, bez zgadywania. Jeśli całe wejście to plik JSONC/JSON5, konwersja jest bardziej przewidywalna niż naprawa. O kompromisach samych dialektów zobacz przewodnik JSON5 i JSONC.
- Po naprawie przepuść wynik przez narzędzie parsowania JSON, żeby walidować i formatować — z błędami lokalizowanymi na wiersz i kolumnę, potwierdzając, że surowy parser naprawdę przyjmuje wyjście.
- Problemy klasy bibliotecznej (literały Python, dokańczanie urwania, opakowania JSONP, ogrodzenia markdown) nadal wymagają jsonrepair / json-repair po stronie kodu — równoważnej naprawy jednym kliknięciem w przeglądarce nie ma, bo te naprawy wymagają wnioskowania intencji, a lokalna biblioteka jest dla nich bezpieczniejszym domem niż uniwersalny konwerter.
Jeśli trzymasz w ręku komunikat błędu, a nie uszkodzone dane, zacznij od przewodnika naprawy błędów parsowania JSON, przetłumacz komunikat na współrzędne i dopiero potem zdecyduj: edytować ręcznie czy naprawiać.
FAQ
Czy naprawa JSON psuje moje dane?
Dla dziewięciu naprawialnych klas zmienia się tylko interpunkcja i opakowania — wartości pozostają nietknięte, a //, przecinki i klamry wewnątrz ciągów automat stanów rozpoznaje i zachowuje. Ale dokańczanie urwania daje niekompletne obiekty, liczby z zerem wiodącym stają się ciągami, a traktowanie NaN różni się między bibliotekami. Weryfikacja kluczowych pól po naprawie jest obowiązkowa.
Jaki jest związek między naprawą a walidacją?
Walidacja mówi, gdzie wejście jest nielegalne; naprawa wręcza ci legalny dokument. Niezawodny proces robi oba: najpierw naprawić, potem walidować — schemat łapie typy i pola wymagane, kontrola składni potwierdza, że surowy parser przyjmuje wynik. Naprawiać bez walidacji to wymienić głośny błąd składni na cichy błąd danych.
LLM zawsze owija wyjście w ogrodzenie ```json — co robić?
Krótkoterminowo: wyciągnij. Weź tekst od pierwszego { lub [ do ostatniego } lub ] i sparsuj go; naprawiacz ze zdejmowaniem ogrodzeń połknie też całą wiadomość. Długoterminowo: użyj structured outputs albo jawnej instrukcji „bez ogrodzeń markdown“, żeby ogrodzenie w ogóle nie powstało.
jsonrepair czy json-repair — co wybrać?
Dla JavaScriptu pakiet npm jsonrepair (obsługuje transform strumieniowy); dla Pythona json-repair z PyPI. Jeśli naprawiają oba końce, wybierz parę o wyrównanej semantyce — na przykład json-repair plus jego port TS — żeby to samo wejście naprawiało się identycznie po obu stronach.
Naprawiacze poradzą sobie z polskimi znakami i cudzysłowami typograficznymi?
Tak. Cudzysłowy typograficzne z polskich klawiatur („“), twarde spacje i BOM na początku pliku — wszystko to jest na standardowej liście napraw; cudzysłowy typograficzne normalizują się do prostych. Przepuść wynik raz przez walidator i gotowe.