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 données structurées en sortie les 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 des fonctions que vous écrivez dans le langage de votre application (c'est-à-dire qu'elles ne sont pas Google Cloud Functions). Le modèle peut vous demander d'appeler une fonction et de renvoyer du résultat pour aider le modèle à traiter votre requête.

Si vous ne l'avez pas déjà fait, consultez le Introduction à l'appel de fonction pour en savoir plus autres.

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

Imaginez que vous disposez d'un système de contrôle de l'éclairage basique avec une application (API) et que vous voulez permettre aux utilisateurs de contrôler les éclairages via des requêtes textuelles. Vous pouvez utiliser la fonctionnalité d'appel de fonction pour interpréter l'éclairage les demandes de modification des utilisateurs et les traduire en appels d'API pour définir l'éclairage valeurs. 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 :

Paramètre	Type	Obligatoire	Description
brightness	Nombre	oui	Niveau d'éclairage compris entre 0 et 100. La valeur 0 correspond à l'arrêt et la valeur 100 à la luminosité maximale.
colorTemperature	chaîne	oui	Température des couleurs du luminaire, qui peut être daylight, cool ou warm.

Par souci de simplicité, ce système d'éclairage imaginaire n'a qu'une seule lumière. L'utilisateur n'a pas besoin de spécifier une pièce ou un lieu. Voici un exemple de requête JSON vous pouvez envoyer à l'API de contrôle de l'éclairage pour faire passer le niveau de luminosité à 50% en utilisant la température des couleurs en plein jour:

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

Ce tutoriel explique comment configurer un appel de fonction pour que l'API Gemini interpréter les requêtes d'éclairage des utilisateurs et les mapper avec les paramètres d'API pour contrôler la luminosité et la température des couleurs de la 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évelopper pour découvrir comment configurer votre projet et votre clé API

Obtenir et sécuriser votre clé API

Vous avez besoin d'une clé API pour appeler l'API Gemini. Si vous n'en avez pas encore, créer une clé dans Google AI Studio.

Obtenir une clé API

Il est fortement recommandé de ne pas vérifier de clé API dans votre version système de contrôle.

Vous devez stocker votre clé API dans un magasin de secrets tel que Secret Manager de Google Cloud.

Dans ce tutoriel, nous partons du principe que vous accédez à votre clé API en tant qu'environnement .

Importer le package SDK et configurer votre clé API

Dans votre application, procédez comme suit :

1. Dans le répertoire de votre module, get le package du SDK Go :

   go get github.com/google/generative-ai-go
   

2. Importez le package et configurez le service avec votre clé API:

   import (
     // import standard libraries
     // Import the GenerativeAI package for Go
     "github.com/google/generative-ai-go/genai"
     "google.golang.org/api/option"
   )
   
   ctx := context.Background()
   // Access your API key as an environment variable
   client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
   if err != nil {
     log.Fatal(err)
   }
   defer client.Close()
   
   // ...
   

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 l'application, mais elle peut appeler des services ou des API en dehors 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 renvoie simplement les valeurs d'éclairage demandées:

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp}
}

Créer une déclaration de fonction

Créez la déclaration de la 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 :

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"brightness", "colorTemperature"},
        },
    }},
}

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 :

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

Générer un appel de fonction

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

// Start new chat session.
session := model.StartChat()

prompt := "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}