บทแนะนำ: การเรียกฟังก์ชันด้วย Gemini API

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

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

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

ตั้งค่าโปรเจ็กต์

ก่อนที่จะเรียกใช้ Gemini API คุณต้องตั้งค่าโปรเจ็กต์ Android ก่อน ซึ่งรวมถึงการตั้งค่าคีย์ API การเพิ่มทรัพยากร Dependency ของ SDK ลงในโปรเจ็กต์ Android และการเริ่มต้นโมเดล

ตั้งค่าและรักษาความปลอดภัยของคีย์ API

หากต้องการใช้ Gemini API คุณจะต้องมีคีย์ API หากยังไม่มี ให้ สร้างคีย์ใน Google AI Studio

รับคีย์ API

รักษาความปลอดภัยของคีย์ API

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

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

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

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

ในโมดูล (ระดับแอป) ไฟล์การกำหนดค่า Gradle (เช่น <project>/<app-module>/build.gradle.kts) ให้เพิ่มทรัพยากร Dependency สำหรับ Google AI SDK สำหรับ Android ดังนี้
```
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.5.0")
}
```
ซิงค์โปรเจ็กต์ Android กับไฟล์ Gradle

เริ่มต้นโมเดล Generative

ก่อนที่จะเรียก API คุณต้องเริ่มต้นออบเจ็กต์ GenerativeModel ก่อน นี่คือการเริ่มต้นแบบพื้นฐาน จากนั้นในบทแนะนำนี้ คุณจะอัปเดตการกำหนดค่าสำหรับการเรียกใช้ฟังก์ชัน

val generativeModel = GenerativeModel(

    // Use a model that supports function calling, like Gemini 1.0 Pro.
    // See "Supported models" in the "Introduction to function calling" page.
    modelName = "MODEL_NAME",

    // Access your API key as a Build Configuration variable (see "Set up your API key" above).
    apiKey = BuildConfig.apiKey
)

ตั้งค่าการเรียกใช้ฟังก์ชัน

สำหรับบทแนะนำนี้ คุณจะให้โมเดลโต้ตอบกับ API การแลกเปลี่ยนสกุลเงินสมมติที่รองรับพารามิเตอร์ต่อไปนี้

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`currencyFrom`	string	ใช่	สกุลเงินที่จะแปลง
`currencyTo`	string	ใช่	สกุลเงินที่จะแปลง

ตัวอย่างคำขอ API

{
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

ตัวอย่างการตอบกลับจาก API

{
  "base": "USD",
  "rates": {"SEK": 0.091}
}

ขั้นตอนที่ 1: สร้างฟังก์ชันที่ส่งคำขอ API

หากยังไม่ได้สร้าง ให้เริ่มด้วยการสร้างฟังก์ชันที่ส่งคำขอ API

เพื่อจุดประสงค์ในการสาธิตในบทแนะนำนี้ คุณจะส่งคืนค่าแบบฮาร์ดโค้ดในรูปแบบเดียวกับที่ API จริงจะแสดง แทนการส่งคำขอ API จริง

suspend fun makeApiRequest(
    currencyFrom: String,
    currencyTo: String
): JSONObject {
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","rates":{"SEK": 0.091}}
    return JSONObject().apply {
        put("base", currencyFrom)
        put("rates", hashMapOf(currencyTo to 0.091))
    }
}

ขั้นตอนที่ 2: สร้างการประกาศฟังก์ชัน

สร้างการประกาศฟังก์ชันที่คุณจะส่งไปยังโมเดล Generative (ขั้นตอนถัดไปของบทแนะนำนี้)

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

val getExchangeRate = defineFunction(
  name = "getExchangeRate",
  description = "Get the exchange rate for currencies between countries",
  Schema.str("currencyFrom", "The currency to convert from."),
  Schema.str("currencyTo", "The currency to convert to.")
) { from, to ->
    // Call the function that you declared above
    makeApiRequest(from, to)
}

ขั้นตอนที่ 3: ระบุการประกาศฟังก์ชันระหว่างการเริ่มต้นโมเดล

ระบุการประกาศฟังก์ชันเมื่อเริ่มต้นโมเดล Generative โดยส่งไปยังพารามิเตอร์ tools ของโมเดล ดังนี้

val generativeModel = GenerativeModel(
  // Use a model that supports function calling, like Gemini 1.0 Pro
  // (see "Supported models" in the "Introduction to function calling" page)
  modelName = "gemini-1.0-pro",
  // Access your API key as a Build Configuration variable (see "Set up your API key" above)
  apiKey = BuildConfig.apiKey,
  // Specify the function declaration.
  tools = listOf(Tool(listOf(getExchangeRate)))
)

ขั้นตอนที่ 4: สร้างการเรียกใช้ฟังก์ชัน

จากนั้นคุณสามารถเรียกพรอมต์โมเดลด้วยฟังก์ชันที่กำหนดไว้ได้

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

val chat = generativeModel.startChat()

val prompt = "How much is 50 US dollars worth in Swedish krona?"

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