JSON Toolkit

LLM-এর স্ট্রাকচার্ড আউটপুট ভেঙে পড়ে: strict মোডের জন্য সত্যিকারের স্কিমা কীভাবে লিখবেন

সংক্ষেপে: সাধারণ JSON Schema-তে সরাসরি strict চালু করলে বেশিরভাগ সময় 400 ফেরত আসে: সব ফিল্ড required, প্রতিটি অবজেক্টে additionalProperties:false, $ref ও allOf সঙ্গে সঙ্গে বাতিল। এই গাইডে দেখানো হয়েছে কীভাবে শিথিল স্কিমাকে ব্যাচে strict-সামঞ্জস্য সংস্করণে পুনর্লিখন করা যায় — nullable ইউনিয়ন, কঠিন সীমা আর refusal শ্রেণিবিন্যাসের চেকলিস্টসহ।

মধ্যম~8 মিনিট পড়াপ্রকাশ 2026-11-19আপডেট 2026-11-19
LLM-এর strict মোডের জন্য JSON Schema পুনর্লিখনের নিয়মের চিত্র

মূল কথা: strict: true কোনো "একটু বেশি সিরিয়াস হও" সুইচ নয় — এটি এমন এক চুক্তি যা JSON Schema-র শুধু একটি উপসেট মেনে নেয়। সব ফিল্ড required-এ, প্রতিটি অবজেক্টে additionalProperties: false, $ref ও allOf সরাসরি বাতিল। পুনর্লিখন না করে strict মোডে স্কিমা পাঠালে উত্তর হলো 400, বিশ্বস্ত আউটপুট নয়।

যে একই স্কিমা আপনার লোকাল ভ্যালিডেটরে নির্বিঘ্নে পাস করে, strict: true জুড়ে মডেল API-তে পাঠালে সেটি সঙ্গে সঙ্গে ফেরত এসে পড়ে। মডেল বোকা হয়ে যায়নি — সরবরাহকারী constrained decoding-এর যে স্কিমা উপসেট দরকার তার চারপাশে একটি কঠোর সীমারেখা এঁকেছে, আর আপনার স্কিমা সেই রেখা পেরিয়ে গেছে।

strict আসলে কী বদলায়: স্যাম্পলারকে ব্যাকরণে তালাবদ্ধ করা

সাধারণ মোডে মডেলের তৈরি JSON আপনার স্কিমার সঙ্গে "সম্ভবত" মেলে মাত্র, প্রম্পটের "JSON আকারে উত্তর দাও" লাইনটি পিঠের ভর দেয়। OpenAI-র অফিসিয়াল evals-এ gpt-4-0613 শুধু প্রম্পট দিয়ে জটিল স্কিমা অনুসরণের হার ছিল ৪০%-এর নিচে; strict চালু করার পর gpt-4o-2024-08-06 একই সেটে ১০০% ছুঁয়েছে।

প্রক্রিয়াটি হলো constrained decoding: প্রথম রিকোয়েস্টে API আপনার স্কিমাকে একটি সসীম স্টেট মেশিনে কম্পাইল করে, ডিকোডিং চলাকালে প্রতিটি টোকেন সেই মেশিনের অনুমতি নিয়ে যেতে হয়। মডেল স্কিমা ভঙ্গ করে এমন টোকেন "জারি করতে পারে না"। এটি অনুস্মারক নয় — এটি ভৌত তালা। দাম দুই কিস্তিতে: নতুন স্কিমার প্রথম কম্পাইলে অতিরিক্ত সময় লাগে (সাধারণত ১০ সেকেন্ডের নিচে, জটিল স্কিমায় এক মিনিট পর্যন্ত) এবং প্রথম টোকেনের লেটেন্সি প্রায় ৫-৮% বাড়ে; কম্পাইল আর্টিফ্যাক্ট ক্যাশ হয়, পরের রিকোয়েস্ট আর কিছু দিতে হয় না।

কী নিশ্চিত হয় আর কী হয় না পরিষ্কার রাখুন: বাক্যগঠন ও আকৃতি তালাবদ্ধ, অর্থ নয়। মডেল তবুও estimate_hours-এ ৪০০ ভরাট করে দিতে পারে, ভুল ইমেইল বের করতে পারে। আকৃতি মেঝে, ছাদ নয় — অর্থগত মান এখনও eval সেট সামলায়। ২০২৬ সালেও সর্বশেষ মডেলগুলো লোডের নিচে প্রায় ০.৪% অবশিষ্ট বিকৃতি হার দেখায়; রিট্রাই লুপ এখনও বাধ্যতামূলক।

