استدعاء الدوال باستخدام Gemini API


تُعدّ النماذج التوليدية فعّالة في حلّ العديد من أنواع المشاكل. ومع ذلك، فإنه تفرض عليهم قيود، مثل:

  • ويتم تجميدها بعد التدريب، ما يؤدي إلى تقادم المعلومات.
  • ولا يمكنهم الاستعلام عن البيانات الخارجية أو تعديلها.

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

يمكنك قراءة مزيد من المعلومات حول استدعاء الدوال في مستندات Google Cloud، بما في ذلك قائمة مفيدة بحالات استخدام استدعاء الدوال.

تتوفّر ميزة "استدعاء الدوالّ" في Gemini 1.0 Pro وGemini 1.5 Pro وGemini 1.5 Flash.

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

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

  2. أنشئ إعلان دالة يصف الدالة ومعاملاتها.

  3. قدِّم بيان الدالة أثناء بدء تشغيل النموذج لكي يعرف النموذج كيفية استخدام الدالة، إذا لزم الأمر.

  4. يمكنك إعداد تطبيقك حتى يتمكن النموذج من إرسال المعلومات المطلوبة لتطبيقك لاستدعاء الدالة.

  5. نقْل ردّ الدالة إلى النموذج لكي يتمكّن من توليد ردّه النهائي

الانتقال إلى تنفيذ الرمز

نظرة عامة على مثال على استدعاء الدوال

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

لنفترض أنّ لديك تطبيقًا يمكن للمستخدم إدخال طلب فيه، مثل: What was the weather in Boston on October 17, 2024?.

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

أولاً، يجب كتابة دالة fetchWeather في تطبيقك تتفاعل مع واجهة برمجة التطبيقات الخارجية الافتراضية هذه، والتي تحتوي على الإدخال والمخرجات التالية:

المعلَمة النوع مطلوبة الوصف
الإدخال
location الكائن نعم اسم المدينة والولاية المطلوب الحصول على معلومات الطقس فيها
تتوفّر هذه الميزة للمدن في الولايات المتحدة فقط. يجب أن يكون دائمًا عنصرًا مُدمَجًا من city وstate.
date سلسلة نعم تاريخ جلب حالة الطقس (يجب أن يكون دائمًا بتنسيق YYYY-MM-DD).
الناتج
temperature العدد الصحيح نعم درجة الحرارة (بالفهرنهايت)
chancePrecipitation سلسلة نعم احتمالية هطول الأمطار (يتم التعبير عنها بالنسبة المئوية)
cloudConditions سلسلة نعم أحوال السحابة الإلكترونية (أحد أيام clear وpartlyCloudy و mostlyCloudy وcloudy)

عند إعداد النموذج، يُطلع النموذج على توفّر دالة fetchWeather وكيف يمكن استخدامها لمعالجة الطلبات الواردة، إذا لزم الأمر. ويُعرف ذلك باسم "تعريف الدالة". لا يستدعي النموذج الدالة بشكل مباشر. بدلاً من ذلك، عندما يعالج النموذج الطلب الوافد، فإنه يقرّر ما إذا كانت الدالة fetchWeather يمكنها مساعدته في الاستجابة للطلب. إذا قرر النموذج أنّ الدالة يمكن أن تكون مفيدة، ينشئ النموذج data منظَّمة ستساعد تطبيقك في استدعاء الدالة.

راجِع الطلب الوارد مرة أخرى: What was the weather in Boston on October 17, 2024?. من المرجّح أن يقرّر النموذج أنّ الدالة fetchWeather يمكن أن تساعده في إنشاء ردّ. سيفحص النموذج معلمات الإدخال اللازمة للدالة fetchWeather، ثم ينشئ بيانات إدخال منظَّمة للدالة التي تبدو تقريبًا على النحو التالي:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

ويُرسِل النموذج بيانات الإدخال المنظَّمة هذه إلى تطبيقك كي يتمكّن من استدعاء دالة fetchWeather. عندما يتلقّى تطبيقك معلومات أحوال الطقس من واجهة برمجة التطبيقات، يرسل المعلومات إلى النموذج. تسمح معلومات الطقس هذه للنموذج بإكمال المعالجة النهائية وإنشاء الردّ على الطلب الأولي من What was the weather in Boston on October 17, 2024?

قد يقدّم النموذج استجابة نهائية باللغة الطبيعية، مثل: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

مخطّط بياني يوضّح كيفية تفاعل النموذج مع دالة في تطبيقك 

تنفيذ استدعاء الدالة

قبل البدء

