टूल कॉलिंग ही मॉडल को एजेंट बनाती है। 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 पसंद करें। स्ट्रिंग, नंबर, बूलियन और 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")
यहाँ डिज़ाइन के तीन फ़ैसले मायने रखते हैं:
- एरर टूल रिज़ल्ट बनकर मॉडल के पास लौटते हैं। मॉडल देखता है कि क्या ग़लत था और आम तौर पर अगले टर्न में उसे ठीक कर देता है। एक्सेप्शन उठाने से यह मौक़ा चला जाता है।
- लूप सीमित है।
max_stepsउस मॉडल को रोकता है जो बिना प्रगति के टूल कॉल करता रहता है। - ट्रांसपोर्ट रीट्राई अलग हैं। क्लाइंट पर
max_retries429 और 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 आपके टूल भरोसेमंद ढंग से कॉल करता है।
