كتب الذكاء الاصطناعيمشاريع الذكاء الاصطناعيمقالات الذكاء الاصطناعيمعجم الذكاء الاصطناعياسئلة واجوبة في الذكاء الاصطناعيأكاديمية الذكاء الاصطناعي للأطفالأكاديمية الذكاء الاصطناعيمدرسة رياضيات الذكاء الاصطناعيمختبر الذكاء الاصطناعيمختبر الخوارزميات المستوحاة من الطبيعةأطلس نماذج الذكاء الاصطناعيموسوعة تطبيقات الذكاء الاصطناعيمستكشف مجموعات البيانات للذكاء الاصطناعياختبارات الذكاء الاصطناعيالفايب كودينغدليل البرمجة بالذكاء الاصطناعيمولّد مشاريع الذكاء الاصطناعيمرصد الذكاء الاصطناعيدليل أدوات الذكاء الاصطناعي البحث والنشر الأكاديميمكتبة البرومبتات الأكاديميةمستودع الرسائل والأطاريح في الذكاء الاصطناعيحاسبة الترقية العلميةأكاديمية الوكلاء الذكيينمختبر أخلاقيات الذكاء الاصطناعي والعدالةساحة ألعاب الذكاء الاصطناعيمختبر التنبؤ بالسلاسل الزمنيةمتحف الذكاء الاصطناعيمختبر الرؤية الحاسوبيةمختبر الشبكات العصبية البيانيةمختبر معالجة اللغة الطبيعيةمختبر الحوسبة الكمّيةخرائط طريق الذكاء الاصطناعي

الوحدة 3 · الدرس 2 · 15 دقيقة قراءة

استدعاء الوظائف خطوة بخطوة

Function Calling

المقدمة

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

أهداف التعلم

  • شرح مراحل دورة استدعاء الوظائف (Function Calling) بالترتيب
  • التمييز بين رسالة النموذج النصية وطلب استدعاء الأداة المنظم
  • بناء حلقة تنفيذ بسيطة تعيد نتيجة الأداة إلى النموذج
  • التعرف على شكل الأدوات الوظيفية في OpenAI Agents SDK

الفكرة الأساسية

في الأيام الأولى لبناء الوكلاء كان المطورون يطلبون من النموذج أن يكتب شيئًا مثل «ACTION: search(...)» ثم يحللون النص بتعابير نمطية هشة. استدعاء الوظائف (Function Calling) حلّ هذه المشكلة: نرسل إلى النموذج قائمة أدوات موصوفة بصيغة منظمة، فيعيد النموذج عند الحاجة طلب استدعاء فيه اسم الأداة ومعاملاتها بصيغة JSON بدل نص حر. البرنامج يقرأ هذا الطلب مباشرة دون تخمين.

المهم أن نتذكر: النموذج لا ينفّذ شيئًا. هو يولّد بيانات منظمة تقول «أريد تشغيل الأداة X بهذه القيم»، والقرار النهائي بالتنفيذ بيد التطبيق.

1234567المستخدمUserالتطبيقApp / RuntimeالنموذجModel + Tool Schemasطلب استدعاء{"name","arguments"}تنفيذ الأداةValidate → Executeنتيجة الأداةTool Resultالإجابة النهائيةFinal Answer
استدعاء الأدوات: النموذج لا ينفذ شيئاً بنفسه؛ يقترح استدعاءً منظماً، والتطبيق يتحقق منه وينفذه ويعيد النتيجة.

الدورة الكاملة في ست خطوات

  1. التعريف: يرسل التطبيق إلى النموذج رسالة المستخدم مع قائمة الأدوات المتاحة (الاسم، الوصف، مخطط المدخلات).
  2. القرار: يقرر النموذج إن كان يحتاج أداة. إن لم يحتج يجيب نصًا مباشرة.
  3. الطلب: إن احتاج، يعيد طلب استدعاء منظمًا، وقد يحمل معرّفًا فريدًا للاستدعاء.
  4. التحقق والتنفيذ: يتحقق التطبيق من اسم الأداة وصحة المعاملات ثم ينفّذ الدالة.
  5. الإرجاع: يضيف التطبيق نتيجة الأداة إلى المحادثة مربوطة بمعرّف الاستدعاء نفسه.
  6. الصياغة: يقرأ النموذج النتيجة ويقرر: استدعاء أداة أخرى أو كتابة الإجابة النهائية.

تتكرر الخطوات من 2 إلى 6 حتى تظهر إجابة نهائية أو يبلغ الوكيل حدًا أقصى من الدورات.

شكل الطلب والنتيجة

تختلف التفاصيل بين المزودين، لكن الفكرة واحدة. هذا شكل توضيحي عام لطلب استدعاء ونتيجته:

json
{
  "tool_call": {
    "id": "call_01",
    "name": "get_exchange_rate",
    "arguments": {"base": "USD", "target": "EGP"}
  },
  "tool_result": {
    "call_id": "call_01",
    "content": {"rate": 48.5, "source": "demo_data"}
  }
}

