Tutorial: chiamate di funzioni con l'API Gemini


Le chiamate di funzione consentono di ottenere più facilmente output di dati strutturati dai modelli generativi. Puoi quindi utilizzare questi output per chiamare altre API e restituire al modello i dati di risposta pertinenti. In altre parole, le chiamate di funzione consentono di collegare i modelli generativi a sistemi esterni in modo che i contenuti generati includano le informazioni più aggiornate e accurate.

Puoi fornire ai modelli Gemini le descrizioni delle funzioni. Si tratta di funzioni che scrivi nel linguaggio dell'app (ovvero non sono funzioni di Google Cloud Functions). Il modello potrebbe chiederti di chiamare una funzione e inviare il risultato per aiutarlo a gestire la query.

Se non l'hai ancora fatto, consulta l'introduzione alle chiamate di funzione per saperne di più.

Configura il progetto

Prima di chiamare l'API Gemini, devi configurare il tuo progetto Android, che include la configurazione della chiave API, l'aggiunta delle dipendenze dell'SDK al progetto Android e l'inizializzazione del modello.

Imposta una chiamata funzione

Per questo tutorial, il modello interagirà con un'API ipotetica di scambio di valute che supporta i seguenti parametri:

Parametro Tipo Obbligatorie Descrizione
currencyFrom stringa sì Valuta da cui eseguire la conversione
currencyTo stringa sì Valuta da convertire

Esempio di richiesta API

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

Esempio di risposta dell'API

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

Passaggio 1: crea la funzione che effettua la richiesta API

Se non l'hai già fatto, inizia creando la funzione che effettui una richiesta API.

A scopo dimostrativo, in questo tutorial, anziché inviare una richiesta API effettiva, riceverai valori impostati come hardcoded nello stesso formato restituito da un'API effettiva.

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

Passaggio 2: crea una dichiarazione di funzione

Crea la dichiarazione della funzione che passerai al modello generativo (passaggio successivo di questo tutorial).

Includi il maggior numero di dettagli possibile nelle descrizioni delle funzioni e dei parametri. Il modello generativo utilizza queste informazioni per determinare quale funzione selezionare e in che modo fornire valori per i parametri nella chiamata di funzione.

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

Passaggio 3: specifica la dichiarazione della funzione durante l'inizializzazione del modello

Specifica la dichiarazione della funzione durante l'inizializzazione del modello generativo passandola al parametro tools del modello:

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

Passaggio 4: genera una chiamata funzione

Ora puoi richiedere al modello la funzione definita.

Consigliamo di utilizzare le chiamate di funzione tramite l'interfaccia della chat, poiché le chiamate di funzione si adattano perfettamente alla struttura multi-turno della chat.

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