JSON Toolkit

যে JSON এখনো পুরো আসেনি তা পার্স করা: স্ট্রিমিং প্রিভিউ ও ইনক্রিমেন্টাল রিপেয়ার

সংক্ষেপে: LLM টোকেন ধরে ধরে JSON ছাড়ে, API বড় রেসপন্স চাঙ্ক ধরে পাঠায়, অথচ JSON.parse গোটা ডকুমেন্ট আসা পর্যন্ত কাজ শুরুই করে না। এই লেখা তিন ধরনের ইমপ্লিমেন্টেশন — সম্পূর্ণ রিপেয়ার, সত্যিকারের ইনক্রিমেন্ট ও পার্শিয়াল পার্সিং — আলাদা করে দেখায়, Allow মাস্ক কীভাবে প্রিভিউ স্থিতিশীল রাখে, সঙ্গে পাইপলাইনের পরিমাপ ও প্রোডাকশন-রেডি কোড।

মধ্যম স্তর~5 মিনিট পড়াপ্রকাশ 2026-11-16আপডেট 2026-11-16
স্ট্রিমিং JSON-এর চাঙ্কের ওপর পার্শিয়াল পার্সিং ও ইনক্রিমেন্টাল রিপেয়ারের ছক

JSON.parse-এর চুক্তি হলো «পুরো ডকুমেন্ট আসা পর্যন্ত শুরু হবে না», আর স্ট্রিমিংয়ের চুক্তি হলো «এক টুকরো এসে এক টুকরো সামলানো হবে» — দুইয়ের দ্বন্দ্ব পারফরম্যান্সে নয়, সম্পূর্ণতার সেমান্টিকসে: যে ডকুমেন্ট এখনো লেখা শেষ হয়নি, তার কোনো «সঠিক পার্স ফলাফল» নেই।

উপসর্গ: তিনটি দৃশ্য যেখানে সম্পূর্ণ টেক্সটের অপেক্ষা করা যায় না

প্রথম দৃশ্যটি LLM অ্যাপ। মডেল টোকেন ধরে ধরে JSON ছাড়ে; 8KB সাইজের স্ট্রাকচার্ড আউটপুট আসতে দশ হাজার সেকেন্ড লাগতে পারে, আর ইউজার তাকিয়ে থাকে ফাঁকা প্যানেলে — অথচ প্রথম সেকেন্ডেই শুরুর কয়েকটি ফিল্ড দেখানো সম্ভব ছিল। দ্বিতীয় দৃশ্যটি গেটওয়ে ও প্রক্সি: upstream কয়েক ডজন MB-র রেসপন্স HTTP chunk-এ ঠেলে পাঠায়, আর যে প্রক্সি ফরওয়ার্ড করার আগে ফিল্ড ফিল্টার করতে চায়, res.json() দিয়ে সব বাফার করলে মেমরির সর্বোচ্চ ব্যবহার কয়েকগুণ বেড়ে যায়। তৃতীয় দৃশ্যটি মেসেজ কিউ ও লগ পাইপলাইন: NDJSON রেকর্ড একটার পর একটা আসে, কনজিউমার ব্যাচ জমাতে চায় না।

সাধারণ বিন্দুটা স্পষ্ট: ডেটা ধীরে ধীরে আসে, অথচ স্ট্যান্ডার্ড পার্সার শুধু সম্পূর্ণ ডকুমেন্ট মেনে নেয়। JSON.parse প্রথম চাঙ্কেই Unexpected end of JSON input ছোড়ে, ৬৫ তম চাঙ্কেও একই এরর ছোড়ে, ফলাফল দেয় শুধু শেষ চাঙ্কে। অপেক্ষা একমাত্র পথ নয় — তবে আগে ঠিক করতে হবে অসমাপ্ত ডকুমেন্ট «পার্স» করা মানে কী।

প্রিফিক্স-ধরে পার্সিংয়ের মৌলিক সেমান্টিকস: প্রতিটি টুকরো কি বৈধ?

