BroadRouter
شروع کریں

اوپن ماڈلز کے ساتھ ٹول کالنگ: اسکیما، متوازی کالز، دوبارہ کوشش

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

OpenAI سے مطابقت رکھنے والے APIs پر اوپن ماڈلز وہی tools اور tool_calls فارمیٹ استعمال کرتے ہیں جو OpenAI کرتا ہے۔ اسکیما چھوٹے اور سادہ رکھیں، arguments کو JSON اسٹرنگ کی طرح پارس کریں، کچھ بھی چلانے سے پہلے ان کی تصدیق کریں، اور ایررز کو ٹول نتیجہ بنا کر ماڈل کو لوٹائیں تاکہ وہ دوبارہ کوشش کرے۔ مراحل محدود رکھیں۔ BroadNet پر GLM 5.3 اور Qwen3.8 27B ٹول سپورٹ درج کرتے ہیں۔

ٹول کالنگ ہی ماڈل کو ایجنٹ بناتی ہے۔ OpenAI سے مطابقت رکھنے والے API پر اوپن ماڈلز کے ساتھ درخواست کا فارمیٹ وہی ہے جو آپ OpenAI کے ساتھ استعمال کرتے۔ فرق اس میں ہے کہ چیزیں کتنی بار بگڑتی ہیں اور سرور انہیں روکنے کے لیے کیا کرتا ہے۔ یہ پوسٹ فارمیٹ، اوپن ماڈلز کے لیے اچھے اسکیما لکھنے کا طریقہ، متوازی کالز، اصل میں نظر آنے والی پانچ خرابیاں، اور انہیں جھیلنے والا ایک Python لوپ بیان کرتی ہے۔

OpenAI سے مطابقت رکھنے والے API پر ٹول کالنگ کیسے کام کرتی ہے؟

  1. آپ messages کے ساتھ ایک tools فہرست بھیجتے ہیں۔ ہر ٹول کا ایک نام، ایک description اور اس کے arguments کے لیے ایک JSON Schema ہوتا ہے۔
  2. ماڈل finish_reason: "tool_calls" اور ایک tool_calls فہرست کے ساتھ جواب دیتا ہے۔ ہر اندراج میں ایک id، فنکشن کا نام اور JSON اسٹرنگ کی صورت میں arguments ہوتے ہیں۔
  3. آپ کا کوڈ ہر کال چلاتا ہے اور ہر کال کے لیے ملتے ہوئے tool_call_id کے ساتھ ایک role: "tool" پیغام جوڑتا ہے۔
  4. آپ 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")

یہاں ڈیزائن کے تین فیصلے اہم ہیں:

  1. ایررز ٹول نتائج بن کر ماڈل کے پاس لوٹتے ہیں۔ ماڈل دیکھتا ہے کہ کیا غلط تھا اور عموماً اگلی باری میں ٹھیک کر دیتا ہے۔ ایکسیپشن اٹھانے سے یہ موقع ضائع ہو جاتا ہے۔
  2. لوپ محدود ہے۔ max_steps اس ماڈل کو روکتا ہے جو بغیر پیش رفت کے ٹولز کال کرتا رہے۔
  3. ٹرانسپورٹ کی دوبارہ کوششیں الگ ہیں۔ کلائنٹ پر max_retries 429 اور 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 آپ کے ٹولز قابلِ اعتماد طریقے سے کال کرتا ہے۔

عام سوالات

کیا اوپن ماڈلز فنکشن کالنگ سپورٹ کرتے ہیں؟

بہت سے کرتے ہیں، لیکن سپورٹ ماڈل پر اور اس پر منحصر ہے کہ فراہم کنندہ اسے کیسے چلاتا ہے۔ BroadNet Inference کی دستاویزات GLM 5.3 اور Qwen3.8 27B کے لیے ٹول کالنگ درج کرتی ہیں۔ DeepSeek V4.1 Flash یا Gemma 4 VL 26B کے لیے درج نہیں کرتیں۔

میری ٹول کال کے arguments غلط JSON کیوں ہوتے ہیں؟

جب تک سرور ڈی کوڈنگ کو پابند نہ کرے، arguments متن کے طور پر بنتے ہیں اور بعد میں پارس ہوتے ہیں۔ vLLM کی دستاویزات کہتی ہیں کہ خام متن سے نکالے گئے arguments کبھی کبھار خراب ہو سکتے ہیں۔ پارس ایرر پکڑیں اور اسے ٹول نتیجے کے طور پر واپس بھیجیں تاکہ ماڈل خود کو درست کر سکے۔

متوازی ٹول کالز کیسے بند کروں؟

OpenAI فارمیٹ میں parallel_tool_calls کو false کریں۔ اس سے ماڈل ہر باری میں صفر یا ایک ٹول کال تک محدود رہتا ہے۔ دیکھیں کہ آپ کا فراہم کنندہ یہ فیلڈ مانتا ہے۔

ماڈل ٹول کال کرنے کے بجائے متن میں جواب کیوں دیتا ہے؟

tool_choice auto پر فیصلہ ماڈل کرتا ہے۔ جب کال لازمی ہو تو tool_choice کو required یا کسی مخصوص فنکشن پر سیٹ کریں۔ یہ بھی دیکھیں کہ ٹول کی description بتاتی ہے کہ اسے کب استعمال کرنا ہے۔

میری ٹول کال درمیان میں کیوں کٹ جاتی ہے؟

ریزننگ ماڈلز تھنکنگ کو max_tokens میں گنتے ہیں۔ چھوٹی حد پر جواب arguments کے بیچ میں ختم ہو سکتا ہے۔ finish_reason دیکھیں اور max_tokens بڑھائیں۔

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