JSON Toolkit

JSON بریده‌شده از LLM: اول دلیل توقف را ببینید، بعد سراغ ترمیم بروید

جمع‌بندی: مدل JSON را وسط یک مقدار رها می‌کند و پارسر فقط شماره ستون می‌دهد. بستن براکت‌ها آن را دوباره قابل پارس می‌کند، اما هر فیلد گمشده حالا داخل داده پنهان است. این مقاله مرز میان چیزی را که ترمیم بریدگی صادقانه برمی‌گرداند و چیزی که باید دوباره درخواست شود روشن می‌کند.

کاربردیحدود 5 دقیقه مطالعهانتشار 2026-11-14به‌روزرسانی 2026-11-14
بستن JSON بریده‌شده با پشته پس از پیمایش حساس به رشته

بریدگی یک خطای نحوی نیست، داده‌ی گمشده است. نحو را می‌توان ترمیم کرد، بریدگی را فقط می‌توان تا حدی برگرداند. همان لحظه‌ای که ابزار شکاف را می‌بندد، شکاف باقی‌مانده از یک خطای پارس به چیزی تبدیل می‌شود که هیچ‌کس خبر ندارد.

بریدگی چه شکلی است: یک شماره ستون کافی نیست

مدل JSON را طبق اسکیمای شما می‌نویسد، به سقف خروجی می‌خورد و متن متوقف می‌شود. این را به ماژول json در پایتون ۳٫۱۱ بدهید:

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads خطای Expecting ':' delimiter, col 94 می‌دهد. ستون به کلید "qty" اشاره می‌کند که مقدار ندارد، اما دلیل واقعی این است که سند پایانی ندارد. رگولار اکسپرشن حریص با افزودن "} شکست می‌خورد؛ بستن پشته‌ای حساس به رشته (بخش ششم) پارس می‌شود، ولی items فقط دو رکورد دارد و رکورد سوم نیمه‌کاره گم شده است. شماره ستون می‌گوید متن کجا تمام شده. هرگز نمی‌گوید چه مقدار گم شده.

این اولین تفاوت واقعی با خطای معمولی JSON است. کامای اضافی یک حالت پایانی روشن دارد: حذفش کن، سند کامل است. بریدگی آن حالت را ندارد. حتی اگر ترمیمش کنی، هنوز تکه‌پاره است.

بریدگی خرابی نحو نیست: نقطه کور ابزار ترمیم

ابزارهایی مثل jsonrepair، JSON خراب از نظر نحو را به JSON معتبر تبدیل می‌کنند: حذف حصار مارک‌داون، کامای انتهایی، تبدیل کوتیشن تکی. آنجا قصد کامل است و ترمیم فقط تمیزکاری. ورودی بریده‌شده برای همان ابزار شبیه JSON خراب است، پس رشته، آرایه و آبجکت باز را می‌بندد و چیزی قابل پارس برمی‌گرداند. از ۸۳ گزارش بریدگی Claude، ابزار ۷۹ مورد را «ترمیم» کرد و فقط ۴ مورد سخت شکست خورد. مانیتورینگ خطا نرخی بیست برابر کمتر از واقعیت دید.

خروجی پس از ترمیم چه شکلی است؟ بازخورد سؤال شش وسط جمله قطع شده، سؤال‌های هفت تا نه وجود ندارند، آرایه next_steps غیب شده. Pydantic همچنان اعتبارسنجی را پاس می‌کند، چون next_steps مقدار پیش‌فرض [] دارد و لیست محدودیت طول ندارد. هر لایه کار خودش را درست انجام می‌دهد. محصول گزارشی مطمئن ولی غلط بیرون می‌دهد.

ترمیم نحوی را روی مسیر بریدگی بگذارید و بی‌صدا از تمیزکاری به جعل تغییر می‌کند. پس اول مرز: ابزار ترمیم فقط آلودگی قالب در پاسخ کامل را مدیریت می‌کند؛ پاسخ بریده‌شده نباید اصلاً به آن برسد. برای آلودگی قالب، راهنمای ترمیم JSON را ببینید.

قدم اول همیشه دلیل توقف است