7847 বাইটের অর্ডার অ্যারে নিয়ে ১২০ অক্ষরের চাঙ্কে কেটে স্ট্রিমিং আগমন সিমুলেট করুন (Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), প্রতিটি প্রিফিক্সে তিনটি পার্সার চালান:

পদ্ধতি 66টি প্রিফিক্সে সফল সংখ্যা সঞ্চিত সময় সেমান্টিকস
JSON.parse 1 (শুধু শেষ চাঙ্ক) 2.1 ms সব নয়তো কিছুই নয়
partial-json (Allow.ALL) 66 (প্রথম চাঙ্ক থেকেই) 14.3 ms সবসময় «এতদূরে জানা» মান দেয়
jsonrepair প্রতি প্রিফিক্সে সম্পূর্ণ রিপেয়ার পুনরায় চালানো 66 23.8 ms বন্ধনী পূরণ করলে পার্সেবল, তবে প্রতিবার শুরু থেকেই গণনা

দুটি গুরুত্বপূর্ণ উপসংহার। এক: JSON.parse-এর ব্যর্থতা কোনো তথ্যই বহন করে না — রিপোর্ট করা পজিশন সবসময় শেষ প্রান্তে, কতটুকু বাকি আছে তা জানা যায় না, প্রাপ্ত অংশ নিজে সংগত কি না তাও জানা যায় না। দুই: প্রতি প্রিফিক্সে সম্পূর্ণ রিপেয়ার পুনরায় চালানো সম্ভব কিন্তু লাভজনক নয়: প্রতি কলে গড় টেক্সট দৈর্ঘ্য রৈখিকভাবে বাড়ে, সঞ্চিত খরচ O(n²) হারে বাড়ে। 23.8 ms অস্বস্তিকর মনে হয় না; টেক্সট megabyte মানদণ্ডে গেলে সেই একই গুণক হয়ে ওঠে নষ্ট হওয়া সেকেন্ড।

আর একটি সতর্কতা: «প্রিফিক্সে পার্সেবল» মানে «ডেটা সম্পূর্ণ» নয়। পূরণ করা প্রিফিক্সের শেষ সংখ্যা পরের চাঙ্কে চলমান থাকতে পারে, শেষ স্ট্রিং escape সিকোয়েন্সের মাঝে কাটা পড়তে পারে — স্ট্রিমিং প্রিভিউয়ের সব অস্থিরতার মূল এখানেই।

তিন ধরনের ইমপ্লিমেন্টেশন কীভাবে ভাগ বাটোয়ারা করে

স্ট্রিমিং পাশের লাইব্রেরিগুলো তিন ভঙ্গিতে ভাগ হয়, আর ভঙ্গি ভুল বেছে নেওয়া লাইব্রেরি ভুল বেছে নেওয়ার চেয়ে বেশি ক্ষতি করে:

লাইব্রেরি ভঙ্গি উপযোগী অনুপযোগী
jsonrepair (3.15.0) সম্পূর্ণ রিপেয়ার + Transform stream যেটা আসে সেটা «শুরুতেই সম্পূর্ণ হবে এমন ডকুমেন্ট», ক্ষয়হীন ফল চাই শুধু প্রিভিউ দরকার (রিপেয়ার আউটপুট গোটা টেক্সট, ডেটা অবজেক্ট নয়)
partial-json (0.1.7) পার্শিয়াল পার্সিং, অসমাপ্ত লেজ ফেলে দিতে দেয় UI প্রিভিউ: প্রতিটি প্রিফিক্সেই ব্যবহারযোগ্য অবজেক্ট ডেটাবেসে লেখা (প্রিভিউতে ফিল্ড থাকতে পারে না, সংখ্যা অস্থির)
jsonmend (0.1.3) সত্যিকারের ইনক্রিমেন্ট, পাবলিক কনসিস্টেন্সি কর্পাস একটু ইন একটু আউট ভার্সন, আগের অংশ আবার স্ক্যান নয় ইতিমধ্যে শেষ হয়ে যাওয়া ডকুমেন্ট (গোটা পার্সই দ্রুত)

