دعوة الوظيفة

1. مقدمة حول استدعاء الدوال

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

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

2. سيناريوهات تطبيقية لاستدعاء الدوال

فيما يلي بعض أمثلة تطبيقاته العملية:

• إنشاء مساعد للرد على الأسئلة من خلال استدعاء واجهات برمجة التطبيقات الخارجية، مثل تعريف الدوال مثل send_email(to: string, body: string) أو get_current_weather(location: string, unit: 'celsius' | 'fahrenheit').
• تحويل اللغة الطبيعية إلى استدعاءات واجهة برمجة التطبيقات، على سبيل المثال ترجمة "Who are my top customers?" إلى get_customers(min_revenue: int, created_before: string, limit: int) ثم إجراء استدعاء داخلي لواجهة برمجة التطبيقات.
• استخراج بيانات منظمة من النص، على سبيل المثال تعريف الدوال مثل extract_data(name: string, birthday: string) أو sql_query(query: string).

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

3. النماذج التي تدعم استدعاء الدوال

ليس جميع إصدارات النموذج قد تم تدريبها باستخدام البيانات الخاصة باستدعاء الدوال. حاليا، النماذج التي تدعم استدعاء الدوال هي: gpt-4, gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, gpt-4-0613, gpt-3.5-turbo, gpt-3.5-turbo-1106, و gpt-3.5-turbo-0613.

علاوة على ذلك، تدعم النماذج gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, و gpt-3.5-turbo-1106 استدعاء الدوال المتوازية، مما يتيح لها تنفيذ استدعاءات دوال متعددة في وقت واحد والتعامل مع هذه الاستدعاءات بشكل متزامن لإنتاج نتائج فعالة وفعالة.

ملاحظة: المخاطر المحتملة المرتبطة بميزة استدعاء الدوال هي أنه قد تؤدي إلى النموذج إنتاج معلمات خاطئة (أي معلمات وهمية). لذا، قبل اتخاذ أي إجراءات تؤثر على العالم الحقيقي (مثل إرسال البريد الإلكتروني، النشر عبر الإنترنت، إجراء مشتريات، إلخ)، من المستحسن دمج عملية تأكيد المستخدم على مستوى المنتج، مما يضمن تنفيذ الدوال فقط بعد تأكيد المستخدم.

4. أمثلة على استدعاء الدوال

4.1 مثال Python

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

الخطوة 1: إعداد الدوال القابلة للاستدعاء وتعريفات الدوال للنموذج

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

import json

def get_current_weather(location, unit="fahrenheit"):
    return json.dumps({
        "location": location, 
        "temperature": "18", 
        "unit": unit
    })

الخطوة 2: استدعاء النموذج استنادًا إلى معامل الاستعلام والأدوات

للتالي، نحتاج إلى استدعاء نموذج GPT من خلال واجهة برمجة التطبيقات للاستكمال الدردشة وتمرير استعلام المستخدم (على سبيل المثال: "ما هو الطقس الحالي") وكذلك معلمة tools، والتي تحتوي على وصف لدالة get_current_weather التي قمنا للتو بتعريفها.

from openai import OpenAI

client = OpenAI()

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "الحصول على الطقس الحالي لموقع معين",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "اسم المدينة، على سبيل المثال: 'سان فرانسيسكو، كاليفورنيا'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["مئوية", "فهرنهايت"]
                }
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "ما هو الطقس الحالي في سان فرانسيسكو؟"}],
    tools=tools
)

الخطوة 3: تنفيذ الدالة محلياً

النتيجة التي تم إرجاعها من قبل النموذج ستتضمن معلومات حول الدالة التي يرغب النموذج في استدعائها، والتي عادة ما تكون موجودة في معلمة الاستجابة tool_calls. يمكننا بعد ذلك تنفيذ استدعاء الدالة المقابلة محلياً استناداً إلى معلومات استدعاء الدالة الموجودة في معلمة tool_calls.

tool_calls = response.choices[0].message.tool_calls

if tool_calls:
    arguments = json.loads(tool_calls[0].function.arguments)
    weather_info = get_current_weather(**arguments)
    print(weather_info) # هنا يمكننا رؤية معلومات الطقس التي تم الاستعلام عنها من خلال استدعاء الدالة

الخطوة 4: استدعاء النموذج مرة أخرى باستخدام نتيجة استدعاء الدالة

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

follow_up_response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "ما هو الطقس الحالي في سان فرانسيسكو؟"},
        {"role": "function", "name": "get_current_weather", "content": weather_info}
    ],
    tools=tools
)

