Structured output — JSON, schema আর যাচাই

এই পর্বের desktop run: Python 3.12, torch 2.15.0 (CPU), transformers 5.22.2, jsonschema 4.26.0, pydantic 2.14.3, lm-format-enforcer 0.11.3, লেখার সময়ে। Model Qwen/Qwen2.5-0.5B-Instruct (Apache 2.0, token ছাড়া নামানো যায়)। ৩০টি অর্ডার-লেখা এই পর্বের জন্য হাতে লেখা কাল্পনিক বাজারঘর ডেটা; কোনো আসল মানুষ, ফোন নম্বর বা ঠিকানা নেই। সব সংখ্যা একটি স্থানীয় run-এর, একটি ছোট model-এর। বড় hosted পণ্য অন্যভাবে আচরণ করতে পারে, আর এই পাতার কোনো সংখ্যা দিয়ে কোনো পণ্যের মান বিচার করা যায় না। JSON ফাইলের মূল কথা AI-এর ভিত্তি কোর্সের পর্ব ১০-এ আর Python প্রোগ্রামিং কোর্সের পর্ব ২৭-এ; LLM-এর মূল ধারণা AI-এর ভিত্তি কোর্সের পর্ব ৭০-এ।

১ · কেন structured output — মানুষের লেখা থেকে যন্ত্রের ফর্ম

বাজারঘরে প্রতিদিন Messenger আর ফোনে শত শত অর্ডার আসে: “রাজশাহীতে ২টা সুতির শাড়ি পাঠাবেন, মোট ১,৫৫০ টাকা, ক্যাশ অন ডেলিভারি।” গুদামের software-কে জানতে হবে জেলা, পণ্য, সংখ্যা, দাম আর টাকা কখন আসবে। Model যদি লেখে “জি, অর্ডারটি রাজশাহীর জন্য, দুইটি শাড়ি…”, মানুষ বোঝে, প্রোগ্রাম বোঝে না। প্রোগ্রাম চায় এমন কিছু:

{"district": "রাজশাহী", "product": "সুতির শাড়ি", "quantity": 2,
 "price_taka": 1550, "cod": true}

এটি JSON: চাবি আর মানের জোড়া, লেখা উদ্ধৃতিচিহ্নে, সংখ্যা উদ্ধৃতি ছাড়া, true/false ছোট হাতের। LLM-কে এই আকারে উত্তর দেওয়ানোকেই বলে structured output. ব্যবহার অনেক: অর্ডার বা রসিদ থেকে তথ্য তোলা, রিভিউ শ্রেণিতে ভাগ, গ্রাহকের বার্তা থেকে টিকিট বানানো, আর পর্ব ৭১ · Tool use আর function calling-এ দেখবেন, model-কে দিয়ে একটি function ডাকানো।

