استدعاء الأدوات هو ما يحوّل النموذج إلى وكيل. ومع النماذج المفتوحة على واجهة API متوافقة مع OpenAI، صيغة الطلب هي نفسها التي تستخدمها مع OpenAI. أما الفرق فهو عدد مرات حدوث الأخطاء وما يفعله الخادم لمنعها. يشرح هذا المقال الصيغة، وكيف تكتب مخططات تتعامل معها النماذج المفتوحة جيدًا، والاستدعاءات المتوازية، وحالات الفشل الخمس التي ستراها فعلًا، وحلقة Python تصمد أمامها.
كيف يعمل استدعاء الأدوات على واجهة API متوافقة مع OpenAI؟
- ترسل
messagesمع قائمةtools. لكل أداة اسم ووصف ومخطط JSON Schema لوسائطها. - يرد النموذج بـ
finish_reason: "tool_calls"وقائمةtool_calls. ولكل عنصر فيهاidواسم دالة وargumentsبوصفها سلسلة JSON. - تشغّل شيفرتك كل استدعاء وتضيف رسالة
role: "tool"واحدة لكل استدعاء، معtool_call_idالمطابق. - تستدعي الواجهة مجددًا. فيجيب النموذج أو يطلب أدوات أخرى.
النموذج لا يشغّل أي شيء بنفسه. شيفرتك هي التي تقرّر ما يُنفَّذ.
كيف تكتب مخططات الأدوات؟
تتبع النماذج المفتوحة المخططات البسيطة بموثوقية أكبر. وهذه القواعد مأخوذة من دليل OpenAI ومما يميل إلى التعطّل:
- سمِّ الأدوات بالفعل الذي تؤديه، مثل
read_fileأوsearch_code، وقل في الوصف متى تُستخدم كل منها. - أبقِ القائمة قصيرة. يصف دليل OpenAI عدد أقل من 20 دالة في بداية الدور بأنه اقتراح مرن. وكل مخطط يُرسل أيضًا مع كل استدعاء؛ راجع ميزانية رموز الوكيل.
- فضّل الوسائط المسطّحة. سلاسل وأرقام وقيم منطقية وقوائم تعداد (enum). وتجنّب التداخل العميق والكائنات حرة الشكل.
- استخدم enum للخيارات الثابتة، حتى لا يخترع النموذج قيمة. ومولّد مخطط JSON يحوّل كائن وسائط نموذجيًا إلى مخطط مسطّح تلصقه في
parameters. - حدّد الحقول الإلزامية. يتطلب الوضع الصارم في OpenAI القيمة
additionalProperties: falseووضع كل حقل فيrequired، معnullنوعًا للحقول الاختيارية. ويتفاوت المزوّدون في فرضstrict، فتحقّق على أي حال.
وماذا عن الاستدعاءات المتوازية للأدوات؟
قد يُعيد النموذج عدة عناصر في tool_calls في دور واحد، كثلاث عمليات قراءة لملفات مثلًا. شغّل الاستدعاءات المستقلة بالتوازي وأعد نتيجة واحدة لكل tool_call_id، بأي ترتيب. وإن كانت لأدواتك آثار جانبية يعتمد بعضها على بعض، فاضبط parallel_tool_calls: false؛ إذ يقول دليل OpenAI إن ذلك يقصر النموذج على استدعاء واحد أو لا شيء في كل دور. واختبر أن مزوّدك يحترم ذلك.
لماذا تفشل استدعاءات الأدوات؟
| الفشل | ما تراه | الحل |
|---|---|---|
| وسائط مشوّهة | 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 استدعاءات الأدوات من النص الخام، لذا قد تكون الوسائط أحيانًا مشوّهة أو مخالفة لمخطط معاملات الدالة»). أما الدالة المسمّاة فتستخدم الواجهة الخلفية للمخرجات المهيكلة في 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_retriesفي العميل تعالج 429 و5xx، والوسائط الخاطئة تُعالج في الحلقة. لا تخلط بينهما؛ راجع الأخطاء وإعادة المحاولة.
وللأدوات ذات الآثار الجانبية، كإرسال بريد إلكتروني، أضف مفتاح منع التكرار (idempotency key) حتى لا تنفّذ الخطوة المعادة الفعل مرتين. ويغطي مقال الوكلاء طويلو التشغيل هذا الموضوع.
أي نماذج 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 النموذجين GLM 5.3 وQwen3.8 27B مع ذكر دعم استدعاء الأدوات، عبر صيغة chat-completions القياسية، فتعمل الحلقة أعلاه دون تعديل مع OpenAI Python SDK. والأسعار لكل رمز موجودة في صفحة الأسعار. ولا تستضيف أدوات على جانب الخادم مثل البحث في الويب أو تنفيذ الشيفرة، ولا تذكر وثائقها استدعاء الأدوات لـ DeepSeek V4.1 Flash، وهو النموذج المتاح في الخطط غير المحدودة. وللوكيل الذي يعتمد على الأدوات بكثافة، استخدم GLM 5.3 أو Qwen3.8 27B بالدفع لكل رمز. وإن أردت الخطة الثابتة رغم ذلك، فتحقق بساعة من خطة الشهاب (Meteor) بسعر $1 من أن DeepSeek V4.1 Flash يستدعي أدواتك بموثوقية قبل شراء شهر.