أكمِل دليل البدء لحِزم تطوير البرامج (SDK) "Vertex AI in Firebase"، إذا لم يسبق لك إجراء ذلك. تأكّد من القيام بكل ما يلي:

  1. إعداد مشروع جديد أو حالي على Firebase، بما في ذلك استخدام خطط أسعار Blaze وتفعيل واجهات برمجة التطبيقات المطلوبة

  2. يمكنك ربط تطبيقك بمنصة Firebase، بما في ذلك تسجيل تطبيقك وإضافة إعدادات Firebase إلى تطبيقك.

  3. أضِف حزمة تطوير البرامج (SDK) وابدأ إعداد خدمة Vertex AI والنموذج التوليدي في تطبيقك.

بعد ربط تطبيقك بمنصّة Firebase وإضافة حزمة تطوير البرامج (SDK) وإعداد خدمة Vertex AI والنموذج التوليدي، ستكون مستعدًا لاستدعاء Gemini API.

توضّح لك الخطوات المتبقية في هذا الدليل كيفية تنفيذ إعداد استدعاء الدوال على نحو مشابه لسير العمل الموضّح في نظرة عامة على مثال عن استدعاء الدوال (اطّلِع على القسم العلوي من هذه الصفحة).

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

الخطوة 1: كتابة الدالة

لنفترض أنّ لديك تطبيقًا يمكن للمستخدم إدخال طلب فيه، مثل: What was the weather in Boston on October 17, 2024?. قد لا تعرف نماذج Gemini معلومات الطقس هذه، ولكن لنفترض أنّك تعرف واجهة برمجة تطبيقات خارجية لخدمة الطقس يمكنها تقديم هذه المعلومات. يعتمد المثال في هذا الدليل على واجهة برمجة التطبيقات الخارجية الافتراضية هذه.

اكتب الدالة في تطبيقك التي ستتفاعل مع واجهة برمجة التطبيقات الخارجية الافتراضية ، وقدِّم للنموذج المعلومات التي يحتاجها لإنشاء طلبه النهائي. في مثال الطقس هذا، ستكون الدالة fetchWeather التي تستدعي استدعاء واجهة برمجة التطبيقات الخارجية الافتراضية هذه.

الخطوة 2: إنشاء بيان دالة

أنشئ بيان الدالة الذي ستوفّره لاحقًا للنموذج (الخطوة التالية في هذا الدليل).

في البيان، أدرِج أكبر قدر ممكن من التفاصيل في أوصاف الدالة ومعلّماتها.

يستخدم النموذج المعلومات الواردة في تعريف الدالة لتحديد الدالة التي يجب اختيارها وكيفية توفير قيم معلَمات للاستدعاء الفعلي للدالة. راجِع السلوكيات والخيارات الإضافية لاحقًا في هذه الصفحة لمعرفة كيفية اختيار النموذج من بين الدوال، وكذلك كيفية التحكّم في هذا الاختيار.

يُرجى مراعاة ما يلي بشأن المخطّط الذي تقدّمه:

  • يجب تقديم تعريفات الدوالّ بتنسيق مخطّط متوافق مع مخطّط OpenAPI. يوفّر Vertex AI دعمًا محدودًا لنموذج OpenAPI.

    • يمكن استخدام السمات التالية: type وnullable وrequired وformat وdescription وproperties وitems وenum.

    • السمات التالية غير متوافقة: default وoptional وmaximum وoneOf.

  • تلقائيًا، بالنسبة إلى Vertex AI in Firebase حِزم تطوير البرامج (SDK)، تُعتبَر جميع الحقول مطلوبة ما لم تحدّدها كحقول اختيارية في صفيف optionalProperties . بالنسبة إلى هذه الحقول الاختيارية، يمكن أن يملأ النموذج الحقول أو يتخطّاها. يُرجى العِلم أنّ ذلك يتناقض مع السلوك التلقائي لـ Vertex AI Gemini API.

لمعرفة أفضل الممارسات المتعلّقة بتصريحات الدوال، بما في ذلك نصائح للأسماء والأوصاف، يمكنك الاطّلاع على أفضل الممارسات في مستندات Google Cloud.

إليك كيفية كتابة بيان دالة:

الخطوة 3: تقديم بيان الدالة أثناء إعداد النموذج

الحد الأقصى لعدد بيانات الدوالّ التي يمكنك تقديمها مع الطلب هو 128. اطّلِع على السلوكيات والخيارات الإضافية في وقت لاحق من هذه الصفحة لمعرفة كيفية اختيار النموذج من بين الدوالّ، بالإضافة إلى كيفية التحكّم في هذا الاختيار (باستخدام toolConfig لضبط وضع استدعاء الدالة).

تعرَّف على كيفية اختيار نموذج Gemini وموقع جغرافي اختياريًا مناسبَين لحالة الاستخدام والتطبيق.

