BroadRouter
شروع کریں

JSON mode بمقابلہ json_schema: قابل اعتماد اسٹرکچرڈ آؤٹ پٹ

BroadNet Inference ٹیم · 4 منٹ کی پڑھائی · شائع شدہ

JSON mode (response_format json_object) صرف درست JSON کا وعدہ کرتا ہے۔ اسٹرکچرڈ آؤٹ پٹ (response_format json_schema) آپ کے فیلڈز اور ٹائپس کا بھی وعدہ کرتا ہے، جہاں فراہم کنندہ اسے نافذ کرتا ہے۔ دونوں صورتوں میں finish_reason دیکھیں، پارس کریں، اور Pydantic ماڈل جیسے اسکیما سے تصدیق کریں۔ تصدیق ناکام ہو تو ایرر واپس بھیج کر دوبارہ مانگیں، کوششوں کی سخت حد کے ساتھ۔

آپ کے کوڈ کو ڈیٹا چاہیے، اور ماڈل متن لکھتے ہیں۔ اسٹرکچرڈ آؤٹ پٹ یہ فاصلہ ختم کرتا ہے، لیکن ”ماڈل JSON لوٹاتا ہے“ کے تین مختلف مطلب ہیں، اس پر منحصر کہ آپ کیسے مانگتے ہیں۔ یہ پوسٹ OpenAI سے مطابقت رکھنے والے اوپن ماڈلز پر ان آپشنز کا موازنہ کرتی ہے، ہر ایک کو مانگنے کا طریقہ دکھاتی ہے، اور تصدیق اور مرمت کا ایک لوپ دیتی ہے جسے آپ براہ راست پروڈکشن میں لگا سکتے ہیں۔

JSON mode اور json_schema میں کیا فرق ہے؟

طریقہ درخواست آپ کو کس بات کا وعدہ ملتا ہے
صرف پرامپٹ ”ان فیلڈز کے ساتھ JSON میں جواب دیں…“ کسی بات کا نہیں؛ عموماً JSON، کبھی اضافی متن کے ساتھ
JSON mode response_format: {"type": "json_object"} درست JSON، کوئی بھی ساخت
اسٹرکچرڈ آؤٹ پٹ response_format: {"type": "json_schema", ...} آپ کے اسکیما سے مطابقت رکھنے والا JSON، جہاں نافذ ہو

OpenAI کی Structured Outputs گائیڈ یہ صاف کہتی ہے: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (ترجمہ: دونوں درست JSON بننا یقینی بناتے ہیں، لیکن اسکیما کی پابندی صرف Structured Outputs یقینی بناتے ہیں۔) یہ جہاں بھی ممکن ہو JSON mode کے بجائے اسٹرکچرڈ آؤٹ پٹ کی سفارش کرتی ہے۔

اوپن ماڈلز کے فراہم کنندگان پر یہ ضمانت اس پر منحصر ہے کہ سرور اسے کیسے نافذ کرتا ہے۔ کئی constrained decoding استعمال کرتے ہیں، جو ان ٹوکنز کو روک دیتی ہے جو اسکیما توڑتے۔ کچھ فیلڈ قبول تو کرتے ہیں مگر اسے نافذ نہیں کرتے۔ اسی لیے نیچے کا کوڈ ہر حال میں تصدیق کرتا ہے۔

json_schema کیسے مانگیں؟

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic آپ کی کلاس سے JSON Schema بناتا ہے، اس لیے اسکیما اور ویلیڈیٹر کبھی الگ نہیں ہوتے۔ اگر آپ Pydantic استعمال نہیں کرتے تو JSON schema جنریٹر ایک نمونہ آبجیکٹ سے strict mode والا اسکیما بنا دیتا ہے۔ strict mode کے لیے OpenAI کو additionalProperties: false چاہیے اور ہر پراپرٹی required کے طور پر درج ہونی چاہیے۔

آپ کا فراہم کنندہ کون سا موڈ سپورٹ کرتا ہے؟

کسی ماڈل پر کچھ بنانے سے پہلے یہ ٹیسٹ ایک بار چلائیں:

  1. json_schema کے ساتھ ایسا پرامپٹ بھیجیں جو ایک اضافی فیلڈ مانگے (”ساتھ میں ایک مختصر تبصرہ بھی شامل کریں“)۔
  2. اگر درخواست ایرر دیتی ہے تو فراہم کنندہ json_schema قبول نہیں کرتا۔ json_object آزمائیں۔
  3. اگر جواب میں اضافی فیلڈ ہے تو اسکیما نافذ نہیں ہو رہا۔ اسے JSON mode سمجھیں۔
  4. اگر json_object بھی ایرر دیتا ہے تو تصدیق کے ساتھ صرف پرامپٹ والا طریقہ استعمال کریں۔

