JSON Toolkit

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.

Średniozaawansowany~6 min czytaniaOpublikowano 2026-11-08Zaktualizowano 2026-11-08
Diagram potoku naprawy JSON: zdejmowanie ogrodzenia, normalizacja cudzysłowów, bilansowanie nawiasów, walidacja końcowa

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ł:

  1. 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.
  2. Kopiowanie z innych języków. Obiekt JavaScript wydrukowany przez console.log niesie pojedyncze cudzysłowy i klucze bez cudzysłowów; słownik Python drukuje się jako True/False/None. Te „przypominające JSON“ ciągi eksplodują przy pierwszym kontakcie z JSON.parse.
  3. 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. 007 naprawia się na "007", a nie na 7, ż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. NaN nie da się naprawić na liczbę — niektóre implementacje wypuszczą "NaN", inne null. 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:

  1. 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.
  2. 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.
  3. Danych utraconych przez urwanie. Dokańczanie zmieni {"items": [{"id": 1}, {"na w poprawny JSON, ale wartość pola name nigdy nie wróci. Dostaniesz obiekt „poprawny, ale niekompletny“. W produkcji sprawdzaj stopReason === "max_tokens", zanim zdecydujesz: dokańczać czy ponawiać.
  4. 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-repair z logging: true zwraca 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:

  1. 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.
  2. Tryb JSON (json_object). Gwarantuje tylko poprawność składniową — nie kształt — a urwanie z powodu limitu tokenów i tak się zdarza.
  3. 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%.
  4. Obniżyć temperature, podnieść limit tokenów. Pierwsze ogranicza dryf w prozę; drugie ogranicza urwania.
  5. 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.