Tutoriel sur l'appel de fonction

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

L'appel de fonction vous permet d'obtenir plus facilement des sorties de données structurées à partir de modèles génératifs. Vous pouvez ensuite utiliser ces sorties pour appeler d'autres API et renvoyer les données de réponse pertinentes au modèle. En d'autres termes, les appels de fonction vous aident à connecter des modèles génératifs à des systèmes externes afin que le contenu généré inclue les informations les plus récentes et les plus précises.

Vous pouvez fournir des descriptions de fonctions aux modèles Gemini. Il s'agit de fonctions que vous écrivez dans la langue de votre application (c'est-à-dire qu'elles ne sont pas des fonctions Google Cloud). Le modèle peut vous demander d'appeler une fonction et de renvoyer le résultat pour l'aider à gérer votre requête.

Si vous ne l'avez pas déjà fait, consultez la section Présentation de l'appel de fonction pour en savoir plus.

Exemple d'API pour le contrôle de l'éclairage

Imaginons que vous disposiez d'un système de contrôle d'éclairage de base avec une interface de programmation d'application (API) et que vous souhaitiez permettre aux utilisateurs de contrôler les lumières à l'aide de requêtes textuelles simples. Vous pouvez utiliser la fonctionnalité d'appel de fonction pour interpréter les demandes de modification de l'éclairage des utilisateurs et les traduire en appels d'API pour définir les valeurs d'éclairage. Ce système de contrôle d'éclairage hypothétique vous permet de contrôler la luminosité de la lumière et sa température de couleur, définies comme deux paramètres distincts:

Par souci de simplicité, ce système d'éclairage imaginaire ne comporte qu'une seule ampoule. L'utilisateur n'a donc pas besoin de spécifier de pièce ni d'emplacement. Voici un exemple de requête JSON que vous pouvez envoyer à l'API de contrôle de l'éclairage pour définir le niveau d'éclairage sur 50 % à l'aide de la température de couleur de la lumière du jour:

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

Ce tutoriel vous explique comment configurer un appel de fonction pour l'API Gemini afin d'interpréter les requêtes d'éclairage des utilisateurs et de les mapper sur les paramètres de l'API pour contrôler les valeurs de luminosité et de température de couleur d'une lumière.

Avant de commencer: configurez votre projet et votre clé API

Avant d'appeler l'API Gemini, vous devez configurer votre projet et votre clé API.

Définir une fonction d'API

Créez une fonction qui envoie une requête API. Cette fonction doit être définie dans le code de votre application, mais elle peut appeler des services ou des API en dehors de votre application. L'API Gemini n'appelle pas directement cette fonction. Vous pouvez donc contrôler comment et quand cette fonction est exécutée via le code de votre application. À des fins de démonstration, ce tutoriel définit une fonction d'API fictive qui ne renvoie que les valeurs d'éclairage demandées:

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

Créer des déclarations de fonction

Créez la déclaration de fonction que vous transmettrez au modèle génératif. Lorsque vous déclarez une fonction à utiliser par le modèle, vous devez inclure autant de détails que possible dans les descriptions de la fonction et des paramètres. Le modèle génératif utilise ces informations pour déterminer quelle fonction sélectionner et comment fournir des valeurs pour les paramètres de l'appel de fonction. Le code suivant montre comment déclarer la fonction de contrôle de l'éclairage:

// Function declaration, to pass to the model.
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, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

Déclarer des fonctions lors de l'initialisation du modèle

Lorsque vous souhaitez utiliser l'appel de fonction avec un modèle, vous devez fournir vos déclarations de fonction lorsque vous initialisez l'objet du modèle. Vous déclarez des fonctions en définissant le paramètre tools du modèle:

<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: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

Générer un appel de fonction

Une fois que vous avez initialisé le modèle avec vos déclarations de fonction, vous pouvez l'inviter avec la fonction définie. Vous devez utiliser l'appel de fonction à l'aide d'une requête de chat (sendMessage()), car l'appel de fonction bénéficie généralement du contexte des requêtes et réponses précédentes.

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

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