القيم هنا بيانات تجريبية للشرح فقط. لاحظ أن call_id في النتيجة يطابق id في الطلب؛ هذا الربط ضروري عندما يطلب النموذج أكثر من أداة في دورة واحدة.

مثال عملي: حلقة استدعاء مبسطة

لنحاكِ الدورة كاملة ببايثون عادي. سنستبدل النموذج بدالة قواعد بسيطة fake_model حتى يعمل المثال دون أي مفتاح API، تمامًا كما يفعل محاكي الأكاديمية:

python
import json

def get_exchange_rate(base: str, target: str) -> dict:
    demo = {("USD", "EGP"): 48.5, ("USD", "SAR"): 3.75}
    return {"rate": demo.get((base, target)), "source": "demo_data"}

TOOLS = {"get_exchange_rate": get_exchange_rate}

def fake_model(messages):
    # نموذج وهمي قائم على قواعد: يطلب الأداة أولًا ثم يجيب
    last = messages[-1]
    if last["role"] == "user":
        return {"tool_call": {"id": "call_01", "name": "get_exchange_rate",
                              "arguments": {"base": "USD", "target": "SAR"}}}
    rate = last["content"]["rate"]
    return {"text": f"سعر الدولار بالريال في البيانات التجريبية: {rate}"}

messages = [{"role": "user", "content": "كم سعر الدولار بالريال؟"}]
for turn in range(5):                      # حد أقصى للدورات
    reply = fake_model(messages)
    if "text" in reply:
        print(reply["text"])
        break
    call = reply["tool_call"]
    fn = TOOLS.get(call["name"])
    if fn is None:
        result = {"error": "unknown tool"}
    else:
        result = fn(**call["arguments"])
    messages.append({"role": "tool", "call_id": call["id"], "content": result})
    print("استدعاء:", json.dumps(call, ensure_ascii=False))

حين تستبدل fake_model باستدعاء نموذج حقيقي يبقى هيكل الحلقة كما هو: إرسال، فحص الرد، تنفيذ، إرجاع، تكرار.

الشكل نفسه في مكتبة حقيقية

في OpenAI Agents SDK (بحسب التوثيق الرسمي، مراجعة 18 نوفمبر 2026، الإصدار 0.25.0) تحوّل المكتبة دالة بايثون إلى أداة عبر المزخرف @function_tool، وتستنتج المخطط من تلميحات الأنواع، ثم يدير Runner الحلقة بنفسه. هذا المثال يتطلب تثبيت openai-agents ومتغير البيئة OPENAI_API_KEY:

python
# يتطلب: pip install openai-agents  ومفتاح OPENAI_API_KEY
from agents import Agent, Runner, function_tool

@function_tool
def get_exchange_rate(base: str, target: str) -> str:
    return "3.75 (بيانات تجريبية)"

agent = Agent(name="Assistant",
              instructions="أجب عن أسئلة العملات مستخدمًا الأداة.",
              tools=[get_exchange_rate])
result = Runner.run_sync(agent, "كم سعر الدولار بالريال؟")
print(result.final_output)

إذا تجاوزت الحلقة الحد max_turns ترفع المكتبة الاستثناء MaxTurnsExceeded، وهو المكافئ الرسمي للحد الأقصى في مثالنا اليدوي.

الملخص

استدعاء الوظائف يجعل النموذج يعبّر عن حاجته إلى أداة بطلب منظم بصيغة JSON بدل نص حر. تمر الدورة بالتعريف والقرار والطلب والتحقق والتنفيذ والإرجاع والصياغة، وتتكرر حتى الإجابة النهائية أو الحد الأقصى. ربط النتيجة بمعرّف الاستدعاء ضروري عند تعدد الاستدعاءات. المكتبات مثل OpenAI Agents SDK تدير هذه الحلقة نيابة عنك لكن المنطق نفسه.

المصطلحات

المصطلحEnglishالتعريف
استدعاء الوظائفFunction Callingقدرة النموذج على إرجاع طلب منظم لتشغيل دالة معرّفة
طلب استدعاءTool Callكائن يحمل اسم الأداة ومعاملاتها ومعرّفًا فريدًا
المعاملاتArgumentsالقيم التي يمررها النموذج إلى الأداة
معرّف الاستدعاءCall IDرمز يربط نتيجة الأداة بالطلب الذي أنتجها
الحد الأقصى للدوراتMax Turnsسقف لعدد دورات الحلقة يمنع الدوران بلا نهاية

أسئلة المراجعة

  1. رتّب مراحل دورة استدعاء الوظائف واشرح دور التطبيق في كل منها.
  2. لماذا يُعد معرّف الاستدعاء مهمًا عند طلب أداتين في دورة واحدة؟
  3. ما خطر استخدام eval لتنفيذ اسم أداة يقترحه النموذج؟
  4. كيف يقابل max_turns في OpenAI Agents SDK الحد الأقصى في الحلقة اليدوية؟

المراجع