Tutoriel sur l'appel de fonction

<ph type="x-smartling-placeholder"></ph> Python Node.js OK Dart (Flutter) Android Swift Web .

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, l'appel de fonction aide vous connectez des modèles génératifs à des systèmes externes inclut 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 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 le 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 fictif de contrôle d'éclairage vous permet de contrôler la luminosité de la lumière et sa température de couleur, définie comme paramètres:

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: configurer votre projet et votre clé API

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

dart pub add google_generative_ai

flutter pub add google_generative_ai

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 l'application, mais elle peut appeler des services ou des API en dehors votre application. L'API Gemini n'appelle pas cette fonction directement. Vous devez donc peuvent contrôler quand et comment cette fonction est exécutée via votre application du code source. À des fins de démonstration, ce tutoriel définit une fonction d'API fictive qui renvoie simplement les valeurs d'éclairage demandées:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

Créer des déclarations de fonction

Créez la déclaration de la fonction que vous transmettrez au modèle génératif. Quand ? lorsque vous déclarez une fonction à utiliser par le modèle, incluez 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 quelle fonction sélectionner et comment fournir pour les paramètres de l'appel de fonction. Le code suivant montre comment Déclarez la fonction de contrôle de l'éclairage:

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      '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 indiquer votre lorsque vous initialisez l'objet de modèle. Vous déclarez en définissant le paramètre tools du modèle. Le SDK Dart accepte également déclarer les fonctions en tant qu'arguments de l'objet generateContent ou API generateContentStream.

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [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 le modèle 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 le contexte des requêtes et réponses précédentes.

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}