บทแนะนำการเรียกใช้ฟังก์ชัน

การเรียกใช้ฟังก์ชันช่วยให้คุณรับเอาต์พุต Structured Data จากโมเดล Generative ได้ง่ายขึ้น จากนั้นคุณก็ใช้เอาต์พุตเหล่านี้เพื่อเรียก API อื่นๆ และส่งข้อมูลการตอบกลับที่เกี่ยวข้องกลับไปยังโมเดลได้ กล่าวคือ การเรียกใช้ฟังก์ชันจะช่วยคุณเชื่อมต่อโมเดล Generative กับระบบภายนอกเพื่อให้เนื้อหาที่สร้างขึ้นมีข้อมูลล่าสุดและถูกต้อง

คุณสามารถระบุคำอธิบายฟังก์ชันให้กับโมเดล Gemini ได้ ฟังก์ชันเหล่านี้คือฟังก์ชันที่คุณเขียนในภาษาของแอป (ไม่ใช่ Google Cloud Functions) โมเดลอาจขอให้คุณเรียกใช้ฟังก์ชันและส่งผลลัพธ์กลับเพื่อช่วยโมเดลจัดการการค้นหาของคุณ

หากยังไม่ได้อ่าน โปรดดูข้อมูลเบื้องต้นเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อดูข้อมูลเพิ่มเติม

ตัวอย่าง API สำหรับการควบคุมแสง

สมมติว่าคุณมีระบบควบคุมแสงพื้นฐานที่มี Application Programming Interface (API) และต้องการอนุญาตให้ผู้ใช้ควบคุมไฟผ่านคำขอข้อความง่ายๆ คุณสามารถใช้ฟีเจอร์การเรียกฟังก์ชันเพื่อตีความคําขอเปลี่ยนแปลงแสงจากผู้ใช้และแปลเป็นคําเรียก API เพื่อตั้งค่าแสงได้ ระบบควบคุมแสงสมมตินี้ช่วยให้คุณควบคุมความสว่างของแสงและอุณหภูมิสีของแสงได้ ซึ่งกำหนดเป็น 2 พารามิเตอร์แยกกัน ดังนี้

พารามิเตอร์ ประเภท ต้องระบุ คำอธิบาย
brightness ตัวเลข ใช่ ระดับแสงจาก 0 ถึง 100 0 คือปิดและ 100 คือความสว่างเต็มที่
colorTemperature สตริง ใช่ อุณหภูมิสีของอุปกรณ์ให้แสงสว่าง ซึ่งอาจเป็น daylight, cool หรือ warm

ระบบแสงสว่างสมมตินี้จะมีเพียงหลอดไฟเดียวเพื่อความง่ายดาย ผู้ใช้จึงไม่ต้องระบุห้องหรือตำแหน่ง ต่อไปนี้คือตัวอย่างคําขอ JSON ที่คุณสามารถส่งไปยัง API การควบคุมแสงเพื่อเปลี่ยนระดับแสงเป็น 50% โดยใช้อุณหภูมิสีของแสงแดด

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

บทแนะนำนี้จะแสดงวิธีตั้งค่าการเรียกฟังก์ชันสําหรับ Gemini API เพื่อตีความคําขอแสงของผู้ใช้และจับคู่กับการตั้งค่า API เพื่อควบคุมค่าความสว่างและอุณหภูมิสีของแสง

ก่อนเริ่มต้น: ตั้งค่าโปรเจ็กต์และคีย์ API

คุณต้องตั้งค่าโปรเจ็กต์และกำหนดค่าคีย์ API ก่อนเรียกใช้ Gemini 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)
    }
}

สร้างประกาศฟังก์ชัน

สร้างการประกาศฟังก์ชันที่จะส่งไปยังโมเดล Generative เมื่อประกาศฟังก์ชันให้โมเดลใช้ คุณควรระบุรายละเอียดให้มากที่สุดในคำอธิบายฟังก์ชันและพารามิเตอร์ โมเดล Generative ใช้ข้อมูลนี้เพื่อพิจารณาว่าควรเลือกฟังก์ชันใดและวิธีระบุค่าสำหรับพารามิเตอร์ในการเรียกใช้ฟังก์ชัน โค้ดต่อไปนี้แสดงวิธีประกาศฟังก์ชันการควบคุมแสง

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