তিনটি কঠোর নিয়ম: সব required, অতিরিক্ত কী বন্ধ, nullable-ই optional

strict মোড স্কিমায় তিনটি পুনর্লিখন-শর্ত আরোপ করে, আর প্রতিটিই সাধারণ JSON Schema অনুশীলনের অন্তর্দৃষ্টির ঠিক উল্টো:

  1. প্রতিটি ফিল্ড required-এ লিখতে হবে। strict-এ ঐচ্ছিক ফিল্ডের ধারণা নেই। "ঐচ্ছিক" বোঝাতে ফিল্ডটি required-এ রাখুন, কিন্তু টাইপ লিখুন nullable ইউনিয়ন হিসেবে — "type": ["string", "null"] — আর অনুপস্থিতিতে মডেলকে null ফেরত দিন। এটি সাধারণ প্রচলিত রীতির ঠিক বিপরীত, যেখানে required-এ শুধু সত্যিই দরকারি ফিল্ড থাকে।
  2. প্রতিটি অবজেক্টে additionalProperties: false স্পষ্টভাবে ঘোষণা করতে হবে। সাধারণ স্কিমায় এটি প্রায়ই না-সেট রাখা হয় (আমাদের additionalProperties-এর রানটাইম-ভেদে আচরণ নিবন্ধ দেখুন), কিন্তু strict মোডে এটি প্রবেশাধিকারের শর্ত: না লিখলে রিকোয়েস্ট পড়ে। কারণটি সরাসরি — স্টেট মেশিন শুধু ঘোষিত কী তৈরি করতে পারে, যে কোনো অঘোষিত কী গঠনগতভাবেই অপ্রাপ্য।
  3. Python ব্যবহারকারীর ফাঁদ: Pydantic ডিফল্টসহ ফিল্ডকে required থেকে ফেলে দেয়। priority: str = "low" লিখলেই জেনারেট হওয়া স্কিমার required একটি ঘাটতি হয়, strict সরাসরি বাতিল করে। ডিফল্ট সরান অথবা নিচের স্ক্রিপ্ট দিয়ে ব্যাচে ভরাট করুন।

তিনটি নিয়ম প্রতিটি নেস্টেড অবজেক্ট স্তরে রিকার্সিভভাবে প্রয়োগ হতে হবে। শুধু উপরের স্তর ঠিক করে চাইল্ড অবজেক্ট ছেড়ে দিলেও 400 আসবে। ন্যূনতম সামঞ্জস্যপূর্ণ উদাহরণ:

{
  "type": "object",
  "properties": {
    "intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
    "note": { "type": ["string", "null"] }
  },
  "required": ["intent", "note"],
  "additionalProperties": false
}

এসব লেখা সরাসরি 400: নিষিদ্ধ ও নীরব কীওয়ার্ড

strict মোড JSON Schema-র শুধু একটি উপসেট সমর্থন করে। কীওয়ার্ড দুই ঝুড়িতে ভাগ করে আলাদা করে সামলান:

ঝুড়ি কীওয়ার্ড strict মোডে আচরণ
সরাসরি বাতিল $ref / $defs রেফারেন্স, allOf, not, dependentRequired, dependentSchemas, if/then/else API ত্রুটি ফেরত দেয়; রিকোয়েস্ট ব্যর্থ
নীরবে অকার্যকর pattern, minLength, maxLength, format, minimum, maximum, multipleOf (ফাইন-টিউনড মডেল) না ত্রুটি না প্রয়োগ — regex বিধিনিষেধ অ্যাপ স্তরে নিজে যাচাই করতে হয়

সামলানোর পদ্ধতি আলাদা: প্রথম ঝুড়ি পুনর্লিখন করতে হবে — $ref ইনলাইনে বিস্তার করুন, allOf-কে properties-এ একীভূত করুন। দ্বিতীয় ঝুড়ি থাকতে পারে (কিছু কনফিগ মেনে নেয়), তবে কখনো এটিকে প্রতিরক্ষা ভাববেন না। ভার্সন ফরম্যাটের নিশ্চয়তার জন্য "pattern": "^v\\d+\\.\\d+\\.\\d+$"-এর উপর ভরসা করা strict-এর নিচে নগ্ন দৌড়; প্রতিটি রেসপন্সে স্পষ্ট যাচাই চালান। একদম ওপরের আরেকটি নিয়ম: স্কিমার রুট অ্যারে বা খালি ইউনিয়ন হতে পারে না — একটি object দিয়ে মুড়িয়ে নিন।

