استدعاء الدوال (Function Calling): خلّي النموذج يطلب تشغيل كودك

المستوى: متوسط — الكلام ده للي عنده أساس في البرمجة وبيتعامل مع الـ APIs، مش لأول يوم في البايثون.

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

استدعاء الدوال: إزاي النموذج بيطلب تشغيل كودك بـ JSON منظّم

المشكلة باختصار

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

يعني إيه استدعاء الدوال؟

تخيّل موظف استقبال خبير بيرد على أي سؤال بطلاقة، بس ممنوع يلمس أنظمة الشركة. لما تطلب منه حاجة محتاجة النظام — «اطبعلي فاتورة العميل ده» — هو مش بيروح ينفّذ بنفسه. بيملالك استمارة مكتوبة بدقة: اسم الإجراء المطلوب، وتفاصيله. انت بتاخد الاستمارة، تنفّذها على النظام، وترجّعله النتيجة عشان يكمّل كلامه مع العميل.

علميًا: انت بتوصّف للنموذج مجموعة «أدوات» (tools)، كل واحدة ليها اسم ووصف وschema بصيغة JSON Schema يحدّد المعاملات وأنواعها. النموذج بيقرأ السؤال، ولو محتاج أداة، بيرجّع كتلة منظّمة (tool call) فيها اسم الدالة والمعاملات كـ JSON — مش نص حر. تطبيقك هو اللي بينفّذ الكود فعليًا، ويرجّع النتيجة للنموذج في الدورة اللي بعدها.

إزاي بتشتغل — الحلقة

1. المستخدم يسأل: «كام درجة الحرارة في القاهرة دلوقتي؟».
2. النموذج يرجّع طلب أداة: بدل رد نصي، يرجّع {"name":"get_weather","arguments":{"city":"Cairo"}}.
3. تطبيقك ينفّذ الدالة: ينده الـ API الحقيقي ويجيب 34 درجة.
4. ترجّع النتيجة للنموذج في رسالة نتيجة الأداة (tool result).
5. النموذج يصيغ الإجابة النهائية بلغة طبيعية للمستخدم.

ركز في نقطة مهمة: النموذج ما نفّذش أي كود. هو بس طلب التنفيذ. ده بيخليك تتحكم في الأمان بالظبط، لأنك انت اللي بتقرّر أنهي دوال متاحة وبأي صلاحيات.

مثال كود شغّال

ده مثال بصيغة واجهة OpenAI، ونفس الفكرة موجودة عند Anthropic باسم tool use. عرّفنا أداة واحدة، وبعتناها مع الرسالة:

from openai import OpenAI
import json

client = OpenAI()

tools = [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "ارجع درجة الحرارة الحالية لمدينة",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }
}]

messages = [{"role": "user", "content": "كام الحرارة في القاهرة؟"}]

resp = client.chat.completions.create(
    model="gpt-4o-mini", messages=messages, tools=tools
)

call = resp.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)   # {"city": "Cairo"}

# تطبيقك هو اللي بينفّذ الدالة الحقيقية
result = get_weather(args["city"])           # مثلاً 34

# ارجع النتيجة للنموذج عشان يصيغ الرد النهائي
messages.append(resp.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": str(result)
})

final = client.chat.completions.create(
    model="gpt-4o-mini", messages=messages, tools=tools
)
print(final.choices[0].message.content)

لاحظ إننا استدعينا النموذج مرتين: مرة عشان ياخد قرار الأداة، ومرة تانية بعد ما رجّعنا النتيجة عشان يكتب الرد.

خلّي المخرج مضمون: الوضع الصارم

المشكلة القديمة إن النموذج أحيانًا كان يرجّع JSON ناقص قوس أو بفاصلة زيادة، فيكسر الكود اللي بيقرأه. الحل الحديث اسمه المخرجات المنظّمة (Structured Outputs) مع strict: true، اللي بيجبر المخرج يطابق الـ schema حرفيًا. أوبن إيه أعلنت في أغسطس 2024 إن الموديل مع الوضع ده بيوصل دقة 100% في اختبار مطابقة الـ schema عندهم، مقابل أقل من 40% من غيره. الفرق ده معناه إنك تشيل كود التحقق اليدوي اللي بيتعب في الإنتاج.

وتقدر تجبر النموذج يستخدم أداة معينة عن طريق tool_choice: القيمة auto للاختيار التلقائي، وrequired (أو any عند Anthropic) للإجبار على أداة، وnone للمنع، أو اسم أداة محدد للإجبار عليها بالذات. ده مفيد لما تبني «مستخرج بيانات» لازم يرجّع JSON منظّم في كل مرة.

سيناريو واقعي والأرقام

لو عندك مساعد دعم فني بيخدم 50 ألف طلب في اليوم، وكل طلب محتاج يقرأ حالة الأوردر من قاعدة بياناتك: من غير أدوات، النموذج هيألّف حالات مش موجودة. مع أداة get_order_status بترجّع رقم الأوردر منظّم، وانت بتقرأ الحقيقة من الـ DB وترجّعهاله. الفرق هنا مش تجميلي — ده الفرق بين رد صح ورد بيخسّرك عميل.

الـ trade-offs ومتى لا تستخدمها

• تكلفة ووقت: كل دورة أداة تساوي استدعاء إضافي للنموذج، يعني زمن استجابة أطول وتوكنز أكتر. حلقة فيها 3 أدوات ممكن تبقى 4 استدعاءات.
• الوضع الصارم مش متوافق مع الاستدعاء المتوازي: أوبن إيه بتوضّح إن Structured Outputs مش بيشتغل مع parallel tool calls. لو محتاج تشغّل أكتر من أداة في نفس اللحظة، اقفل parallel_tool_calls أو استغنى عن الوضع الصارم.
• صيانة الـ schemas: كل أداة ليها schema لازم يتصان مع أي تغيير في الـ API بتاعك.

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

الخطوة التالية

اختار أبسط استدعاء API في تطبيقك (زي «هات حالة الأوردر»)، عرّفه كأداة واحدة بـ schema صارم، وشغّل الحلقة اللي فوق. قِس زمن الاستجابة قبل وبعد؛ ولو زاد أكتر من اللازم، قلّل عدد الأدوات المتاحة في كل طلب وخلّيها على قد الحاجة.

المصادر

• OpenAI — Function calling guide
• OpenAI — Introducing Structured Outputs in the API (أغسطس 2024)
• Anthropic — Tool use (function calling)
• Anthropic — Structured outputs