Présentation des appels de fonction avec l'API Gemini

À l'aide de la fonctionnalité d'appel de fonction de l'API Gemini, vous pouvez fournir des définitions de fonction personnalisées au modèle. Le modèle n'appelle pas directement ces fonctions, mais génère une sortie structurée qui spécifie un nom de fonction et des arguments suggérés. Vous pouvez ensuite utiliser le nom et les arguments de la fonction pour appeler une API externe, et intégrer la sortie de l'API obtenue à une autre requête adressée au modèle, ce qui lui permet de fournir une réponse plus complète et d'effectuer des actions supplémentaires.

L'appel de fonction permet aux utilisateurs d'interagir avec des informations et des services en temps réel, tels que des bases de données, des systèmes de gestion de la relation client et des dépôts de documents. Cette fonctionnalité améliore également la capacité du modèle à fournir des réponses pertinentes et contextuelles. Les appels de fonction sont particulièrement adaptés à l'interaction avec des systèmes externes. Si votre cas d'utilisation nécessite que le modèle effectue des calculs, mais n'implique pas de systèmes ou d'API externes, envisagez plutôt d'utiliser l'exécution de code.

Pour obtenir un exemple fonctionnel d'appel de fonction, consultez le notebook "light bot".

Fonctionnement des appels de fonction

Pour utiliser la fonctionnalité d'appel de fonction, ajoutez des données de requête structurées décrivant des interfaces de programmation, appelées déclarations de fonction, à une requête du modèle. Les déclarations de fonction fournissent le nom de la fonction de l'API, expliquent son objectif, les paramètres qu'elle accepte et les descriptions de ces paramètres. Une fois que vous avez transmis une liste de déclarations de fonction dans une requête au modèle, celui-ci analyse les déclarations de fonction et le reste de la requête pour déterminer comment utiliser l'API déclarée en réponse à la requête.

Le modèle renvoie ensuite un objet dans un schéma compatible avec OpenAPI spécifiant comment appeler une ou plusieurs des fonctions déclarées pour répondre à la question de l'utilisateur. Vous pouvez ensuite utiliser les paramètres d'appel de fonction recommandés, appeler l'API réelle, obtenir une réponse et la fournir à l'utilisateur ou prendre d'autres mesures. Notez que le modèle n'appelle pas réellement les fonctions déclarées. À la place, vous utilisez les paramètres de l'objet de schéma renvoyé pour appeler la fonction. L'API Gemini est également compatible avec les appels de fonction en parallèle, où le modèle recommande plusieurs appels de fonction d'API en fonction d'une seule requête.

Déclarations de fonctions

Lorsque vous implémentez l'appel de fonction dans une invite, vous créez un objet tools, qui contient un ou plusieurs function declarations. Vous définissez des fonctions à l'aide de JSON, en particulier avec un sous-ensemble sélectionné du format de schéma OpenAPI. Une seule déclaration de fonction peut inclure les paramètres suivants:

  • name (chaîne): identifiant unique de la fonction dans l'appel d'API.
  • description (chaîne): explication complète de l'objectif et des fonctionnalités de la fonction.
  • parameters (objet): définit les données d'entrée requises par la fonction.
    • type (chaîne): spécifie le type de données global, par exemple object.
    • properties (objet): liste les paramètres individuels, chacun avec les éléments suivants :
      • type (chaîne): type de données du paramètre, par exemple string, integer ou boolean.
      • description (chaîne): explication claire de l'objectif du paramètre et du format attendu.
    • required (tableau): tableau de chaînes listant les noms de paramètres obligatoires pour le fonctionnement de la fonction.

Pour obtenir des exemples de code d'une déclaration de fonction à l'aide de commandes cURL, consultez les exemples d'appel de fonction. Pour obtenir des exemples de création de déclarations de fonction à l'aide des SDK de l'API Gemini, consultez le tutoriel sur les appels de fonction.

Bonnes pratiques pour les déclarations de fonction