همه APIهای اصلی در متادیتا و رایگان می‌گویند چرا تولید متوقف شده. این همچنین نادیده‌گرفته‌شده‌ترین خط کد در یکپارچه‌سازی LLM است. Anthropic فیلد stop_reason را می‌دهد، API چت OpenAI فیلد finish_reason را: max_tokens یعنی بریده شده، end_turn یا stop یعنی مدل خودش تمام کرده.

resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
    raise TruncatedOutput(
        f"stop_reason={resp.stop_reason}, "
        f"output_tokens={resp.usage.output_tokens}"
    )
data = json.loads(resp.content[0].text)

وقتی بریدگی استثنای صریح شود، مسیر تلاش دوباره تریگر دارد و مانیتورینگ منبع هشدار. آن ۸۳ گزارش بعداً با یک کوئری روی فیلد stop_reason در لاگ‌هایی پیدا شد که همیشه ذخیره می‌شدند ولی هرگز خوانده نمی‌شدند. Gemini با length و incomplete همین معنی را می‌رساند؛ وقتی ارائه‌دهنده تازه اضافه می‌کنید، جدول نگاشت را ببینید و حدس نزنید.

max_tokens حفاظ ایمنی است، نه بودجه

دلیل مستقیم معمولاً سقفی است که برای نسخه قدیمی محصول گذاشته شده: ۱۵۰۰ توکن که به‌محض ورود جلسه‌های طولانی، ۳۹٪ گزارش‌های بلند را می‌برید. بالا بردن آن سقف رایگان است. صورت‌حساب بر اساس توکن واقعاً تولیدشده است، پس سقف ۴۰۹۶ روی گزارشی با ۱۱۰۰ توکن همان اندازه ۱۵۰۰ هزینه دارد. سقف برای متوقف کردن خروجی بی‌مهار است، نه صرفه‌جویی پول.

از داده تعیین کنید: توزیع واقعی یک هفته را ببینید، p99 را بردارید و کمی فاصله بگذارید. تیم آن حادثه ۴۰۹۶ را انتخاب کرد چون p99 بعد از ترمیم ۲۳۵۰ بود. مسیر دیگر کوچک کردن خود خروجی است. کلیدهای تکراری در آرایه‌های همگن بخش بزرگی از توکن را می‌خورند؛ رمزگذاری جدولی پیش از فراخوانی (ببینید راهنمای قالب TOON) حجمی را که باید زیر سقف بیاید کم می‌کند.

ترتیب فیلدهای اسکیما تعیین می‌کند چه چیزی بریده شود

مدل JSON را از بالا به پایین می‌نویسد. وقتی بودجه تمام شود، آخرین عضو فهرست properties اول از همه می‌رود. اسکیمای مرتب‌شده summary, per_question_feedback, scores, next_steps اول scores را از دست می‌دهد، دقیقاً همان بخشی که کاربران هر هفته اسکرین‌شات می‌گیرند و مقایسه می‌کنند. اصلاح، بازآرایی است: فیلدهای کوتاه حیاتی جلو، جزئیات بلند قابل بازتولید بعد، متن آزاد آخر همه.

رفتار ارائه‌دهنده هم پیامد همان بریدگی را عوض می‌کند:

ارائه‌دهنده سازوکار خروجی ساختاریافته رفتار هنگام بریدگی
OpenAI response_format با strict: true تضمین در سطح نمونه‌گیری، ولی تنگ‌ترین گویش؛ اغلب از تولید امتناع می‌کند
Anthropic input_schema در tool use هیچ تضمینی هنگام رمزگشایی نیست؛ ممکن است براکت بسته‌نشده برگرداند
Gemini responseSchema با MIME JSON رمزگشا فقط enum و نوع را تحمیل می‌کند؛ بریدگی هنوز ممکن است

«خروجی ساختاریافته روشن است، اعتبارسنجی لازم نیست» یک توهم است. هرچه تضمین ارائه‌دهنده شل‌تر، اعتبارسنجی اسکیمای خودتان و حلقه تلاش دوباره بیشتر لازم است. روش ساختن آن تست قرارداد در تست قرارداد JSON Schema آمده است.

وقتی بازیابی جزئی واقعاً لازم است: بستن پشته‌ای حساس به رشته

