I modelli generativi sono potenti per 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 funzione possono aiutarti a superare alcuni di questi limiti. La chiamata di funzione è a volte indicata come uso di strumenti perché consente a un modello di usare strumenti esterni, come API e funzioni, per generare la risposta finale.
Per ulteriori informazioni sulle chiamate di funzione consulta la 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. A livello generale, questi sono i passaggi per configurare le chiamate di funzione nella tua app:
Scrivi una funzione che possa fornire al modello le informazioni necessarie per generare la risposta finale (ad esempio, la funzione può chiamare un'API esterna).
Crea una dichiarazione di funzione che descriva la funzione e i relativi parametri.
Fornisci la dichiarazione di funzione durante l'inizializzazione del modello in modo che il modello sappia come può utilizzare la funzione, se necessario.
Configura l'app in modo che il modello possa inviare le informazioni richieste affinché l'app chiami la funzione.
Ripassa la risposta della funzione al modello in modo che quest'ultimo 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 tra di loro, quindi il modo consigliato per utilizzare la chiamata di funzione è tramite l'interfaccia di chat in più passaggi.
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 avere un'API di un servizio meteo esterno in grado di fornirle. Puoi utilizzare le chiamate di funzione per fornire al modello Gemini un percorso verso l'API e le relative informazioni meteo.
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ì | La data per cui recuperare il meteo (deve essere sempre in 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.
Questo processo è chiamato "dichiarazione di funzione". Il modello non chiama la funzione
direttamente. Poiché il modello sta elaborando la richiesta in entrata,
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 alla tua app in modo che quest'ultima 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.
Implementare la chiamata di funzione
Prima di iniziare
Se non l'hai ancora fatto, consulta la Guida introduttiva agli SDK Vertex AI in Firebase. Assicurati di aver eseguito tutte le seguenti operazioni:
Imposta un progetto Firebase nuovo o esistente, incluso l'utilizzo del piano tariffario Blaze e l'abilitazione delle API richieste.
Collega la tua app a Firebase, registrandola e aggiungendo la configurazione di Firebase all'app.
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 l'esempio di codice completo per questo esempio di chiamata di funzione più avanti in questa pagina.
Passaggio 1: scrivi la funzione
Immagina di avere un'app in cui un utente può 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 di 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 è il contrario del comportamento predefinito per Vertex AI Gemini API.
Per le best practice relative alle dichiarazioni delle funzioni, inclusi suggerimenti per nomi e descrizioni, consulta Best practice nella documentazione 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 funzione 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 aiutarla
a generare una risposta finale, la tua app deve effettuare la chiamata effettiva alla
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 in più passaggi.
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
Ecco alcuni comportamenti aggiuntivi per le chiamate di funzione che devi specificare 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. Il secondo può verificarsi solo se fornisci più di una funzione al modello nell'elenco di dichiarazioni 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. Detto questo, il modello può decidere che sono necessarie più funzioni per generare la risposta finale. Potrebbe decidere di chiamare contemporaneamente alcune di queste funzioni, in questo modo si parla di chiamate di funzioni parallele.
La tua app deve soddisfare il fatto che il modello può richiedere più funzioni in esecuzione contemporaneamente e l'app deve fornire al modello tutte le risposte dalle funzioni.
Le chiamate di funzione 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 definire 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:
Invece di 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.
Puoi implementare questi vincoli (o modalità) aggiungendo una configurazione dello strumento (toolConfig) insieme alle dichiarazioni del prompt e delle funzioni. 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 equivale a una richiesta di modello senza dichiarazioni di funzione associate. |
La modalità di chiamata di funzione è supportata da Gemini 1.5 Pro e Gemini 1.5 Flash.
Cosa puoi fare ancora?
Prova altre funzionalità di Gemini API
- Crea conversazioni a più turni (chat).
- Genera testo da prompt di solo testo.
- Genera testo da prompt multimodali (inclusi testo, immagini, PDF, video e audio).
Scopri come controllare la generazione di contenuti
- Comprendi la progettazione dei prompt, tra cui best practice, strategie e prompt di esempio.
- Configura parametri del modello come temperatura e numero massimo di token di output.
- Utilizza le impostazioni di sicurezza per modificare la probabilità di ricevere risposte che potrebbero essere considerate dannose.
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