ফাংশন কলিং ব্যবহার করা

ML Kit-এর ডাইরেক্ট মডেল অ্যাক্সেসের মাধ্যমে, আপনি ফাংশন কলিং ব্যবহার করে Gemini Nano মডেলকে প্লেন টেক্সট উত্তরের পরিবর্তে স্ট্রাকচার্ড ফাংশন এক্সিকিউশন অনুরোধ (টুল কল) আউটপুট করার জন্য সক্ষম করতে পারেন। ফাংশন কলিং আপনাকে অন-ডিভাইস জেনারেটিভ AI মডেলকে এক্সটার্নাল টুল, API এবং লোকাল অ্যাপ ফিচারের সাথে কানেক্ট করতে দেয়।

মূল ক্ষমতা

ফাংশন কলিং নিম্নলিখিত মূল কার্যকারিতা প্রদান করে:

  • সিঙ্গেল-টার্ন ফাংশন কলিং: Gemini Nano এক বা একাধিক টুল কল (FunctionCall) অনুমান করে, আপনার অ্যাপ স্থানীয়ভাবে ফাংশনগুলি এক্সিকিউট করে এবং ফলো-আপ মডেল রেসপন্সের প্রয়োজন ছাড়াই ফ্লো সম্পূর্ণ হয়।
  • মাল্টি-টার্ন ফাংশন কলিং: Gemini Nano এক বা একাধিক টুল কল (FunctionCall) অনুমান করে, আপনার অ্যাপ স্থানীয়ভাবে ফাংশনগুলি এক্সিকিউট করে এবং আরও টুল কল বা চূড়ান্ত সিন্থেসাইজ করা টেক্সট রেসপন্স ফিরিয়ে আনতে ফলাফলগুলি (FunctionResponsePart) ফেরত পাঠায়।

ফাংশন কলিং প্রয়োগ করার সময়, আপনি নিম্নলিখিত সুবিধা নিতে পারেন:

  • প্রোগ্রাম্যাটিক টুল ডেফিনিশন: ML Kit GenAI Schema API (com.google.mlkit:genai-schema) ব্যবহার করে রানটাইমে ডাইনামিক FunctionDeclaration এবং FunctionSchema টুল ডেফিনিশন তৈরি করুন।
  • স্ট্রাকচার্ড আর্গুমেন্ট পার্সিং: আপনার লোকাল অ্যাপ লজিক এক্সিকিউট করার জন্য মডেল রেসপন্স ক্যান্ডিডেট থেকে সরাসরি স্ট্রংলি টাইপড আর্গুমেন্ট ভ্যালু পান।

ফলাফলের উদাহরণ

ফাংশন কলিং সিঙ্গেল-টার্ন ও মাল্টি-টার্ন ফ্লো, দুটিতেই কাজ করে। উভয় ক্ষেত্রেই, মডেলটি ফাংশনের নাম এবং আর্গুমেন্ট সহ এক বা একাধিক টুল কল পূর্বাভাস দেয়। মাল্টি-টার্ন ফ্লোয়ের ক্ষেত্রে, অ্যাপের এক্সিকিউশন ফলাফল পাওয়ার পরে, অ্যাপটি মডেলের কাছে সম্পূর্ণ কথোপকথনের ইতিহাস সহ আরেকটি অনুরোধ পাঠাতে পারে যাতে ব্যবহারকারীর জন্য আরও টুল কল বা চূড়ান্ত টেক্সট উত্তর পাওয়া যায়।

এক্সিকিউশন ফ্লো ব্যবহারকারীর প্রম্পট মডেল আউটপুট
সিঙ্গেল-টার্ন "বসার ঘরের লাইট ৮০% উজ্জ্বলতায় চালু করো।" টুল কল:
turn_on_light(room="living room", brightness=80)
সিঙ্গেল-টার্ন "ক্যামেরা অ্যাপ খুলুন।" টুল কল:
open_app(appName="Camera")
মাল্টি-টার্ন "সেলসিয়াসে সান ফ্রান্সিসকোর আবহাওয়া কেমন?" ইন্টারমিডিয়েট টুল কল:
get_current_weather(location="San Francisco, CA", unit="celsius")