এরা প্রতিদ্বন্দ্বী নয়। jsonrepair তার ./stream সাবপাথ দিয়ে jsonrepairTransform এক্সপোর্ট করে — একটি স্ট্যান্ডার্ড Transform stream: বাঁ দিকে চাঙ্ক ঢোকান, ডান দিক থেকে ঠিক করা JSON টেক্সট ব্লক বেরোয়, আর জোড়া লাগালে গোটা টেক্সট একবারে পার্সের সঙ্গে নিখুঁতভাবে মিলে যায় বলে গ্যারান্টি — decode(encode(x)) === x সমতা সে ধরে রাখে। partial-json অন্য রেখা ধরে রাখে: প্রতিটি প্রিফিক্স সঙ্গে সঙ্গে অবজেক্ট দেয়, বিনিময়ে «ফলাফল শেষে বদলাবে না» প্রতিশ্রুতি ছেড়ে দেয়। jsonmend পাবলিক কনসিস্টেন্সি কর্পাস দিয়ে তৃতীয় রেখাকে নিয়ন্ত্রণ করে: সত্যিকারের ইনক্রিমেন্ট, সেমান্টিক মিল সম্ভব, দুই পাশের ইমপ্লিমেন্টেশনের একই রিগ্রেশন ভিত্তি।

Allow মাস্ক: প্রিভিউয়ে কোন ফিল্ড দেখানো সাহস হয়

partial-json-এর মূল কথা «যত ভাঙা ইনপুটই পার্স করা যায়» নয়, বরং কলার নিজেই ঘোষণা করে কতটুকু অসম্পূর্ণতা সে বহন করতে রাজি। মাস্ক JSON টাইপ অনুসারে বিট ধরে জোড়া হয় (STR, NUM, ARR, OBJ…); একটি টাইপ বাদ দিলে সেই টাইপের অসমাপ্ত মান প্রিভিউতে ঢোকে না:

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        সংখ্যা 12 হলো «এতদূরে পড়া হয়েছে»
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    একই ফিল্ড বদলে গেল: প্রিভিউ অস্থির
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   NUM বিট বাদ দিলে অসমাপ্ত সংখ্যা দেখানো হয় না

পরিমাপে সবচেয়ে ইঞ্জিনিয়ারিং-মূল্যবান এই পর্যবেক্ষণ: দাম, কাউন্টারের মতো সংখ্যা যা পরের চাঙ্কে চলমান হতে পারে, UI-তে প্রতিটি ফ্রেমে বদলায়; আর Allow.ALL & ~Allow.NUM তাদের নির্দেশ দেয় নিঃশব্দে লেখা শেষ না হওয়া পর্যন্ত অপেক্ষা করতে। স্ট্রিংয়ের ক্ষেত্রেও তা-ই — Unicode escape সিকোয়েন্সের মাঝে কাটা স্ট্রিং partial-json 0.1.7 নিরাপদে বাদ দেয়, অনুমান করে না। প্রিভিউয়ের স্থিতিশীলতা পার্সারের দান নয়; কলার মাস্ক দিয়ে সেটা কিনে নেয়।

স্ট্রিমিং রিপেয়ারের ইমপ্লিমেন্টেশন খরচ: লুক-ব্যাক বাফার ও বর্গীয় কপি

