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 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, 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 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 l'aider à gérer votre requête.

Si vous ne l'avez pas déjà fait, consultez la section Présentation de l'appel de fonction pour en savoir plus. Vous pouvez également tester cette fonctionnalité dans Google Colab ou consulter l'exemple de code dans le dépôt Cookbook de l'API Gemini.

Exemple d'API de 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 les demandes de modification de l'éclairage des utilisateurs et les traduire en appels d'API pour définir les valeurs d'éclairage. 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:

Par souci de simplicité, ce système d'éclairage imaginaire ne comporte qu'une seule ampoule. L'utilisateur n'a donc pas besoin de spécifier de pièce ni d'emplacement. Voici un exemple de requête JSON que vous pouvez envoyer à l'API de contrôle de l'éclairage pour définir le niveau d'éclairage sur 50 % à l'aide de la température de couleur de la lumière du jour:

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

Ce tutoriel vous 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 sur les paramètres de l'API pour contrôler les valeurs de luminosité et de température de couleur d'une 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: int, color_temp: str) -> dict[str, int | str]:
    """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, vous définissez les fonctions en tant qu'outils dans GenerateContentConfig, ainsi que d'autres paramètres liés à la génération (tels que la température ou les jetons d'arrêt).

from google.genai import types

config = types.GenerateContentConfig(tools=[set_light_values])

Vous pouvez également le définir en tant que dictionnaire Python.

config = {
    'tools': [set_light_values],
}

Générer un appel de fonction

Une fois que vous avez défini vos déclarations de fonction, vous pouvez demander au modèle d'utiliser la fonction. Vous pouvez générer du contenu directement ou à l'aide de l'interface de chat.

from google import genai

client = genai.Client()

# Generate directly with generate_content.
response = client.models.generate_content(
    model='gemini-2.0-flash',
    config=config,
    contents='Turn the lights down to a romantic level'
)
print(response.text)

# Use the chat interface.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn the lights down to a romantic level')
print(response.text)

Dans le SDK Python, les fonctions sont appelées automatiquement. Si vous souhaitez gérer chaque appel de fonction ou effectuer une autre logique entre les appels, vous pouvez le désactiver à l'aide de l'indicateur dans la configuration de génération.

from google.genai import types

# Use strong types.
config = types.GenerateContentConfig(
    tools=[set_light_values],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

# Use a dictionary.
config = {
    'tools': [set_light_values],
    'automatic_function_calling': {'disable': True},
}

Appel 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éfinissez 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) -> 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.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}")
    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. Cet exemple utilise un tool_config. Pour en savoir plus, consultez la section Configurer l'appel de fonction.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

config = {
    # Set the available functions.
    'tools': house_fns,
    # Disable AFC so you can inspect the results first.
    'automatic_function_calling': {'disable': True},
    # Force the model to act (call 'any' function), instead of chatting.
    'tool_config': {
        'function_calling_config': {
            'mode': 'any'
        }
    }
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn this place into a party!')

# Print out each of the function calls requested from this single call.
for fn in response.function_calls:
  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)
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 l'ordre dans lequel elles ont été demandées.

Le moyen le plus simple d'y parvenir consiste à laisser automatic_function_calling activé, de sorte que le SDK gère automatiquement les appels de fonction et la transmission des réponses.

config = {
    'tools': house_fns,
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Do everything you need to this place into party!')

print(response.text)

Disco ball is spinning!
Starting music! energetic=True loud=True
Lights are now set to 50%
Alright, I've turned on the disco ball, started playing "Never gonna give you up.", and dimmed the lights. Let's get this party started!

Mappage des types de données d'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])

Pour voir à quoi ressemble le schéma inféré, vous pouvez le convertir à l'aide de from_callable:

from pprint import pprint

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
pprint(fn_decl.to_json_dict())

{'description': 'Returns a * b.',
 'name': 'multiply',
 'parameters': {'properties': {'a': {'type': 'NUMBER'},
                               'b': {'type': 'NUMBER'}},
                'type': 'OBJECT'}}

Ces champs JSON sont mappés sur les champs équivalents du schéma Pydantic et peuvent être encapsulés en tant que Tool.

config = types.GenerateContentConfig(
    tools=[types.Tool(function_declarations=[fn_decl])]
)

Voici une déclaration de la même fonction multiply écrite à l'aide des classes genai.types. Notez que ces classes ne décrivent que la fonction pour l'API. Elles n'incluent pas d'implémentation. Par conséquent, cette approche ne fonctionne pas avec l'appel automatique des fonctions. Toutefois, il vous permet de définir des fonctions qui ne sont pas des fonctions Python concrètes (par exemple, pour encapsuler un appel HTTP distant) et vous offre plus de contrôle entre les appels de fonction (par exemple, pour modifier function_calling_config afin de suivre un graphique d'état).

tool = types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="multiply",
        description="Returns a * b.",
        parameters=types.Schema(
            properties={
                'a': types.Schema(type='NUMBER'),
                'b': types.Schema(type='NUMBER'),
            },
            type='OBJECT',
        ),
    )
])
assert tool.function_declarations[0] == fn_decl