مواردی هست که چاره‌ای جز بیرون کشیدن چیزی از تکه‌پاره نیست: پیش‌نمایش استریم، پاسخ تخریب‌شده، صف بازبینی انسانی. آنجا بستن، آخرین پله نردبان ترمیم است و دو شرط دارد. اول، پیمایش براکت باید حساس به رشته باشد: حالت کوتیشن و escape را کاراکتر به کاراکتر دنبال کنید، وگرنه { داخل یک مقدار پشته را خراب می‌کند. دوم، جفت کلید-مقدار ناقص را پیش از بستن حذف کنید. کلید "qty" بدون مقدار را نمی‌توان به‌صورت {"qty"} بست؛ کل جفت باید حذف شود.

def close_truncated(s: str) -> str:
    # ۱) پیمایش حساس به رشته؛ اول رشته باز را ببندید
    out, in_str, esc = [], False, False
    for ch in s:
        out.append(ch)
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str
    text = ''.join(out) + ('"' if in_str else '')
    # ۲) جفت ناقص و دونقطه یا کامای آویزان را حذف کنید
    text = re.sub(r',\s*"[^"]*"\s*$', '', text)
    text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
    text = re.sub(r':\s*$', '', text)
    text = re.sub(r',\s*$', '', text)
    # ۳) دوباره پشته را بپیمایید و LIFO ببندید
    stack, in_str, esc = [], False, False
    for ch in text:
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str; continue
        if not in_str:
            if ch in '{[': stack.append(ch)
            elif ch in '}]' and stack: stack.pop()
    return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))

روی ورودی ابتدای مقاله، این کد با پایتون ۳٫۱۱ و فقط کتابخانه استاندارد خروجی {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} را برمی‌گرداند. پارس می‌شود و رکورد سوم گم است. در سمت مدل‌های محلی، کتابخانه‌های اختصاصی مثل partial-json-parser همین کار را می‌کنند: با پشته می‌بندند، بر اساس کامل بودن می‌برند.

نکته مهم افشا است. تابع بستن باید بگوید نتیجه از کدام پله آمده؛ هر چیزی که از پله truncation بیرون بیاید نتیجه جزئی است و باید برچسب بخورد: بخش گمشده را دوباره بخواهید، با سقف بزرگ‌تر تلاش کنید، یا به کاربر بگویید داده ناقص است. تظاهر به اینکه چیزی نشده، ساختن توهم با کد قطعی است.

ترمیم یا تلاش دوباره: جدول مرز

شکل ورودی اقدام درست دلیل
حصار، کامای انتهایی، کوتیشن تکی ابزار ترمیم قصد کامل، فقط نحو آلوده
قطع‌شده وسط رشته تلاش دوباره یا بازیابی جزئی با افشا خود مقدار گم شده
قطع‌شده وسط ساختار بازیابی جزئی با افشا فیلدهای کامل می‌مانند، جفت‌های ناقص باید حذف شوند
پارس می‌شود ولی غلط به نظر می‌رسد اعتبارسنجی کسب‌وکار بریدگی نیست، ولی اغلب همراه آن می‌آید

یک تیم مالی هزینه را اندازه گرفت. فاکتور بلند بریده شد، بستن براکت‌ها JSON معتبر ساخت، فیلد total گمشده مقدار پیش‌فرض ۰ را گرفت، و سیستمی با ۹۸٫۲٪ انطباق قالب ماهی حدود ۲۰۰ فاکتور غلط صادر کرد. بعد از اینکه بریدگی به‌عنوان تخریب سخت تلقی شد و بررسی هویت (total == جمع خطوط) اضافه شد، نرخ خطای پولی از ۰٫۸٪ به ۰٫۰۲٪ رسید، در حالی که انطباق قالب فقط به ۹۹٫۱٪ بالا رفت. سه ماه بهینه‌سازی «انطباق قالب» هدف غلطی را نشانه گرفته بود. پاس شدن در پارسر یعنی پاس شدن در کسب‌وکار نیست.

فهرست چهار موردی: پیش از پارس دلیل توقف را ببینید؛ سقف را با p99 تعیین کنید نه به‌عنوان بودجه؛ فیلدهای حیاتی اسکیما را جلو بگذارید؛ ابزار ترمیم را فقط به آلودگی قالب پاسخ کامل بدهید. با این چهار مورد، بریدگی از خرابی خاموش داده به شکستی پرصدا و قابل تلاش دوباره برمی‌گردد.