Définir précisément vos fonctions est essentiel lorsque vous les intégrez à vos requêtes. Chaque fonction s'appuie sur des paramètres spécifiques qui guident son comportement et son interaction avec le modèle. La liste suivante fournit des conseils pour définir les paramètres d'une fonction individuelle dans un tableau functions_declarations.

  • name: utilisez des noms clairs et descriptifs sans espace, point (.) ni tiret (-). Utilisez plutôt des traits de soulignement (_) ou la casse camel.

  • description: fournissez des descriptions de fonction détaillées, claires et spécifiques, en fournissant des exemples si nécessaire. Par exemple, au lieu de find theaters, utilisez find theaters based on location and optionally movie title that is currently playing in theaters.. Évitez les descriptions trop générales ou ambiguës.

  • properties > type: utilisez des paramètres fortement typés pour réduire les hallucinations du modèle. Par exemple, si les valeurs des paramètres proviennent d'un ensemble fini, utilisez un champ enum au lieu de lister les valeurs dans la description (par exemple, "type": "enum", "values": ["now_playing", "upcoming"]). Si la valeur du paramètre est toujours un entier, définissez le type sur integer plutôt que sur number.

  • properties > description: fournissez des exemples et des contraintes concrets. Par exemple, au lieu de the location to search, utilisez The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

Pour connaître d'autres bonnes pratiques lors de l'utilisation d'appels de fonction, consultez la section Bonnes pratiques.

Mode d'appel de fonction

Vous pouvez utiliser le paramètre mode de l'appel de fonction pour modifier le comportement d'exécution de la fonctionnalité. Trois modes sont disponibles:

  • AUTO: comportement par défaut du modèle. Le modèle décide de prédire un appel de fonction ou une réponse en langage naturel.
  • ANY: le modèle est contraint de toujours prédire un appel de fonction. Si allowed_function_names n'est pas fourni, le modèle choisit parmi toutes les déclarations de fonction disponibles. Si allowed_function_names est fourni, le modèle choisit parmi l'ensemble des fonctions autorisées.
  • NONE: le modèle ne prédit pas d'appel de fonction. Dans ce cas, le comportement du modèle est le même que si vous ne transmettez aucune déclaration de fonction.

L'utilisation du mode ANY ("appel de fonction forcé") n'est compatible qu'avec les modèles Gemini 1.5 Pro et Gemini 1.5 Flash.

Vous pouvez également transmettre un ensemble de allowed_function_names qui, lorsqu'il est fourni, limite les fonctions que le modèle appellera. Vous ne devez inclure allowed_function_names que lorsque le mode est ANY. Les noms de fonction doivent correspondre aux noms de déclaration de fonction. Lorsque le mode est défini sur ANY et que allowed_function_names est défini, le modèle prédit un appel de fonction à partir de l'ensemble de noms de fonctions fournis.

L'extrait de code suivant d'un exemple de requête montre comment définir mode sur ANY et spécifier une liste de fonctions autorisées:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Exemples d'appels de fonction

Cette section fournit des exemples d'invites pour les appels de fonction à l'aide de commandes cURL. Les exemples incluent des scénarios à tour unique et à plusieurs tours, ainsi que l'activation de différents modes d'appel de fonction.

Lorsque vous utilisez des commandes cURL avec cette fonctionnalité, les informations sur la fonction et les paramètres sont incluses dans l'élément tools. Chaque déclaration de fonction de l'élément tools contient le nom de la fonction. Vous spécifiez les paramètres à l'aide d'un schéma compatible avec OpenAPI et d'une description de la fonction.

Exemple d'un seul tour

Avec le mode "un seul tour", vous appelez un modèle de langue une fois. Avec les appels de fonction, vous pouvez utiliser un seul tour lorsque vous fournissez au modèle une requête en langage naturel et une liste de fonctions. Dans ce cas, le modèle utilise la déclaration de la fonction, qui inclut le nom, les paramètres et la description de la fonction, pour prédire quelle fonction appeler et les arguments à appeler.

L'exemple curl suivant est un exemple de transmission d'une description d'une fonction qui renvoie des informations sur l'emplacement de la lecture d'un film. Plusieurs déclarations de fonctions, telles que find_movies et find_theaters, sont incluses dans la requête.

