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

iOS والإصدارات الأحدث Android الويب Flutter

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

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

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

يمكنك قراءة مزيد من المعلومات عن استدعاء الدوال في مستندات 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.

 

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

iOS والإصدارات الأحدث Android الويب Flutter

قبل البدء

يُرجى إكمال دليل بدء استخدام حِزم تطوير البرامج (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: إنشاء بيان دالة

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

ملاحظة: يوضّح مثال هذا الدليل تقديم بيان دالة واحد فقط للنموذج، ولكن يمكنك تقديم ما يصل إلى 128 بيان دالة للنموذج ليختار من بينها.

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

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

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

• يجب تقديم تعريفات الدوالّ بتنسيق مخطّط متوافق مع مخطّط 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: تقديم بيان الدالة أثناء بدء تشغيل النموذج

ملاحظة: يتيح كل من Gemini 1.0 Pro وGemini 1.5 Pro استدعاء الدوالّ. عند تحديد النموذج الذي تريد استخدامه، احرص على مراجعة الحصص لكل نموذج.

الحد الأقصى لعدد تعريفات الدوالّ التي يمكنك تقديمها مع الطلب هو 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

• إنشاء محادثات متعددة المقاطع (محادثة)
• إنشاء نص من الطلبات النصية فقط
• إنشاء نص من طلبات متعددة الوسائط (بما في ذلك النصوص والصور وملفات PDF والفيديوهات والصوت)

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

• التعرّف على تصميم الطلبات، بما في ذلك أفضل الممارسات والاستراتيجيات وأمثلة الطلبات
• ضبط مَعلمات النموذج، مثل مستوى الإبداع والحد الأقصى لوحدات ترميز الإخراج
• استخدام إعدادات الأمان لضبط احتمالية تلقّي ردود قد تُعتبر ضارة

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

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

اطّلِع على مزيد من المعلومات عن النماذج المتاحة لحالات الاستخدام المختلفة واطلاعك على الحصص والأسعار.

تقديم ملاحظات حول تجربتك مع Vertex AI in Firebase