Tutorial: chiamate di funzioni con l'API Gemini


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, che include l'ottenimento di una chiave API, l'importazione dell'SDK e l'inizializzazione del modello. Per istruzioni dettagliate, espandi ciascuna delle sezioni seguenti.

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.

async function makeApiRequest(currencyFrom, currencyTo) {
  // This hypothetical API returns a JSON such as:
  // {"base":"USD","rates":{"SEK": 0.091}}
  return {
    base: currencyFrom,
    rates: { [currencyTo]: 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.

// Function declaration, to pass to the model.
const getExchangeRateFunctionDeclaration = {
  name: "getExchangeRate",
  parameters: {
    type: "OBJECT",
    description: "Get the exchange rate for currencies between countries",
    properties: {
      currencyFrom: {
        type: "STRING",
        description: "The currency to convert from.",
      },
      currencyTo: {
        type: "STRING",
        description: "The currency to convert to.",
      },
    },
    required: ["currencyTo", "currencyFrom"],
  },
};

// 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 = {
  getExchangeRate: ({ currencyFrom, currencyTo }) => {
    return makeApiRequest( currencyFrom, currencyTo)
  }
};

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:

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(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: [getExchangeRateFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

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.

const chat = generativeModel.startChat();
const prompt = "How much is 50 US dollars worth in Swedish krona?";

// 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 result = await chat.sendMessage([{functionResponse: {
    name: 'getExchangeRate',
    response: apiResponse
  }}]);

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