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 aux modèles Gemini des descriptions de fonctions. 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 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. Vous pouvez aussi essayez cette fonctionnalité dans Google Colab ou consultez l'exemple de code dans le dépôt du livre de recettes de l'API Gemini.
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 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:
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
brightness |
Nombre | oui | Niveau de luminosité compris entre 0 et 100. Le zéro est désactivé et la valeur 100 correspond à la luminosité maximale. |
colorTemperature |
chaîne | oui | Température de couleur de l'appareil d'éclairage, 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é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 :
def set_light_values(brightness, color_temp):
"""Set the brightness and color temperature of a room light. (mock API).
Args:
brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
Returns:
A dictionary containing the set brightness and color temperature.
"""
return {
"brightness": brightness,
"colorTemperature": color_temp
}
Lorsque vous créez une fonction à utiliser dans un appel de fonction 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 dans l'appel de fonction.
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 déclarer vos fonctions lorsque vous initialisez l'objet modèle. Vous déclarez des fonctions en définissant
le paramètre tools du modèle:
model = genai.GenerativeModel(model_name='gemini-1.5-flash',
tools=[set_light_values])
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.
chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text
L'objet ChatSession du SDK Python simplifie la gestion des sessions de chat en gérant l'historique des conversations à votre place. Vous pouvez utiliser enable_automatic_function_calling pour obtenir le SDK
appelle automatiquement la fonction.
# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)
Appels de fonction en parallèle
En plus de l'appel de fonction de base décrit ci-dessus, vous pouvez également appeler plusieurs fonctions en un seul tour. Cette section présente un exemple d'utilisation de l'appel de fonction parallèle.
Définir les outils
def power_disco_ball(power: bool) -> bool:
"""Powers the spinning disco ball."""
print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
return True
def start_music(energetic: bool, loud: bool, bpm: int) -> str:
"""Play some music matching the specified parameters.
Args:
energetic: Whether the music is energetic or not.
loud: Whether the music is loud or not.
bpm: The beats per minute of the music.
Returns: The name of the song being played.
"""
print(f"Starting music! {energetic=} {loud=}, {bpm=}")
return "Never gonna give you up."
def dim_lights(brightness: float) -> bool:
"""Dim the lights.
Args:
brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
"""
print(f"Lights are now set to {brightness:.0%}")
return True
Appelez maintenant le modèle avec une instruction pouvant utiliser tous les outils spécifiés.
# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]
model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)
# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")
# Print out each of the function calls requested from this single call.
for part in response.parts:
if fn := part.function_call:
args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
print(f"{fn.name}({args})")
power_disco_ball(power=True) start_music(energetic=True, loud=True, bpm=120.0) dim_lights(brightness=0.3)
Chacun des résultats imprimés reflète un seul appel de fonction que le modèle a demandé. Pour renvoyer les résultats, incluez les réponses dans le même ordre que celui demandé.
# Simulate the responses from the specified tools.
responses = {
"power_disco_ball": True,
"start_music": "Never gonna give you up.",
"dim_lights": True,
}
# Build the response parts.
response_parts = [
genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
for fn, val in responses.items()
]
response = chat.send_message(response_parts)
print(response.text)
Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨ Get ready to dance! 🕺💃
Mappage des types de données d'un appel de fonction
L'extraction automatique de schémas à partir de fonctions Python ne fonctionne pas dans tous les cas. Par exemple, il ne gère pas les cas où vous décrivez les champs d'un objet de dictionnaire imbriqué, mais l'API le fait. L'API peut décrire l'un des types suivants :
AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])
La bibliothèque cliente google.ai.generativelanguage vous permet d'accéder aux types de bas niveau et de contrôler entièrement votre application.
Examinez d'abord l'attribut _tools du modèle. Vous pouvez voir comment il décrit la ou les fonctions que vous lui avez transmises :
def multiply(a:float, b:float):
"""returns a * b."""
return a*b
model = genai.GenerativeModel(model_name='gemini-1.5-flash',
tools=[multiply])
model._tools.to_proto()
[function_declarations {
name: "multiply"
description: "returns a * b."
parameters {
type_: OBJECT
properties {
key: "b"
value {
type_: NUMBER
}
}
properties {
key: "a"
value {
type_: NUMBER
}
}
required: "a"
required: "b"
}
}]
Cela renvoie la liste des objets genai.protos.Tool qui seraient envoyés à l'API. Si le format imprimé ne vous est pas familier, c'est parce qu'il s'agit
protobuf. Chaque genai.protos.Tool (1 dans ce cas) contient une liste de genai.protos.FunctionDeclarations, qui décrivent une fonction et ses arguments.
Voici une déclaration de la même fonction de multiplication écrite à l'aide des classes genai.protos. Notez que ces classes décrivent simplement la fonction
l'API, ils n'incluent aucune implémentation de celle-ci. Cela ne fonctionne donc pas
avec l'appel de fonction automatique, mais celles-ci n'ont pas toujours besoin
la mise en œuvre.
calculator = genai.protos.Tool(
function_declarations=[
genai.protos.FunctionDeclaration(
name='multiply',
description="Returns the product of two numbers.",
parameters=genai.protos.Schema(
type=genai.protos.Type.OBJECT,
properties={
'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
},
required=['a','b']
)
)
])
Vous pouvez également décrire cela comme un objet compatible avec le format JSON :
calculator = {'function_declarations': [
{'name': 'multiply',
'description': 'Returns the product of two numbers.',
'parameters': {'type_': 'OBJECT',
'properties': {
'a': {'type_': 'NUMBER'},
'b': {'type_': 'NUMBER'} },
'required': ['a', 'b']} }]}
genai.protos.Tool(calculator)
function_declarations {
name: "multiply"
description: "Returns the product of two numbers."
parameters {
type_: OBJECT
properties {
key: "b"
value {
type_: NUMBER
}
}
properties {
key: "a"
value {
type_: NUMBER
}
}
required: "a"
required: "b"
}
}
Dans tous les cas, vous transmettez une représentation d'un genai.protos.Tool ou d'une liste d'outils à
model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()
response = chat.send_message(
f"What's 234551 X 325552 ?",
)
Comme précédemment, le modèle renvoie un genai.protos.FunctionCall qui appelle la fonction multiply de la calculatrice :
response.candidates
[index: 0
content {
parts {
function_call {
name: "multiply"
args {
fields {
key: "b"
value {
number_value: 325552
}
}
fields {
key: "a"
value {
number_value: 234551
}
}
}
}
}
role: "model"
}
finish_reason: STOP
]
Exécutez la fonction vous-même :
fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'
result = fc.args['a'] * fc.args['b']
result
76358547152.0
Envoyez le résultat au modèle pour poursuivre la conversation:
response = chat.send_message(
genai.protos.Content(
parts=[genai.protos.Part(
function_response = genai.protos.FunctionResponse(
name='multiply',
response={'result': result}))]))