Gemini API function calling : appels d’outils dans les workflows architecturaux

Ce que vous apprendrez dans ce guide

Gemini API function calling permet à un modèle, au lieu de simplement produire un texte de réponse, de choisir une fonction utilisable dans des systèmes externes et de préparer les paramètres nécessaires. Ce n’est pas le modèle qui exécute réellement la fonction : c’est l’application qui fait le lien entre le modèle et le système externe. Le guide de Google décrit cette approche pour effectuer des opérations dans des systèmes externes, récupérer des informations provenant de ressources telles que des API ou des bases de données, et étendre les capacités du modèle à l’aide d’outils de calcul, par exemple.

Pour les équipes d’architecture, de décoration intérieure et de visualisation, cette structure peut servir de base à une application qui, par exemple, recherche des matériaux dans un catalogue ou récupère des informations sur un projet. L’exemple ci-dessous montre comment le modèle prépare les paramètres à transmettre à une fonction de recherche dans un catalogue. La connexion au catalogue réel et l’utilisation des résultats dépendent du développement de l’application.

Prérequis

Pour commencer, il faut une clé API Gemini et un environnement capable d’envoyer des requêtes à l’API. Le guide officiel de démarrage présente le SDK Python, le SDK JavaScript et l’utilisation de REST ; il propose également des exemples en Java et en Go. Ce guide utilise Python.

Google AI Studio crée automatiquement un projet et une clé API pour les nouveaux utilisateurs. La clé est disponible sur la page API keys d’AI Studio. Le guide montre comment la définir comme variable d’environnement. La clé API sert à associer les requêtes au compte et à suivre l’utilisation ; elle contribue également à appliquer des limites de sécurité aux requêtes.

Le passage à l’offre payante permet d’augmenter les limites de requêtes du compte ; Cloud Billing doit alors être configuré. Le guide de Google indique qu’un paiement anticipé d’au moins 5 dollars US, ou l’équivalent dans une autre devise, est requis pour les crédits payants. Il ne s’agit pas d’une estimation du coût d’utilisation, mais de la condition de prépaiement mentionnée dans la source. Vérifiez les paramètres du compte et de facturation avant de passer à l’offre payante.

Commande du guide officiel pour installer le SDK Python :

pip install -U google-genai

Créer un appel de fonction étape par étape

1. Définissez l’objectif de la fonction. Son nom et sa description doivent indiquer clairement ce qu’elle fait. Dans cet exemple, l’objectif est de rechercher dans un catalogue externe des matériaux adaptés à un projet. La requête au catalogue n’est pas exécutée ici ; l’exemple montre comment le modèle génère les arguments nécessaires à cette requête.

2. Définissez les informations à demander au modèle. Une requête utilisateur pourrait, par exemple, être formulée ainsi :

Recherchez dans le catalogue de matériaux des revêtements de sol clairs à l’aspect pierre pour mon projet.

Ce texte montre comment le modèle peut convertir une requête en langage naturel en paramètres de fonction. Les champs requis côté application doivent être définis en fonction de la structure du catalogue ; dans l’exemple ci-dessous, la requête est stockée dans un seul champ texte.

1. Préparez le schéma de la fonction. Les exemples de function calling de Google définissent le nom et la description de la fonction, ainsi que le schéma de ses paramètres. Le type de chaque paramètre est indiqué ; les champs obligatoires sont ajoutés à la liste required. search_materials et le champ query ci-dessous sont des exemples adaptés à un catalogue architectural.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

Rédigez la description de façon à expliquer la tâche réelle de la fonction. Choisissez également des noms de paramètres qui correspondent aux champs attendus par l’application connectée. Si un catalogue nécessite plusieurs filtres, adaptez le schéma en conséquence ; les champs et filtres doivent toutefois correspondre aux informations réellement disponibles dans le système.