BroadNet Inference پر دستاویزات GLM 5.3 اور Qwen3.8 27B (آمنے سامنے موازنہ) کے لیے اسٹرکچرڈ آؤٹ پٹ درج کرتی ہیں، لیکن درخواست کا پیرامیٹر نہیں بتاتیں۔ جس ماڈل کو آپ پروڈکشن میں لے جاتے ہیں، اس پر اوپر کا ٹیسٹ چلائیں۔

غلط آؤٹ پٹ کی تصدیق اور مرمت کیسے کریں؟

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

یہ لوپ کیوں کام کرتا ہے:

  • پہلے finish_reason دیکھیں۔ جو جواب max_tokens تک پہنچ گیا وہ کٹا ہوا JSON ہے۔ اسی حد کے ساتھ دوبارہ کوشش اسی طرح ناکام ہوگی۔ اوپر کے دونوں ماڈلز جواب دینے سے پہلے ریزننگ کرتے ہیں، اور ریزننگ حد میں شمار ہوتی ہے، اس لیے گنجائش چھوڑیں۔
  • انکار کو الگ سنبھالیں۔ OpenAI کی گائیڈ بتاتی ہے کہ انکار “does not necessarily follow the schema you have supplied” (ترجمہ: ضروری نہیں کہ آپ کے دیے گئے اسکیما کی پیروی کرے)۔
  • عین ایرر واپس بھیجیں۔ اندھی دوبارہ کوشش اکثر وہی غلطی لوٹاتی ہے۔ “line_items: field required” ماڈل کو درست کرنے کے لیے کچھ ٹھوس دیتا ہے۔
  • کاروباری اصول کوڈ میں جانچیں۔ اسکیما یہ نہیں کہہ سکتا کہ ٹوٹل اس کے لائن آئٹمز کے برابر ہونا چاہیے۔ اوپر کی جانچ کہہ سکتی ہے۔
  • کوششیں محدود رکھیں۔ ہر کوشش پورا پرامپٹ ان پٹ ٹوکنز کے طور پر دوبارہ بھیجتی ہے۔

اسکیما کے کون سے فیچرز مسئلہ کرتے ہیں؟

اسکیما سادہ رکھیں:

  1. نیسٹڈ سے فلیٹ بہتر۔ زیادہ تر ایکسٹریکشن کے لیے دو سطحیں کافی ہیں۔
  2. کیٹیگریز کے لیے کھلی strings کے بجائے enums۔
  3. کوئی کھلے آبجیکٹس نہیں۔ آزاد dict فیلڈز سارا مقصد ہی ختم کر دیتے ہیں۔
  4. وضاحت کے ساتھ مختصر فیلڈ نام۔ اسکیما میں دی گئی وضاحتیں ماڈل کی رہنمائی کرتی ہیں۔
  5. اختیاری فیلڈز nullable کے طور پر۔ strict mode میں ہر فیلڈ کو required درج کریں اور null کی اجازت دیں۔

OpenAI کی گائیڈ بتاتی ہے کہ JSON Schema کے کچھ فیچرز strict mode میں سپورٹ نہیں ہوتے۔ اوپن ماڈل سرورز کی اپنی حدیں ہوتی ہیں۔ اگر کوئی اسکیما مسترد ہو جائے تو موڈ بدلنے سے پہلے اسے سادہ کریں۔

پروڈکشن میں اسٹرکچرڈ آؤٹ پٹ کی نگرانی کیسے کریں؟

خاموشی سے مرمت کرنے والا لوپ ایسا مسئلہ چھپا سکتا ہے جو آپ سے روز ٹوکن خرچ کرواتا ہے۔ ہر کال سائٹ پر تین اعداد لاگ کریں:

میٹرک یہ کیا بتاتا ہے
پہلی کوشش میں کامیابی کی شرح ماڈل اور اسکیما کتنے ہم آہنگ ہیں؛ کمی اکثر پرامپٹ یا ماڈل بدلنے کے بعد آتی ہے
ہر کامیابی پر اوسط کوششیں مرمت کی ٹوکن لاگت
حتمی ناکامیاں وہ ان پٹس جنہیں آپ کی پائپ لائن نہیں سنبھال پاتی؛ انہیں ہاتھ سے دیکھیں