সমস্যা হলো, LLM শেষ পর্যন্ত token-এর পর token বাছাই করে (পর্ব ৫০)। “JSON দাও” বললে সে JSON-এর মতো দেখতে লেখা দেয়, কিন্তু নিশ্চয়তা নেই। সামনে কথা জুড়ে দিতে পারে, ```json বেড়া দিতে পারে, কমা ভুলতে পারে, “Rajshahi” লিখতে পারে, বা দাম লিখতে পারে "১,৫৫০" লেখা হিসেবে। নিচের পথটি প্রতিটি ধাপে এসব ধরার জন্য।

২ · JSON Schema — উত্তরের নিয়ম লিখে রাখা

JSON Schema হলো JSON দিয়েই লেখা একটি নিয়মপত্র: কোন চাবি থাকবে, প্রতিটির ধরন কী, কোন মান চলবে। এটি একটি খোলা মান (json-schema.org; এখনকার draft 2020-12). বাজারঘরের অর্ডারের schema:

{
  "type": "object",
  "properties": {
    "district":   {"type": "string", "enum": ["ঢাকা", "চট্টগ্রাম", "রাজশাহী",
                   "খুলনা", "সিলেট", "বরিশাল", "রংপুর", "ময়মনসিংহ",
                   "কুমিল্লা", "গাজীপুর"]},
    "product":    {"type": "string", "minLength": 1},
    "quantity":   {"type": "integer", "minimum": 1, "maximum": 50},
    "price_taka": {"type": "integer", "minimum": 1, "maximum": 200000},
    "cod":        {"type": "boolean"}
  },
  "required": ["district", "product", "quantity", "price_taka", "cod"],
  "additionalProperties": false
}

প্রতিটি শব্দের অর্থ: type ধরন বলে (string, integer, number, boolean, object, array, null). properties প্রতিটি চাবির নিজের নিয়ম। required কোন চাবি বাদ দেওয়া যাবে না। additionalProperties: false মানে তালিকার বাইরে কোনো চাবি নয়: model নিজে থেকে "phone" যোগ করলে বাতিল। enum মানে নির্দিষ্ট তালিকার একটি মানই চলবে। minimum/maximum সংখ্যার সীমা, minLength লেখার ন্যূনতম দৈর্ঘ্য।

এই schema-তে ইচ্ছে করে ফোন নম্বরের ঘর নেই। যে তথ্য কাজে লাগে না, তা তোলাই উচিত নয়; additionalProperties: false সেটি জোর করে। নিচের stepper-এ একটি সত্যিকারের model output এই schema-র সঙ্গে ধাপে ধাপে মেলানো হয়েছে।

৩ · তিন স্তরের উপায় — prompt, JSON mode আর schema-বাঁধা output

সব API-তে মূল ধারণা একই, তিন স্তরে:

Function calling (tool calling) একই কৌশলের আরেক রূপ। আপনি function-এর নাম, বর্ণনা আর parameter-এর JSON Schema দেন; model উত্তর না লিখে বলে “এই function, এই argument দিয়ে”। Argument-টি JSON, তাই এখানেও একই যাচাই লাগে। Function চালানো আর ফল ফেরত দেওয়ার পুরো চক্র পর্ব ৭১ · Tool use আর function calling-এ।

নিচের সারণি প্রতিটি কোম্পানির নিজের API নথি থেকে, লেখার সময়ে (নভেম্বর ২০২৬) পড়া; নাম আর নিয়ম পরিবর্তন হতে পারে, ব্যবহারের আগে নথিটি নিজে খুলে মিলিয়ে নিন। যেখানে নথিতে বিষয়টি খুঁজে পাইনি, সেখানে তা-ই লেখা। কোনটি “ভালো”, এই সারণি তা বলে না।

সারণির একটি শিক্ষা সরাসরি আমাদের schema-তে লাগে। "maximum": 200000 কোনো API decoding-এ মানায়, কোনো API নথি অনুযায়ী নেয়ই না, কোনোটি নেয় কিন্তু “best-effort”. তাই schema একই হলেও নিশ্চয়তা আলাদা, আর নিজের যাচাই সব অবস্থায় লাগে। নিচে অনুরোধের আকার, নথির কাঠামো অনুসরণ করে লেখা; চালানো হয়নি, কারণ এখানে কোনো API key নেই।

# নমুনা (চালানো হয়নি): শুধু body-র মূল অংশ; model-এর নাম নিজে বসান
# OpenAI Responses API
{"model": "…", "input": [{"role": "user", "content": "অর্ডার: …"}],
 "text": {"format": {"type": "json_schema", "name": "order",
                     "strict": true, "schema": ORDER_SCHEMA}}}
# Gemini generateContent
{"contents": [{"parts": [{"text": "অর্ডার: …"}]}],
 "generationConfig": {"responseMimeType": "application/json",
                      "responseJsonSchema": ORDER_SCHEMA}}
# Claude Messages API
{"model": "…", "max_tokens": 300,
 "messages": [{"role": "user", "content": "অর্ডার: …"}],
 "output_config": {"format": {"type": "json_schema", "schema": ORDER_SCHEMA}}}
# DeepSeek বা Kimi: শুধু JSON mode, schema prompt-এ লিখে
{"model": "…", "response_format": {"type": "json_object"},
 "messages": [{"role": "user", "content": "json আকারে দাও: … অর্ডার: …"}]}

একটি খুঁটিনাটি খরচও বদলায়। Python-এর json.dumps নিজে থেকে বাংলাকে র-এর মতো escape করে। Qwen2.5-এর tokenizer-এ (সত্যিকারের run) একটি অর্ডারের JSON escape-সহ ১১২ token, ensure_ascii=False দিলে ৫৩, ফাঁকা জায়গা বাদ দিলে ৪৫; prompt-এ পুরো schema escape-সহ ৪৪৫ token, ছাড়া ২১৮. Prompt-এ schema দেওয়ার সময় তাই ensure_ascii=False. বাংলার token খরচ পর্ব ৪০-এ, টাকার হিসাব পর্ব ৬৫ · Token, খরচ আর latency-তে।

৪ · যাচাই — parse, schema, তারপর ব্যবসার নিয়ম

Model-এর JSON-কে বাইরের ইনপুটের মতো দেখুন, যেমন ওয়েবসাইটের form থেকে আসা ডেটা। ফুল-স্ট্যাক ওয়েব ফ্রেমওয়ার্ক কোর্সের পর্ব ২৭-এ request যাচাইয়ের যে নিয়ম, এখানেও তা-ই: আগে বিশ্বাস নয়, আগে পরীক্ষা। পরীক্ষা তিন স্তরে।

1. Parse: json.loads চলে কি না। সামনে কথা, ```json বেড়া, বা শেষের কাটা বন্ধনী এখানে ধরা পড়ে।
2. Schema যাচাই: চাবি, ধরন, enum, সীমা। Python-এ jsonschema library, বা Pydantic-এর class (FastAPI-র ভিত্তি, ফুল-স্ট্যাক ওয়েব ফ্রেমওয়ার্ক কোর্সের পর্ব ৬৯)।
3. ব্যবসার নিয়ম: যা schema-তে লেখা যায় না বা কঠিন: দাম কি এই পণ্যের সাধারণ সীমায়? জেলা কি মূল লেখায় আসলেই আছে? সংখ্যা ৫০-এর বেশি হলে মানুষ দেখুক।