ব্যবহারকারীকে দেখানো ফাইনাল মডেল আউটপুট:
In SF it's currently 25 degrees Celsius.

পূর্বশর্ত

ফাংশন কলিং ব্যবহার করতে, আপনার ডিভাইস ও অ্যাকাউন্টকে নিম্নলিখিত শর্তাবলী পূরণ করতে হবে:

আপনি এইসব প্রয়োজনীয়তা পূরণ করেছেন কিনা তা চেক করতে, AICore অ্যাপে Gemini Nano 4 Fast মডেল উপলভ্য কিনা তা চেক করুন: AICore অ্যাপ খুলে, মডেল বেছে নিন ড্রপডাউনে ক্লিক করুন এবং Gemini Nano 4 Fast তালিকাভুক্ত আছে কিনা তা চেক করুন। মডেলটি সেখানে না থাকলে, ডিভাইস সাপোর্ট বা অ্যাকাউন্ট এনরোলমেন্টে সমস্যা আছে এবং ফাংশন কলিং কাজ করবে না।

এছাড়াও, আপনার প্রোজেক্টকে নিম্নলিখিত প্রয়োজনীয়তাগুলি পূরণ করতে হবে:

  • Kotlin ভার্সন 2.3.0 বা তার পরের যেকোনও ভার্সন
  • ন্যূনতম SDK (minSdk) ভার্সন ২৬ বা তার পরবর্তী ভার্সন

শুরু করুন

ফাংশন কলিং ব্যবহার শুরু করার ধাপগুলি এখানে দেওয়া হল।

  1. আপনার প্রোজেক্ট-লেভেল settings.gradle.kts (বা settings.gradle) ফাইলে, repositories {} ব্লকে mavenCentral() যোগ করুন।

    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

  2. আপনার মডিউল-লেভেল build.gradle.kts (বা build.gradle ফাইল)-এ, ML Kit Prompt API এবং স্কিমা ডিপেন্ডেন্সি যোগ করুন:

    Kotlin

    plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

dependencies {
    // ML Kit GenAI Prompt and Schema SDKs
    implementation("com.google.mlkit:genai-prompt:1.0.0-beta5")
    implementation("com.google.mlkit:genai-schema:1.0.0-alpha2")
}

    Groovy

    plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

dependencies {
    // ML Kit GenAI Prompt and Schema SDKs
    implementation 'com.google.mlkit:genai-prompt:1.0.0-beta5'
    implementation 'com.google.mlkit:genai-schema:1.0.0-alpha2'
}

  3. আপনার মডিউল-লেভেল build.gradle (বা build.gradle.kts ফাইল)-এ, minSdk ভার্সন 26 বা তার পরবর্তী ভার্সনে সেট করুন।

    Kotlin

    android {
    defaultConfig {
        // ...
        minSdk = 26
        // ...
    }
}

    Groovy

    android {
    defaultConfig {
        // ...
        minSdk 26
        // ...
    }
}

কীভাবে ফাংশন কলিং API ব্যবহার করতে হয়

ফাংশন কলিং প্রয়োগ করতে, নিম্নলিখিত ধাপগুলি অনুসরণ করুন:

  1. আপনার টুল নির্ধারণ করুন।
  2. মডেল বেছে নিন।
  3. আপনার অনুরোধে টুল অ্যাটাচ করুন।
  4. টুল কল (সিঙ্গেল-টার্ন বা মাল্টি-টার্ন) ম্যানেজ করা।

পরবর্তী বিভাগে একটি উদাহরণের মাধ্যমে এই ধাপগুলি দেখানো হয়েছে।

আপনার টুল নির্ধারণ করুন

