كيفية استخدام استدعاء الدوال في أوبن إيه آي

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

ما تحتاجه قبل أن تبدأ

استدعاء الدوال (غالبًا ما يُسمى استدعاء الأداة) هو كيفية اتصال النموذج بالتعليمات البرمجية والأنظمة الخارجية الخاصة بك. تقوم بوصف الدوال التي يعرضها تطبيقك، ويقرأ النموذج طلب المستخدم، وعندما تتناسب إحدى الدوال، فإنه يعيد اسم الدالة بالإضافة إلى كائن JSON من الوسيطات. النموذج لا يقوم بتشغيل أي شيء بنفسه. إنه يسلمك طلبًا منظمًا، وتقوم التعليمات البرمجية الخاصة بك بالعمل.

هذا الانقسام هو ما يجب أن تتذكره أثناء البناء. يختار النموذج النية ويملأ المعلمات. أنت تظل متحكمًا في التنفيذ. تتحول رسالة "الحصول على الطقس في باريس" إلى استدعاء نظيف get_weather({"location": "Paris, France"}) بدلاً من فقرة سيتعين عليك تحليلها يدويًا.

للمتابعة، تحتاج إلى مفتاح OpenAI API ووظيفة في التعليمات البرمجية الخاصة بك تريد أن يتمكن النموذج من تشغيلها. شيء آخر يجب تحديده مسبقًا: نقطة النهاية التي تستخدمها. تعمل نفس الميزة في مكانين. تدعمها واجهة برمجة تطبيقات إكمال الدردشة (Chat Completions API) الأقدم، وكذلك واجهة برمجة تطبيقات الاستجابات (Responses API) الأحدث، التي توحد ما كان مقسمًا في السابق بين إكمال الدردشة وواجهة برمجة تطبيقات المساعدين (Assistants API). تختلف الأشكال قليلاً، وتغطي الخطوات أدناه كليهما.

الخطوة 1: تحديد أداتك

الأداة هي تعريف دالة يمكن للنموذج قراءتها. تمنحها اسمًا ووصفًا ومخطط JSON للوسيطات. يقوم الوصف بعمل حقيقي هنا. يخبر النموذج متى يجب استخدام الدالة، لذا اكتبه كتعليمات، وليس كتسمية.

إليك تعريف أداة في شكل إكمال الدردشة (Chat Completions)، حيث توجد الدالة تحت غلاف function:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}

تقوم واجهة برمجة تطبيقات الاستجابات (Responses API) بتبسيط هذا. توجد حقول name و description و parameters و strict في المستوى الأعلى لكائن الأداة، بدون مفتاح function متداخل. نفس المعلومات، طبقات أقل.

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

الخطوة 2: قم بإجراء طلبك الأول

أرسل أداتك إلى النموذج مع رسالة المستخدم. يبدو طلب إكمال الدردشة (Chat Completions) الكامل الذي يقوم بذلك كما يلي:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in Paris right now?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string"}
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

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

الخطوة 3: قراءة استدعاء الأداة الذي يعيده النموذج

عندما يقرر النموذج استدعاء دالة، فإنه لا يعيد نصًا. إنه يعيد استدعاء أداة تقرأه من الاستجابة.

في إكمال الدردشة (Chat Completions)، تحمل رسالة المساعد مصفوفة tool_calls. يحتوي كل إدخال على id، و type من نوع function، وكائن function مع name وسلسلة arguments:

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}

في Responses API، يظهر الاستدعاء في مصفوفة output بشكل مسطح أكثر: type من نوع function_call، و call_id، و name، و arguments:

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

تفصيلة واحدة تربك الناس: arguments هي سلسلة مشفرة بصيغة JSON، وليست كائنًا مُحللاً. تقوم بتحليلها بنفسك، وتشغيل وظيفتك، ثم إرسال النتيجة مرة أخرى حتى يتمكن النموذج من إنهاء رده.

الخطوة 4: إرجاع النتيجة إلى النموذج

بعد تشغيل وظيفتك، أعد النتيجة حتى يتمكن النموذج من إنتاج إجابة نهائية. في إكمال الدردشة (Chat Completions)، تقوم بإلحاق رسالة دور tool مرتبطة بمعرف الاستدعاء id. في واجهة برمجة تطبيقات الاستجابات (Responses API)، ترسل عنصر function_call_output مرتبطًا بمعرف الاستدعاء call_id. في كلتا الحالتين، الحلقة هي نفسها: النموذج يسأل، أنت تقوم بالتشغيل، أنت تعيد النتيجة، النموذج يستجيب.

الخطوة 5: إضافة استدعاءات متوازية ووضع صارم

يغير إعدادان مدى موثوقية وسرعة هذا، وتقوم بإضافتهما بمجرد أن تعمل الحلقة الأساسية.

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

الوضع الصارم (Strict mode). قم بتعيين strict: true على تعريف الدالة وتكون وسيطات النموذج مضمونة لمطابقة مخطط JSON الخاص بك بدلاً من أن تكون أفضل جهد. توصي OpenAI دائمًا بتمكينه. الوضع الصارم له قواعد: كل كائن يحتاج إلى additionalProperties: false، ويجب أن يظهر كل حقل في properties في required. لجعل حقل اختياريًا، لا تسقطه من required؛ بل تضيف null إلى قائمة أنواعه المسموح بها.

