BroadRouter

ओपन मॉडल के साथ टूल कॉलिंग: स्कीमा, पैरेलल कॉल, रीट्राई

BroadNet Inference टीम · 4 मिनट में पढ़ें · प्रकाशित · अपडेट किया गया

OpenAI-कम्पैटिबल API पर ओपन मॉडल वही 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 पसंद करें। स्ट्रिंग, नंबर, बूलियन और enum। गहरी नेस्टिंग और खुले-ढाँचे वाले ऑब्जेक्ट से बचें।
  • तय विकल्पों के लिए enum इस्तेमाल करें, ताकि मॉडल कोई वैल्यू गढ़ न सके। 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 key जोड़ें ताकि रीट्राई किया गया स्टेप दो बार काम न करे। लंबे चलने वाले एजेंट में यह कवर है।

BroadNet के कौन से मॉडल टूल कॉलिंग सपोर्ट करते हैं?

मॉडल टूल दर्ज कॉन्टेक्स्ट नोट
GLM 5.3 हाँ 1,048,576 स्ट्रक्चर्ड आउटपुट भी
Qwen3.8 27B हाँ 262,144 इमेज इनपुट भी
DeepSeek V4.1 Flash लिस्टेड नहीं 1,048,576 इमेज इनपुट; भरोसा करने से पहले tools टेस्ट करें
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 से पूछें