Chiamate di funzione utilizzando l'API Gemini


I modelli generativi sono molto efficaci nel risolvere molti tipi di problemi. Tuttavia, sono vincolate da limitazioni quali:

  • Vengono bloccati dopo l'addestramento, il che porta a conoscenze obsolete.
  • Non possono eseguire query o modificare i dati esterni.

Le chiamate di funzioni possono aiutarti a superare alcuni di questi limiti. A volte le chiamate di funzione sono indicate come utilizzo di strumenti perché consentono a un modello di utilizzare strumenti esterni come API e funzioni per generare la risposta finale.

Puoi scoprire di più sulle chiamate di funzione nella documentazione di Google Cloud, incluso un utile elenco di casi d'uso per le chiamate di funzione.

Le chiamate di funzione sono supportate da Gemini 1.0 Pro, Gemini 1.5 Pro e Gemini 1.5 Flash.

Questa guida mostra come implementare una configurazione di chiamata di funzione simile all'esempio descritto nella sezione principale successiva di questa pagina. In linea di massima, Ecco i passaggi per configurare le chiamate di funzione nella tua app:

  1. Scrivi una funzione che possa fornire al modello le informazioni di cui ha bisogno per generare la risposta finale (ad esempio, la funzione può chiamare un'API esterna).

  2. Crea una dichiarazione di funzione che descriva la funzione e i relativi parametri.

  3. Fornisci la dichiarazione della funzione durante l'inizializzazione del modello in modo che il modello sappia come utilizzare la funzione, se necessario.

  4. Configura l'app in modo che il modello possa inviare le informazioni richieste per consentirle di chiamare la funzione.

  5. Passa la risposta della funzione al modello in modo che possa generare la risposta finale.

Vai all'implementazione del codice

Panoramica di un esempio di chiamata di funzione

Quando invii una richiesta al modello, puoi anche fornirgli un insieme di "strumenti" (come le funzioni) che può utilizzare per generare la risposta finale. Per utilizzare queste funzioni e chiamarle ("chiamate di funzione"), il modello e la tua app devono scambiarsi informazioni, pertanto il modo consigliato per utilizzare le chiamate di funzione è tramite l'interfaccia di chat con più turni.

Immagina di avere un'app in cui un utente potrebbe inserire un prompt come: What was the weather in Boston on October 17, 2024?.

I modelli Gemini potrebbero non conoscere queste informazioni meteo. Tuttavia, immagina di conoscere un'API di servizio meteo esterno che può fornirle. Puoi utilizzare le chiamate di funzione per indicare al modello Gemini un percorso per accedere all'API e alle sue informazioni sul clima.

Innanzitutto, scrivi una funzione fetchWeather nella tua app che interagisce con questa ipotetica API esterna, che ha questo input e output:

Parametro Tipo Obbligatorio Descrizione
Input
location Oggetto Sì Il nome della città e il relativo stato per cui recuperare il meteo.
Sono supportate solo le città degli Stati Uniti. Deve sempre essere un oggetto nidificato di city e state.
date Stringa Sì Data per cui recuperare il meteo (deve sempre essere nel formato YYYY-MM-DD).
Output
temperature Numero intero Sì Temperatura (in Fahrenheit)
chancePrecipitation Stringa Sì Probabilità di precipitazioni (espressa in percentuale)
cloudConditions Stringa Sì Condizioni cloud (una di clear, partlyCloudy, mostlyCloudy, cloudy)

Quando lo inzializzi, devi indicare al modello che esiste questa funzione fetchWeather e come può essere utilizzata per elaborare le richieste in arrivo, se necessario. Questa è una "dichiarazione di funzione". Il modello non chiama la funzione direttamente. Invece, durante l'elaborazione della richiesta in arrivo, il modello decide se la funzione fetchWeather può aiutarlo a rispondere alla richiesta. Se il modello decide che la funzione può essere effettivamente utile, genera dati strutturati che aiuteranno la tua app a chiamare la funzione.

Esamina di nuovo la richiesta in arrivo: What was the weather in Boston on October 17, 2024?. Il modello probabilmente decider'à che la funzione fetchWeather può aiutarlo a generare una risposta. Il modello esaminerà i parametri di input necessari per fetchWeather e poi genererà dati di input strutturati per la funzione che hanno all'incirca il seguente aspetto:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

Il modello passa questi dati di input strutturati all'app in modo che possa chiamare la funzione fetchWeather. Quando l'app riceve le condizioni meteorologiche dall'API, le passa al modello. Queste informazioni sul clima consentono al modello di completare l'elaborazione finale e di generare la risposta alla richiesta iniziale diWhat was the weather in Boston on October 17, 2024?

Il modello potrebbe fornire una risposta finale in linguaggio naturale, ad esempio: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Diagramma che mostra come la chiamata di funzione implichi l'interazione del modello con una funzione nell'app 

Implementare le chiamate di funzione

Prima di iniziare

Se non l'hai ancora fatto, completa la guida introduttiva agli SDK Vertex AI in Firebase. Assicurati di aver eseguito tutte le seguenti operazioni:

  1. Configura un progetto Firebase nuovo o esistente, ad esempio utilizzando il piano di prezzi Blaze e attivando le API richieste.

  2. Collega la tua app a Firebase, inclusa la registrazione e l'aggiunta della configurazione Firebase.

  3. Aggiungi l'SDK e inizializza il servizio Vertex AI e il modello generativo nella tua app.

Dopo aver collegato l'app a Firebase, aggiunto l'SDK e inizializzato il servizio Vertex AI e il modello generativo, puoi chiamare Gemini API.

I passaggi rimanenti di questa guida mostrano come implementare una configurazione di chiamata di funzione simile al flusso di lavoro descritto in Panoramica di un esempio di chiamata di funzione (vedi la sezione in alto di questa pagina).

Puoi visualizzare il codice di esempio completo per questa chiamata di funzione più avanti in questa pagina.

Passaggio 1: scrivi la funzione

Immagina di avere un'app in cui un utente potrebbe inserire un prompt come: What was the weather in Boston on October 17, 2024?. I modelli Gemini potrebbero non conoscere queste informazioni meteo, ma immagina di conoscere un'API di servizio meteo esterno che può fornirle. L'esempio in questa guida si basa su questa API esterna ipotetica.

Scrivi nella tua app la funzione che interagirà con l'ipotetica API esterna e fornirà al modello le informazioni di cui ha bisogno per generare la richiesta finale. In questo esempio di meteo, sarà una funzione fetchWeather che effettuerà la chiamata a questa ipotetica API esterna.

Passaggio 2: crea una dichiarazione di funzione

Crea la dichiarazione della funzione che fornirai in un secondo momento al modello (passaggio successivo di questa guida).

Nella dichiarazione, includi il maggior numero di dettagli possibile nelle descrizioni della funzione e dei relativi parametri.

Il modello utilizza le informazioni nella dichiarazione della funzione per determinare quale funzione selezionare e come fornire i valori dei parametri per la chiamata effettiva alla funzione. Consulta la sezione Comportamenti e opzioni aggiuntivi di questa pagina per scoprire in che modo il modello può scegliere tra le funzioni e come puoi controllare questa scelta.

Tieni presente quanto segue in merito allo schema fornito:

  • Devi fornire le dichiarazioni di funzione in un formato dello schema compatibile con lo schema OpenAPI. Vertex AI offre un supporto limitato dello schema OpenAPI.

    • Sono supportati i seguenti attributi: type, nullable, required, format, description, properties, items, enum.

    • I seguenti attributi non sono supportati: default, optional, maximum, oneOf.

  • Per impostazione predefinita, per gli SDK Vertex AI in Firebase tutti i campi sono considerati obbligatori, a meno che non li specifichi come facoltativi in un array optionalProperties. Per questi campi facoltativi, il modello può completarli o ignorarli. Tieni presente che questo è opposto al comportamento predefinito per Vertex AI Gemini API.

Per le best practice relative alle dichiarazioni di funzione, inclusi suggerimenti per nomi e descrizioni, consulta Best practice nella documentazione di Google Cloud.

Ecco come scrivere una dichiarazione di funzione:

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

Il numero massimo di dichiarazioni di funzioni che puoi fornire con la richiesta è 128. Consulta la sezione Comportamenti e opzioni aggiuntivi di questa pagina per scoprire in che modo il modello può scegliere tra le funzioni e come puoi controllare questa scelta (utilizzando un toolConfig per impostare la modalità di chiamata delle funzioni).

Scopri come scegliere un modello Gemini e, facoltativamente, una posizione appropriata per il tuo caso d'uso e la tua app.

Passaggio 4: chiama la funzione per richiamare l'API esterna

Se il modello decide che la funzione fetchWeather può effettivamente aiutarlo a generare una risposta finale, l'app deve effettuare la chiamata effettiva a questa funzione utilizzando i dati di input strutturati forniti dal modello.

Poiché le informazioni devono essere trasmesse avanti e indietro tra il modello e l'app, il modo consigliato per utilizzare le chiamate di funzione è tramite l'interfaccia di chat con più turni.

Il seguente snippet di codice mostra come viene comunicato all'app che il modello vuole utilizzare la funzione fetchWeather. Mostra anche che il modello ha fornito i valori dei parametri di input necessari per la chiamata della funzione (e la relativa API esterna di base).

In questo esempio, la richiesta in arrivo conteneva il prompt What was the weather in Boston on October 17, 2024?. Da questo prompt, il modello ha dedotto i parametri di input richiesti dalla funzione fetchWeather (ovvero city, state e date).

Passaggio 5: fornisci l'output della funzione al modello per generare la risposta finale

Dopo che la funzione fetchWeather restituisce le informazioni meteo, la tua app deve trasmetterle nuovamente al modello.

Il modello esegue l'elaborazione finale e genera una risposta finale in linguaggio naturale, ad esempio:On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Comportamenti e opzioni aggiuntivi

Di seguito sono riportati alcuni comportamenti aggiuntivi per le chiamate di funzioni che devi gestire nel codice e le opzioni che puoi controllare.

Il modello potrebbe chiedere di chiamare di nuovo una funzione o un'altra funzione.

Se la risposta di una chiamata di funzione non è sufficiente per consentire al modello di generare la risposta finale, il modello potrebbe richiedere un'altra chiamata di funzione o una chiamata a una funzione completamente diversa. Quest'ultimo può verificarsi solo se fornisci più di una funzione al modello nell'elenco di dichiarazione delle funzioni.

L'app deve tenere conto del fatto che il modello potrebbe richiedere chiamate di funzioni aggiuntive.

Il modello potrebbe richiedere di chiamare più funzioni contemporaneamente.

Puoi fornire fino a 128 funzioni nell'elenco delle dichiarazioni di funzione al modello. Di conseguenza, il modello potrebbe decidere che sono necessarie più funzioni per aiutarlo a generare la risposta finale. Potrebbe anche decidere di chiamare alcune di queste funzioni contemporaneamente: si tratta della chiamata di funzioni in parallelo.

L'app deve tenere conto del fatto che il modello potrebbe richiedere l'esecuzione di più funzioni contemporaneamente e deve fornire tutte le risposte delle funzioni al modello.

Le chiamate di funzioni parallele sono supportate da Gemini 1.5 Pro e Gemini 1.5 Flash.

Puoi controllare come e se il modello può chiedere di chiamare funzioni.

Puoi applicare alcuni vincoli su come e se il modello deve utilizzare le dichiarazioni di funzione fornite. Questa operazione viene chiamata impostazione della modalità di chiamata di funzione. Ecco alcuni esempi:

  • Anziché consentire al modello di scegliere tra una risposta immediata in linguaggio naturale e una chiamata di funzione, puoi forzarlo a utilizzare sempre le chiamate di funzione. Questa operazione è chiamata chiamata di funzione forzata.

  • Se fornisci più dichiarazioni di funzioni, puoi limitare il modello a utilizzare solo un sottoinsieme delle funzioni fornite.

Implementi questi vincoli (o modalità) aggiungendo una configurazione dello strumento (toolConfig) insieme al prompt e alle dichiarazioni di funzione. Nella configurazione dello strumento, puoi specificare una delle seguenti modalità. La modalità più utile è ANY.

Modalità Descrizione
AUTO Il comportamento predefinito del modello. Il modello decide se utilizzare una chiamata di funzione o una risposta in linguaggio naturale.
ANY Il modello deve utilizzare chiamate di funzione ("chiamate di funzione forzate"). Per limitare il modello a un sottoinsieme di funzioni, specifica i nomi delle funzioni consentite in allowedFunctionNames.
NONE Il modello non deve utilizzare chiamate di funzione. Questo comportamento è equivalente a una richiesta di modello senza dichiarazioni di funzioni associate.

La modalità di chiamata di funzione è supportata da Gemini 1.5 Pro e Gemini 1.5 Flash.

Cosa puoi fare ancora?

Provare altre funzionalità di Gemini API

Scopri come controllare la generazione di contenuti

Puoi anche sperimentare con i prompt e le configurazioni del modello utilizzando Vertex AI Studio.

Scopri di più sui modelli Gemini

Scopri i modelli disponibili per vari casi d'uso e le relative quote e prezzi.


Inviare un feedback sulla tua esperienza con Vertex AI in Firebase