اگر پہلی کوشش کی کامیابی آپ کی معمول کی شرح سے نیچے گرے تو مزید دوبارہ کوششیں جوڑنے سے پہلے اسکیما سادہ کریں یا کوئی دوسرا ماڈل آزمائیں۔ ناکام خام جوابوں کا ایک نمونہ رکھیں، تاکہ آپ اصلاحات کو حقیقی کیسز پر ٹیسٹ کر سکیں۔

اس کے بجائے ٹول کب استعمال کریں؟

آخری جواب کے لیے اسٹرکچرڈ آؤٹ پٹ استعمال کریں: ایکسٹریکشن، درجہ بندی، منصوبہ۔ ٹول کالنگ تب استعمال کریں جب ماڈل کو آپ کے کوڈ سے کچھ کروانا ہو اور پھر آگے بڑھنا ہو۔ کئی ایجنٹس دونوں استعمال کرتے ہیں: لوپ کے دوران ٹولز، اور آخری قدم کے لیے اسکیما۔ تصویر سے JSON کی مثال کے لیے وژن ماڈل سے عربی انوائسز پڑھنا دیکھیں۔

BroadNet Inference کہاں موزوں ہے

BroadNet Inference، GLM 5.3 اور Qwen3.8 27B کے لیے اسٹرکچرڈ آؤٹ پٹ درج کرتا ہے، معیاری chat-completions فارمیٹ کے پیچھے، اس لیے اوپر کا کوڈ OpenAI Python SDK کے ساتھ بغیر تبدیلی چلتا ہے۔ Qwen3.8 27B تصاویر بھی لیتا ہے، جو دستاویزات سے ایکسٹریکشن کے لیے موزوں ہے۔ BroadNet کی دستاویزات DeepSeek V4.1 Flash یا Gemma 4 VL 26B کے لیے اسٹرکچرڈ آؤٹ پٹ نہیں بتاتیں، اس لیے وہاں تصدیق کے ساتھ صرف پرامپٹ والا طریقہ استعمال کریں۔ فی ٹوکن قیمتوں کا موازنہ قیمتوں کے صفحے پر کریں۔

عام سوالات

JSON mode اور اسٹرکچرڈ آؤٹ پٹ میں کیا فرق ہے؟

JSON mode، یعنی response_format کی type json_object، صرف یہ وعدہ کرتا ہے کہ جواب JSON کے طور پر پارس ہوگا۔ اسٹرکچرڈ آؤٹ پٹ، یعنی type json_schema، آپ کے طے کردہ فیلڈز اور ٹائپس کا بھی وعدہ کرتا ہے، جہاں فراہم کنندہ اسے نافذ کرتا ہے۔ OpenAI جہاں ممکن ہو JSON mode کے بجائے اسٹرکچرڈ آؤٹ پٹ کی سفارش کرتا ہے۔

کیا اوپن ماڈلز json_schema والا response_format سپورٹ کرتے ہیں؟

یہ فراہم کنندہ پر منحصر ہے۔ کچھ json_schema قبول کرتے ہیں، کچھ صرف json_object، اور کچھ اس فیلڈ کو نظرانداز کر دیتے ہیں۔ ایک اسکیما اور ایسے پرامپٹ کے ساتھ ٹیسٹ درخواست بھیجیں جو ماڈل کو ایک اضافی فیلڈ جوڑنے پر اکسائے، پھر جواب دیکھیں۔

کیا اسٹرکچرڈ آؤٹ پٹ کی پھر بھی تصدیق ضروری ہے؟

جی ہاں۔ جواب max_tokens سے کٹ سکتے ہیں، انکار ہو سکتے ہیں، اور ایسے کاروباری اصول توڑ سکتے ہیں جنہیں اسکیما بیان نہیں کر سکتا، جیسے ایسے ٹوٹل جن کا میزان ملنا چاہیے۔

غلط JSON پر کتنی بار دوبارہ کوشش کریں؟

تصدیق کے ایرر کے ساتھ دو یا تین کوششیں عموماً کافی ہیں۔ اس کے بعد ان پٹ لاگ کریں اور اسے کسی متبادل راستے، زیادہ طاقتور ماڈل یا کسی انسان کے پاس بھیجیں۔ لامحدود لوپ ٹوکن ضائع کرتے ہیں۔

اسٹرکچرڈ آؤٹ پٹ استعمال کروں یا ٹول کالنگ؟

جب آپ کو آخری جواب ایک مقررہ ساخت میں چاہیے تو اسٹرکچرڈ آؤٹ پٹ۔ جب ماڈل کو آپ کے کوڈ سے کچھ کروا کر آگے بڑھنا ہو تو ٹول کالنگ۔

Markdown میں پڑھیںChatGPT سے پوچھیںClaude سے پوچھیںPerplexity سے پوچھیں