কঠিন সীমা: ৫০০০ প্রপার্টি, ১০ স্তর নেস্টিং, ১২০ হাজার অক্ষর

সব কীওয়ার্ড সামঞ্জস্যপূর্ণ থাকলেও আকারের সীমা ছাড়ালে ব্যর্থ হবে। OpenAI-র অফিসিয়াল সংখ্যা:

  • পুরো স্কিমায় অবজেক্ট প্রপার্টি সর্বোচ্চ ৫০০০টি, নেস্টিং সর্বোচ্চ ১০ স্তর (Anthropic-এর সীমা প্রায় ৬ স্তর);
  • প্রপার্টি নাম, ডেফিনিশন নাম, enum ও const মানের স্ট্রিংয়ের মোট দৈর্ঘ্য ১২০০০০ অক্ষরে সীমাবদ্ধ;
  • enum মান মোট সর্বোচ্চ ১০০০টি; ২৫০-এর বেশি মানসহ একক স্ট্রিং enum ১৫০০০ অক্ষর ছাড়াতে পারে না।

সাধারণত এই সীমায় স্পর্শ করেন না, তবে "কোম্পানির পুরো অভিধান enum বানানো" আর "তিন স্তরের অবজেক্ট গ্রাফ এক স্তরে চেপে ভরা" — দুটিই বাস্তব দুর্ঘটনার জায়গা। পেলে ভাগ করুন: বিশাল স্কিমা একাধিক কলে ভাঙুন বা গঠন সমতল করুন। কাজের একটি বোনাস: আউটপুট কী-এর ক্রম স্কিমার কী ক্রম অনুসরণ করে; নির্দিষ্ট ক্রমে নির্ভরশীল ডাউনস্ট্রিম পার্সার এটিকে ফিচার হিসেবে ব্যবহার করতে পারে।

এক স্ক্রিপ্টে শিথিল স্কিমাকে ব্যাচে strict রূপে পুনর্লিখন

হাতে স্তরে স্তরে সম্পাদনা বাদ পড়ার আমন্ত্রণ। নিচের রিকার্সিভ স্ক্রিপ্ট (DevToolLab-এর ২০২৬ গাইডে প্রকাশিত প্যাটার্ন) এক পাসে "প্রতিটি অবজেক্ট বন্ধ, প্রতিটি কী required" সম্পূর্ণ করে:

def make_strict(schema: dict) -> dict:
    """additionalProperties:false + প্রতিটি কী required, প্রতি স্তরে।"""
    if isinstance(schema, dict):
        if schema.get("type") == "object" and "properties" in schema:
            schema["additionalProperties"] = False
            schema["required"] = list(schema["properties"].keys())
            for value in schema["properties"].values():
                make_strict(value)
        elif isinstance(schema, dict):
            for value in schema.values():
                make_strict(value)
    elif isinstance(schema, list):
        for item in schema:
            make_strict(item)
    return schema

সঙ্গী ওয়ার্কফ্লো: প্রথমে নমুনা JSON থেকে স্কিমার কঙ্কাল অনুমান করুন (এই সাইটের /convert/schema টুল পেজ JSON থেকে Schema-র একমুখী অনুমান করে), কঙ্কালকে সূচনা-বিন্দু ধরুন, strict-এর তিন নিয়মে শক্ত করুন, শেষে make_strict শেষ সেফটি নেট হিসেবে চালান। খেয়াল রাখুন: স্ক্রিপ্ট শুধু আকৃতি ঠিক করে — nullable ইউনিয়ন, enum ও অর্থবহ ফিল্ড মানুষই নির্ধারণ করে; $ref-সহ স্কিমা আগে ইনলাইনে বিস্তার করে তবেই দিন।

Anthropic-এর সমতুল্য লেখা: tool-as-schema

Anthropic-এর strict: true সুইচ নেই। ২০২৬-এর প্রচলিত প্যাটার্ন হলো রেসপন্স স্কিমাকে একটি টুলের input_schema হিসেবে জুড়ে tool_choice দিয়ে মডেলকে তা কল করতে বাধ্য করা:

await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
  tool_choice: { type: "tool", name: "emit" },
  messages,
});

