JSON Toolkit

מדריך תיקון JSON: להציל פלט LLM שבור בלי לאבד אמון

שורה תחתונה: פלט LLM עטוף בגדרות markdown, עם פסיקים תוחמים וליטרלים של Python, לא ישרוד parser מחמיר — וגם קונפיגורציות שנערכו ידנית בלי מרכאות. המדריך הזה מצייר את הגבול האמיתי בין תשע קטגוריות של שגיאות שמתקן מתקן וארבע שלא יתוקנו לעולם, מסביר למה מכונת מצבים מנצחת regex, ומספק שרשרת פענוח מוכנה לפרודקשן עם jsonrepair ו-json-repair.

בינוניכ-6 דקות קריאהפורסם 2026-11-08עודכן 2026-11-08
דיאגרמת צינור תיקון JSON: הסרת גדרות, נירמול מרכאות, איזון סוגריים ואימות סופי

Parser מחמיר לא נותן שום פינה לקלט שבור: הודעת שגיאה אחת, מספר שורה אחד — ואפס בייטים מהנתונים שלכם. מתקן קיים כדי להפוך "כישלון מוחלט" ל"טוב מספיק כדי לרוץ" — אבל מה שהוא משלים תמיד רק ניחוש הטוב ביותר לגבי הכוונה, לעולם לא ערבות לנכונות.

אחד: מאין מגיע JSON שבור

