BroadRouter
ابدأ الآن

استدعاء الأدوات في النماذج المفتوحة: المخططات والتوازي والإعادة

بقلم فريق BroadNet Inference · قراءة في 4 دقائق · تاريخ النشر · آخر تحديث

تستخدم النماذج المفتوحة على واجهات API المتوافقة مع OpenAI صيغة tools وtool_calls نفسها التي تستخدمها OpenAI. اجعل المخططات صغيرة ومسطّحة، وحلّل الوسائط بوصفها سلاسل JSON، وتحقّق منها قبل تشغيل أي شيء، وأعد الأخطاء إلى النموذج بوصفها نتائج أدوات ليعيد المحاولة. وضع حدًا للخطوات. وعلى BroadNet يُذكر دعم الأدوات لـ GLM 5.3 وQwen3.8 27B.

استدعاء الأدوات هو ما يحوّل النموذج إلى وكيل. ومع النماذج المفتوحة على واجهة API متوافقة مع OpenAI، صيغة الطلب هي نفسها التي تستخدمها مع OpenAI. أما الفرق فهو عدد مرات حدوث الأخطاء وما يفعله الخادم لمنعها. يشرح هذا المقال الصيغة، وكيف تكتب مخططات تتعامل معها النماذج المفتوحة جيدًا، والاستدعاءات المتوازية، وحالات الفشل الخمس التي ستراها فعلًا، وحلقة Python تصمد أمامها.

كيف يعمل استدعاء الأدوات على واجهة API متوافقة مع OpenAI؟

  1. ترسل messages مع قائمة tools. لكل أداة اسم ووصف ومخطط JSON Schema لوسائطها.
  2. يرد النموذج بـ finish_reason: "tool_calls" وقائمة tool_calls. ولكل عنصر فيها id واسم دالة وarguments بوصفها سلسلة JSON.
  3. تشغّل شيفرتك كل استدعاء وتضيف رسالة role: "tool" واحدة لكل استدعاء، مع tool_call_id المطابق.
  4. تستدعي الواجهة مجددًا. فيجيب النموذج أو يطلب أدوات أخرى.

النموذج لا يشغّل أي شيء بنفسه. شيفرتك هي التي تقرّر ما يُنفَّذ.

كيف تكتب مخططات الأدوات؟

تتبع النماذج المفتوحة المخططات البسيطة بموثوقية أكبر. وهذه القواعد مأخوذة من دليل 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")

ثلاثة قرارات تصميمية مهمة هنا:

  1. الأخطاء تعود إلى النموذج بوصفها نتائج أدوات. فيرى النموذج ما كان خاطئًا ويصلحه عادةً في الدور التالي. أما إطلاق استثناء فيُضيّع هذه الفرصة.
  2. الحلقة محدودة. فالقيمة max_steps توقف نموذجًا يواصل استدعاء الأدوات دون تقدّم.
  3. إعادة المحاولة على مستوى الاتصال منفصلة. فالقيمة 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 يستدعي أدواتك بموثوقية قبل شراء شهر.

أسئلة شائعة

هل تدعم النماذج المفتوحة استدعاء الدوال؟

كثير منها يدعمه، لكن الدعم يعتمد على النموذج وعلى طريقة تقديم المزوّد له. وعلى BroadNet Inference تذكر الوثائق استدعاء الأدوات لـ GLM 5.3 وQwen3.8 27B، ولا تذكره لـ DeepSeek V4.1 Flash ولا Gemma 4 VL 26B.

لماذا تأتي وسائط استدعاء الأداة بصيغة JSON غير صالحة؟

ما لم يقيّد الخادم فك الترميز، تُولَّد الوسائط نصًا ثم تُحلَّل لاحقًا. وتقول وثائق vLLM إن الوسائط المستخرجة من النص الخام قد تكون مشوّهة أحيانًا. التقط خطأ التحليل وأعده بوصفه نتيجة أداة ليصحّح النموذج نفسه.

كيف أوقف الاستدعاءات المتوازية للأدوات؟

في صيغة OpenAI اضبط parallel_tool_calls على false. فهذا يقصر النموذج على استدعاء واحد أو لا شيء في كل دور. وتأكّد أن مزوّدك يحترم هذا الحقل.

لماذا يجيب النموذج نصًا بدل أن يستدعي أداة؟

مع tool_choice بقيمة auto يقرّر النموذج بنفسه. اضبط tool_choice على required، أو على دالة بعينها، حين يكون الاستدعاء إلزاميًا. وتأكّد كذلك أن وصف الأداة يقول متى تُستخدم.

لماذا ينقطع استدعاء الأداة؟

نماذج الاستدلال المنطقي تحتسب التفكير ضمن max_tokens. فقد ينهي الحد الصغير الرد في منتصف الوسائط. افحص finish_reason وارفع max_tokens.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity