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

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

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

अगर आपने अब तक इस सुविधा का इस्तेमाल नहीं किया है, तो ज़्यादा जानने के लिए, फ़ंक्शन कॉलिंग के बारे में जानकारी देखें.

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

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

पैरामीटर टाइप ज़रूरी है कंपनी का ब्यौरा
brightness नंबर हां रोशनी का स्तर 0 से 100 तक. 'शून्य' सेटिंग बंद है और '100' मोड में पूरी स्क्रीन की रोशनी है.
colorTemperature स्ट्रिंग हां लाइट फ़िक्स्चर का कलर टेंपरेचर, जो daylight, cool या warm हो सकता है.

सादगी के लिए, इस काल्पनिक लाइटिंग सिस्टम में सिर्फ़ एक लाइट होती है, इसलिए उपयोगकर्ता को कमरे या जगह की जानकारी देने की ज़रूरत नहीं होती. यहां JSON अनुरोध का एक उदाहरण दिया गया है. आप डेलाइट कलर टेंपरेचर का इस्तेमाल करके लाइट लेवल को 50% में बदलने के लिए, लाइटिंग कंट्रोल एपीआई को भेज सकते हैं:

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

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

शुरू करने से पहले: अपना प्रोजेक्ट और एपीआई पासकोड सेट अप करें

Gemini API को कॉल करने से पहले, आपको अपना प्रोजेक्ट सेट अप करना होगा और एपीआई पासकोड कॉन्फ़िगर करना होगा.

एपीआई फ़ंक्शन तय करना

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

suspend fun setLightValues(
    brightness: Int,
    colorTemp: String
): JSONObject {
    // This mock API returns the requested lighting values
    return JSONObject().apply {
        put("brightness", brightness)
        put("colorTemperature", colorTemp)
    }
}

फ़ंक्शन का एलान करें

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

val lightControlTool = defineFunction(
  name = "setLightValues",
  description = "Set the brightness and color temperature of a room light.",
  Schema.int("brightness", "Light level from 0 to 100. Zero is off and 100" +
    " is full brightness."),
  Schema.str("colorTemperature", "Color temperature of the light fixture" +
    " which can be `daylight`, `cool` or `warm`.")
) { brightness, colorTemp ->
    // Call the function you declared above
    setLightValues(brightness.toInt(), colorTemp)
}

मॉडल शुरू करने के दौरान, फ़ंक्शन बताएं

जब आपको किसी मॉडल के साथ फ़ंक्शन कॉलिंग का इस्तेमाल करना हो, तो मॉडल ऑब्जेक्ट को शुरू करते समय, आपको फ़ंक्शन का एलान करना होगा. मॉडल के tools पैरामीटर को सेट करके, फ़ंक्शन का एलान किया जाता है:

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",

    // Access your API key as a Build Configuration variable
    apiKey = BuildConfig.apiKey,

    // Specify the function declaration.
    tools = listOf(Tool(listOf(lightControlTool)))
)

फ़ंक्शन कॉल जनरेट करें

अपने फ़ंक्शन के एलान के साथ मॉडल शुरू करने के बाद, तय किए गए फ़ंक्शन के साथ मॉडल को प्रॉम्प्ट दिया जा सकता है. आपको चैट प्रॉम्प्ट (sendMessage()) का इस्तेमाल करके, फ़ंक्शन कॉलिंग का इस्तेमाल करना चाहिए. इसकी वजह यह है कि फ़ंक्शन कॉलिंग को आम तौर पर पिछले प्रॉम्प्ट और रिस्पॉन्स के कॉन्टेक्स्ट के आधार पर फ़ायदा मिलता है.

val chat = generativeModel.startChat()

val prompt = "Dim the lights so the room feels cozy and warm."

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

// Check if the model responded with a function call
response.functionCall?.let { functionCall ->
  // Try to retrieve the stored lambda from the model's tools and
  // throw an exception if the returned function was not declared
  val matchedFunction = generativeModel.tools?.flatMap { it.functionDeclarations }
      ?.first { it.name == functionCall.name }
      ?: throw InvalidStateException("Function not found: ${functionCall.name}")

  // Call the lambda retrieved above
  val apiResponse: JSONObject = matchedFunction.execute(functionCall)

  // Send the API response back to the generative model
  // so that it generates a text response that can be displayed to the user
  response = chat.sendMessage(
    content(role = "function") {
        part(FunctionResponsePart(functionCall.name, apiResponse))
    }
  )
}

// Whenever the model responds with text, show it in the UI
response.text?.let { modelResponse ->
    println(modelResponse)
}