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

Python Node.js Go Dart (Flutter) Android Swift الويب

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

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

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

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

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

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

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

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

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

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

dart pub add google_generative_ai

flutter pub add google_generative_ai

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

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

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

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

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

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

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

عندما تريد استخدام استدعاء الدالة مع نموذج، عليك تقديم تعريفات الدوالّ عند بدء عنصر النموذج. يمكنك تحديد الدوالّ من خلال ضبط المَعلمة tools للنموذج. تدعم Dart SDK أيضًا إعلان الدوال كوسيطات في generateContent أو واجهات برمجة تطبيقات generateContentStream.

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

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

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

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}