Exemple de requête d'appel de fonction à un seul tour

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'
    

La réponse à cet exemple curl peut ressembler à ce qui suit.

Exemple de réponse d'appel de fonction à un seul tour curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]
    

Exemple de rotation unique avec le mode "ANY"

L'exemple curl suivant est semblable à l'exemple à un seul tour, mais il définit le mode sur ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

Appel de fonction à un seul tour à l'aide du mode "ANY" (demande)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'
    

La réponse peut ressembler à ce qui suit :

Appel de fonction à un seul tour à l'aide de n'importe quel mode (réponse)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}
    

Exemple de tour unique utilisant le mode "ANY" et les fonctions autorisées

L'exemple curl suivant est semblable à l'exemple d'un seul virage, mais il définit le mode sur ANY et inclut une liste des fonctions autorisées:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Appel de fonction à un seul tour à l'aide du mode "ANY" et des fonctions autorisées (requête)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'
    

Le modèle ne peut pas prédire la fonction find_movies, car elle ne figure pas dans la liste des fonctions autorisées. Il prédit donc une fonction différente. La réponse peut ressembler à ce qui suit:

Appel de fonction à un seul tour à l'aide du mode "ANY" et des fonctions autorisées (réponse)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}
    

Exemples de conversations multitours

Vous pouvez mettre en œuvre un scénario d'appel de fonction multitour en procédant comme suit:

  1. Obtenez une réponse à un appel de fonction en appelant le modèle de langage. C'est le premier tour.
  2. Appelez le modèle de langage à l'aide de la réponse d'appel de fonction du premier tour et de la réponse de fonction que vous obtenez en appelant cette fonction. Il s'agit du deuxième tour.

La réponse du deuxième tour résume les résultats pour répondre à votre requête lors du premier tour ou contient un deuxième appel de fonction que vous pouvez utiliser pour obtenir plus d'informations sur votre requête.

Cet article inclut deux exemples curl multitours:

Utiliser une réponse d'un tour précédent

L'exemple curl suivant appelle la fonction et les arguments renvoyés par l'exemple de tour unique précédent pour obtenir une réponse. La méthode et les paramètres renvoyés par l'exemple de tour unique sont dans cette entrée JSON.

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

Exemple de requête d'appel de fonction multitours curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'
    

La réponse à cet exemple curl inclut le résultat de l'appel de la méthode find_theaters. La réponse peut ressembler à ce qui suit :

Exemple de réponse d'appel de fonction multitours curl

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}
    

Appeler le modèle plusieurs fois

L'exemple cURL suivant appelle le modèle d'IA générative plusieurs fois pour appeler une fonction. Chaque fois que le modèle appelle la fonction, elle peut utiliser une fonction différente pour répondre à une requête utilisateur différente dans la requête.

Exemple de requête d'appel de fonction multitours curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'
    

Exemple de réponse d'appel de fonction multitours curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]
    

Bonnes pratiques

Suivez ces bonnes pratiques pour améliorer la précision et la fiabilité de vos appels de fonction.

Requête de l'utilisateur

Pour de meilleurs résultats, ajoutez les informations suivantes en préfixe à la requête utilisateur:

  • Contexte supplémentaire pour le modèle. Par exemple : You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • Détails ou instructions sur quand et comment utiliser des fonctions. Par exemple, Don't make assumptions on showtimes. Always use a future date for showtimes..
  • Instructions pour poser des questions de clarification si les requêtes des utilisateurs sont ambiguës. Par exemple : Ask clarifying questions if not enough information is available to complete the request.

Paramètres d'échantillonnage

Pour le paramètre de température, utilisez 0 ou une autre valeur faible. Cela indique au modèle de générer des résultats plus fiables et de réduire les hallucinations.

Appel d'API

Si le modèle propose d'appeler une fonction qui permet d'envoyer une commande, de mettre à jour une base de données ou de provoquer des conséquences importantes, validez l'appel de fonction auprès de l'utilisateur avant de l'exécuter.