Tutorial sulla chiamata di funzione

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

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

Puoi fornire ai modelli Gemini descrizioni delle funzioni. Si tratta delle funzioni che scrivi nella lingua della tua app (ovvero non sono Google Cloud Functions). Il modello potrebbe chiederti di richiamare una funzione e restituire il risultato per aiutare il modello a gestire la query.

Se non lo hai già fatto, consulta Introduzione alle chiamate di funzione per saperne di più.

API di esempio per il controllo dell'illuminazione

Immagina di avere un sistema di base per il controllo dell'illuminazione con un'interfaccia di programmazione di un'applicazione (API) e di voler consentire agli utenti di controllare le luci tramite semplici richieste di testo. Puoi utilizzare la funzionalità di chiamata di funzione per interpretare le richieste di modifica dell'illuminazione da parte degli utenti e tradurle in chiamate API per impostare i valori dell'illuminazione. Questo ipotetico sistema di controllo dell'illuminazione consente di controllare la luminosità della luce e la sua temperatura di colore, definita come due parametri separati:

Per semplicità, questo sistema di illuminazione immaginario ha una sola illuminazione, quindi l'utente non deve specificare una stanza o un luogo. Ecco un esempio di richiesta JSON che potresti inviare all'API di controllo della luce per modificare il livello della luce al 50% utilizzando la temperatura di colore della luce diurna:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

Questo tutorial mostra come configurare una chiamata di funzione per l'API Gemini per interpretare le richieste di illuminazione degli utenti e mapparle alle impostazioni dell'API per controllare i valori di luminosità e temperatura di colore di una luce.

Prima di iniziare: configura il progetto e la chiave API

Prima di chiamare l'API Gemini, devi impostare il progetto e configurare la chiave API.

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

Definisci una funzione API

Creare una funzione che invia una richiesta API. Questa funzione dovrebbe essere definita all'interno del codice dell'applicazione, ma potrebbe chiamare servizi o API al di fuori dell'applicazione. L'API Gemini non chiama direttamente questa funzione, quindi puoi controllare come e quando questa funzione viene eseguita tramite il codice della tua applicazione. A scopo dimostrativo, questo tutorial definisce una funzione API simulata che restituisce semplicemente i valori di illuminazione richiesti:

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

crea dichiarazioni di funzione

Crea la dichiarazione di funzione che passerai al modello generativo. Quando dichiari una funzione per l'utilizzo da parte del modello, devi includere il maggior numero possibile di dettagli nelle descrizioni delle funzioni e dei parametri. Il modello generativo utilizza queste informazioni per determinare quale funzione selezionare e come fornire valori per i parametri nella chiamata di funzione. Il seguente codice mostra come dichiarare la funzione di controllo dell'illuminazione:

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

Dichiara le funzioni durante l'inizializzazione del modello

Se vuoi utilizzare le chiamate di funzione con un modello, devi fornire le dichiarazioni di funzione al momento dell'inizializzazione dell'oggetto di modello. Dichiari le funzioni impostando il parametro tools del modello:

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

Genera una chiamata di funzione

Dopo aver inizializzato il modello con le dichiarazioni di funzione, puoi inviare un prompt al modello con la funzione definita. Dovresti usare le chiamate di funzione tramite i prompt di chat (sendMessage()), poiché in genere le chiamate di funzione traggono vantaggio dal contesto dei prompt e delle risposte precedenti.

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