com.google.mlkit.genai.schema.tools প্যাকেজ থেকে FunctionDeclaration, FunctionSchema এবং FunctionType ব্যবহার করে প্রোগ্রাম্যাটিক্যালি টুল স্কিমা তৈরি করুন। (অটোমেটিক এক্সিকিউশন সহ Android-এর @AppFunction অ্যানোটেশন ব্যবহার করে কম্পাইল করার সময় ডিক্লেরেটিভভাবে টুল সংজ্ঞায়িত করতে, টুল সংজ্ঞায়িত করুন দেখুন।)

যেমন, আপনি অ্যাকশন-ভিত্তিক টুল (যেমন, একবার এক্সিকিউট করার জন্য স্মার্ট লাইট চালু করা) সংজ্ঞায়িত করতে পারেন:

import com.google.mlkit.genai.schema.tools.FunctionDeclaration
import com.google.mlkit.genai.schema.tools.FunctionSchema
import com.google.mlkit.genai.schema.tools.FunctionType

val turnOnLightTool = FunctionDeclaration(
    name = "turn_on_light",
    description = "Turn on the lights in a room and set the brightness",
    parameters = FunctionSchema(
        type = FunctionType.OBJECT,
        properties = mapOf(
            "room" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The room name"
            ),
            "brightness" to FunctionSchema(
                type = FunctionType.INTEGER,
                description = "Brightness level from 0 to 100"
            )
        ),
        required = listOf("room")
    )
)

অথবা ডেটা-রিট্রিভাল টুল (যেমন, মাল্টি-টার্ন সিন্থেসিসের জন্য বর্তমান আবহাওয়ার তথ্য নিয়ে আসা) সংজ্ঞায়িত করুন:

import com.google.mlkit.genai.schema.tools.FunctionDeclaration
import com.google.mlkit.genai.schema.tools.FunctionSchema
import com.google.mlkit.genai.schema.tools.FunctionType

val getWeatherTool = FunctionDeclaration(
    name = "get_current_weather",
    description = "Get the current weather for a location",
    parameters = FunctionSchema(
        type = FunctionType.OBJECT,
        properties = mapOf(
            "location" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The city and state, e.g. San Francisco, CA"
            ),
            "unit" to FunctionSchema(
                type = FunctionType.STRING,
                description = "The temperature unit, either 'celsius' or 'fahrenheit'"
            )
        ),
        required = listOf("location")
    )
)

মডেল বেছে নিন

ফাংশন কলিংয়ের জন্য Gemini Nano 4 প্রয়োজন। Gemini Nano 4 অ্যাক্সেস করতে, মডেল বেছে নেওয়ার API ব্যবহার করে আপনার GenerativeModel ইনস্ট্যান্স কনফিগার করুন যাতে ModelReleaseStage.PREVIEW এবং ModelPreference.FAST টার্গেট করা যায়।

import com.google.mlkit.genai.prompt.Generation
import com.google.mlkit.genai.prompt.ModelPreference
import com.google.mlkit.genai.prompt.ModelReleaseStage
import com.google.mlkit.genai.prompt.generationConfig
import com.google.mlkit.genai.prompt.modelConfig

// Target the preview fast model (Gemini Nano 4)
val config = generationConfig {
    modelConfig = modelConfig {
        releaseStage = ModelReleaseStage.PREVIEW
        preference = ModelPreference.FAST
    }
}
val generativeModel = Generation.getClient(config)

আপনার অনুরোধে টুল অ্যাটাচ করুন

GenerateContentRequest অবজেক্ট তৈরি করার সময়, রিকোয়েস্ট বিল্ডারে আপনার FunctionDeclaration তালিকা setTools()-এ পাস করুন।

যেমন, সিস্টেম নির্দেশের সাথে সিঙ্গেল-টার্ন অ্যাকশন অনুরোধের জন্য টুল অ্যাটাচ করতে:

import com.google.mlkit.genai.prompt.SystemInstruction
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.generateContentRequest

val requestText = "Turn on the living room lights and set brightness to 50"