টুল-কল চ্যানেল নিজেই JSON যাচাই করে, তাই ফল strict মোডের সমতুল্য। পার্থক্য বিস্তারিতে: Anthropic-এর নেস্টিং সীমা প্রায় ৬ স্তর, .optional()-এর বদলে .nullable() সমর্থন; তিন সরবরাহকারীই (OpenAI, Anthropic, Gemini) সামান্য ভিন্ন উপসেট মেনে নেয়। একই স্কিমা অপরিবর্তিতভাবে সরবরাহকারী পেরিয়ে পুনর্ব্যবহার নির্ভরযোগ্য নয় — মডেল বদলালেই পুনঃযাচাই করুন।

refusal, কাটাকাটি আর টাইমআউট আগে শ্রেণিবিন্যাস করুন, তারপর রিট্রাই

strict মোড অবৈধ কিছু দিলে কারণ মাত্র তিনটি, আর প্রতিটির জবাব আলাদা:

  • Refusal: মডেল সম্পাদন অস্বীকার করেছে (অনিরাপদ রিকোয়েস্ট ইত্যাদি)। রেসপন্সের refusal ফিল্ড সত্য — তখন JSON পড়া অর্থহীন; মানুষের কাছে পাঠান বা রিকোয়েস্ট পুনর্লিখন করুন।
  • কাটাকাটি: finish_reason হলো length — max_tokens কম পড়েছে, আউটপুট ভৌতভাবে অসম্পূর্ণ। স্কিমা বিধিনিষেধ কাটা আউটপুট বাঁচায় না; বাজেট বাড়ান বা গঠন সংকুচিত করুন। শনাক্তকরণ ও আংশিক পুনরুদ্ধার আমাদের কাটা JSON-এর রোগনির্ণয় ও মেরামত নিবন্ধে।
  • বিকৃতি: সরবরাহকারী উপসেট পুরোপুরি সমর্থন না করলে খারাপ JSON এখনও আসতে পারে। শুধু "আবার চেষ্টা করো" বলে রিট্রাই নয় — ভ্যালিডেশন ত্রুটির হুবহু টেক্সট প্রম্পটে ফেরত জুড়ে দিন: "severity অবশ্যই low/medium/high/critical হবে; তুমি urgent দিয়েছ; শুধরে আবার দাও।" ত্রুটি-প্রসঙ্গসহ রিট্রাই গড় রিট্রাই সংখ্যা ৩ থেকে প্রায় ১.৫-এ নামায়।

রিট্রাইতে কঠোর ছাদ দিন (ধরুন ২টি); ছাড়িলে ছোট সংশোধন-মডেলে বা মানুষের কুয়েতে ডাউনগ্রেড করুন। একটি খারাপ আউটপুটকে গোটা পাইপলাইন দমবন্ধ করতে দেবেন না।

প্রকাশের আগে চেকলিস্ট

পরীক্ষা পাসের মানদণ্ড
required প্রতিটি অবজেক্টের প্রতিটি ফিল্ড required-এ আছে
additionalProperties প্রতিটি অবজেক্টে স্পষ্ট false, গভীরতম স্তর পর্যন্ত
ঐচ্ছিক অর্থ ["string", "null"] ইউনিয়নে মডেল; খালি optional নেই
নিষিদ্ধ কীওয়ার্ড $ref / allOf / if-then-else / dependentRequired নেই
নীরব কীওয়ার্ড pattern ও format অ্যাপ স্তরে পুনঃযাচাইকৃত
আকার ≤৫০০০ প্রপার্টি, ≤১০ স্তর, ≤১২০ হাজার অক্ষর
শ্রেণিবিন্যাস refusal / length / পার্স-ব্যর্থতা তিন পথে আলাদা সামলানো
রিট্রাই ত্রুটির মূল টেক্সটসহ, ছাদ ২, ছাড়লে ডাউনগ্রেড
অর্থ স্কিমার বাইরে evals বা ফিল্ড-স্তরের অ্যাসার্শন

চেকলিস্ট পাস হলে আকৃতির নির্ভরযোগ্যতা কার্যত তালাবদ্ধ। অর্থ ও চুক্তির বিবর্তন — স্কিমা ভার্সনিং আর ভাঙা স্কিমাকে CI-তে আগে লাল করানো — দেখুন স্কিমা চুক্তি CI-তে ঢালাই।

FAQ

strict মোড কি ফিল্ড মানের শুদ্ধতা নিশ্চিত করে?

না। এটি ডিকোডিংয়ে শুধু বাক্যগঠন ও আকৃতি তালাবদ্ধ করে: প্রতিটি কী উপস্থিত, টাইপ শুদ্ধ, enum বৈধ। অর্থগত শুদ্ধতার কথা এটি বলে না — মডেল এখনও গঠনে ঠিক কিন্তু ভুল ডেটা দিতে পারে। অর্থ স্তর eval সেট বা ফিল্ড-স্তরের অ্যাসার্শনের ভরসায় থাকে।