নিচের কোডে একটি ছোট validator নিজে লেখা, যাতে প্রতিটি নিয়ম চোখে পড়ে। ইনপুট হলো Qwen2.5-0.5B-Instruct-এর সত্যিকারের output, §৭-এর run থেকে বেছে তোলা, হুবহু।

import json
D = ["ঢাকা", "চট্টগ্রাম", "রাজশাহী", "খুলনা", "সিলেট", "বরিশাল", "রংপুর", "ময়মনসিংহ", "কুমিল্লা", "গাজীপুর"]
S = {"district": ("str", D), "product": ("str", None), "quantity": ("int", (1, 50)),
     "price_taka": ("int", (1, 200000)), "cod": ("bool", None)}

def check(raw):
    try:
        obj = json.loads(raw)
    except json.JSONDecodeError as e:
        return f"parse ভুল: {e.msg} (অক্ষর {e.pos})"
    if not isinstance(obj, dict): return "object নয়"
    errs = [f"'{k}' নেই" for k in S if k not in obj] + [f"বাড়তি '{k}'" for k in obj if k not in S]
    for k, (t, rule) in S.items():
        if k not in obj: continue
        v = obj[k]
        if t == "int" and (isinstance(v, bool) or not isinstance(v, int)):  # True-ও int!
            errs.append(f"{k}: integer নয় ({v!r})"); continue
        if (t == "str" and not isinstance(v, str)) or (t == "bool" and not isinstance(v, bool)):
            errs.append(f"{k}: {t} নয় ({v!r})"); continue
        if t == "str" and rule and v not in rule: errs.append(f"{k}: তালিকায় নেই ({v!r})")
        if t == "str" and not v.strip(): errs.append(f"{k}: খালি")
        if t == "int" and not rule[0] <= v <= rule[1]: errs.append(f"{k}: সীমার বাইরে ({v})")
    return "; ".join(errs) or "বৈধ"

OUTS = [  # Qwen2.5-0.5B-Instruct-এর সত্যিকারের output
 '```json\n{\n  "district": "রাজশাহী",\n  "product": "সুতির শাড়ি",\n  "quantity": 2,\n  "price_taka": 1550,\n  "cod": true\n}\n```',
 '{"district": "চট্টগ্রাম", "product": "ব্লেন্ডার", "quantity": 3500, "price_taka": 3500, "cod": false}',
 '{\n  "district": "Mymensingh"\n}',
 '{"arbor": "Sylhet", "district": "e 3 ta panjabi lagbe", "product": "panjabi lagbe", "quantity": "2700", "price_taka": "2700"}',
 '{"district": "রাজশাহী", "product": "সুতির শাড়ি", "quantity": 2, "price_taka": 1550, "cod": false}']
for i, raw in enumerate(OUTS, 1):
    print(f"[{i}] {check(raw)}")

