برنامج تعليمي حول استدعاء الدوال

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

يمكنك تزويد نماذج Gemini بأوصاف الدوالّ. هذه هي الدوالّ التي تكتبها بلغة تطبيقك (أي أنّها ليست Google Cloud Functions). قد يطلب منك النموذج استدعاء دالة وإرسال النتيجة مرة أخرى لمساعدة النموذج في معالجة طلبك.

يمكنك الاطّلاع على مقالة مقدّمة حول استدعاء الدوالّ للتعرّف على مزيد من المعلومات، إذا لم يسبق لك ذلك.

مثال على واجهة برمجة تطبيقات للتحكّم في الإضاءة

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

المَعلمة النوع مطلوب الوصف
brightness الرقم نعم مستوى الإضاءة من 0 إلى 100 القيمة 0 تعني إيقاف الإضاءة والقيمة 100 تعني الإضاءة الكاملة.
colorTemperature سلسلة نعم درجة حرارة الألوان لتركيبات الإضاءة التي يمكن أن تكون daylight أو cool أو warm.

للتبسيط، يتضمّن نظام الإضاءة الخيالي هذا مصباحًا واحدًا فقط، لذا ليس على المستخدِم تحديد غرفة أو موقع جغرافي. في ما يلي مثال على طلب JSON يمكنك إرساله إلى واجهة برمجة التطبيقات لنظام التحكّم في الإضاءة لتغيير مستوى الإضاءة إلى %50 باستخدام درجة حرارة ألوان ضوء النهار:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

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

قبل البدء: إعداد مشروعك ومفتاح واجهة برمجة التطبيقات

قبل طلب Gemini API، عليك إعداد مشروعك وضبط مفتاح واجهة برمجة التطبيقات.

تحديد وظيفة واجهة برمجة التطبيقات

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

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

إنشاء تعريفات الدوالّ

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

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

تحديد الدوالّ أثناء بدء تشغيل النموذج

عندما تريد استخدام استدعاء الدالة مع نموذج، عليك تقديم تعريفات الدوالّ عند بدء عنصر النموذج. يمكنك تحديد الدوالّ من خلال ضبط المَعلمة tools للنموذج:

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

إنشاء استدعاء دالة

بعد بدء النموذج باستخدام تعريفات الدوالّ، يمكنك توجيه النموذج باستخدام الدالة المحدّدة. يجب استخدام طلب الوظيفة باستخدام طلبات المحادثة (sendMessage())، لأنّ طلب الوظيفة يستفيد بشكل عام من معرفة سياق الطلبات والردود السابقة.

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}