Tutoriel sur l'appel de fonction

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

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, l'appel de fonction vous aide à 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 aux modèles Gemini des descriptions de fonctions. Il s'agit de fonctions que vous écrivez dans le langage de votre application (il ne s'agit pas de fonctions Google Cloud Functions). 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 page Présentation de l'appel de fonction pour en savoir plus.

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

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

Pour des raisons de simplicité, ce système d'éclairage imaginaire ne comporte qu'une seule lumière. L'utilisateur n'a donc pas besoin de spécifier une pièce ni un emplacement. Voici un exemple de requête JSON que vous pouvez envoyer à l'API de contrôle de la luminosité pour définir le niveau de luminosité sur 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 l'API Gemini afin d'interpréter les requêtes d'éclairage des utilisateurs et de les mapper aux paramètres de l'API afin de contrôler la luminosité et les valeurs de température des couleurs d'une lumière.

Avant de commencer: configurer 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 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 l'application. L'API Gemini n'appelle pas cette fonction directement. Vous pouvez donc contrôler quand et comment 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 des fonctions et des paramètres. Le modèle génératif utilise ces informations pour déterminer la 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{"currencyDate", "currencyFrom"},
        },
    }},
}

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

Si vous souhaitez utiliser l'appel de fonction avec un modèle, vous devez fournir vos déclarations de fonction lorsque vous initialisez l'objet de 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 au modèle avec la fonction définie. Vous devez utiliser l'appel de fonction à l'aide des invites de chat (SendMessage()), car il est généralement utile de disposer 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)
}