[1] parse ভুল: Expecting value (অক্ষর 0)
[2] quantity: সীমার বাইরে (3500)
[3] 'product' নেই; 'quantity' নেই; 'price_taka' নেই; 'cod' নেই; district: তালিকায় নেই ('Mymensingh')
[4] 'cod' নেই; বাড়তি 'arbor'; district: তালিকায় নেই ('e 3 ta panjabi lagbe'); quantity: integer নয় ('2700'); price_taka: integer নয় ('2700')
[5] বৈধ

আসল কাজে নিজে validator না লিখে পরীক্ষিত library নিন। একই ভাঙা JSON (এবার হাতে বানানো, তিনটি ভুলসহ, ফোন নম্বরটি নকল) Pydantic আর jsonschema-কে দেওয়া হলো। কোড একটু ছোট করে দেখানো; আউটপুট সত্যিকারের run-এর:

class Order(BaseModel):                       # pydantic 2.14.3
    model_config = ConfigDict(extra="forbid", strict=True)
    district: Literal["ঢাকা", "চট্টগ্রাম", "রাজশাহী", …]   # ১০টি জেলা
    product: str = Field(min_length=1)
    quantity: int = Field(ge=1, le=50)
    price_taka: int = Field(ge=1, le=200000)
    cod: bool

raw = '{"district": "Rajshahi", "product": "শাড়ি", "quantity": "২",
        "price_taka": 1550, "cod": true, "phone": "01XXXXXXXXX"}'
Order.model_validate_json(raw)

~/bazarghar-dl$ uv run python desk_validate.py     # সত্যিকারের run; লিংকের লাইন বাদ
3 validation errors for Order
district
  Input should be 'ঢাকা', 'চট্টগ্রাম', 'রাজশাহী', 'খুলনা', 'সিলেট', 'বরিশাল',
  'রংপুর', 'ময়মনসিংহ', 'কুমিল্লা' or 'গাজীপুর' [type=literal_error,
  input_value='Rajshahi', input_type=str]
quantity
  Input should be a valid integer [type=int_type, input_value='২', input_type=str]
phone
  Extra inputs are not permitted [type=extra_forbidden, input_value='01XXXXXXXXX', input_type=str]
