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