Anleitung: Funktionsaufruf mit der Gemini API

Python Node.js Go Dart (Flutter) Android Swift Web

Funktionsaufrufe erleichtern Ihnen die Ausgabe strukturierter Daten aus generativen Modellen. Sie können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zurückzugeben. Mit anderen Worten: Funktionsaufrufe helfen Ihnen, generative Modelle mit externen Systemen zu verbinden, damit der generierte Inhalt die aktuellsten und genauesten Informationen enthält.

Sie können Gemini-Modelle mit Funktionsbeschreibungen bereitstellen. Dies sind Funktionen, die Sie in der Sprache Ihrer Anwendung schreiben (d. h. sie sind nicht Google Cloud Functions). Möglicherweise fordert das Modell Sie auf, eine Funktion aufzurufen und das Ergebnis zurückzusenden, um das Modell bei der Verarbeitung Ihrer Abfrage zu unterstützen.

Weitere Informationen finden Sie unter Einführung in Funktionsaufrufe.

Projekt einrichten

Bevor Sie die Gemini API aufrufen, müssen Sie Ihr Android-Projekt einrichten. Dazu müssen Sie Ihren API-Schlüssel einrichten, dem Android-Projekt die SDK-Abhängigkeiten hinzufügen und das Modell initialisieren.

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

val generativeModel = GenerativeModel(

    // Use a model that supports function calling, like a Gemini 1.5 model
    modelName = "gemini-1.5-flash",

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

Funktionsaufruf einrichten

Im Rahmen dieser Anleitung interagiert das Modell mit einer hypothetischen Währungstausch-API, die die folgenden Parameter unterstützt:

Beispiel für eine API-Anfrage

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

Beispiel für eine API-Antwort

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

Schritt 1: Funktion erstellen, die die API-Anfrage stellt

Erstellen Sie zuerst die Funktion, die eine API-Anfrage stellt, falls noch nicht geschehen.

Zu Demonstrationszwecken werden in dieser Anleitung statt einer API-Anfrage hartcodierte Werte in demselben Format zurückgegeben, das eine echte API zurückgeben würde.

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

Schritt 2: Funktionsdeklaration erstellen

Erstellen Sie die Funktionsdeklaration, die Sie an das generative Modell übergeben (nächster Schritt dieser Anleitung).

Geben Sie so viele Details wie möglich in die Funktions- und Parameterbeschreibung ein. Das generative Modell verwendet diese Informationen, um zu bestimmen, welche Funktion ausgewählt werden soll und wie Werte für die Parameter im Funktionsaufruf bereitgestellt werden.

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

Schritt 3: Funktionsdeklaration bei der Modellinitialisierung angeben

Geben Sie die Funktionsdeklaration beim Initialisieren des generativen Modells an, indem Sie sie an den Parameter tools des Modells übergeben:

val generativeModel = GenerativeModel(
  // Use a model that supports function calling, like a Gemini 1.5 model
  modelName = "gemini-1.5-flash",
  // 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)))
)

Schritt 4: Funktionsaufruf generieren

Jetzt können Sie das Modell mit der definierten Funktion abfragen.

Die empfohlene Methode zum Verwenden von Funktionsaufrufen erfolgt über die Chat-Oberfläche, da Funktionsaufrufe gut in die Multi-Turn-Struktur eines Chats passen.

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