نمی‌توانم فقط براکت‌ها را ببندم و نتیجه را استفاده کنم؟

نه. بستن فقط اعتبار نحوی را تضمین می‌کند؛ داده هنوز تکه‌پاره است با جمله نیمه‌کاره، رکورد آخر گم‌شده و مقادیر پیش‌فرض که جای مقدار واقعی را گرفته‌اند. آن را جزئی علامت بزنید، تلاش دوباره یا تخریب را فعال کنید و نرخ بازیابی را لاگ کنید.

چطور بریدگی را از خطای نحوی واقعی تشخیص بدهم؟

دلیل توقف را در متادیتا بخوانید: max_tokens، length یا incomplete یعنی بریدگی؛ end_turn یا stop همراه با شکست پارس یعنی خرابی نحوی واقعی. بدون متادیتا، انتها را ببینید: توقف داخل کوتیشن یا براکت با ساختار بیرونی هنوز بسته‌نشده تقریباً همیشه بریدگی است.

چرا بریدگی ترمیم‌شده از شکست پرصدا خطرناک‌تر است؟

ابزار ترمیم «قابل پارس بودن» را بهینه می‌کند و بریدگی بسته‌شده واقعاً قابل پارس است، پس مانیتورینگ خاموش می‌شود و اعتبارسنجی پایین‌دست به‌خاطر مقادیر پیش‌فرض پاس می‌شود. به همین دلیل ۸۳ گزارش بریدگی فقط ۴ خطا تولید کرد. ابزار مفهومی از قصد ندارد و نمی‌داند چه گم شده، پس بریدگی باید در بالادست گرفته شود.

آیا بالا بردن max_tokens هزینه را زیاد می‌کند؟

نه. صورت‌حساب بر اساس توکن واقعاً تولیدشده است؛ سقف فقط حفاظ است. ۴۰۹۶ روی ۱۱۰۰ توکن تولیدشده همان اندازه ۱۵۰۰ هزینه دارد. آن را طبق p99 واقعی با فاصله تعیین کنید و تلاش را صرف جلوگیری از خروجی بی‌مهار کنید.

منابع

ابزارهای مرتبط

مقالات مرتبط

راهنمای ترمیم JSON: نجات خروجی خراب LLM بدون از دست دادن اعتماد

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

متوسطحدود 6 دقیقه مطالعهبه‌روزرسانی 2026-11-08

راهنمای فرمت TOON: سبک‌سازی JSON پیش از دادن به LLM

وقتی آرایه‌ای یکنواخت را با فرمت JSON به یک مدل زبانی می‌دهید، نام کلیدهای تکراری و پرانتزها توکن می‌بلورند. TOON ساختار را فقط یک‌بار با اشیای تورفتگی‌دار و آرایه‌های جدولی اعلام می‌کند و داده‌ها را خط به خط تخلیه می‌کند. بنچمارک رسمی حدود ۴۰٪ توکن کمتر با دقت پارس بالاتر را نشان می‌دهد. این راهنما سینتکس، زمانی که صرفه‌جویی کار می‌کند، زمانی که تبدیل ارزش ندارد و نحوهٔ اتصال encode و decode را پوشش می‌دهد.

متوسطحدود 6 دقیقه مطالعهبه‌روزرسانی 2026-11-10

تست قرارداد JSON Schema: قواعد اعتبارسنجی را در CI جوش دهید

اسکیما با نوشتن تمام نمی‌شود — از همان‌جا زوال آغاز می‌شود. یک غلط تایپی بی‌صدا اعتبارسنجی را شل می‌کند، یک ریفکتور همه فیکسچرها را می‌شکند. این راهنما ساختاری عملی برای تست قرارداد ارائه می‌دهد: فیکسچرهای مثبت، منفی و اسنپ‌شات، لینت خودِ اسکیما، کامپایل یک‌باره و استفاده مجدد، و چهار دروازه CI که شکست قرارداد را به بیلد قرمز تبدیل می‌کند.

متوسطحدود 8 دقیقه مطالعهبه‌روزرسانی 2026-11-05