--- jsonschema
[] additionalProperties | Additional properties are not allowed ('phone' was unexpected)
['district'] enum | 'Rajshahi' is not one of ['ঢাকা', 'চট্টগ্রাম', 'রাজশাহী', 'খুলনা', 'সি
['quantity'] type | '২' is not of type 'integer'

৫ · বাংলা অঙ্ক, দাম আর জেলার নাম — এক রূপে আনা

বাংলাদেশের অর্ডারে একই দাম অনেক রূপে আসে: “১,৫৫০ টাকা”, “৳১৫৫০”, “1,550 tk”, “দেড় হাজার”. লাখের হিসাবে কমার জায়গাও আলাদা: “১,২৫,০০০”. জেলাও আসে “Sylhet”, “সিলেটে”, “Cumilla” রূপে। Model-কে schema-তে integer চাইলেও ছোট model প্রায়ই "১,৫৫০" লেখা দেয়। দুটি পথ আছে: model-কে আরও চাপ দেওয়া, অথবা model-এর লেখা মান নিজের কোডে normalise করা। দ্বিতীয়টি সস্তা আর পরীক্ষাযোগ্য। পর্ব ৫৮-এ exact match-এর আগে একই ধরনের নিয়ম দেখেছেন; এবার লক্ষ্য মাপা নয়, ডেটা ঠিক রাখা।

মূল নিয়ম: যা নিশ্চিতভাবে বোঝা যায়, শুধু তা-ই বদলান; বাকিগুলোতে None, যাতে মানুষ দেখে। “৯৯.৫০ টাকা” পূর্ণসংখ্যা নয়; চুপচাপ ৯৯ বা ১০০ বানানো ঠিক নয়।

import re, unicodedata
DIG = str.maketrans("০১২৩৪৫৬৭৮৯", "0123456789")
WORD = {"দেড়": 1.5, "আড়াই": 2.5, "এক": 1, "দুই": 2, "তিন": 3}
SCALE = {"হাজার": 1000, "শ": 100, "শো": 100, "লাখ": 100000}

def price_to_int(s):
    """'১,৫৫০ টাকা' -> 1550; না বুঝলে None (আন্দাজ নয়)"""
    s = unicodedata.normalize("NFC", str(s)).translate(DIG).lower()
    s = re.sub(r"(৳|টাকা|taka|tk\.?|/-)", " ", s).replace(",", "").strip()
    m = re.fullmatch(r"(\d+(?:\.\d+)?)\s*(হাজার|শ|শো|লাখ)?", s)
    if m:
        v = float(m.group(1)) * SCALE.get(m.group(2), 1)
    else:
        m = re.fullmatch(r"(দেড়|আড়াই|এক|দুই|তিন)\s*(হাজার|শ|শো|লাখ)", s)
        if not m:
            return None
        v = WORD[m.group(1)] * SCALE[m.group(2)]
    return int(v) if v == int(v) else None   # পয়সা থাকলে মানুষ দেখুক
TESTS = ["১,৫৫০ টাকা", "৳২,০০০", "1,800 tk", "১,২৫,০০০/-", "১৫৫০.০০",
         "দেড় হাজার", "৩.৫ হাজার", "আড়াইশো", "৯৯.৫০ টাকা", "দাম জানি না", 1550]
for t in TESTS:
    print(f"{str(t):>14} → {price_to_int(t)}")

# জেলার নামও এক রূপে: model 'Sylhet' বা 'সিলেটে' লিখতে পারে
N = lambda s: unicodedata.normalize("NFC", s).strip().lower()
DISTRICTS = [N(d) for d in ["ঢাকা", "চট্টগ্রাম", "রাজশাহী", "সিলেট", "কুমিল্লা"]]
ALIAS = {"sylhet": "সিলেট", "comilla": "কুমিল্লা", "cumilla": "কুমিল্লা", "dhaka": "ঢাকা"}
def district(s):
    s = N(ALIAS.get(N(s), s))
    for suf in ["", "তে", "য়", "ে", "এ"]:          # রাজশাহীতে, ঢাকায়, সিলেটে
        if s.endswith(N(suf)) and s[:len(s) - len(N(suf))] in DISTRICTS:
            return s[:len(s) - len(N(suf))]
    return None
for d in ["Sylhet", "সিলেটে", "ঢাকায়", "Cumilla", "রাজশাহীতে", "নারায়ণগঞ্জ"]:
    print(f"{d:>10} → {district(d)}")

    ১,৫৫০ টাকা → 1550
        ৳২,০০০ → 2000
      1,800 tk → 1800
    ১,২৫,০০০/- → 125000
       ১৫৫০.০০ → 1550
    দেড় হাজার → 1500
     ৩.৫ হাজার → 3500
       আড়াইশো → 250
    ৯৯.৫০ টাকা → None
   দাম জানি না → None
          1550 → 1550
    Sylhet → সিলেট
    সিলেটে → সিলেট
    ঢাকায় → ঢাকা
   Cumilla → কুমিল্লা
 রাজশাহীতে → রাজশাহী
নারায়ণগঞ্জ → None

৬ · Constrained decoding — প্রতি ধাপে অচল token বাদ

এ পর্যন্ত যাচাই হয়েছে উত্তর আসার পরে। এবার উল্টো প্রশ্ন: উত্তর লেখার সময়েই কি ভুল আটকানো যায়? পর্ব ৫০-এ দেখেছেন, প্রতি ধাপে model পুরো vocabulary-র logit দেয়, তারপর একটি token বাছা হয়। Constrained decoding-এ বাছাইয়ের ঠিক আগে একটি token mask বসে: এখন পর্যন্ত লেখা অংশের পরে ব্যাকরণ যে token-গুলো চলতে দেয় না, তাদের logit −∞ করা হয়। Softmax-এর পর তাদের সম্ভাবনা শূন্য; বাকিদের সম্ভাবনা আবার যোগফল ১ হয়।

ব্যাকরণটি আসে schema থেকে। {"district": " লেখার পরে শুধু enum-এর দশটি জেলার শুরু চলতে পারে; "price_taka": -এর পরে শুধু অঙ্ক, কারণ ধরন integer. এই নিয়মগুলো একটি finite-state machine বা context-free grammar হিসেবে লেখা যায় (JSON-এর বন্ধনী ভেতরে ভেতরে বসে বলে পুরো JSON-এর জন্য দ্বিতীয়টি লাগে)। কঠিন অংশ token: “রাজশাহী” একটি token নয়, Qwen-এর tokenizer-এ কয়েকটি byte-টুকরো (পর্ব ৪০)। তাই প্রতি ধাপে দেখতে হয়, কোন token-এর অক্ষরগুলো যোগ করলে লেখাটি তখনো কোনো বৈধ উত্তরের শুরু থাকে। lm-format-enforcer আর outlines-এর মতো library এই কাজটি করে; Willard ও Louf (২০২৩) regex আর grammar থেকে এই হিসাব আগে থেকে index করার একটি পদ্ধতি প্রকাশ করেন, যা outlines-এর ভিত্তি।

নিচের stepper-এর সংখ্যা সত্যিকারের run থেকে: Qwen2.5-0.5B-Instruct, প্রথম অর্ডার, schema-সহ prompt, আর lm-format-enforcer-এর mask.

এবার পুরো চক্রটি একটি খেলনা model-এ নিজে চালান। Vocabulary ১৫টি token, ব্যাকরণ একটি ছোট state machine, আর “model” হলো seed দেওয়া এলোমেলো logit, যার কয়েকটি ভুল token-এর দিকে ঝোঁক (Sylhet, বাংলা ৩, “জি, ”)।

import numpy as np, json
# ছোট vocabulary; একটি token একাধিক অক্ষরও হতে পারে, আসল tokenizer-এর মতো
V = ['{', '}', '"district": ', '"qty": ', ', ', '"ঢাকা"', '"সিলেট"',
     '"Dhaka"', '"Sylhet"', '1', '2', '৩', '"3"', 'জি, ', '<eos>']
# ব্যাকরণ: { "district": ENUM , "qty": DIGIT+ } <eos>
ENUM, DIG = {'"ঢাকা"', '"সিলেট"'}, {'1', '2'}
G = {"start": ({'{'}, "key1"), "key1": ({'"district": '}, "val1"),
     "val1": (ENUM, "comma"), "comma": ({', '}, "key2"),
     "key2": ({'"qty": '}, "num"), "num": (DIG, "num+"),
     "num+": (DIG | {'}'}, None), "end": ({'<eos>'}, "done")}

def nxt(state, tok):                       # অবস্থা বদলের নিয়ম
    if state == "num+":
        return "num+" if tok in DIG else "end"
    return G[state][1]

rng = np.random.default_rng(62)
bias = {'"Sylhet"': 2.0, '৩': 2.5, 'জি, ': 1.5}   # খেলনা model-এর বদভ্যাস
state, free, out = "start", [], []
print(f"{'ধাপ':>3} {'অবস্থা':7} {'অনুমোদিত':>8}  {'mask ছাড়া':12} mask সহ")
for t in range(9):
    logit = rng.normal(0, 1, len(V)) + np.array([bias.get(v, 0) for v in V])
    allowed = np.array([v in G[state][0] for v in V])
    logit[allowed] += 1.0                  # ঠিক token-ও বেশ সম্ভাব্য
    best_free = V[int(np.argmax(logit))]
    tok = V[int(np.argmax(np.where(allowed, logit, -np.inf)))]   # −∞ = বাদ
    print(f"{t:>3} {state:7} {allowed.sum():>8}  {best_free!r:12} {tok!r}")
    free.append(best_free); out.append(tok)
    state = nxt(state, tok)
    if state == "done": break
for name, toks in (("mask ছাড়া", free), ("mask সহ", out)):
    s = "".join(toks).replace("<eos>", "")
    try: json.loads(s); ok = "বৈধ JSON"
    except ValueError: ok = "JSON নয়"
    print(f"{name}: {s}  → {ok}")

ধাপ অবস্থা  অনুমোদিত  mask ছাড়া   mask সহ
  0 start          1  '৩'          '{'
  1 key1           1  '"ঢাকা"'     '"district": '
  2 val1           2  '"Sylhet"'   '"ঢাকা"'
  3 comma          1  '৩'          ', '
  4 key2           1  '"Sylhet"'   '"qty": '
  5 num            2  '৩'          '2'
  6 num+           3  '"Sylhet"'   '1'
  7 num+           3  '৩'          '}'
  8 end            1  'জি, '       '<eos>'
mask ছাড়া: ৩"ঢাকা""Sylhet"৩"Sylhet"৩"Sylhet"৩জি,   → JSON নয়
mask সহ: {"district": "ঢাকা", "qty": 21}  → বৈধ JSON

৭ · সত্যিকারের run — ৩০টি অর্ডারে পদ্ধতিগুলোর তুলনা

এবার একটি ছোট পরীক্ষা। ৩০টি হাতে লেখা কাল্পনিক বাজারঘর অর্ডার: বাংলা, Banglish আর মিশ্র; দাম “১,৫৫০”, “৳২,০০০”, “1,800 tk” রূপে; প্রতিটির সঠিক উত্তর আগে থেকে লেখা। Model Qwen2.5-0.5B-Instruct, CPU-তে ৩টি thread, greedy decoding (do_sample=False, repetition_penalty=1.0), সর্বোচ্চ ১২০টি নতুন token. পদ্ধতিগুলো:

• সাধারণ prompt: “district, product, quantity, price_taka আর cod বের করে JSON দাও।” আরেকটি ভাষ্যে একই অনুরোধ অন্য শব্দে।
• Schema-সহ prompt: §২-এর পুরো schema prompt-এ, সঙ্গে “শুধু JSON”; এরও দ্বিতীয় একটি ভাষ্য।
• Few-shot: schema-সহ prompt, আগে দুটি আলাদা অর্ডারের উদাহরণ-উত্তর (এই ৩০টির বাইরের)।
• lm-format-enforcer: library-র JSON Schema parser, transformers-এর prefix_allowed_tokens_fn দিয়ে।
• নিজের token mask: §৬-এর মতো, কিন্তু UTF-8 byte ধরে (নিচে কারণ)। দুটি সংস্করণ: সরল, আর token-সীমানা-সচেতন।
• Schema + মেরামত + retry: §৮-এ।

~/bazarghar-dl$ uv run python summary.py res_q05.jsonl v3.jsonl   # সত্যিকারের run-এর ফল
condition        strict  defenced  schema-valid [95% CI]  all-5-fields [95% CI]  mean s
plain            0.00    0.83      0.00                   0.00                   5.07
plain2           0.00    0.00      0.00                   0.00                   7.31
schema           0.00    1.00      0.80 [0.63, 0.93]      0.20 [0.07, 0.37]      6.17
schema2          0.00    0.17      0.07 [0.00, 0.17]      0.00                   9.82
fewshot          1.00    1.00      0.93 [0.83, 1.00]      0.23 [0.10, 0.40]      9.08
lm-format-enf.   0.03    0.03      0.03 [0.00, 0.10]      0.00                   3.21
mask (simple)    1.00    1.00      1.00                   0.23 [0.10, 0.40]      5.24
mask (boundary)  1.00    1.00      1.00                   0.30 [0.13, 0.47]      4.35
per field (schema / fewshot / mask-boundary):
  district 0.80/0.93/0.83  product 0.43/0.57/0.43  quantity 0.90/0.93/0.90
  price_taka 0.73/0.93/0.67  cod 0.57/0.43/0.73
paired vs schema (all-5-fields): fewshot +0.03 [-0.20, +0.27]  mask(boundary) +0.10 [+0.00, +0.23]

নিজের mask-এর মূল অংশ, জেলার ঘরের জন্য (একটু ছোট করে দেখানো; পুরো mask প্রায় ১৫০ লাইন, বাকি ঘরের নিয়ম একই ধাঁচের):

TB = [token_bytes(i) for i in range(len(tok))]   # প্রতিটি token-এর আসল UTF-8 byte
BY = group_by_bytes(TB)                          # byte → token id-এর তালিকা
def allowed_enum(cur):                           # cur: এই ঘরে এ পর্যন্ত লেখা byte
    out = set()
    for e in ENUM_BYTES:                         # '"রাজশাহী"' + পরের কাঠামো, byte-এ
        if e.startswith(cur):
            rest = e[len(cur):]
            for k in range(1, len(rest) + 1):    # বাকি অংশের যেকোনো শুরু একটি token হলে চলবে
                out.update(BY.get(rest[:k], []))
    return out
masked = torch.full_like(logits, float("-inf"))
masked[ids] = logits[ids]; t = int(masked.argmax())   # তারপর greedy বাছাই

৮ · Validate–repair–retry — কখন আবার জিজ্ঞাসা, কখন মানুষ

যাচাই ব্যর্থ হলে তিনটি পথ, খরচের ক্রমে: (১) নিজে মেরামত, যেমন বেড়া সরানো, model না ডেকেই; (২) আবার জিজ্ঞাসা, আগের উত্তর আর ভুলের বার্তাসহ, যাতে model জানে কী ভাঙল; (৩) সীমা পার হলে মানুষের কাছে. পুরো loop-টিকে বলে repair-retry loop. সীমা না থাকলে খরচ আর অপেক্ষা থামে না; Instructor-এর মতো library-ও retry-এর সংখ্যা একটি parameter হিসেবে রাখে।

এবার পুরো ৩০টি অর্ডারে। একই schema-prompt দুইভাবে চালানো হয়েছে, সর্বোচ্চ দুবার retry: একবার প্রতিটি চেষ্টার পরে আগে নিজে মেরামত, একবার মেরামত ছাড়া, শুধু আবার জিজ্ঞাসা। নিচের কোডে সেই সত্যিকারের চেষ্টাগুলোর ফল ক্রমমতো রাখা; কোড শুধু গোনে, retry-এর সীমা ০, ১ আর ২ হলে কী হতো।

# সত্যিকারের run: ৩০টি অর্ডার, schema-prompt, প্রতিটি চেষ্টার ফল ক্রমমতো।
# P = JSON-ই নয় (বেড়ায় মোড়া), F = বেড়া সরালেই বৈধ, S = বেড়া সরালেও schema ভুল
WITH_REPAIR = ("F F F F SSS F F F F F SSS F F F F F F SSS F F SSS SSS SSS "
               "F F F F F F F").split()          # প্রতিটি চেষ্টার পরে আগে নিজে মেরামত
NO_REPAIR = ["PPP"] * 30                          # মেরামত ছাড়া: তিনবারই হুবহু একই উত্তর
FIRST = [65, 56, 56, 63, 65, 58, 54, 57, 58, 67, 52, 51, 54, 61, 61,
         59, 63, 50, 60, 62, 60, 58, 49, 60, 69, 57, 73, 52, 76, 57]   # প্রথম চেষ্টার token
LATER = {4: [65, 65], 10: [16, 52], 17: [17, 50], 20: [60, 60],
         21: [17, 58], 22: [16, 49]}                # মেরামতসহ পথে পরের চেষ্টার token

def simulate(log, repair, max_retry):
    ok = calls = tokens = human = 0
    for i, tries in enumerate(log):
        toks = [FIRST[i]] + (LATER.get(i, [FIRST[i]] * 2) if repair else [FIRST[i]] * 2)
        for k, t in enumerate(tries[:max_retry + 1]):
            calls += 1; tokens += toks[k]
            if t == "F" and repair:
                ok += 1; break
        else:
            human += 1                               # সীমা শেষ: মানুষের কাছে
    return ok, calls, tokens, human

print("নীতি            retry  বৈধ  ডাক  token  মানুষের কাছে")
for name, log, rep in (("মেরামত ছাড়া", NO_REPAIR, False), ("আগে মেরামত", WITH_REPAIR, True)):
    for r in (0, 1, 2):
        ok, c, t, h = simulate(log, rep, r)
        print(f"{name:14} {r:5} {ok:4} {c:4} {t:6} {h:6}")

নীতি            retry  বৈধ  ডাক  token  মানুষের কাছে
মেরামত ছাড়া       0    0   30   1783     30
মেরামত ছাড়া       1    0   60   3566     30
মেরামত ছাড়া       2    0   90   5349     30
আগে মেরামত         0   24   30   1783      6
আগে মেরামত         1   24   36   1974      6
আগে মেরামত         2   24   42   2308      6

৯ · AI-এর যুগে — structured output-এর কোড আর দাবি যাচাই

Extraction-এর কোড AI assistant দ্রুত লিখে দেয়। ভুলগুলো সাধারণত ক্র্যাশ করে না; চুপচাপ ভুল ডেটা database-এ ঢোকে।

Structured output-এর চেকলিস্ট

• Schema-তে শুধু দরকারি ঘর; ব্যক্তিগত তথ্য নেই
• Parse, schema আর ব্যবসার নিয়ম, তিনটিই কোডে আছে
• ব্যবহৃত API নথিতে কোন keyword decoding-এ মানা হয়, তা দেখে নিয়েছি
• বাংলা অঙ্ক, দাম আর নামের normalisation-এর test আছে
• Retry-এর সীমা আর মানুষের কাছে পাঠানোর পথ আছে; retry-এর হার log হয়
• Valid-JSON আর field accuracy একটি eval set-এ, n আর CI-সহ মেপেছি