val request = generateContentRequest(
    SystemInstruction("You are a helpful home automation assistant."),
    TextPart(requestText)
) {
    // Attach the FunctionDeclaration tool schemas
    setTools(listOf(turnOnLightTool))
    temperature = 0.2f
}

// Run non-streaming inference
val response = generativeModel.generateContent(request)

অথবা মাল্টি-টার্ন কোয়েরির জন্য আপনার FunctionDeclaration তালিকা অ্যাটাচ করতে:

import com.google.mlkit.genai.prompt.SystemInstruction
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.generateContentRequest

val availableTools = listOf(getWeatherTool)

// Use the generateContentRequest DSL
val request = generateContentRequest(
    TextPart("What is the weather in San Francisco, CA in celsius?")
) {
    setTools(availableTools)
}
val response = generativeModel.generateContent(request)

টুল কল ম্যানেজ করা

Gemini Nano কোনও টুল ইনভোক করার সিদ্ধান্ত নিলে, মডেলের রেসপন্স ক্যান্ডিডেটে candidate.functionCalls-এ এক বা একাধিক FunctionCall অবজেক্ট থাকে। টুল কল ম্যানেজ করতে, আপনার অ্যাপকে প্রথমে রেসপন্স ক্যান্ডিডেট পরীক্ষা করে দেখতে হবে যে কোনও টুল কল প্রেডিক্ট করা হয়েছে কিনা:

import com.google.mlkit.genai.common.FunctionArgValue
import com.google.mlkit.genai.prompt.Content
import com.google.mlkit.genai.prompt.FunctionCallPart
import com.google.mlkit.genai.prompt.FunctionResponsePart
import com.google.mlkit.genai.prompt.GenerateContentRequest
import com.google.mlkit.genai.prompt.TextPart
import com.google.mlkit.genai.prompt.content

val candidate = response.candidates.firstOrNull()
val functionCalls = candidate?.functionCalls ?: emptyList()

if (functionCalls.isNotEmpty()) {
    // Process tool calls using either the single-turn or multi-turn flow
    // described in the following sections
}

সিঙ্গেল-টার্ন ফাংশন কলিং

অ্যাকশন-ভিত্তিক টাস্কের জন্য সিঙ্গেল-টার্ন ফাংশন কলিং ব্যবহার করুন যেখানে অ্যাপ সরাসরি অনুরোধ পূরণ করে (যেমন, "ক্যামেরা অ্যাপ খোলো" বা "বসার ঘরের লাইট জ্বালাও")। আপনার অ্যাপ স্থানীয়ভাবে ফাংশনটি এক্সিকিউট করলে, ফ্লো সম্পূর্ণ হয়; ফলো-আপ মডেলের উত্তরের প্রয়োজন হয় না।

for (functionCall in functionCalls) {
    val name = functionCall.name
    val args = functionCall.arguments // Map<String, FunctionArgValue>

    when (name) {
        "open_app" -> {
            val appName = (args["appName"] as? FunctionArgValue.StringValue)?.value
            launchApp(appName)
        }
        "turn_on_light" -> {
            val room = (args["room"] as? FunctionArgValue.StringValue)?.value
            val brightness = (args["brightness"] as? FunctionArgValue.IntValue)?.value ?: 100
            setLightState(room, brightness)
        }
        else -> Log.w(TAG, "Unhandled tool call: $name")
    }
}

মাল্টি-টার্ন ফাংশন কলিং

ব্যবহারকারী যখন টুলের মাধ্যমে রিট্রিভ করা ডেটার উপর ভিত্তি করে ন্যাচারাল ল্যাঙ্গুয়েজে উত্তর আশা করেন, তখন মাল্টি-টার্ন ফাংশন কলিং ব্যবহার করুন (যেমন, "সান ফ্রান্সিসকোতে আবহাওয়া কেমন?")।

