फ़ंक्शन कॉलिंग का ट्यूटोरियल

फ़ंक्शन कॉलिंग की मदद से, स्ट्रक्चर्ड डेटा के आउटपुट आसानी से हासिल किए जा सकते हैं जनरेटिव मॉडल. इसके बाद, इन आउटपुट का इस्तेमाल करके अन्य एपीआई को कॉल किया जा सकता है और मॉडल को काम का रिस्पॉन्स डेटा दिखाया जा सकता है. दूसरे शब्दों में, फ़ंक्शन कॉलिंग मदद करता है आप जनरेटिव मॉडल को बाहरी सिस्टम से जोड़ते हैं. इससे, जनरेट किया गया कॉन्टेंट में अप-टू-डेट और सटीक जानकारी होती है.

Gemini के मॉडल के हिसाब से, उनके काम करने के तरीक़े की जानकारी दी जा सकती है. ये ऐसे फ़ंक्शन होते हैं जिन्हें आप अपने ऐप्लिकेशन की भाषा में लिखते हैं. इसका मतलब है कि ये Google Cloud फ़ंक्शन नहीं होते. मॉडल, आपकी क्वेरी को मैनेज करने में मदद करने के लिए, आपसे किसी फ़ंक्शन को कॉल करने और नतीजा भेजने के लिए कह सकता है.

अगर आपने अब तक ऐसा नहीं किया है, तो इसे देखें सीखने के लिए, फ़ंक्शन कॉलिंग के बारे में जानकारी ज़्यादा. आप यह भी कर सकते हैं इस सुविधा को आज़माएँ Google Colab या उदाहरण कोड यहां देखें: Gemini API कुकबुक का डेटा स्टोर करने की जगह.

लाइटिंग कंट्रोल के लिए एपीआई का उदाहरण

मान लें कि आपके पास एक बेसिक लाइटिंग सिस्टम है, जो किसी ऐप्लिकेशन प्रोग्रामिंग के साथ काम करता है का इंटरफ़ेस (API) है और आप उपयोगकर्ताओं को आसान तरीके से लाइटों को नियंत्रित करने की अनुमति देना चाहते हैं टेक्स्ट अनुरोध. फ़ंक्शन कॉलिंग की सुविधा का इस्तेमाल करके, उपयोगकर्ताओं से मिले लाइटिंग में बदलाव करने के अनुरोधों को समझा जा सकता है. साथ ही, लाइटिंग की वैल्यू सेट करने के लिए, उन्हें एपीआई कॉल में बदला जा सकता है. इस काल्पनिक लाइटिंग सिस्टम की मदद से, आपको लाइट की चमक और उसका कलर टेंपरेचर, जिन्हें दो अलग-अलग तरीकों से दिखाया गया है पैरामीटर:

पैरामीटर टाइप ज़रूरी है ब्यौरा
brightness संख्या हां लाइट का लेवल 0 से 100 तक होता है. शून्य का मतलब है कि रोशनी बंद है और 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

Python SDK टूल ChatSession यह ऑब्जेक्ट, बातचीत के इतिहास को हैंडल करके चैट सेशन को मैनेज करना आसान बनाता है आपके लिए. SDK टूल को फ़ंक्शन को अपने-आप कॉल करने के लिए, enable_automatic_function_calling का इस्तेमाल किया जा सकता है.

# 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 ?",
)

जैसा कि मॉडल, कैलकुलेटर के multiply फ़ंक्शन को शुरू करने के लिए, genai.protos.FunctionCall दिखाता है:

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}))]))