স্ট্রিমিং পাইপলাইন মানে গোটা API-কে for লুপে মুড়ে ফেলা নয়। একই 66 চাঙ্কের নমুনায় jsonrepairTransform পাইপলাইন মোট 6.7ms খেয়েছে, অথচ প্রতি প্রিফিক্সে সম্পূর্ণ রিপেয়ার পুনরায় চালানো সঞ্চিত 23.8ms — 3.5 গুণের ব্যবধান আসে ইমপ্লিমেন্টেশন স্তর থেকে: স্ট্রিমিং ইমপ্লিমেন্টেশন প্রয়োজনের জানালাতেই পেছনে তাকায়, আউটপুট ইনক্রিমেন্টাল বাফারে জোড়ে, আগের টেক্সট বারবার কপি করে না।

jsonrepair-এর স্ট্রিমিং কোর HarmonyOS ArkTS-এ পোর্ট করার অভিজ্ঞতা তিনটি সুনির্দিষ্ট খরচ উন্মোচন করেছে: upstream-এর streaming পথ «লুক-ব্যাক বাফার» জমাতে হয়, ছোট ডকুমেন্টে ফল এমনকি flush অবধি অপেক্ষা করে — তাই লেখক স্বল্প টেক্সটের জন্য আলাদা IncrementalRepairer লিখেছেন; upstream-এর regular পথ আউটপুট গোটা জুড়ে বারবার কপি করে, সেটা বর্গীয়, পোর্টের সময় OutputBuilder সেটা সরিয়ে দিয়েছে; আরও আছে বর্ডার অক্ষরের ফাঁদ — «শেষ প্রান্তে পৌঁছেছি» পরীক্ষার text[i] === undefined শর্ত charAt-এ গেলে ধোঁকা খায়, কারণ ''.includes('') সর্বদা true, তাই সীমা অতিক্রম আগেই খালি স্ট্রিং দিয়ে বন্ধ করতে হয়। এই বিশদগুলোই ব্যাখ্যা করে কেন «স্ট্রিমিং রিপেয়ার» একটি নিজস্ব ক্যাটাগরি স্লট পাওয়া মূল্যবান: তার ইঞ্জিনিয়ারিং জটিলতা ও এককালীন রিপেয়ার এক স্তরে নেই।

জানা সীমাটিও উল্লেখ করা উচিত: jsonrepair-এর issue #214 রিপোর্ট করে স্ট্রিমিং রিপেয়ার slash-প্রিফিক্সড মানের আগে কমা না থাকলে বৈধ প্রিফিক্সকেও প্রত্যাখ্যান করে — স্ট্রিমিং অবস্থায় লেক্সিক্যাল স্তরে «পরের অক্ষর এখনো আসেনি» আর «ইনপুট অবৈধ» আলাদা করা কঠিন; লুক-ব্যাক জানালাই এই অস্পষ্টতার জন্য দেওয়া দাম।

বাস্তবায়ন কীভাবে: প্রিভিউ ও স্টোরেজ আলাদা পথে চলে

উপরের সেমান্টিকস একটি পাইপলাইনে গেঁথে দিন; নীতিটি এক বাক্যে ধরা যায়: প্রিভিউ পার্শিয়াল পার্সিং দিয়ে, স্টোরেজ কড়া পার্সিং দিয়ে।

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// পথ ১: ক্ষয়হীন পাইপলাইন। ঢোকে: চাঙ্ক, বেরোয়: ঠিক করা JSON টেক্সট, শেষে কড়া যাচাই
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink পরে JSON.parse + বিজনেস যাচাই করবে
chunkStream.pipe(tr);

// পথ ২: প্রিভিউ পাইপলাইন। প্রতিটি প্রিফিক্স এক ফ্রেম UI দেয়; অসমাপ্ত সংখ্যা ও স্ট্রিং মাস্ক আটকে রাখে
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // শুধু স্থিতিশীল ফিল্ড আঁকো; দ্রুত বদলানো ফিল্ড অপেক্ষা করুক
}

