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

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

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

يمكنك الاطّلاع على مقالة مقدّمة حول استدعاء الدوالّ للتعرّف على مزيد من المعلومات، إذا لم يسبق لك ذلك. يمكنك أيضًا اختبار هذه الميزة في Google Colab أو الاطّلاع على مثال على الرمز البرمجي في مستودع Gemini API Cookbook.

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

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

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

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

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

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

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

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

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

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

def set_light_values(brightness, color_temp):
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

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

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

عندما تريد استخدام استدعاء الدالة مع نموذج، يجب تعريف وظائفك عند بدء عنصر النموذج. يمكنك الإعلان عن الدوال من خلال ضبط معلمة tools للنموذج:

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

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

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

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

يسهّل عنصر ChatSession في حزمة تطوير البرامج (SDK) لبرنامج Python إدارة جلسات المحادثة من خلال معالجة سجلّ المحادثة نيابةً عنك. يمكنك استخدام "enable_automatic_function_calling" للحصول على حزمة تطوير البرامج (SDK). لاستدعاء الدالة تلقائيًا.

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

استدعاء الدوالّ بشكلٍ موازٍ

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

حدِّد الأدوات.

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool, bpm: int) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

الآن، يمكنك استدعاء النموذج باستخدام تعليمات يمكنها استخدام جميع الأدوات المحدّدة.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
        print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True, bpm=120.0)
dim_lights(brightness=0.3)

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

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

ربط أنواع البيانات لاستدعاء الدوالّ

لا تعمل عملية استخراج المخطّط التلقائية من وظائف Python في جميع الحالات. على سبيل المثال: لا تتعامل واجهة برمجة التطبيقات مع الحالات التي تصف فيها حقول كائن قاموس-مدمج، غير أنّ واجهة برمجة التطبيقات تتيح ذلك. ويمكن لواجهة برمجة التطبيقات وصف أي من الأنواع التالية:

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

توفّر مكتبة العميل google.ai.generativelanguage إمكانية الوصول إلى الأنواع المنخفضة المستوى، ما يمنحك التحكّم الكامل.

ألقِ نظرة أولاً على سمة _tools للنموذج، يمكنك التعرّف على كيفية وصفها للدوال التي مررتها إلى النموذج:

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

يؤدي ذلك إلى عرض قائمة عناصر genai.protos.Tool التي سيتم إرسالها إلى واجهة برمجة التطبيقات. إذا لم يكن التنسيق المطبوع مألوفًا، فالغرض من ذلك هو Google دورات أولية. يحتوي كل genai.protos.Tool (1 في هذه الحالة) على قائمة بعلامات genai.protos.FunctionDeclarations التي تصف دالة و مَعلماتها.

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

calculator = genai.protos.Tool(
    function_declarations=[
      genai.protos.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=genai.protos.Schema(
            type=genai.protos.Type.OBJECT,
            properties={
                'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
                'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

يمكنك وصف ذلك أيضًا ككائن متوافق مع JSON:

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

genai.protos.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

وفي كلتا الحالتين، يمكنك تمرير تمثيل لـ genai.protos.Tool أو قائمة من الأدوات إلى

model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

وكما هو الحال قبل أن يعرض النموذج genai.protos.FunctionCall لاستدعاء دالة multiply في الآلة الحاسبة:

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

نفذ الدالة بنفسك:

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

يمكنك إرسال النتيجة إلى النموذج لمتابعة المحادثة:

response = chat.send_message(
    genai.protos.Content(
    parts=[genai.protos.Part(
        function_response = genai.protos.FunctionResponse(
          name='multiply',
          response={'result': result}))]))