توضيح: في المثال أعلاه، يتم إرسال محتوى عودة الدالة إلى نموذج GPT من خلال رسالة الدالة كما يلي:

{"role": "function", "name": "get_current_weather", "content": weather_info}

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

الخطوة 5: الحصول على الاستجابة النهائية من النموذج

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

final_output = follow_up_response.choices[0].message.content
print(final_output) # هذه النتيجة هي معلومات الطقس التي نريد عرضها للمستخدم

بعد اتباع الخطوات السابقة، قمنا بإكمال مثال كامل للاستعلام عن الطقس باستخدام نموذج GPT واستدعاء الدوال.

4.2. شرح تعريف دالة استدعاء الدالة

4.2.1 معنى حقول المعلمات 'الأدوات'

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

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

4.2.2 أمثلة لتعريفات الأدوات

الآن دعونا نقدم بعض أمثلة على تعريفات 'الأدوات' للمساعدة في فهم كيفية استخدام كل حقل.

Example 1: الحصول على معلومات الطقس الحالي

{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "الحصول على معلومات الطقس الحالي للموقع المحدد",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "المدينة التي يجب الاستعلام عن حالة الطقس، على سبيل المثال، 'سان فرانسيسكو، كاليفورنيا'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["سلسيوس", "فهرنهايت"],
                    "description": "وحدة الحرارة، 'سلسيوس' للسيلسيوس، 'فهرنهايت' للفهرنهايت"
                }
            },
            "required": ["location", "unit"]
        }
    }
}

في المثال أعلاه، قمنا بتحديد دالة باسم get_current_weather للحصول على الطقس الحالي لموقع محدد. تتضمن المعلمات الموقع و الوحدة، حيث تحتوي الوحدة على قيمتين صالحتين: "سلسيوس" (سيلسيوس) و "فهرنهايت" (فهرنهايت).

Example 2: البحث عن ألبومات لفنان معين

{
    "type": "function",
    "function": {
        "name": "find_artist_albums",
        "description": "البحث عن جميع الألبومات لفنان معين",
        "parameters": {
            "type": "object",
            "properties": {
                "artist_name": {
                    "type": "string",
                    "description": "اسم الفنان"
                }
            },
            "required": ["artist_name"]
        }
    }
}

في هذا المثال، قمنا بإنشاء دالة باسم find_artist_albums للبحث عن جميع الألبومات لفنان معين. تتطلب هذه الوظيفة معلمة واحدة فقط: artist_name (اسم الفنان).

4.3. مثال على استدعاء دالة طلب HTTP

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

4.3.1. الخطوة 1: استدعاء النموذج باستخدام استعلام المستخدم وتعريف الوظيفة

أولاً، نحتاج إلى إرسال استعلام المستخدم وقائمة الوظائف التي ندعمها إلى نموذج GPT، حتى يتمكن النموذج تحليلياً من تحديد الوظيفة التي يجب استدعاؤها للرد على استعلام المستخدم استناداً إلى سؤال المستخدم.

في المثال التالي، نُخبر GPT أن لدينا وظيفة get_current_weather يمكن استخدامها للاستعلام عن معلومات الطقس لمدينة معينة.

curl --location 'https://api.aiproxy.io/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {OPENAI_KEY}' \
--data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like in Shanghai today?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "الحصول على معلومات الطقس الحالي للموقع المحدد",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "المدينة التي يحتاج الاستعلام عن حالة الطقس فيها، مثل 'سان فرانسيسكو، كاليفورنيا'"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "celsius",
                                "fahrenheit"
                            ],
                            "description": "وحدة الحرارة، 'celsius' لدرجة مئوية، 'fahrenheit' لدرجة فهرنهايت"
                        }
                    },
                    "required": [
                        "location",
                        "unit"
                    ]
                }
            }
        }
    ]
}'

شرح المعلمات المُرسلة:

{
    "model": "gpt-3.5-turbo", // النموذج GPT الذي سيتم استدعاؤه
    "messages": [ // هذه قائمة الرسائل لـ GPT، بما في ذلك استعلام المستخدم
        {
            "role": "user",
            "content": "What's the weather like in Shanghai today?"
        }
    ],
    "tools": [
	  // هذا هو تعريف الوظيفة الخاصة بك، والذي يُبلغ GPT عن الوظائف المتاحة
    ]
}

يرجى الرجوع إلى القسم 4.2.2 لتعريف معلمة tools.

خلال المعالجة الطبيعية من قبل نموذج GPT، ستتلقى استجابة API مشابهة للتالي:

{
    "model": "gpt-3.5-turbo-0613",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 122,
        "completion_tokens": 27,
        "total_tokens": 149
    },
    "id": "chatcmpl-8mL4hS4zNMocyR2ajKyAvSTcbNaao",
    "created": 1706531447,
    "choices": [
        {
            "index": 0,
            "delta": null,
            "message": {
                "role": "assistant",
                "tool_calls": [ // معلمة tool_calls تمثل قائمة الوظائف التي يرغب GPT في استدعائها
                    {
                        "id": "call_1iF09ttX1R9ESR18Ul2nLe1R",
                        "type": "function",
                        "function": {
                            "name": "get_current_weather",  // يشير إلى أن GPT يرغب في الرد على استعلام المستخدم بالاستدعاء لوظيفة get_current_weather
                            "arguments": "{\n  \"location\": \"Shanghai, China\",\n  \"unit\": \"celsius\"\n}" // هذا هو المعلمة الداخلية لاستدعاء الوظيفة get_current_weather
                        }
                    }
                ]
            },
            "finish_reason": "tool_calls"
        }
    ]
}

4.3.2. الخطوة 2: تنفيذ استدعاء الوظيفة المحلية

نظرًا لأن نموذج GPT بذاته لا يمكنه تنفيذ استدعاءات وظائف محددة ويُعلمنا فقط بالوظيفة التي يرغب في استدعائها، يحتاج برنامجنا المحلي إلى تنفيذ استدعاء الوظيفة المحددة استنادًا إلى معلمة tool_calls التي يتم إعادتها من النموذج. تختلف طريقة تنفيذ الوظائف المحلية في لغات البرمجة المختلفة. على سبيل المثال، في Python، يمكنك الرجوع إلى القسم السابق.

4.3.3. الخطوة 3: استدعاء النموذج مرة أخرى بنتيجة إرجاع الدالة

نظرًا لتنفيذ استدعاء الدالة محليًا، نحتاج إلى تمرير نتيجة تنفيذ الدالة وسؤال المستخدم مرة أخرى إلى نموذج GPT لإعطاء الاستجابة النهائية.

curl --location 'https://api.aiproxy.io/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-Roc5MX1zEuVxiuaMaETV6wZ2jXcCehjUCzwP9AcNErUiwppQ' \
--data '{
    "model": "gpt-3.5-turbo",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like in Shanghai today?"
        },
        {
            "role": "function",
            "name": "get_current_weather",
            "content": "{\"city\":\"Shanghai\", \"temperature\":\"25 degrees Celsius\"}"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "الحصول على معلومات الطقس الحالي للموقع المحدد",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "المدينة التي ترغب بالاستعلام عن حالة الطقس فيها، مثال: 'شانغهاي'"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "سيلسيوس",
                                "فهرنهايت"
                            ],
                            "description": "وحدة الحرارة، 'سيلسيوس' لدرجات الحرارة بالسيلسيوس، 'فهرنهايت' لدرجات الحرارة بالفهرنهايت"
                        }
                    },
                    "required": [
                        "location",
                        "unit"
                    ]
                }
            }
        }
    ]
}'

ملاحظة: الطلب أعلاه يتضمن رسالة دالة إضافية لإبلاغ نموذج GPT بقيمة إرجاع الدالة. سيقوم GPT مباشرة بالرد على سؤال المستخدم استنادًا إلى معلومات إرجاع الدالة ولن يستدعي الدالة مرة أخرى.

تمثل رسالة الدالة قيمة إرجاع الدالة وتتبع الصيغة التالية:

{
    "role": "function", // نوع الرسالة هو دالة، مما يشير إلى قيمة إرجاع الدالة
    "name": "get_current_weather", // يُبلغ GPT بأن الرسالة الحالية هي قيمة إرجاع دالة get_current_weather
    "content": "{\"city\":\"Shanghai\", \"temperature\":\"25 degrees Celsius\"}" // محتوى إرجاع الدالة، يمكن أن يكون في تنسيق JSON أو محتوى نصي آخر.
}

فيما يلي الاستجابة النهائية التي تم إنشاؤها بواسطة GPT:

{
    "model": "gpt-3.5-turbo-0613",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 144,
        "completion_tokens": 17,
        "total_tokens": 161
    },
    "id": "chatcmpl-8mLmvvKAjSql7rGF8fvQeddKhWYvr",
    "created": 1706534189,
    "choices": [
        {
            "index": 0,
            "delta": null,
            "message": {
                "role": "assistant",
                "content": "حالة الطقس في شانغهاي اليوم هي 25 درجة مئوية."
            },
            "finish_reason": "stop"
        }
    ]
}