দুই পথের চুক্তি ভিন্ন এবং একে অন্যকে প্রতিস্থাপন করে না: প্রিভিউ ফ্রেমে ফিল্ড না থাকতে পারে, স্টোরেজ ফ্রেমে থাকতে পারে না; স্টোরেজ ফ্রেমকে স্ট্রিম শেষ পর্যন্ত অপেক্ষা করে গোটা JSON.parse ও বিজনেস যাচাই পার হতে হয়, আর প্রিভিউ ফ্রেম কোথাও লেখা হয় না। যদি upstream LLM আউটপুট হয়, লেখার আগে stop_reason দেখে কাটা হয়েছে কি না বিচার করতে হবে — «আগে stop_reason, পরে রিপেয়ার» প্রবাহটি LLM কাটা JSON রিপেয়ার লেখায় বিস্তৃত আছে, এখানে পুনরাবৃত্তি করছি না।

কখন স্ট্রিমিং করবেন না

তিনটি ভেটো শর্ত; একটিতে ভুলেও পড়লে আন্তরিকভাবে গোটা পার্সই করুন: ফাইল ছোট — সাধারণ JSON.parse ~22MB পর্যন্ত একবারে পড়তে সাধারণত এক সেকেন্ডের নিচে, স্ট্রিমিং শুধু কোড বাড়ায়; শুধু এককালীন পরিসংখ্যান — অ্যাগ্রিগেশন jq --stream বা লাইন-ধরে NDJSON দিয়ে সহজ, দেখুন JSONL প্র্যাকটিক্যাল গাইড; পাশের ভোক্তা পার্শিয়াল ডেটা মেনে নেয় না — যেমন মোট টাকা, প্রিভিউ থেকে একটি ভুল গুণিত মধ্যবর্তী মানই সত্যিকারের ক্ষতি; তখন স্ট্রিমিং প্রিভিউর মূল্য কেবল «অগ্রগতি বার»।

স্ট্রিমিং পার্সিং যেটা সমাধান করে সেটা সবসময় «অপেক্ষা করা যায় না», «দ্রুত» নয়। একই টেক্সট পরিমাণে গোটা পার্সের সমষ্টিগত CPU সময় সবসময় যেকোনো স্ট্রিমিং বিকল্পের চেয়ে কম; আপনি বিনিময় করেন প্রথম ব্যবহারযোগ্য বাইটের সময় ও ধ্রুব মেমরির জলস্তর। এই লেনদেনটি পরিষ্কার করলে প্রযুক্তি নির্বাচনে দুলবেন না।

সাধারণ প্রশ্ন

প্রিভিউ অবজেক্ট সরাসরি ডেটাবেসে রাখা যায়?

যায় না। প্রিভিউ হলো «এতদূরে জানা»-র ছবি: সংখ্যা পরের চাঙ্কে চলমান হতে পারে, স্ট্রিং কাটা পড়তে পারে, ফিল্ড সাময়িকভাবে অনুপস্থিত থাকতে পারে। লেখার আগে স্ট্রিম শেষ অবধি অপেক্ষা করে গোটা টেক্সটে এক রাউন্ড কড়া JSON.parse চালিয়ে, তারপর বিজনেস যাচাই পার করতে হবে। প্রিভিউ শুধু UI স্তরের।

partial-json না jsonrepair?

আপনি টেক্সট চান না অবজেক্ট তার ওপর নির্ভর করে। ক্ষয়হীন রিপেয়ার করা টেক্সট (পাশে পার্স করাতে পাঠানোর জন্য) jsonrepair — এর স্ট্রিমিং আউটপুট গোটা পার্সের সঙ্গে মিলের গ্যারান্টি দেয়; প্রতি প্রিফিক্সে অবজেক্ট তৎক্ষণাৎ UI-তে দেখাতে partial-json, Allow মাস্ক আপনি যতটা অস্থিরতা বহন করতে পারেন তার ভিত্তিতে সেট করুন।

স্ট্রিমিং পার্সিং কি মোট সময় কমায়?

