מדריך להפעלת פונקציות

הפעלת פונקציות מאפשרת לקבל פלט של נתונים מובְנים בקלות רבה יותר גנרטיביים. לאחר מכן תוכלו להשתמש בפלט הזה כדי לקרוא לממשקי API אחרים ולהחזיר את נתוני התגובה הרלוונטיים למודל. במילים אחרות, קריאה לפונקציות לחבר מודלים גנרטיביים למערכות חיצוניות, כדי שהתוכן שנוצר כוללת את המידע העדכני והמדויק ביותר.

אתם יכולים להוסיף למודלים של Gemini תיאורים של פונקציות. הנושאים האלה הפונקציות שכותבים בשפה של האפליקציה (כלומר, Google Cloud Functions). יכול להיות שהמודל יבקש מכם להפעיל פונקציה ולשלוח חזרה התוצאה כדי לעזור למודל לטפל בשאילתה.

אם עדיין לא עשיתם זאת, כדאי לעיין מבוא לקריאת פונקציות כדי ללמוד נוספים.

דוגמה לממשק API לבקרת תאורה

נניח שיש לכם מערכת בסיסית לבקרת תאורה עם תוכנת אפליקציה ממשק API ורוצים לאפשר למשתמשים לשלוט באורות באמצעות בקשות טקסט. אפשר להשתמש בתכונה 'קריאת פונקציות' כדי לפרש תאורה לשנות בקשות ממשתמשים ולתרגם אותן לקריאות ל-API כדי להגדיר את התאורה ערכים. המערכת ההיפותטית הזו לבקרת תאורה מאפשרת לכם לשלוט בהירות האור וטמפרטורת הצבע שלו, מוגדרות כשני :

פרמטר סוג נדרש תיאור
brightness number כן רמת האור מ-0 עד 100. אפס כבוי ו-100 מציג בהירות מלאה.
colorTemperature מחרוזת כן טמפרטורת הצבע של גוף התאורה יכולה להיות daylight, cool או warm.

כדי לשמור על פשטות, למערכת התאורה הדמיונית הזו יש רק אור אחד, כך שלמשתמש לא חייבת לציין חדר או מיקום. הנה דוגמה לבקשת JSON אפשר לשלוח לממשק ה-API של בקרת התאורה כדי לשנות את עוצמת התאורה ל-50% באמצעות טמפרטורת הצבע של אור היום:

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

במדריך הזה מוסבר איך להגדיר קריאת פונקציה ל-Gemini API כדי לפרש משתמשים אור בקשות ולמפות אותם להגדרות API כדי לשלוט את הבהירות ואת טמפרטורת הצבע של האור.

לפני שמתחילים: מגדירים את הפרויקט ואת מפתח ה-API

לפני הקריאה ל-Gemini API, צריך להגדיר את הפרויקט ולהגדיר במפתח ה-API.

הגדרה של פונקציית API

יוצרים פונקציה שיוצרת בקשת API. צריך להגדיר את הפונקציה הזו בתוך קוד האפליקציה, אך יכולה לקרוא לשירותים או לממשקי API מחוץ ל- את האפליקציה שלך. Gemini API לא קורא לפונקציה הזו ישירות, לכן אפשרות לקבוע איך ומתי הפונקציה הזו תופעל באמצעות האפליקציה לצורך הדגמה, המדריך הזה מגדיר פונקציית 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)
    }
}

יצירת הצהרות לגבי פונקציות

יוצרים את הצהרת הפונקציה שתעבירו למודל הגנרטיבי. מתי אתם מצהירים (declare) על פונקציה שהמודל משתמש בה, צריך לכלול כמה שיותר פרטים בתיאורי הפונקציות והפרמטרים, המודל הגנרטיבי משתמשת במידע הזה כדי לקבוע איזו פונקציה לבחור ואיך לספק של הפרמטרים בקריאה לפונקציה. הקוד הבא מראה איך מצהירים על פונקציית בקרת התאורה:

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