آپ کے کوڈ کو ڈیٹا چاہیے، اور ماڈل متن لکھتے ہیں۔ اسٹرکچرڈ آؤٹ پٹ یہ فاصلہ ختم کرتا ہے، لیکن ”ماڈل 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 کے طور پر درج ہونی چاہیے۔
آپ کا فراہم کنندہ کون سا موڈ سپورٹ کرتا ہے؟
کسی ماڈل پر کچھ بنانے سے پہلے یہ ٹیسٹ ایک بار چلائیں:
json_schemaکے ساتھ ایسا پرامپٹ بھیجیں جو ایک اضافی فیلڈ مانگے (”ساتھ میں ایک مختصر تبصرہ بھی شامل کریں“)۔- اگر درخواست ایرر دیتی ہے تو فراہم کنندہ
json_schemaقبول نہیں کرتا۔json_objectآزمائیں۔ - اگر جواب میں اضافی فیلڈ ہے تو اسکیما نافذ نہیں ہو رہا۔ اسے JSON mode سمجھیں۔
- اگر
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” ماڈل کو درست کرنے کے لیے کچھ ٹھوس دیتا ہے۔
- کاروباری اصول کوڈ میں جانچیں۔ اسکیما یہ نہیں کہہ سکتا کہ ٹوٹل اس کے لائن آئٹمز کے برابر ہونا چاہیے۔ اوپر کی جانچ کہہ سکتی ہے۔
- کوششیں محدود رکھیں۔ ہر کوشش پورا پرامپٹ ان پٹ ٹوکنز کے طور پر دوبارہ بھیجتی ہے۔
اسکیما کے کون سے فیچرز مسئلہ کرتے ہیں؟
اسکیما سادہ رکھیں:
- نیسٹڈ سے فلیٹ بہتر۔ زیادہ تر ایکسٹریکشن کے لیے دو سطحیں کافی ہیں۔
- کیٹیگریز کے لیے کھلی strings کے بجائے enums۔
- کوئی کھلے آبجیکٹس نہیں۔ آزاد
dictفیلڈز سارا مقصد ہی ختم کر دیتے ہیں۔ - وضاحت کے ساتھ مختصر فیلڈ نام۔ اسکیما میں دی گئی وضاحتیں ماڈل کی رہنمائی کرتی ہیں۔
- اختیاری فیلڈز 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 کے لیے اسٹرکچرڈ آؤٹ پٹ نہیں بتاتیں، اس لیے وہاں تصدیق کے ساتھ صرف پرامپٹ والا طریقہ استعمال کریں۔ فی ٹوکن قیمتوں کا موازنہ قیمتوں کے صفحے پر کریں۔