মাল্টি-টার্ন ফ্লোতে, আপনার অ্যাপ নিম্নলিখিত কাজগুলি করে:

  1. অনুরোধ করা ফাংশন লোকালি এক্সিকিউট করে।
  2. FunctionResponsePart অবজেক্টে ফলাফল প্যাকেজ করে।
  3. কথোপকথনের ইতিহাসে মডেলের কল (MODEL ভূমিকা) এবং আপনার এক্সিকিউশন ফলাফল (USER ভূমিকা) উভয়ই যোগ করে।
  4. চূড়ান্ত ন্যাচারাল ল্যাঙ্গুয়েজ উত্তর সিন্থেসাইজ করার জন্য Gemini Nano-তে ফলো-আপ অনুরোধ পাঠায়।
// 1. Execute each predicted tool call and collect results
val responseParts = mutableListOf<FunctionResponsePart>()

for (functionCall in functionCalls) {
    val responsePart: FunctionResponsePart = when {
        functionCall.name == "get_current_weather" -> {
            val location = (functionCall.arguments["location"] as? FunctionArgValue.StringValue)?.value ?: ""
            val unit = (functionCall.arguments["unit"] as? FunctionArgValue.StringValue)?.value ?: "celsius"

            val weatherData = fetchWeather(location, unit) // Local network/API call

            // Package the tool execution result as a key-value map
            FunctionResponsePart(
                id = functionCall.id,
                name = functionCall.name,
                response = mapOf("result" to weatherData)
            )
        }

        else -> throw IllegalArgumentException("Unknown tool: ${functionCall.name}")
    }
    responseParts.add(responsePart)
}

// 2. Append turns to conversation history to construct the multi-turn context
val history = request.contents.toMutableList().apply {
    // Turn 1: Model's request containing the predicted FunctionCallPart object
    add(
        content(Content.Role.MODEL) {
            for (call in functionCalls) {
                addPart(FunctionCallPart(call))
            }
        }
    )
    // Turn 2: User's response containing the executed FunctionResponsePart object
    add(
        content(Content.Role.USER) {
            for (responsePart in responseParts) {
                addPart(responsePart)
            }
        }
    )
}

// 3. Send the updated history back to Gemini Nano for final text synthesis
val followUpRequest = GenerateContentRequest.Builder(history)
    .setTools(availableTools) // Include tools in case the model requires subsequent tool calls
    .build()

val finalResponse = generativeModel.generateContent(followUpRequest)
val answer = finalResponse.candidates.firstOrNull()?.text

Log.d(TAG, "Final Model Response: $answer")

নমুনা কোড

Android অ্যাপে ফাংশন কলিংয়ের সম্পূর্ণ কার্যকরী উদাহরণ দেখতে, এই ML Kit স্যাম্পেল অ্যাপ দেখুন।

পরিচিত সমস্যা

  • সরাসরি মডেল অ্যাক্সেসে AndroidX AppFunctions (@AppFunction) (genai-prompt): Prompt API-এর (com.google.mlkit:genai-prompt:1.0.0-beta5) মাধ্যমে সরাসরি কম্পাইল-টাইম @AppFunction টুল খুঁজে বের করা ও এক্সিকিউট করার সুবিধা এখনও উপলভ্য নয়; genai-prompt লাইব্রেরিতে থাকা টুল অবশ্যই FunctionDeclaration ক্লাস ব্যবহার করে প্রোগ্রাম্যাটিক্যালি সংজ্ঞায়িত করতে হবে। আজ @AppFunction টুল ব্যবহার করতে, এজেন্টিক ওয়ার্কফ্লো (com.google.mlkit:genai-agent) ব্যবহার করুন।
  • স্ট্রিমিং অনুরোধ (generateContentStream) ব্যবহার করার সময়, টুল কল টোকেন-বাই-টোকেন স্ট্রিম করা হয় না। পরিবর্তে, মডেলটি টুল কল জেনারেট করা শেষ করলে, সম্পূর্ণ FunctionCall অবজেক্ট এমিট করা হয় (StreamingCallback.onNewFunctionCall-এর মাধ্যমে বা চূড়ান্ত স্ট্রিম করা GenerateContentResponse.candidates[0].functionCalls-এ)।