Tutorial sulla chiamata di funzione

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

La chiamata di funzioni semplifica l'ottenimento di 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, la chiamata di funzione ti aiuta a 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 descrizioni delle funzioni. Si tratta di di funzioni che scrivi nella lingua della tua app (ovvero, Google Cloud Functions). Il modello potrebbe chiederti di chiamare una funzione e di inviare nuovamente il risultato per aiutarlo a gestire la tua query.

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

API di esempio per il controllo dell'illuminazione

Immagina di avere un sistema di controllo dell'illuminazione di base con un'API (Application Programming Interface) 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 di illuminazione. Questo ipotetico sistema di controllo dell'illuminazione ti consente di regolare la luminosità della luce e la sua temperatura di colore, definite come due parametri distinti:

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

{
  "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 configurare il progetto e la chiave API.

Definire una funzione API

Creare una funzione che invia una richiesta API. Questa funzione deve essere definita nel codice della tua applicazione, ma potresti chiamare servizi o API all'esterno la tua applicazione. L'API Gemini non chiama direttamente questa funzione, quindi puoi controllare come e quando questa funzione viene eseguita tramite la tua applicazione le API nel tuo codice. A scopo dimostrativo, questo tutorial definisce una funzione API simulata che restituisce solo i valori di illuminazione richiesti:

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

Crea dichiarazioni di funzione

Crea la dichiarazione di funzione da passare al modello generativo. Quando dichiari una funzione che deve essere utilizzata dal modello, devi includere il maggior numero di dettagli il più possibile 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 dichiara la funzione di controllo dell'illuminazione:

const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

Dichiara le funzioni durante l'inizializzazione del modello

Quando vuoi utilizzare la chiamata di funzione con un modello, devi fornire le dichiarazioni di funzione quando inizializzato l'oggetto modello. Dichiari le funzioni impostando il parametro tools del modello:

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// ...

const generativeModel = genAI.getGenerativeModel({
  // Use a model that supports function calling, like a Gemini 1.5 model
  model: "gemini-1.5-flash",

  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

Genera una chiamata di funzione

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

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result2.response.text());
}