না। গোটা পার্সের সমষ্টিগত CPU সময় সর্বদা সবচেয়ে কম, স্ট্রিমিং বিকল্প অতিরিক্ত স্টেট বজায় রাখার খরচও দেয়। স্ট্রিমিং বদলে তিনটি জিনিস: প্রথম চাঙ্ক ব্যবহারযোগ্য হওয়ার সময়, গোটা দৈর্ঘ্য অনুসারে না বাড়া মেমরি, এবং প্রাপ্তির মধ্যেই প্রসেস করার ক্ষমতা (ফরওয়ার্ড, ফিল্টার, প্রদর্শন)।

অ্যারের উপাদান একটা একটা করে আসছে, একটা একটা করে সামলাতে চাই?

সেটা অন্য পথ: stream-json-এর streamArray উপাদান বন্ধ হওয়ামাত্র {key, value} ছোড়ে, আর for await-এর সঙ্গে স্বাভাবিক ব্যাকপ্রেশার তৈরি হয় — «পার্স করে লেখা» বাল্ক ইমপোর্টে মানানসই; এই লেখা কথা বলছে গোটা ডকুমেন্ট স্তরের প্রিভিউ নিয়ে।

তথ্যসূত্র

সংশ্লিষ্ট টুল

সম্পর্কিত নিবন্ধ

JSON মেরামত গাইড: ভাঙা LLM আউটপুট উদ্ধার ও বিশ্বাসের সীমানা

markdown ফেন্সে মোড়ানো, trailing comma ও Python লিটারালযুক্ত LLM আউটপুট কঠোর পার্সার পুরোপুরি বাতিল করে — উদ্ধৃতি ছাড়া হাতে সম্পাদিত কনফিগও তাই। এই গাইডে মেরামতকারী যে নয় শ্রেণির ত্রুটি ঠিক করে আর যে চার শ্রেণি কখনো ঠিক করে না, তার প্রকৃত সীমানা টানা হয়েছে, স্টেট মেশিন কেন regex-কে হারায় তা ব্যাখ্যা করা হয়েছে এবং jsonrepair ও json-repair দিয়ে প্রোডাকশন-রেডি পার্স চেইন দেওয়া হয়েছে।

মধ্যবর্তী~6 মিনিট পড়াআপডেট 2026-11-08

LLM-এর JSON মাঝপথে কাটা পড়লে: আগে থামার কারণ দেখুন, তারপর মেরামতের কথা ভাবুন

মডেল কোনো মানের মাঝখানে JSON কেটে ফেলে, আর পার্সার শুধু একটা কলাম নম্বর দেয়। বন্ধনী বন্ধ করলে সেটা আবার পার্স হয়, কিন্তু তখন হারানো প্রতিটি ফিল্ড ডেটার ভেতরে লুকিয়ে যায়। এই লেখাটি স্পষ্ট করে দেয়, ট্রাঙ্কেশন মেরামত সৎভাবে কী ফিরিয়ে আনতে পারে আর কী আবার চাওয়া ছাড়া সম্ভব নয়।

ব্যবহারিক~5 মিনিট পড়াআপডেট 2026-11-14

JSONL ফাইল প্র্যাকটিক্যাল গাইড: খোলা, কনভার্ট ও ত্রুটিপূর্ণ লাইন শনাক্তকরণ

পুরো .jsonl ফাইল JSON.parse-এ দিলে এরর আসা প্রায় কখনোই বোঝায় না যে ফাইল নষ্ট — বোঝায় পড়ার পদ্ধতি ভুল। এই গাইডে থাকছে পরীক্ষা ও লাইন ধরে পড়ার মানক প্যাটার্ন, JSON অ্যারের সাথে দুই দিকের রূপান্তরের কমান্ড, ছয় ধরনের ত্রুটিপূর্ণ লাইনের টেবিল, আর স্ট্রিমিং HTTP রেসপন্স থেকে NDJSON সঠিকভাবে ব্যবহারের পদ্ধতি।

মধ্যবর্তী~9 মিনিট পড়াআপডেট 2026-11-06