ٹول کالنگ ہی ماڈل کو ایجنٹ بناتی ہے۔ OpenAI سے مطابقت رکھنے والے API پر اوپن ماڈلز کے ساتھ درخواست کا فارمیٹ وہی ہے جو آپ OpenAI کے ساتھ استعمال کرتے۔ فرق اس میں ہے کہ چیزیں کتنی بار بگڑتی ہیں اور سرور انہیں روکنے کے لیے کیا کرتا ہے۔ یہ پوسٹ فارمیٹ، اوپن ماڈلز کے لیے اچھے اسکیما لکھنے کا طریقہ، متوازی کالز، اصل میں نظر آنے والی پانچ خرابیاں، اور انہیں جھیلنے والا ایک Python لوپ بیان کرتی ہے۔
OpenAI سے مطابقت رکھنے والے API پر ٹول کالنگ کیسے کام کرتی ہے؟
- آپ
messagesکے ساتھ ایکtoolsفہرست بھیجتے ہیں۔ ہر ٹول کا ایک نام، ایک description اور اس کے arguments کے لیے ایک JSON Schema ہوتا ہے۔ - ماڈل
finish_reason: "tool_calls"اور ایکtool_callsفہرست کے ساتھ جواب دیتا ہے۔ ہر اندراج میں ایکid، فنکشن کا نام اور JSON اسٹرنگ کی صورت میںargumentsہوتے ہیں۔ - آپ کا کوڈ ہر کال چلاتا ہے اور ہر کال کے لیے ملتے ہوئے
tool_call_idکے ساتھ ایکrole: "tool"پیغام جوڑتا ہے۔ - آپ API کو دوبارہ کال کرتے ہیں۔ ماڈل جواب دیتا ہے یا مزید ٹولز مانگتا ہے۔
ماڈل خود کبھی کچھ نہیں چلاتا۔ کیا چلے گا، یہ آپ کا کوڈ طے کرتا ہے۔
ٹول اسکیما کیسے لکھیں؟
اوپن ماڈلز سادہ اسکیما زیادہ قابل اعتماد طریقے سے فالو کرتے ہیں۔ یہ اصول OpenAI کی گائیڈ سے اور عموماً ٹوٹنے والی چیزوں سے آتے ہیں:
- ٹولز کے نام کام کے حساب سے رکھیں، جیسے
read_fileیاsearch_code، اور description میں بتائیں کہ ہر ایک کب استعمال کرنا ہے۔ - فہرست مختصر رکھیں۔ OpenAI کی گائیڈ باری کے شروع میں 20 سے کم فنکشنز کو ایک نرم مشورہ کہتی ہے۔ ہر اسکیما ہر کال پر بھیجا بھی جاتا ہے؛ دیکھیں ایجنٹ کا ٹوکن بجٹ۔
- سادہ arguments کو ترجیح دیں۔ اسٹرنگز، نمبرز، بولینز اور enums۔ گہری نیسٹنگ اور آزاد ساخت والے آبجیکٹس سے بچیں۔
- مقررہ انتخاب کے لیے enums استعمال کریں، تاکہ ماڈل کوئی ویلیو گھڑ نہ سکے۔ JSON schema جنریٹر ایک نمونہ arguments آبجیکٹ کو سادہ اسکیما میں بدلتا ہے جسے آپ
parametersمیں پیسٹ کر سکتے ہیں۔ - لازمی فیلڈز نشان زد کریں۔ OpenAI کے strict موڈ میں
additionalProperties: falseاور ہر فیلڈ کاrequiredمیں ہونا ضروری ہے، اختیاری فیلڈز کی ٹائپ میںnullکے ساتھ۔ کوئی فراہم کنندہstrictنافذ کرتا ہے یا نہیں، یہ مختلف ہے، اس لیے پھر بھی تصدیق کریں۔
متوازی ٹول کالز کا کیا؟
ماڈل ایک باری میں tool_calls میں کئی اندراجات لوٹا سکتا ہے، مثلاً تین فائلیں پڑھنا۔ آزاد کالز ایک ساتھ چلائیں اور ہر tool_call_id کے لیے ایک نتیجہ لوٹائیں، کسی بھی ترتیب میں۔ اگر آپ کے ٹولز کے سائیڈ ایفیکٹس ایک دوسرے پر منحصر ہیں تو parallel_tool_calls: false سیٹ کریں؛ OpenAI کی گائیڈ کہتی ہے کہ اس سے ماڈل ہر باری میں صفر یا ایک کال تک محدود رہتا ہے۔ ٹیسٹ کریں کہ آپ کا فراہم کنندہ اسے مانتا ہے۔
ٹول کالز ناکام کیوں ہوتی ہیں؟
| خرابی | آپ کو کیا نظر آتا ہے | حل |
|---|---|---|
| خراب arguments | json.loads ایرر اٹھاتا ہے |
پارس ایرر کو ٹول نتیجے کے طور پر لوٹائیں؛ دوبارہ کوشش |
| اسکیما سے میل نہیں | غائب فیلڈ، غلط ٹائپ، گھڑا ہوا enum | تصدیق کریں؛ تصدیق کا ایرر لوٹائیں |
| نامعلوم ٹول | ایسا نام جو آپ نے کبھی متعین نہیں کیا | “unknown tool, available: …” لوٹائیں |
| ضرورت کے باوجود کال نہیں | اس کی جگہ متنی جواب | tool_choice: "required" یا نام والا فنکشن |
| کٹی ہوئی کال | finish_reason: "length" |
max_tokens بڑھائیں؛ ریزننگ بھی اسی میں سے لیتی ہے |
پہلی دو خرابیاں متوقع ہیں، نایاب نہیں۔ vLLM کی ٹول کالنگ دستاویزات کہتی ہیں کہ auto موڈ میں، جب تک کوئی ٹول strict: true سیٹ نہ کرے (یا سرور سختی کی کم از کم حد نافذ نہ کرے) اور ماڈل کا پارسر پابندیاں سپورٹ نہ کرے، “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (ترجمہ: vLLM خام متن سے ٹول کالز نکالتا ہے، اس لیے arguments کبھی کبھار خراب ہو سکتے ہیں یا فنکشن کے پیرامیٹر اسکیما کی خلاف ورزی کر سکتے ہیں۔) نام والا فنکشن vLLM کا اسٹرکچرڈ آؤٹ پٹ بیک اینڈ استعمال کرتا ہے۔ آپ کا فراہم کنندہ ماڈلز مختلف طریقے سے چلا سکتا ہے، اس لیے تصدیق کو لازمی سمجھیں۔
آخری قطار ریزننگ ماڈلز استعمال کرنے والوں کو پکڑتی ہے۔ GLM 5.3 اور Qwen3.8 27B جواب سے پہلے سوچتے ہیں، اور تھنکنگ max_tokens میں گنی جاتی ہے۔ جواب خالی یا کٹے ہوئے کیوں آتے ہیں بتاتا ہے کہ کتنی گنجائش چھوڑنی ہے۔
تصدیق اور دوبارہ کوشش کرنے والا ٹول لوپ
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
یہاں ڈیزائن کے تین فیصلے اہم ہیں:
- ایررز ٹول نتائج بن کر ماڈل کے پاس لوٹتے ہیں۔ ماڈل دیکھتا ہے کہ کیا غلط تھا اور عموماً اگلی باری میں ٹھیک کر دیتا ہے۔ ایکسیپشن اٹھانے سے یہ موقع ضائع ہو جاتا ہے۔
- لوپ محدود ہے۔
max_stepsاس ماڈل کو روکتا ہے جو بغیر پیش رفت کے ٹولز کال کرتا رہے۔ - ٹرانسپورٹ کی دوبارہ کوششیں الگ ہیں۔ کلائنٹ پر
max_retries429 اور 5xx سنبھالتا ہے۔ غلط arguments لوپ میں سنبھالے جاتے ہیں۔ دونوں کو نہ ملائیں؛ دیکھیں ایررز اور دوبارہ کوشش۔
سائیڈ ایفیکٹ والے ٹولز کے لیے، جیسے ای میل بھیجنا، ایک idempotency کلید جوڑیں تاکہ دوبارہ کوشش کیا گیا مرحلہ دو بار عمل نہ کرے۔ لمبے چلنے والے ایجنٹس میں یہ موضوع ہے۔
BroadNet کے کون سے ماڈلز ٹول کالنگ سپورٹ کرتے ہیں؟
| ماڈل | ٹولز درج | کانٹیکسٹ | نوٹ |
|---|---|---|---|
| GLM 5.3 | ہاں | 1,048,576 | اسٹرکچرڈ آؤٹ پٹ بھی |
| Qwen3.8 27B | ہاں | 262,144 | تصویری ان پٹ بھی |
| DeepSeek V4.1 Flash | درج نہیں | 1,048,576 | تصویری ان پٹ؛ انحصار سے پہلے ٹولز ٹیسٹ کریں |
| Gemma 4 VL 26B | درج نہیں | 32,768 | ٹول لوپس کے لیے نہیں |
ٹول چلانے والے دونوں ماڈلز میں سے انتخاب کے لیے دیکھیں GLM 5.3 بمقابلہ Qwen3.8 27B۔ جب آخری جواب کو کسی ساخت میں ہونا ہو لیکن کوئی فنکشن نہ چلانا ہو تو اسٹرکچرڈ آؤٹ پٹ ٹول سے آسان ہے۔
BroadNet Inference کہاں فٹ ہوتا ہے
BroadNet Inference اسٹینڈرڈ chat-completions فارمیٹ کے ذریعے GLM 5.3 اور Qwen3.8 27B کو ٹول کالنگ کے ساتھ چلاتا ہے، اس لیے اوپر کا لوپ OpenAI Python SDK کے ساتھ بغیر تبدیلی چلتا ہے۔ فی ٹوکن قیمتیں قیمتوں کے صفحے پر ہیں۔ یہ ویب سرچ یا کوڈ چلانے جیسے سرور کی طرف کے ٹولز ہوسٹ نہیں کرتا، اور اس کی دستاویزات DeepSeek V4.1 Flash کے لیے ٹول کالنگ درج نہیں کرتیں، جو لامحدود پلانز والا ماڈل ہے۔ ٹولز پر بہت زیادہ منحصر ایجنٹ کے لیے فی ٹوکن GLM 5.3 یا Qwen3.8 27B استعمال کریں۔ اگر پھر بھی مقررہ قیمت والا پلان چاہیے، تو مہینہ خریدنے سے پہلے $1 والے Meteor گھنٹے پر جانچ لیں کہ DeepSeek V4.1 Flash آپ کے ٹولز قابلِ اعتماد طریقے سے کال کرتا ہے۔