الخطوة 4: استدعاء الدالة لاستدعاء واجهة برمجة التطبيقات الخارجية

إذا قرّر النموذج أنّ دالة fetchWeather يمكنها مساعدته في توليد ردّ نهائي، على تطبيقك إجراء الطلب الفعلي لهذه الدالة باستخدام بيانات الإدخال المنظَّمة التي يقدّمها النموذج.

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

يوضِّح مقتطف الرمز التالي كيفية إبلاغ تطبيقك بأنّ النموذج يريد استخدام الدالة fetchWeather. ويوضّح أيضًا أنّ النموذج قد قدّم قيم مَعلمات الإدخال اللازمة لاستدعاء الدالة (وواجهة برمجة التطبيقات الخارجية الأساسية).

في هذا المثال، كان الطلب الواردة يتضمّن الطلب التالي: What was the weather in Boston on October 17, 2024?. من هذا الطلب، استنتَج النموذج معلَمات الإدخال المطلوبة للدالة fetchWeather (أي city وstate وdate).

الخطوة 5: قدّم ناتج الدالة إلى النموذج لإنشاء الاستجابة النهائية.

بعد أن تعرض الدالة fetchWeather معلومات الطقس، يجب على التطبيق إرجاعها إلى النموذج.

بعد ذلك، يُجري النموذج المعالجة النهائية وينشئ ردًا نهائيًا باللغة الطبيعية مثل: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

السلوكيات والخيارات الإضافية

في ما يلي بعض السلوكيات الإضافية لاستدعاء الدوالّ التي عليك مراعاتها في الرمز البرمجي والخيارات التي يمكنك التحكّم فيها.

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

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

يجب أن يتيح تطبيقك للنموذج طلب مزيد من طلبات معالجة وظائف إضافية.

قد يطلب النموذج استدعاء وظائف متعددة في الوقت نفسه.

يمكنك تقديم ما يصل إلى 128 دالة في قائمة تعريف الدوال لملف النموذج. بناءً على ذلك، قد يقرر النموذج أنّه يجب استخدام دوال متعددة لمساعدة النموذج في إنشاء الردّ النهائي. وقد يقرّر استدعاء بعض هذه الدوال في الوقت نفسه، ويُعرف ذلك باسم استدعاء الدوالّ بشكل موازٍ.

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

تتوفّر ميزة "استدعاء الدوالّ بشكل موازٍ" في Gemini 1.5 Pro وGemini 1.5 Flash.

يمكنك التحكّم في كيفية طلب النموذج لاستدعاء الدوالّ وما إذا كان ذلك ممكنًا.

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

  • وبدلاً من السماح للنموذج بالاختيار بين استجابة فورية للغة طبيعية واستدعاء دالة، يمكنك إجباره على استخدام استدعاءات الدوال دائمًا. وتُعرف هذه العملية باسم استدعاء الدوال البرمجية.

  • إذا قدمت تعريفات دوال متعددة، يمكنك تقييد النموذج باستخدام مجموعة فرعية فقط من الدوال المقدمة.

يمكنك تنفيذ هذه القيود (أو الأوضاع) من خلال إضافة إعدادات أداة (toolConfig) إلى جانب المطالبة وتعريفات الدالة. في إعدادات الأدوات، يمكنك تحديد أحد الأوضاع التالية. الوضع الأكثر فائدة هو ANY.

الوضع الوصف
AUTO سلوك النموذج التلقائي. يقرّر النموذج ما إذا كان سيستخدم دالة أو ردًا باللغة الطبيعية.
ANY يجب أن يستخدم النموذج استدعاءات الدالة ("استدعاء الدالة القسري"). لتقييد النموذج بمجموعة فرعية من الدوال، حدِّد أسماء الدوال المسموح بها في allowedFunctionNames.
NONE يجب ألا يستخدم النموذج استدعاءات الدوال. ويشبه هذا السلوك طلب نموذج بدون أي إعلانات وظائف مرتبطة.

يتوفّر وضع "استدعاء الوظيفة" في Gemini 1.5 Pro وGemini 1.5 Flash.

الإجراءات الأخرى التي يمكنك اتخاذها

تجربة إمكانات أخرى في Gemini API

التعرّف على كيفية التحكّم في إنشاء المحتوى

يمكنك أيضًا تجربة الطلبات وإعدادات النماذج باستخدام Vertex AI Studio.

مزيد من المعلومات حول طُرز Gemini

تعرَّف على مزيد من المعلومات حول النماذج المتاحة لحالات الاستخدام المختلفة وأسعارها وأسعارها.


تقديم ملاحظات حول تجربتك في استخدام "Vertex AI in Firebase"