תיקון הוא לא קסם — קודם כל תבחנו את הקלט. בפרויקטים אמיתיים, JSON לא סטנדרטי מגיע משלושה מקורות מרוכזים:

  1. פלט של LLM. מודלי שפה מייצרים טקסט טוקן אחר טוקן; הם לא מריצים מסדר JSON. גם כשמבקשים "רק JSON", המודל עוטף את התשובה בגדר ```json, מוסיף לפניה "הנה הנתונים שלך", משאיר פסיק תוחם, או נתקל בתקרת הטוקנים ועוצר באמצע אובייקט.
  2. העתקה משפות אחרות. אובייקט JavaScript שמודפס דרך console.log נושא מרכאות בודדות ומפתחות בלי מרכאות; מילון Python מודפס כ-True/False/None. המחרוזות ה"דומות ל-JSON" האלה מתפוצצות במפגש הראשון עם JSON.parse.
  3. קונפיגורציות JSON5/JSONC. קבצים כמו tsconfig מתירים לגיטימית הערות ופסיקים תוחמים. הדביקו אחד כזה ל-parser מחמיר — והוא ידחה את הקובץ כולו.

שלושת המקורות דורשות טיפול שונה, אבל מתקנים מכסים את כולם — בתנאי שהשגיאה נמצאת ברשימת המקרים הניתנים לתיקון שהם מצהירים.

שניים: תשע קטגוריות של שגיאות שמתקן באמת מתקן

בשילוב התיעוד של ספריית jsonrepair עם רשימות היכולות שפרסמו ספקי הכלים, שגיאות שניתן לתקן אוטומטית מתחלקות לתשע קטגוריות:

קטגוריה קלט שבור תוצאה אחרי תיקון
פסיק תוחם [1, 2, 3,] [1, 2, 3]
מרכאות בודדות / מעוגלות {'a': 'b'}、{"a": "b"} {"a": "b"}
מפתחות בלי מרכאות {name: 'Ada'} {"name": "Ada"}
הערות {"a": 1 /* הערה */} {"a": 1}
ליטרלים של Python {"ok": True, "v": None} {"ok": true, "v": null}
גדרות markdown ```json {...} ``` {...}
פסיקים חסרים [1 2] [1, 2]
סוגריים / מרכאות לא סגורים {"a": [1, 2 {"a": [1, 2]}
JSONP / שרשור מחרוזות cb({...})、"x" + "y" {...}、"xy"

המשותף לתשע הקטגוריות: הנתונים כולם שם; שבור רק התחביר. המתקן מכוונן פיסוק ועטיפות בלי לגעת אפילו בערך אחד. כמה פרטים ראויים לזכירה נפרדת:

  • מספרים עם אפס מוביל הופכים למחרוזות. 007 מתוקן ל-"007", לא ל-7, כדי שלא תאבדנה ספרות. אם השדה הוא באמת קוד טקסטואלי, זה נכון; אם זה מספר אמיתי, ההחלטה שלכם.
  • מילים חשופות הופכות למחרוזות. NaN לא ניתן לתיקון למספר — מימושים מסוימים יפיקו "NaN", אחרים null. ההתנהגות שונה בין ספריות; בדקו את שלכם לפני שאתם מחברים אותה לצינור.
  • קלט תקין עובר ללא שינוי. כל מתקן רציני מריץ קודם מסלול מהיר של פענוח מחמיר. JSON תקין לעולם לא נכנס ללוגיקת התיקון, ולכן "לתקן מסמך טוב לשבור" הוא בלתי אפשרי.

שלושה: ארבעה דברים שמתקן לא יתקן

הגבול בצד השני ברור בדיוק כמו הגבול הראשון. אל תצפו לתיקון עבור:

  1. דפי שגיאת HTML או פרוזה טהורה. אין שום מבנה JSON בקלט, ואף כלי לא יברא נתונים משום דבר.
  2. נתונים תקינים תחבירית אך שגויים. מפתח עם שגיאת כתיב, ערך במקום הלא נכון, מספר שנשמר כמחרוזת — אלה בעיות סמנטיות שכל parser, מתקנים כלולים, ישאיר לעבור בלי למחות.
  3. נתונים שאבדו בגלל קטיעה. השלמה תהפוך את {"items": [{"id": 1}, {"na ל-JSON תקין, אבל הערך של השדה name לא יחזור לעולם. מקבלים אובייקט "תקין אך לא שלם". בפרודקשן בדקו stopReason === "max_tokens" לפני שאתם מחליטים בין השלמה לניסיון חוזר.
  4. מפתחות משוכפלים ומבנים דו-משמעיים. איזה משני מפתחות זהים ינצח תלוי במימוש ה-parser. מתקנים אחראיים מציעים מצב strict שזורק שגיאה במקום לבחור אחד בשקט.

גבול האמון במשפט אחד: תיקון הוא ניחוש הטוב ביותר, לא ערבות לנכונות. לתת לתוצאת תיקון לא מאומתת להמשיך במורד הצינור פירושו להחליף שגיאת תחביר רועמת בשגיאת נתונים שקטה.

ארבעה: שתי אסכולות מימוש — כתובת אחת מכריעה את הוויכוח

מתקנים בשוק מגיעים בשתי גרסאות, והפער מתגלה מיד על סוג קלט מאוד מסוים.

אסכולת החלפת regex מיישמת חיפוש-והחלפה גלובליים על דפוסים שבורים. שקלו את הקלט הזה:

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

regex שממיר מרכאות בודדות לכפולות יכתוש גם את תוכן הכתובת; regex לניקוי הערות שמוחק כל // יחתוך את http:// לשניים. בתוך מחרוזת ומחוץ למבנה התווים נראים זהים — ו-regex לא יכול להבחין ביניהם.

אסכולת מכונת המצבים תו-אחר-תו עוקבת אחרי מצב פענוח: בתוך מחרוזת מרכאות כפולות, בודדות, בתוך הערת שורה, הערת בלוק, או בהמתנה לערך. כשהיא רואה ', היא שואלת קודם "האם אני בתוך מחרוזת?" ורק אז מחליטה אם להמיר את המרכא או לדלג עליו. http://example.com נמצא בתוך מחרוזת מרכאות כפולות, ולכן מכונת המצבים יודעת שה-// שם הוא נתון ולא הערה, ומשמרת אותו. jsonrepair ו-json-healer שייכים לאסכולה הזו, והמנטרה הקהילתית "מתקן הוא לא חיפוש-והחלפה" מתייחסת בדיוק לזה.

הסדר המלא של צינור התיקון (כפי שנחשף במימוש devkits) ראוי גם הוא למבט: להסיר גדרות → לנרמל מרכאות מעוגלות → לחלץ את הבלוק המאוזן הראשון → להסיר הערות → לעטוף מפתחות חשופים במרכאות → להסיר פסיקים תוחמים → להמיר ליטרלים → בסוף לסדר מחדש באמצעות JSON.stringify. הסידור המחודש הסופי הוא הצעד המפתח: מה שם שעשו השלבים הקודמים, הפלט נוצר מחדש מתוצאת הפענוח, כך שכל parser מחמיר במורד הזרם יבלע אותו.

חמישה: חיבור בקוד — שרשרת פענוח סדורה

כשמחברים תיקון לקוד, הסדר חשוב יותר מבחירת הספרייה. על פי הדפוסים שפרסמו json2toon ו-aijsonmedic, הרצף צריך להיות: בדיקת קטיעה → חילוץ קטע JSON → פענוח מחמיר → תיקון כגיבוי → אימות סכימה.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // תיקון פלט קטוע עדיין ישאיר נתונים חסרים — נסו שוב במקום
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // חלצו קטע JSON: ה-LLM עלול לפטפט לפני ואחרי
  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);   // מסלול מהיר לקלט תקין
  } catch {
    return JSON.parse(jsonrepair(candidate));  // תיקון כגיבוי
  }
}

בצד Python, חבילת json-repair (יותר מ-4,700 כוכבים) מספקת loads() שמחזירה אובייקט ישירות:

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}

עוד שני פרטים הנדסיים:

  • יישרו את ה-Stacks. אם גם ה-frontend וגם ה-backend מתקנים, בחרו מימושים בסמנטיקה משותפת — ה-json-repair של Python ואת הפורט שלו ל-TypeScript @yarmu/json-repair, או jsonmend שגרסאות ה-Python וה-JS שלו עוברות את אותו קורפוס התאמה של 485 מקרים. אחרת אותו פלט יתוקן ל-A בלקוח ול-B בשרת, והדיבוג יהפוך לסיוט.
  • הפעילו יומן תיקונים. @yarmu/json-repair עם logging: true מחזיר מערך של כל פעולת תיקון. זינוק פתאומי בקצב התיקונים בדרך כלל אומר שהפרומפט או גרסת המודל השתנו — אות מוקדם יותר מכל דוח שגיאות.

עוד צעד אחרי התיקון שאינו נתון למשא ומתן: אימות סכימה. תקין תחבירית לא אומר שמיש לשימוש. שדות חסרים, טיפוסים שגויים ומפתחות בלתי צפויים — הסכימה תופסת את כולם. גישת בדיקות החוזה חלה כאן ישירות; ראו את המדריך שלנו על בדיקות חוזה של JSON Schema.

שישה: רשימת מנע — התיקון הזול ביותר הוא זה שלא צריך

תיקון הוא גיבוי. הניצחון האמיתי הוא לייצר פחות JSON שבור במקור, בסדר עדיפויות:

  1. Structured Outputs (מצב json_schema). הפענוח מוגבל על ידי הסכימה, ולכן פסיק תוחם פשוט לא יכול להיווצר. מצב ה-strict של OpenAI נכשל בכ-0.1% — במחיר של דרישות קשות כמו additionalProperties: false.
  2. מצב JSON (json_object). מבטיח רק תקינות תחבירית — לא צורה — וקטיעה עקב תקרת טוקנים עדיין קורה.
  3. הוראות מפורשות. בנקודות קצה בלי מצב JSON, ניסוח "בלי גדרות, בלי הערות, בלי פסיקים תוחמים, הוצא רק את האובייקט" מוריד את שיעור השגיאות ב-70–80%.
  4. הורידו temperature, העלו תקרת טוקנים. הראשון מצמצם סחיבה לפרוזה; השני מצמצם קטיעות.
  5. ניסיון חוזר עם השגיאה מצורפת. כשהאימות נכשל, הוסיפו לשיחה את הפלט השבור פלוס "נתיב JSON + הודעת שגיאה" ובקשו שוב. עם שגיאה מדויקת, מודלים בדרך כלל מתקנים את עצמם.

בפועל, היערכות בשלוש שכבות "structured outputs + תיקון כגיבוי + אימות סכימה" מכסה כמעט כל תרחיש.

שבעה: חלוקת העבודה — המרת דיאלקט היא לא תיקון

בתיבת הכלים של האתר הזה שני יעדים שמכסים מקטעים שונים של הצינור הזה:

  • בעיות דיאלקט (הערות, מרכאות בודדות, פסיקים תוחמים) הולכות ישר לממיר JSON5. ההמרה JSON5 ↔ JSON סטנדרטי מכסה בדיוק את שלוש הקטגוריות האלה, בסמנטיקה מפורשת, בלי ניחושים. אם הקלט כולו קובץ JSONC/JSON5, ההמרה צפויה יותר מהתיקון. על המסחר של הדיאלקטים עצמם, ראו את מדריך JSON5 ו-JSONC.
  • אחרי התיקון, העבירו את התוצאה דרך כלי הפענוח של JSON לאימות ועיצוב — שגיאות ממוקמות לשורה ועמודה, מאשרות ש-parser מחמיר באמת מקבל את הפלט.
  • בעיות ברמת ספרייה (ליטרלים של Python, השלמת קטיעה, עטיפות JSONP, גדרות markdown) עדיין דורשות jsonrepair / json-repair בצד הקוד — תיקון בקליק אחד שקול בדפדפן עדיין אינו קיים, כי התיקונים האלה כוללים הסקת כוונה, וספרייה מקומית היא בית בטוח יותר לזה מאשר ממיר אוניברסלי.

אם בידיכם הודעת שגיאה ולא נתונים שבורים, התחילו במדריך לתיקון שגיאות פענוח JSON כדי לתרגם את ההודעה לקואורדינטות, ורק אז החליטו: עריכה ידנית או תיקון.

שאלות נפוצות

האם תיקון JSON פוגע בנתונים שלי?

לתשע הקטגוריות הניתנות לתיקון משתנים רק פיסוק ועטיפות — הערכים נשארים שלמים, ואת ה-//, הפסיקים והסוגריים המסולסלים בתוך מחרוזות שומרת מכונת המצבים. אבל השלמת קטיעה מספקת אובייקטים לא שלמים, מספרים עם אפס מוביל הופכים למחרוזות, והטיפול ב-NaN שונה בין ספריות. בדיקת השדות המרכזיים אחרי התיקון היא חובה.

מה היחס בין תיקון ואימות?

האימות אומר לכם איפה הקלט לא חוקי; התיקון מוסר לכם מסמך חוקי. תהליך העבודה האמין עושה את שניהם: לתקן קודם, ואז לאמת — הסכימה תופסת טיפוסים ושדות חובה, בדיקת התחביר מאשרת ש-parser מחמיר מקבל את התוצאה. לתקן בלי לאמת פירושו להחליף שגיאת תחביר רועמת בשגיאת נתונים שקטה.

ה-LLM תמיד עוטף את הפלט בגדרת ```json — מה לעשות?

לטווח קצר: חלצו. קחו את הטקסט מה-{ או ה-[ הראשון עד ה-} או ה-] האחרון ופענחו אותו; מתקן עם הסרת גדרות יבלע גם את ההודעה כולה. לטווח ארוך: השתמשו ב-structured outputs או בהוראה מפורשת "בלי גדרות markdown" כדי שהגדרה לא תיווצר בכלל.

jsonrepair או json-repair — מה לבחור?

ל-JavaScript את חבילת ה-npm jsonrepair (תומכת ב-transform זרימתי); ל-Python את json-repair מ-PyPI. אם שני הקצוות מתקנים, בחרו זוג בסמנטיקה מיושרת — למשל json-repair פלוס הפורט שלו ל-TS — כדי שקלט זהה יתוקן זהה בשני הצדדים.

האם מתקנים מתמודדים עם עברית ומרכאות מעוגלות?

כן. מרכאות טיפוגרפיות ממקלדות עבריות («»), רווחים ברוחב מלא ו-BOM בראש הקובץ — הכול ברשימת התיקון הסטנדרטית; מרכאות מעוגלות מנורמלות לישרות. העבירו את התוצאה פעם אחת דרך מאמת וזהו.