استدعاء الدوال باستخدام 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 يمكنها مساعدته في الاستجابة للطلب. إذا قرّر النموذج أنّ الدالة يمكن أن تكون مفيدة، ينشئ النموذج بيانات منظَّمة تساعد تطبيقك في استدعاء الدالة.

راجِع الطلب الوارد مرة أخرى: 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