1. Envoyez la requête à Gemini API et examinez l’étape d’appel. Les exemples du guide de démarrage utilisent le client genai.Client(), une requête interactions.create et des champs de résultat tels que interaction.output_text. La documentation sur function calling montre quant à elle comment vérifier le type function_call parmi les étapes de réponse et lire le nom de la fonction ainsi que ses arguments.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recherchez des revêtements de sol clairs à l’aspect pierre pour mon projet.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("Fonction :", step.name)
        print("Arguments :", step.arguments)

Dans cet exemple, le modèle doit renvoyer le nom de l’appel de fonction et ses arguments. Examinez les arguments générés par le modèle côté application. L’accès au catalogue, l’exécution de la requête et la présentation des résultats à l’utilisateur sont des étapes de développement qui ne sont pas couvertes par cet exemple.

1. Testez les entrées avant une utilisation réelle. Observez la fonction choisie par le modèle et les arguments qu’il génère pour différentes demandes liées à des projets. Si une demande est ambiguë, concevez dans votre propre système les contrôles nécessaires à un fonctionnement sûr et correct. Les guides de référence expliquent l’utilisation de l’API et les étapes d’appel ; ils ne garantissent ni l’exactitude d’un catalogue architectural spécifique ni la qualité de ses données.

Erreurs fréquentes

• Laisser la description de la fonction dans le flou : décrivez clairement le rôle de l’outil que le modèle est censé sélectionner. Le nom, la description et la définition des paramètres doivent être cohérents.

• Ne pas faire correspondre les paramètres à l’application : les champs du schéma doivent correspondre aux informations attendues par le système externe. Sinon, même si le modèle génère des arguments, l’application risque de ne pas pouvoir les utiliser correctement.

• Confondre l’appel du modèle avec l’exécution de l’opération : function calling génère les appels et les arguments permettant de communiquer avec un système externe. L’exécution réelle de la fonction dépend de la connexion mise en place côté application.

• Gérer la clé API sans précaution : la clé permet d’associer les requêtes API à un compte et d’en suivre l’utilisation. Le guide de démarrage montre comment la conserver dans une variable d’environnement.

• Négliger les coûts et les limites d’utilisation : lors du passage à l’offre payante, les limites de requêtes et les paramètres de facturation changent. Consultez les informations d’utilisation et de facturation dans AI Studio avant de commencer.

Effets sur les workflows d’architecture et de visualisation

Cette approche peut être utile aux équipes qui souhaitent orienter une demande formulée en langage naturel vers les outils définis par leur application. Par exemple, dans un projet d’intérieur, le modèle peut convertir une demande de recherche de matériaux en une requête structurée dans un catalogue. La récupération d’informations depuis une API ou une base de données externe fait également partie des usages mentionnés dans la source. Cela ne signifie pas qu’une connexion prête à l’emploi est fournie avec Revit, 3ds Max ou un autre logiciel de conception : l’intégration doit être mise en place.

Pour les agences et les étudiants, les points importants sont la clé API, la compatibilité de l’application avec le système externe, les limites de requêtes et les éventuelles conditions d’utilisation payante. Aucune exigence matérielle particulière n’est mentionnée dans les sources. Il est donc préférable d’évaluer l’utilisation de l’API et les données qui seront exportées dans le workflow plutôt que de partir d’hypothèses sur le matériel.

Étapes suivantes

Commencez par créer le schéma d’une fonction au périmètre bien défini, comme une recherche dans un catalogue, puis vérifiez les arguments renvoyés à partir de requêtes utilisateur types. Déterminez ensuite quelle API externe ou quelle source de données l’application devra utiliser pour traiter ces arguments. Si vous préférez un autre langage, consultez également les exemples JavaScript ou REST du guide officiel de démarrage. Pour les conversations en plusieurs étapes, le guide présente l’approche previous_interaction_id, dans laquelle le serveur gère l’historique, comme méthode recommandée de gestion de l’état.

Sources et licence

Ce guide est adapté des guides de Google sur Gemini API function calling et sur la prise en main. Les deux sources sont sous licence CC BY 4.0. Le contenu a été traduit en turc et adapté à un scénario de catalogue de matériaux architecturaux.