راهنمای ترمیم JSON: نجات خروجی خراب LLM بدون از دست دادن اعتماد
جمعبندی: خروجیهای LLM که در دیوارکش markdown پیچیده شدهاند و کامای انتهایی و لفظهای Python دارند، هرگز از پارسر سختگیر جان سالم به در نمیبرند — فایلهای پیکربندیِ دستیِ بدون گیومه هم همینطور. این راهنما مرز واقعی بین نه کلاس خطای قابل ترمیم و چهار کلاس بیامان را ترسیم میکند، توضیح میدهد چرا ماشین حالت از regex قویتر است، و یک زنجیره تجزیه آماده تولید با jsonrepair و json-repair تحویل میدهد.

پارسر سختگیر به ورودی خراب هیچ بخششی نمیدهد: یک پیام خطا، یک شماره خط — و نه یک بایت از دادههای تو. ابزار ترمیم برای همین وجود دارد که «شکست کامل» را به «به اندازه کافی خوب برای اجرا» تبدیل کند — اما هرچه پر میکند همیشه بهترین حدس از قصد است، نه تضمین درستی.
یک: JSON خراب از کجا میآید
ترمیم جادو نیست — پس اول ورودی را ببین. در پروژههای واقعی، JSON غیراستاندارد از سه منبع متمرکز میآید:
- خروجی LLM. مدلهای زبانی متن را توکن به توکن تولید میکنند؛ هیچ سریالساز JSONی را اجرا نمیکنند. حتی وقتی «فقط JSON» خواستهای، مدل پاسخ را در دیوارکش
```jsonمیپیچد، «این هم دادههای تو» را جلوی آن میگذارد، کامای انتهایی جا میگذارد، یا به سقف توکن میخورد و وسط یک شیء میایستد. - کپی از زبانهای دیگر. شیء جاوااسکریپتی که با
console.logچاپ شده، گیومه تکی و کلیدهای بدون گیومه دارد؛ دیکشنری پایتون به صورتTrue/False/Noneچاپ میشود. این رشتههای «شبه JSON» با اولین تماس باJSON.parseمنفجر میشوند. - پیکربندیهای JSON5/JSONC. فایلهایی مثل tsconfig بهطور قانونی کامنت و کامای انتهایی را مجاز میدانند. یکی از اینها را در پارسر سختگیر پیست کنی، کل فایل را رد میکند.
سه منبع رفتار متفاوتی میطلبند، اما ابزارهای ترمیم همه را پوشش میدهند — به شرط آنکه خطا در فهرست اعلامشده موارد قابل اصلاح باشد.
دو: نه کلاس خطایی که ابزار ترمیم واقعاً اصلاح میکند
با ترکیب مستندات کتابخانه 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 معتبر هرگز وارد منطق ترمیم نمیشود، پس «ترمیم سند خوب به بد» ناممکن است.
سه: چهار چیزی که ابزار ترمیم اصلاح نمیکند
مرز آن سمت هم به همان اندازه صریح است. منتظر ترمیم اینها نباش:
- صفحات خطای HTML یا نثر خالص. هیچ ساختار JSONی در ورودی نیست و هیچ ابزاری نمیتواند داده از هیچ بسازد.
- دادههای از نظر نحوی معتبر ولی غلط. کلید با غلط املایی، مقدار در جای اشتباه، عدد ذخیرهشده به شکل رشته — اینها مسائل معناییاند که هر پارسری، از جمله ابزارهای ترمیم، بیسروصدا رد میکند.
- دادههای ازدسترفته بهخاطر قطعشدن. تکمیل میتواند
{"items": [{"id": 1}, {"naرا به JSON معتبر تبدیل کند، اما مقدارnameهرگز برنمیگردد. چیزی که میگیری «معتبر ولی ناقص» است. در تولید، قبل از تصمیم بین تکمیل و تلاش دوباره،stopReason === "max_tokens"را چک کن. - کلیدهای تکراری و ساختارهای مبهم. کدامیک از دو کلید یکسان برنده میشود به پیادهسازی پارسر بستگی دارد. ابزارهای ترمیمِ مسئولانه حالت strict دارند که بهجای بیسروصدا یکی را انتخاب کردن، خطا پرتاب میکند.
مرز اعتماد در یک جمله: ترمیم «بهترین حدس» است، نه «تضمین درستی». فرستادن خروجی ترمیم تأییدنشده به پاییندست، یعنی معاوضه خطای نحوی پرسر و صدا با خطای داده بیصدا.
چهار: دو مکتب پیادهسازی — یک URL دعوا را تمام میکند
ابزارهای ترمیم بازار دو طعم دارند و اختلاف در نوع مشخصی از ورودی فوراً خودش را نشان میدهد.
مکتب جایگزینی با regex جستوجو-و-جایگزینی سراسری روی الگوهای خراب اعمال میکند. این ورودی را ببین:
{"url": "http://example.com", 'note': 'fine'}
یک regex که گیومه تکی را به دوتایی تبدیل میکند، محتوای URL را هم میجود؛ یک regex پاکسازی کامنت که هر // را حذف میکند، http:// را دو نیم میکند. داخل رشته و بیرون ساختار، کاراکترها یکساناند — regex نمیتواند تفکیکشان کند.
مکتب ماشین حالتِ کاراکتر به کاراکتر یک وضعیت پارس را دنبال میکند: داخل رشته با گیومه دوتایی، داخل رشته با گیومه تکی، داخل کامنت خطی، داخل کامنت بلوکی، یا در انتظار مقدار. وقتی ' میبیند، اول میپرسد «آیا داخل رشتهام؟» و بعد تصمیم میگیرد گیومه را تبدیل کند یا رد کند. http://example.com داخل رشته گیومهدوتایی است، پس ماشین حالت میداند // آنجا داده است نه کامنت، و حفظش میکند. jsonrepair و json-healer از این مکتباند و شعار جامعه که «ابزار ترمیم، جستوجو-و-جایگزینی نیست» دقیقاً به همین اشاره دارد.
ترتیب کامل خط لوله ترمیم (طبق پیادهسازی منتشرشده devkits) هم ارزش نگاه دارد: برداشتن دیوارکشها → استانداردسازی گیومه خمیده → استخراج اولین بلوک متوازن → حذف کامنتها → گیومهگذاری کلیدهای لخت → حذف کاماهای انتهایی → تبدیل لفظها → در نهایت سریالسازی مجدد با JSON.stringify. همین سریالسازی مجدد نهایی، گام کلیدی است: فارغ از اینکه مراحل قبل چه کردند، خروجی از نتیجه پارس بازتولید میشود، پس هر پارسر سختگیرِ پاییندستی آن را میبلعد.
پنج: اتصال در کد — زنجیره پارس ترتیبی
وقتی ترمیم را در کد وصل میکنی، ترتیب مهمتر از انتخاب کتابخانه است. طبق الگوهای منتشرشده 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)); // ترمیم بهعنوان جایگزین
}
}
در سمت پایتون، پکیج json-repair (بیش از ۴۷۰۰ ستاره) 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}
دو جزئیات مهندسی:
- استکها را همتراز کن. اگر فرانتاند و بکاند هر دو ترمیم میکنند، پیادهسازیهایی با معناشناسی مشترک انتخاب کن — پایتون json-repair و پورت TypeScript آن
@yarmu/json-repair، یا jsonmend که نسخههای پایتون و JS آن از همان مجموعه انطباق ۴۸۵ کیسی عبور میکنند. وگرنه همان خروجی سمت کلاینت به A و سمت سرور به B ترمیم میشود و دیباگ به کابوس تبدیل میشود. - لاگ ترمیم را روشن کن.
@yarmu/json-repairباlogging: trueآرایه هر عملیات ترمیم را برمیگرداند. جهش ناگهانی در نرخ ترمیم معمولاً یعنی پرامپت یا نسخه مدل عوض شده — سیگنالی زودتر از هر گزارش خطا.
یک گام بعد از ترمیم غیرقابل مذاکره است: اعتبارسنجی اسکیما. معتبر از نظر نحو به معنای قابل استفاده نیست. فیلدهای جاافتاده، نوعهای غلط و کلیدهای ناخواسته همه را اسکیما میگیرد. رویکرد تست قرارداد همینجا مستقیماً کاربرد دارد؛ راهنمای تست قرارداد JSON Schema ما را ببین.
شش: چکلیست پیشگیری — ارزانترین ترمیم، ترمیمی است که اصلاً لازم نداری
ترمیم همان پشتیبان است. تولید JSON خراب کمتر در مبدأ، پیروزی واقعی است، به ترتیب اولویت:
- Structured Outputs (حالت json_schema). رمزگشایی با اسکیما محدود میشود، پس کامای انتهایی اصلاً قابل تولید نیست. حالت strict اوپنایآی حدود ۰٫۱٪ شکست میخورد، به بهای الزامات سخت مثل
additionalProperties: false. - حالت JSON (json_object). فقط اعتبار نحوی را تضمین میکند — نه شکل را — و قطعشدن بهخاطر سقف توکن همچنان رخ میدهد.
- دستورالعملهای صریح. در انپوینتهای بدون حالت JSON، نوشتنِ «بدون دیوارکش، بدون کامنت، بدون کامای انتهایی، فقط شیء را خروجی بده» نرخ خطا را ۷۰ تا ۸۰ درصد کم میکند.
- temperature را پایین بیاور، سقف توکن را بالا ببر. اولی احتمال راندهشدن به نثر را کم میکند؛ دومی قطعشدن را.
- تلاش دوباره با خطای ضمیمه. وقتی اعتبارسنجی شکست میخورد، خروجی خراب بهعلاوه «مسیر JSON + پیام خطا» را به گفتگو اضافه کن و دوباره بخواه. مدلها با خطای دقیق معمولاً خودشان را اصلاح میکنند.
در عمل، لایهبندی «structured outputs + ترمیم جایگزین + اعتبارسنجی اسکیما» تقریباً هر سناریویی را پوشش میدهد.
هفت: تقسیم کار — تبدیل گویش، ترمیم نیست
در جعبهابزار این سایت دو مقصد داریم که بخشهای متمایزی از این خط لوله را پوشش میدهند:
- مسائل گویشی (کامنت، گیومه تکی، کامای انتهایی) مستقیم به مبدل JSON5 میروند. تبدیل متقابل JSON5 ↔ JSON استاندارد دقیقاً همین سه کلاس را پوشش میدهد، با معناشناسی صریح و بدون حدس. اگر کل ورودی یک فایل JSONC/JSON5 است، تبدیل از ترمیم قابل پیشبینیتر است. برای موازنههای خود گویشها، راهنمای JSON5 و JSONC را ببین.
- بعد از ترمیم نتیجه را از ابزار پارس JSON عبور بده تا اعتبارسنجی و قالببندی شود، خطاها به سطر و ستون مشخص شوند، و مطمئن شوی پارسر سختگیر واقعاً خروجی را میپذیرد.
- مسائل رده کتابخانه (لفظهای Python، تکمیل قطعشدن، بستهبندی JSONP، دیوارکشهای markdown) فعلاً به jsonrepair / json-repair سمت کد نیاز دارند — معادل یککلیکی در مرورگر وجود ندارد، چون این ترمیمها استنتاج قصد را در بر دارند و کتابخانه محلی برای این کار خانه امنتری از یک مبدل عمومی است.
اگر چیزی که در دست داری پیام خطاست نه داده خراب، اول از راهنمای اصلاح خطاهای پارس JSON شروع کن تا پیام را به مختصات ترجمه کنی، بعد تصمیم بگیر: ویرایش دستی یا ترمیم.
پرسشهای متداول
آیا ترمیم JSON دادههای من را خراب میکند؟
برای نه کلاس قابل اصلاح فقط نشانهگذاری و بستهبندی عوض میشود — مقادیر دستنخورده میمانند و //، کاما و آکولاد داخل رشتهها با ماشین حالت شناسایی و حفظ میشوند. اما تکمیل قطعشدن اشیای ناقص میدهد، عددهای با صفر ابتدایی رشته میشوند، و رفتار با NaN بین کتابخانهها متفاوت است. بررسی فیلدهای کلیدی بعد از ترمیم اجباری است.
رابطه ترمیم و اعتبارسنجی چیست؟
اعتبارسنجی میگوید ورودی کجا غیرقانونی است؛ ترمیم دستت را به یک سند قانونی میدهد. جریان کاری قابل اتکا هر دو را انجام میدهد: اول ترمیم، بعد اعتبارسنجی — اسکیما نوعها و فیلدهای الزامی را میگیرد، بررسی نحوی تأیید میکند پارسر سختگیر نتیجه را میپذیرد. ترمیم بدون اعتبارسنجی یعنی معاوضه خطای نحوی پرسر و صدا با خطای داده بیصدا.
خروجی LLM همیشه در دیوارکش ```json پیچیده میشود — چه کنم؟
کوتاهمدت: استخراج کن. از اولین { یا [ تا آخرین } یا ] را بگیر و پارس کن؛ ابزار ترمیمی که دیوارکش را برمیدارد کل پیام را هم میبلعد. بلندمدت: از structured outputs یا دستور صریح «بدون دیوارکش markdown» استفاده کن تا دیوارکش اصلاً تولید نشود.
jsonrepair یا json-repair — کدام را انتخاب کنم؟
برای جاوااسکریپت پکیج npm jsonrepair (با پشتیبانی transform جریانی)؛ برای پایتون json-repair از PyPI. اگر دو سر ترمیم میکنند، جفتی با معناشناسی همتراز انتخاب کن — مثلاً json-repair بهعلاوه پورت TS آن — تا همان ورودی در دو سمت یکسان ترمیم شود.
آیا ابزارهای ترمیم فارسی و گیومه خمیده را پشتیبانی میکنند؟
بله. گیومههای تایپوگرافیک صفحهکلیدهای فارسی («»)، فاصلههای کامل و BOM ابتدای فایل همه در فهرست استاندارد ترمیماند؛ گیومه خمیده به گیومه راست استاندارد میشود. نتیجه را یک بار از اعتبارسنج رد کن و تمام.