ฟีเจอร์ "ค้นหาข้อมูลเกี่ยวกับสถานที่ตั้งปัจจุบัน" พร้อมให้บริการแล้วใน Google Search ดูข้อมูลเพิ่มเติม

หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

ลองนึกภาพว่าคุณมีระบบควบคุมแสงพื้นฐานที่มีการเขียนโปรแกรมแอปพลิเคชัน อินเทอร์เฟซ (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 หากคุณยังไม่มี สร้างคีย์ใน Google AI Studio

รับคีย์ API

เราขอแนะนำอย่างยิ่งให้คุณไม่ตรวจสอบคีย์ API ในระบบควบคุมเวอร์ชัน

คุณควรจัดเก็บคีย์ API ในไฟล์ local.properties ที่อยู่ใน ไดเรกทอรีรากของโครงการ และยกเว้นไฟล์นี้จากการควบคุมเวอร์ชัน สําหรับการติดตั้งใช้งานในเวอร์ชันที่ใช้งานจริง ให้ใช้ปลั๊กอินข้อมูลลับ Gradle สําหรับ Android เพื่ออ่านคีย์ API เป็นตัวแปรการกําหนดค่าบิลด์

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

ข้อมูลโค้ดทั้งหมดในบทแนะนํานี้ใช้แนวทางปฏิบัติแนะนำนี้ นอกจากนี้ หากคุณ หากต้องการดูการใช้งานปลั๊กอิน Secrets Gradle คุณสามารถดู ตัวอย่างแอป สำหรับ SDK นี้ หรือใช้การแสดงตัวอย่างล่าสุดของ Android Studio ที่มี เทมเพลต Gemini API Starter (ซึ่งรวมถึงไฟล์ local.properties สำหรับใช้เริ่มต้น)

เพิ่มทรัพยากร Dependency ของ SDK ในโปรเจ็กต์ของคุณ

ในสภาพแวดล้อมการพัฒนาแอปพลิเคชันของคุณ ให้ทำดังนี้

ในไฟล์การกําหนดค่า Gradle ของโมดูล (ระดับแอปพลิเคชัน) ให้เพิ่มทรัพยากร Dependency สําหรับ Google AI SDK สําหรับ Android ดังนี้

Kotlin

// add to <project>/<app-module>/build.gradle.kts
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.0")
}

Java

// add to <project>/<app-module>/build.gradle
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.0")

  // Required for one-shot operations to use `ListenableFuture` from Guava Android
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations to use `Publisher` from Reactive Streams
  implementation("org.reactivestreams:reactive-streams:1.0.4")

}

ซิงค์โปรเจ็กต์ Android กับไฟล์ Gradle

กำหนดฟังก์ชัน 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-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)
}