ঐচ্ছিক ফিল্ডও কেন required-এ যায়?

strict-এর স্টেট মেশিন চায় প্রতিটি ঘোষিত প্রপার্টি প্রাপ্য হোক; required-এর একটি ঘাটতি ভ্যালিডেশনে পড়ে। ঐচ্ছিকতা ["string", "null"] ইউনিয়নে নকল করা হয়: ফিল্ড সর্বদা আসে, মান null হতে পারে, ডাউনস্ট্রিম null-কে অনুপস্থিতি ধরে।

pattern আর minLength কি সম্পূর্ণ অকেজো?

ফাইন-টিউনড মডেল ও বেশিরভাগ strict কনফিগে প্রয়োগ হয় না। ত্রুটিও দেয় না — আর এজন্যই বিপজ্জনক: প্রতিরক্ষা আছে ভাবেন, থাকে না। এই বিধিনিষেধের উপর নির্ভরশীল রেসপন্স পাওয়ার পর ajv বা jsonschema দিয়ে স্পষ্টভাবে যাচাই করুন।

strict কি রেসপন্স ধীর করে?

শুধু নতুন স্কিমার প্রথম রিকোয়েস্ট কম্পাইল খরচ দেয় (সাধারণত ১০ সেকেন্ডের নিচে, জটিল হলে এক মিনিট পর্যন্ত)। কম্পাইল আর্টিফ্যাক্ট ক্যাশ হওয়ার পর পরের রিকোয়েস্টে প্রথম টোকেনে প্রায় ৫-৮% বাড়তি লেটেন্সি দেখা যায়। স্থিতিশীল অবস্থায় এটি অনুভূতই হয় না; প্রকৃত খরচ তখনই যখন স্কিমা ঘনঘন বদলায়।

মডেল ভার্সন বদলালে কী পুনঃপরীক্ষা করবেন?

তিনটি জিনিস: সেই ভার্সনে সমর্থিত স্কিমা উপসেট বদলেছে কি না, refusal ও finish_reason ফিল্ড আছে কি না, নেস্টিং ও আকারের সীমা আঁটসাঁট হয়েছে কি না। সরবরাহকারীরা ভিন্ন উপসেট মেনে নেয়; স্কিমা মডেল পেরিয়ে পুনর্ব্যবহারের আগে ন্যূনতম এক রিকোয়েস্টে যাচাই করুন।

তথ্যসূত্র

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

জেসন স্কিমা কন্ট্রাক্ট টেস্টিং: ভ্যালিডেশন নিয়মগুলো CI-তে ঢেলে দিন

স্কিমা লেখা শেষ হওয়াই শেষ নয় — সেখান থেকেই অবনতি শুরু হয়। একটা টাইপো নীরবে ভ্যালিডেশন শিথিল করে, একটা রিফ্যাক্টরিং সব ফিক্সচার ভেঙে দেয়। এই নির্দেশিকায় একটি বাস্তবসম্মত কন্ট্রাক্ট টেস্টিং কাঠামো ব্যাখ্যা করা হয়েছে: পজিটিভ, নেগেটিভ ও স্ন্যাপশট ফিক্সচার, স্কিমা নিজের লিন্ট, একবার কম্পাইল করে পুনর্ব্যবহার এবং চারটি CI গেট যা কন্ট্রাক্ট ভাঙাকে লাল বিল্ডে পরিণত করে।

মধ্যম~8 মিনিট পড়াআপডেট 2026-11-05

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

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

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

additionalProperties ছাড়া Schema যাচাই কিছুই যাচাই করে না

যাচাই পাস মানে পরিষ্কার ডেটা নয়। Pydantic ডিফল্টভাবে অজানা ফিল্ড উপেক্ষা করে, Zod সেগুলো সরিয়ে দেয়, Ajv ছেড়ে দেয় — ভুল প্যারামিটার ও টাইপো কী নীরবে পার হয়ে যায়। এই নিবন্ধ নীরব গ্রহণের তিনটি রূপ দেখায় এবং সম্পূর্ণ পদ্ধতি দেয়: অবজেক্ট বন্ধ করা, কোয়ার্সন নিয়ন্ত্রণ, প্রতিটি নেস্টিং স্তর শক্ত করা।

Intermediate~8 মিনিট পড়াআপডেট 2026-11-02