قاعدة الحقل الاختياري تفاجئ الناس. لنفترض أن unit اختياري في get_weather. في الوضع الصارم، ما زلت تدرجه في required، ثم تحدده على أنه قابل للقيمة الفارغة (nullable) في المخطط، مثل "unit": {"type": ["string", "null"], "enum": ["celsius", "fahrenheit"]}. يمكن للنموذج الآن تمرير وحدة حقيقية أو null صريح، لكنه لا يمكنه أبدًا حذف المفتاح. هذه القدرة على التنبؤ هي الهدف كله: تعرف التعليمات البرمجية للتحليل الخاصة بك بالضبط أي مفاتيح تتوقعها في كل مرة.

يقلل الوضع الصارم من JSON المشوه، لكنه لا يتحقق من أن القيم منطقية من الناحية التجارية. يمكن أن يكون الموقع صالحًا للمخطط ولكنه لا يزال مدينة لا تخدمها. هنا يأتي دور الاختبار.

كيفية اختباره في Apidog

يقدم لك النموذج استدعاء أداة. قبل ربطه بوظيفة حية، تريد ضمانين: أن الوسيطات تتوافق مع الشكل الذي تتوقعه، وأن واجهة برمجة التطبيقات النهائية (downstream API) التي ستستدعيها وظيفتك تتصرف بالطريقة التي تفترضها. يغطي Apidog كلا الجانبين من ذلك، ويستحق الأمر أن تكون دقيقًا بشأن أي منهما.

يقوم Apidog بالتحقق ومحاكاة جانب واجهة برمجة التطبيقات. إنه لا يقوم بتنفيذ وظائف تطبيقك. ما يفعله جيدًا هو العقد المحيط بها.

التحقق من بنية الوسيطات. خذ سلسلة arguments من استدعاء أداة حقيقي، تعامل معها كجسم طلب، وقم بإجراء التحققات عليها في Apidog. تحقق من أن location موجودة وأنها سلسلة نصية، وأن حقل التعداد لا يحتوي أبدًا إلا على قيمة مسموح بها، وأن الحقول المطلوبة موجودة. من السهل استخراج حقول محددة من الحمولة باستخدام تعبيرات JSONPath، ولإجراء فحوصات هيكلية أعمق، هناك التحقق من صحة مخطط JSON، والذي يعكس نفس المخطط الذي سلمته إلى OpenAI في الوضع الصارم. إذا اجتاز إخراج النموذج نفس المخطط الذي تتوقعه وظيفتك، فقد أغلقت الحلقة.

محاكاة واجهة برمجة التطبيقات النهائية التي ستستدعيها الدالة. من المحتمل أن تستدعي وظيفتك get_weather مزودًا للطقس. أثناء التطوير، قد يكون هذا المزود مقيدًا بالمعدل أو مدفوعًا أو لم يتم إنشاؤه بعد. قم بإنشاء واجهة برمجة تطبيقات وهمية (mock API) في Apidog تعيد حمولة طقس واقعية، ووجه وظيفتك إلى المحاكاة، وقم بتشغيل مسار الاستدعاء بأكمله دون إنفاق طلب على الخدمة الحقيقية. أنت تتحكم في الاستجابة، بما في ذلك حالات الخطأ التي نادرًا ما تنتجها واجهة برمجة التطبيقات الحية عند الطلب، حتى تتمكن من تأكيد أن التعليمات البرمجية الخاصة بك تتعامل مع مهلة أو خطأ 429 قبل أن يكتشفها المستخدم.

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

أسئلة مكررة

هل يعمل استدعاء الدوال في كل من Chat Completions و Responses API؟ نعم. تدعمه كلتا نقطتي النهاية. توحد Responses API القدرات التي كانت مقسمة سابقًا بين Chat Completions و Assistants API. الاختلاف الرئيسي هو الشكل: Chat Completions تضع الدالة تحت مفتاح function وتُعيد tool_calls، بينما Responses API تستخدم تعريف أداة مسطح وتُعيد عناصر function_call في مصفوفة output.

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

هل يضمن الوضع الصارم (strict mode) نجاح الدالة؟ لا. يضمن الوضع الصارم أن الوسيطات تتطابق مع مخطط JSON الخاص بك، لذا تكون البنية موثوقة. لكنه لا يتحقق من أن القيم صحيحة لمنطق عملك، ولا يقوم بتشغيل وظيفتك. لا يزال يتعين عليك التحقق من القيم والتعامل مع حالات فشل الاستدعاء النهائي بنفسك.

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

الخلاصة

لديك الآن الحلقة الكاملة: حدد أدواتك بوضوح، أرسلها مع الطلب، اقرأ مخرجات tool_calls أو function_call، أعد النتيجة، ثم قم بتشغيل الوضع الصارم وقرر ما إذا كانت الاستدعاءات المتوازية تساعد أو تضر. اختتم الأمر بالاختبار عن طريق التحقق من تطابق الوسيطات مع المخطط الخاص بك ومحاكاة واجهة برمجة التطبيقات النهائية (downstream API) لتكون واثقًا قبل الإنتاج.

هل تريد تجربة جانب الاختبار؟ قم بتنزيل Apidog للتحقق من وسيطات استدعاء الأداة مقابل المخطط الخاص بك ومحاكاة واجهات برمجة التطبيقات التي تعتمد عليها وظائفك، كل ذلك في مكان واحد.